6.8. Mac OS X Convenience API

[Important]Mac OS X-specific

The Mac OS X Convenience API is only available for the Squish for Mac OS X editions.

[Note]Terminology

The Squish documentation uses the term widget when referring to GUI objects. Mac OS X developers may be more familiar with the term view for this concept.

[Note]Mac Convenience Function Parameters

Some of the Mac OS X convenience functions can take a modifierState argument which indicates which special keys are pressed at the time of a mouse click. And some of the functions can also take a button argument which indicates which mouse button was clicked.

The modifierState is an integer used as a bit-flag. Its value can be 0 (no modifiers) or one or more of: 1 (Shift), 2 (Control), 4 (Command), 8 (Option), with multiple modifiers or-ed together (e.g., 1|2 for Shift+Control).

The button is an integer: 0 signifies the “primary” mouse button (most commonly the left button), and 1 signifies the right button.

Here are some quick links to the Mac OS X Convenience API's functions:

activateItem(objectOrName);

This function activates the objectOrName menu item. This menu item must be a reference to (or a name that identifies) an NSMenuItem or a Carbon menu item. The menu item can be part of the application menu or a menu item inside an NSPopUpButton.

[Tip]Mac OS X Universal Access

In order to replay menu activations on Mac OS X you have to enable accessibility support in the System Preferences. For this, please open the System Preferences and choose Security & Privacy. The choose the Privacy tab and select Accessibility on the left side.

In order to make changes, click the lock symbol in the lower left and enter the credentials of an administrative user. Then please check the squishide app from the list.

If you use Mac OS X 10.8 and earlier, open System Preferenes, choose Universal Access and enable the checkbox Enable access for assistive devices.

clearWebObjectCache(

This function clears the cache for hierarchical names for objects in a WebView. This can be useful in cases where a web application removes some elements of a web page after interacting with it and then the same hierarchical name used before should find a different object. Without clearing the cache in this situation the old object will be retrieved from the cache when searching for the hierarchical name after the website has changed its content. The cache however is necessary to keep lookup for hierarchical performant and scalable for deeper hierarchies.

—deprecated— clickButton(objectOrName);

This function is identical to mouseClick. It is included only for compatibility with old scripts. It should not be used in new scripts since it may eventually be removed from Squish.

—deprecated— clickTab(objectOrName);

This function is identical to mouseClick. It is included only for compatibility with old scripts. It should not be used in new scripts since it may eventually be removed from Squish.

doubleClick(objectOrName);

doubleClick(objectOrName, x, y);

doubleClick(objectOrName, x, y, modifierState, button);

This function double-clicks the mouse on the specified objectOrName widget.

By default the object is clicked in the middle, but this can be changed by passing object-relative coordinates, x and y. By default button 0 (the primary button) is used, but this can be changed by specifying the optional button argument. Similarly a default modifier state of 0 (no modifiers) is used, but this can be changed by specifying the modifierState argument. Note that to specify the modifier, the button must also be specified, and to specify the modifier, the position must be specified. See Mac Convenience Function Parameters for which values are valid for the modifierState and for the button arguments.

Image grabWidget(object);

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

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

installEventHandler(eventName, handlerFunctionName);

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, except for Python, which supports passing a function reference, too), will be called when an event of the eventName type occurs.

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

When the SheetOpened event occurs, the function named in handlerFunctionName is called. The function is passed one argument—the window object that opened the sheet. If you want to access the sheet itself, call the attachedSheet function on the NSWindow object.

When the WindowOpened event occurs, the function named in handlerFunctionName is called. The function is passed one argument—the window object that was opened. The event occurs only for toplevel windows (NSWindow and NSPanel objects), but it does not occur for windows that are shown as sheets. Use the SheetOpened event if you are interested in sheets.

[Note]Python-specific

In Python scripts, you can specify the callback function to invoke by passing an actual function or a lambda function.

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

[Important]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).

mouseClick(objectOrName);

mouseClick(objectOrName, x, y);

mouseClick(objectOrName, x, y, modifierState, button);

This function clicks the mouse on the specified objectOrName widget.

By default the object is clicked in the middle, but this can be changed by passing object-relative coordinates, x and y. By default button 0 (the primary button) is used, but this can be changed by specifying the optional button argument. Similarly a default modifier state of 0 (no modifiers) is used, but this can be changed by specifying the modifierState argument. Note that to specify the modifier, the button must also be specified, and to specify the modifier, the position must be specified. See Mac Convenience Function Parameters for which values are valid for the modifierState and for the button arguments.

mouseDrag(objectOrName, x, y, dx, dy);

mouseDrag(objectOrName, x, y, dx, dy, modifierState, button);

This function performs a mouse drag from the objectOrName widget to a position that is horizontally offset by dx pixels and vertically offset by dy pixels from position x, y in the objectOrName widget's coordinates.

By default button 0 (the primary button) is used, but this can be changed by specifying the optional button argument. Similarly a default modifier state of 0 (no modifiers) is used, but this can be changed by specifying the modifierState argument. Note that to specify the modifier, the button must also be specified, and to specify the modifier, the position must be specified. See Mac Convenience Function Parameters for which values are valid for the modifierState and for the button arguments.

mouseMove(objectOrName);

mouseMove(objectOrName, x, y);

This function moves the mouse to the center of the objectOrName widget, or if coordinates are specified, to position x and y relative to the objectOrName widget.

This function is useful if you want to trigger events that need the mouse to be at a particular position. For example, tooltips normally only appear when the mouse is over a certain area.

scrollToObject(objectOrName);

This function ensures that the objectOrName widget is visible in the scroll widget that contains it, by scrolling if necessary.

If there are nested scroll widgets, the innermost one that contains the objectOrName widget is the one that will be scrolled.

Currently this function only works for NSView subclasses and for items in a NSTableView and NSOutlineView. If you need support for other classes, contact froglogic support.

type(objectOrName, text);

This function types the specified text (as if the user had used the keyboard) into the objectOrName 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").

The following non-printable keys are supported in key combinations: <Ctrl>, <Command>, <Shift>, <Option>, <Up>, <Down>, <Left>, <Right>, <Del>, <Return>, <Tab>, <Backtab>, <Esc>, and <Backspace>.

uninstallEventHandler(eventName, handlerFunctionName);

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