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

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

Mac Convenience Function Parameters

Some of the macOS 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 macOS Convenience API's functions:

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.

macOS Universal Access

In order to replay menu activations on macOS as well as use the nativeType and nativeMouseClick functions you have to enable accessibility support in the System Preferences for certain processes. The system will open up a popup dialog when starting the Squish IDE the first time that allows you to directly go the preferences dialog to enable accessibility support for the Squish IDE. The dialog can also be opened manually: Open the System Preferences and choose Security & Privacy. Then 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 check the Squishide or Terminal app which needs permissions, from the list. Note that at any given time there will be only one Squish IDE instance that has access to the accessibility API and hence can run scripts that automate menus, use the nativeType or the nativeMouseClick function. In order to use another Squish IDE - for example from another Squish installation on the same system - you need to remove the existing entry completely from the list and then start the other instance of the Squish IDE. Then enable accessibility support again when the dialog pops up. Finally it may sometimes happen that macOS always asks for enabling the accessibility support during the startup of the Squish IDE. In such cases it helps to completely reset the database for Accessibility-enablement and clear out the whole list. This can be done using the tccutil from macOS: tccutil reset Accessibility After executing the command restart the Squish IDE to trigger the Accessibility-enablement popup again.

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.

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.

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.

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.

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

	The Newer Way to Grab a Widget
	Instead of using grabWidget to get an AUT-side QImage, it is easier to capture an Image Object (Section 6.3.14) using object.grabScreenshot. The Image.save function allows you to save directly to a location on the squishrunner host.

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

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.

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

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

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.

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.

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

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