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

Qt Convenience Function Parameters

Some of Qt's 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 can be one or more of the following: Qt.NoModifier, Qt.AltModifier, Qt.ControlModifier, Qt.KeypadModifier, Qt.MetaModifier, Qt.ShiftModifier. If more than one is used they must be OR-d together, for example, Qt.AltModifier|Qt.ShiftModifier. The form shown here works for Python and JavaScript. For Perl replace the period with two colons, e.g., Qt::ControlModifier, and for Tcl use the enum function, e.g., enum Qt ControlModifier. The button can be any one of: Qt.NoButton, Qt.LeftButton, Qt.MidButton, Qt.RightButton. The form shown here works for Python and JavaScript. For Perl replace the period with two colons, e.g., Qt::LeftButton, and for Tcl use the enum function, e.g., enum Qt LeftButton.

Native Dialogs on KDE

To ensure the most reliable recording and replaying of tests, Squish uses Qt's own dialogs (e.g., for choosing colors, files, and fonts), rather than the underlying platform's native dialogs. Unfortunately, on KDE, Qt uses the KDE dialogs and this can cause problems when developing cross-platform test scripts. The solution is to set the QT_PLATFORM_PLUGIN environment variable to an invalid value, (e.g., QT_PLATFORM_PLUGIN=nonesuch). This can be done, for instance, in the Squish IDE's Settings view (Section 16.2.14)'s Environment section.

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

This function activates the menu item with the specified itemText in the objectOrName popup menu, context menu, or menu bar. (Note that &'s should not be included in the item text, so if the menu item's text is “Add” (meaning that the text inside the program is really “&Add”), we just write plain “Add”.)

This function casts the object of type QMenuBar, QPopupMenu, or one of their subclasses, to an object of type QMenuData. The reason the function is needed at all is that test scripts for Qt 2 and Qt 3 AUTs often need to access a QPopupMenu or QMenuBar's QMenuData, but due to squishidl's limitation of single inheritance this is not possible. Nor can Squish's cast function be used in this case because it only supports casting up or down in the inheritance chain. Qt 4 uses a different menu inheritance structure that only uses single-inheritance, so Qt 4 menus can be handled directly.

	Qt 2 and Qt 3-specific
	The castToQMenuData function is for testing Qt 2 and Qt 3 applications; it is not needed (or available) for Qt 4 applications.

This function casts the object to a QObject. The object must be a subclass of QObject and QGraphicsItem—or a class derived from QGraphicsItem—and where QObject is inherited first. It is not necessary to use this function for QGraphicsObjects and QGraphicsWidgets since Squish already knows that these are both QObjects and QGraphicsItems at the same time.

	Non-QGraphicsItem Objects
	If this function is called on an object that is not derived from QObject and QGraphicsItem—or a class derived from QGraphicsItem—with QObject inherited first, Squish will crash!

	Qt 4-specific
	The castToQObject function is only available for applications using Qt 4.2 or later since the graphics/view APIs were only introduced in that version of Qt.

Unfortunately QGraphicsItem does not provide support for introspection. This means that although Squish provides full access to all the built-in QGraphicsItem classes and their properties and methods—including their QObject properties and methods if they inherit QObject and the castToQObject function is used—none of the properties or methods you add to your own QGraphicsItem subclasses can be accessed by Squish.

For examples of testing Qt's graphics/view classes see How to Test Graphics Views, Graphics Scenes and Graphics Items (Qt 4) (Section 13.2.6.6).

This function clicks the specified objectOrName button.

This function clicks the mouse on the item with the specified itemText inside the given objectOrName 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. It is safe to pass 0 for the coordinates and for the state; and normally we would pass Qt.LeftButton for the button.

Squish supports this function for view widgets of type QAbstractItemView, and its subclasses, including QListView, QTableView, and QTreeView, and also older Qt 3 classes such as Q3IconView, Q3ListBox, Q3Table, and also classes derived from these types.

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

This function clicks on the tab that has the specified tabText on the objectOrName tab widget. (Note that &'s should not be included in the tabText, so if the tab's text is, say, “Advanced”—meaning that the text inside the program is really “&Advanced”—we just write plain “Advanced”.)

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

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

This function double-clicks the mouse on the item with the specified itemText inside the given objectOrName 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.

Squish supports this function for view widgets of type QAbstractItemView, and its subclasses, including QListView, QTableView, and QTreeView, and also older Qt 3 classes such as Q3IconView, Q3ListBox, Q3Table, and also classes derived from these types.

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

This function performs a drag and drop operation. It begins by initiating a drag on the source_objectOrName widget starting at position sx and sy (in the source_objectOrName widget's coordinates), and then it does the drop on the target_objectOrName widget at position tx and ty (in the target_objectOrName widget's coordinates). The action is an integer (enum)—for Qt 4 it can be Qt::CopyAction or Qt::LinkAction, and for Qt 3 it can be QDropEvent::Copy or QDropEvent::Link.

This function performs a drag operation. It initiates a drag of the specified objectOrName widget starting at position x and y (in the objectOrName widget's coordinates), using the specified button and with the modifierState modifier state. The objectOrName widget is dragged by dx pixels horizontally and by dy pixels vertically.

This function performs a “flick” operation (a move or scroll on a QML Flickable). It initiates a flick of the specified objectOrName item—which must be a QML Flickable—starting with the mouse at position x and y (in the objectOrName item's coordinates) and moving the mouse by dx pixels horizontally and by dy pixels vertically. At the same time the position of the objectOrName item's contents is moved relative to its previous position by cdx pixels horizontally and by cdy pixels vertically.

This function takes a screenshot of the object window (or widget) and returns the image as a QPixmap. The screenshot can easily be saved to file, for example:

widget = waitForObject(objectName)
pixmap = grabWidget(widget)
pixmap.save("screenshot.png")

var widget = waitForObject(objectName);
var pixmap = grabWidget(widget);
pixmap.save("screenshot.png");

my $widget = waitForObject($objectName);
my $pixmap = grabWidget($widget);
$pixmap->save("screenshot.png");

set widget [waitForObject $objectName]
set pixmap [invoke grabWidget $widget]
invoke $pixmap save "screenshot.png"

For a more generic example that shows how to save a screenshot and how to compare screenshots, see the files scriptmodules/python/pixmapcompare.py and scriptmodules/javascript/pixmapcompare.js.

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

This function installs an event handler that is applied to all objects of the className class or to the specified object or globally (if no className or object is specified). 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 on an object of the className class, or to the specified object, or globally.

The eventName can be the name any standard Qt event type such as QKeyEvent event or QMouseEvent, or one of the Squish convenience event types listed below:

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 installs a Qt (not Unix!) signal handler that eavesdrops on the object identified by the given symbolic or real name. The signalSignature must be the exact signature used in C++ with no parameter names—for example, "activated(int)" or "triggered(QAction*)". The handlerFunctionName (which must be passed as a string, not as a function reference), will be called whenever the specified widget emits the specified signal and will be passed a reference to the object that emitted the signal, followed by all the signal's arguments (if there are any).

This function is very flexible in that the object identified by the name does not have to exist at the time the function is called, since the object will be looked for whenever the signal is emitted. The price to be paid for this flexibility is that the use of this function can significantly slow down playback if the signal is emitted a lot. If possible it is better to use the less flexible installSignalHandler function instead.

Where possible the signal's arguments are passed as types that can be handled normally such as numbers, strings, or their actual Qt types such as QAction or QTableWidgetItem. However, some types are sent as plain Squish Objects; custom types and other unrecognized types are passed as strings.

This function installs a Qt (not Unix!) signal handler that eavesdrops on the specified objectOrName widget. The signalSignature must be the exact signature used in C++ with no parameter names—for example, "activated(int)" or "triggered(QAction*)". The handlerFunctionName (which must be passed as a string, not as a function reference), will be called whenever the specified widget emits the specified signal and will be passed a reference to the object that emitted the signal, followed by all the signal's arguments (if there are any).

As is usual with Squish functions, the objectOrName widget must exist at the time this function is called. This requirement is relaxed by the installLazySignalHandler function which can only accept a symbolic or real name, but of an object that need not exist when the function is called. Nonetheless, it is best to use this installSignalHandler function whenever possible since it is potentially a lot faster than the installLazySignalHandler function.

Where possible the signal's arguments are passed as types that can be handled normally such as numbers, strings, or their actual Qt types such as QAction or QTableWidgetItem. However, some types are sent as plain Squish Objects; custom types and other unrecognized types are passed as strings.

For an example, see How to Use Qt Signal Handlers (Section 13.2.5).

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

Note that if this function is used to click Q3ListView objects, Q3TableItem objects, or web objects inside QtWebKit objects, the modifierState and button parameters are optional.

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

This function performs a mouse drag operation. It initiates a mouse drag of the specified objectOrName widget starting at position x and y (in the objectOrName widget's coordinates), using the specified button and with the modifierState modifier state. The objectOrName widget is dragged by dx pixels horizontally and by dy pixels vertically.

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

This function simulates a native mouse click on the specified objectOrName widget at position x and y (in the objectOrName widget's coordinates), using the specified button and with the modifierState modifier state.

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

This function simulates the user opening a context menu by clicking the specified objectOrName widget at position x and y (in the objectOrName widget's coordinates), and with the modifierState modifier state.

See Qt Convenience Function Parameters for which values are valid for the modifierState argument.

This function simulates the user opening a context menu by clicking the menu option with the specified itemText inside the objectOrName view widget at position x and y (in the itemText item's coordinates), and with the modifierState modifier state.

Squish supports this function for view widgets of type QAbstractItemView, and its subclasses, including QListView, QTableView, and QTreeView, and also older Qt 3 classes such as Q3IconView, Q3ListBox, Q3Table, and also classes derived from these types.

See Qt Convenience Function Parameters for which values are valid for the modifierState argument.

This function performs a press and hold operation on the specified objectOrName item—which must be a QML object—starting with the mouse at position x and y (in the objectOrName item's coordinates) and optionally moving the mouse by dx pixels horizontally and by dy pixels vertically if these offsets are specified. (Note that dx and dy are relative to the starting mouse position in QML scene coordinates, not in objectOrName item coordinates which is normally the case.)

The press and hold operation performed by this function is similar to what the dragItemBy function does, except for the “hold” (the initial pause when the mouse is first pressed down). QML scenes support press and hold by using an invisible MouseArea item that is overlaid on top of one or more of the scene's QML items. Squish doesn't record actions for invisible items so for a press and hold it records the item at the mouse (or finger for touch screens) position that is actually under the MouseArea.

This function scrolls the objectOrName 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 is any of the Qt events supported by Squish—this includes all the most commonly used ones, such as, "QCloseEvent", "QHideEvent", "QKeyEvent", "QMouseEvent", "QMoveEvent", "QShowEvent", "QTabletEvent", and "QWheelEvent".

This function can be used in init files to disable or enable the recording of MouseMove events for certain widget classes. The class to disable or enable mouse tracking for is specified by the className parameter. Pass an onOrOff parameter value of true to enable mouse tracking or of false to disable mouse tracking. (By default mouse tracking is off.)

Wrapper-Specific Initialization

The init files are Tcl scripts that are registered with the squishrunner and then read before starting any tests. The registration process is explained in Configuring squishrunner (Section 15.4.1.7). (Although init files must be written in Tcl, this does not affect the scripting language used for test suites, which may be in any of the scripting languages that Squish supports.) We can have as many init scripts as we like for each GUI toolkit; or we can put all the initialization statements in a single Tcl script per toolkit. However many init scripts we use, they must all be registered with the squishrunner.

Example:

setMouseTracking ScribbleArea true

This sets mouse tracking on for an AUT's custom ScribbleArea class.

To make this work we must tell Squish to execute a file that contains this Tcl script at startup when it is used to test a Qt-based AUT:

squishrunner --config addInitScript Qt /home/harri/qt_init1.tcl

Note that an absolute path must be used.

This function can be used in init files to disable or enable the recording of mouseDrag statements for certain widget classes. The class to disable mouse dragging for is specified by the className parameter. Pass an onOrOff parameter value of true to enable mouse drag recording or of false to disable mouse drag recording. (By default mouse drag recording is on.)

Wrapper-Specific Initialization

The init files are Tcl scripts that are registered with the squishrunner and then read before starting any tests. The registration process is explained in Configuring squishrunner (Section 15.4.1.7). (Although init files must be written in Tcl, this does not affect the scripting language used for test suites, which may be in any of the scripting languages that Squish supports.) We can have as many init scripts as we like for each GUI toolkit; or we can put all the initialization statements in a single Tcl script per toolkit. However many init scripts we use, they must all be registered with the squishrunner.

The init files are Tcl scripts that are registered with the server and then read before starting any tests. The registration process is explained in Configuring squishrunner (Section 15.4.1.7) squishrunner.

Example:

setRecordMouseDrag ScribbleArea false

This switches off mouse drag recording for an AUT's custom ScribbleArea class.

To make this work we must tell Squish to execute a file that contains this Tcl script at startup when it is used to test a Qt-based AUT:

squishrunner --config addInitScript Qt /home/harri/qt_init2.tcl

Note that an absolute path must be used.

This function sets the state of the given objectOrName window to that specified by the windowState enumeration. Valid window state values are: WindowState.Fullscreen, WindowState.Maximize, WindowState.Minimize, and WindowState.Normal. The form shown here works for Python and JavaScript. For Perl replace the period with two colons, e.g., WindowState::Maximize, and for Tcl use the enum function, e.g., enum WindowState Maximize. Note that using this function only makes sense for top-level windows.

This function clicks the “up” button on the objectOrName spinbox. The function works for QAbstractSpinBox and its subclasses, such as QSpinBox and QDoubleSpinBox.

This function clicks the “down” button on the objectOrName spinbox. The function works for QAbstractSpinBox and its subclasses, such as QSpinBox and QDoubleSpinBox.

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"). (For a list of the supported special keys see the nativeType function's documentation.)

	Qt 3-specific
	If the key combination is surrounded by an additional pair of angle brackets, an accelerator event is sent instead of a key event—for example, "<<Alt+A>>".

import Qt 4.7
import com.froglogic.squish.qml 0.1

SquishHook {
    // ... extension code...
}