Tk Convenience API

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 button)—but these values can vary between systems.

Tk Convenience Functions

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

activateItem(objectName, itemText)

activateItem(objectName, itemText, itemImageName)

activateItem(objectName, itemText, itemImageName, itemFileName)

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.

asyncClickItem(objectName, itemIdentifier, x, y, modifierState, button)

This function works similar to the normal clickItem(objectName, itemIdentifier, x, y, modifierState, button) 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(objectName, itemIdentifier, x, y, modifierState, button) 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(objectName, itemIdentifier, x, y, modifierState, button) function.

asyncDoubleClickItem(objectName, itemIdentifier, x, y, modifierState, button)

This function works similar to the normal doubleClickItem(objectName, itemText, x, y, modifierState, button) 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(objectName, itemText, x, y, modifierState, button) 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(objectName, itemText, x, y, modifierState, button) function.

asyncMouseClick(objectName, x, y, modifierState, button)

This function works similar to the normal mouseClick(objectName, x, y, modifierState, button) 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(objectName, x, y, modifierState, button) 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(objectName, x, y, modifierState, button) function.

asyncType(objectName, text)

This function works similar to the normal type(objectName, text) 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(objectName, text) 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(objectName, text) function.

clickButton(objectName)

This function clicks the objectName button.

clickItem(objectName, itemIdentifier, x, y, modifierState, 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.

closeWindow(objectName)

This function closes the objectName window.

doubleClick(objectName, x, y, modifierState, button)

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.

doubleClickItem(objectName, itemText, x, y, modifierState, button)

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.

installEventHandler(eventName, handlerFunctionNameOrReference)

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:

• "Crash" – occurs if the AUT crashes
• "Timeout" – occurs when the Squish response timeout is reached

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.

mouseClick(objectName, x, y, modifierState, button)

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.

scrollTo(objectName, position)

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

sendEvent(eventName, objectOrName, ...)

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:

• "ButtonEvent"
• "KeyEvent"
• "MotionEvent"

String tcleval(code)

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

type(objectName, text)

type(objectName, text, modifierState)

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(keys) 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.

dragAndDrop(sourceObjectName, sourcex, sourcey, targetObjectName, targetx, targety)

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.

uninstallEventHandler(eventName, handlerFunctionNameOrReference)

This function uninstalls an event handler that has been previously installed using installEventHandler(eventName, handlerFunctionNameOrReference).