Tk-specific
	The Tk Convenience API is only available for the Squish for Tk editions.

Tk Convenience Function Parameters

Some of Tk's convenience functions can take a modifierState argument which indicates which special keys are pressed at the time of a mouse click and a button argument which indicates which mouse button was clicked. The modifierState is used to indicate whether the Control, Shift, and similar keys are pressed. The value is passed as an integer and is normally 0 (meaning none are pressed). The precise numbers to use depend on the underlying Tk implementation—look in the X.h file for ControlMask, ShiftMask and so on, or ask froglogic support for help. The button is used to indicate which mouse button is pressed. The values are normally, 1 (left button), 2 (middle button), and 3 (right buttton)—but these values can vary between systems.

Here are some quick links to the Tk Convenience API's functions:

This function activates the menu item with the specified itemText in the objectName menu, context menu, or menu bar.

As an alternative, the item can be identified by its itemImageName (i.e., the AUT's internal name for the menu item's image), in which case the itemText can be passed the corresponding text or an empty string. Similarly, the item can be identified by its itemFileName (i.e., the filename of the menu item's image), in which case the itemText and itemImageName can be passed their corresponding texts or empty strings.

This function works similar to the normal clickItem function, but can avoid hanging test executions in cases where the click triggers opening a modal dialog. A modal dialog normally blocks the final step of emulating a click, which causes the normal clickItem function to not return until the dialog has been closed. In order to avoid this, the emulation of the click is slightly delayed and the function returns immediately before the emulation has finished. This has no noticeable effect on the test script.

For details on the parameters and their usage please look at the normal clickItem function.

This function works similar to the normal doubleClickItem function, but can avoid hanging test executions in cases where the double click triggers opening a modal dialog. A modal dialog normally blocks the final step of emulating a click, which causes the normal doubleClickItem function to not return until the dialog has been closed. In order to avoid this the emulation of the click is slightly delayed and the function returns immediately before the emulation has finished. This has no noticeable effect on the test script.

For details on the parameters and their usage please look at the normal doubleClickItem function.

This function works similar to the normal mouseClick function, but can avoid hanging test executions in cases where the click triggers opening a modal dialog. A modal dialog normally blocks the final step of emulating a click, which causes the normal mouseClick function to not return until the dialog has been closed. In order to avoid this the emulation of the click is slightly delayed and the function returns immediately before the emulation has finished. This has no noticeable effect on the test script.

For details on the parameters and their usage please look at the normal mouseClick function.

This function works similar to the normal type function, but can avoid hanging test executions in cases where the text input triggers opening a modal dialog. A modal dialog normally blocks the final step of emulating the text input, which causes the normal type function to not return until the dialog has been closed. In order to avoid this the emulation of the text input is slightly delayed and the function returns immediately before the emulation has finished. This has no noticeable effect on the test script.

For details on the parameters and their usage please look at the normal type function.

This function clicks the objectName button.

This function clicks the mouse on the item with the specified itemIdentifier inside the given objectName view widget. This function is typically used to access items inside views such as lists, tables, and trees. For tables the itemIdentifier is a string with the format row/column, e.g., "4/21"; for other views it is the relevant item's text.

The click is made at position x and y (in the itemText item's coordinates) using the specified button and with the modifierState modifier state.

See Tk Convenience Function Parameters for which values are valid for the modifierState and button arguments.

This function closes the objectName window.

This function double-clicks the mouse on the objectName widget at position x and y (in the objectName widget's coordinates) using the specified button and the modifierState modifier.

See Tk Convenience Function Parameters for which values are valid for the modifierState and button arguments.

This function double-clicks the mouse on the item with the specified itemText inside the given objectName view widget. The click is made at position x and y (in the itemText item's coordinates) using the specified button and with the modifierState modifier state.

See Tk Convenience Function Parameters for which values are valid for the modifierState and button arguments.

This function installs a global event handler. The script function named or referenced in handlerFunctionNameOrReference, will be called when an event of the eventName type occurs.

The eventName can be the name of any of the following event types:

The function named in handlerFunctionName (which must be passed as a string, not as a function reference, except for Python, which supports passing a function reference, too) is called with a single argument—the object on which the event occurred.

For examples see How to Use Event Handlers (Section 5.10).

	The AUT Must be Running
	The installEventHandler function will only work if it is called after the AUT has been started (e.g., using the startApplication function).

This function takes a screenshot of the object window (or widget) and returns it as an QImage Object (Section 6.3.13).

See the waitForObject and findObject functions for how to get an object reference to a window or widget.

This function clicks the mouse on the specified objectName widget. The click is made at position x and y (in the objectName widget's coordinates) using the specified button and with the modifierState modifier state.

See Tk Convenience Function Parameters for which values are valid for the modifierState and button arguments.

This function scrolls the objectName widget to the given position. The position is an absolute value (i.e., a pixel offset).

This function sends an event of type eventName to the objectOrName widget. All the other arguments (...) are passed on to the event constructor—they are typically coordinates, button states, and similar.

The eventName may be any of the following:

This function evaluates the given code in the AUT's Tcl interpreter and returns the result. (For an example see How to Use tcleval (Section 5.6.3).)

This function types the specified text (as if the user had used the keyboard) into the objectName editable widget. If the text is surrounded by angle brackets (<>), it is interpreted as a key combination, e.g "<Ctrl+Return>". The input is case-sensitive, so type object "R" is different from type object "r". (For a list of the supported special keys see the nativeType function's documentation.)

The modifierState is optional and defaults to 0 (no modifier keys are pressed). See Tk Convenience Function Parameters for which values are valid for the modifierState.

This function executes a drag and drop operation. The drag is started from the sourceObjectName widget at the given relative coordinates sourcex and sourcey. The dragged object is dropped onto the targetObjectName widget at the given relative coordinates targetx and targety.

This function uninstalls an event handler that has been previously installed using installEventHandler.