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 clicks the objectName button.

This function 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 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 in handlerFunctionName (which must be passed as a string, not as a function reference), 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 is called with a single argument—the object on which the event occurred.

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

	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 Image Object (Section 14.3.12).

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 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 13.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.