18.4. Qt Convenience API

18.4.1. QWebView Class
18.4.2. QML Extension API
18.4.3. GestureBuilder
[Important]Qt-specific

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

[Note]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 and Ruby 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 above works for Python and JavaScript.

For Perl use this: Qt::LeftButton, etc.

For Ruby use this: Qt::LEFT_BUTTON, etc.

For Tcl use this: enum Qt LeftButton, etc.

[Note]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 20.2.14)'s Environment section.

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

activateItem(itemObject);

activateItem(objectOrName, itemText);

This function activates the specified itemObject, or the item specified by itemText in the popup menu, context menu, or menu bar denoted by objectOrName.

Note that &'s should not be included in the item text, so if the item's text is “Add” (meaning that the text inside the program is really “&Add”), we just write plain “Add”.

activateLink(objectOrName, Url);

This function activates the link with the URL address specified Url inside the objectOrName widget. The function works for QTextBrowser and QLabel and its subclasses.

QMenuData castToQMenuData(object);

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.

[Note]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.

QObject castToQObject(object);

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.

[Warning]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!

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

clickButton(objectOrName);

This function clicks the specified objectOrName button.

clickItem(objectOrName, itemIdentifier, x, y, modifierState, button);

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

clickTab(objectOrName, tabText);

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

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

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.

doubleClickItem(objectOrName, itemText, x, y, modifierState, button);

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.

dragAndDrop(source_­object­Or­Name, sx, sy, target_­object­Or­Name, tx, ty, action);

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.

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

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.

dropOn(target_objectOrName, tx, ty, action);

This function performs a drop that was initiated by a call to the startDrag function. It does the drop on the target_objectOrName widget at position tx and ty (in the target_objectOrName widget's coordinates). See dragAndDrop for possible values of the action parameter.

Normally the dragAndDrop function is used to perform a drag and drop in a single action. However, in some situations it may be necessary to move the mouse over a different object before the drop can take place. In such cases the test code would look something like this:

startDrag(sourceObject, sx, sy)
mouseMove(otherObject, x, y)
dropOn(targetObject, tx, ty, action)

flick(objectOrName, x, y, dx, dy, cdx, cdy);

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.

gesture(objectOrName, touches);

This function plays a gesture. The specified objectOrName can refer to any object that is visible and serves for synchronization only. The specified touches refers to a GestureBuilder object, which can be retrieved using readGesture.

QPixmap grabWidget(object);

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:

Python
widget = waitForObject(objectName)
pixmap = grabWidget(widget)
pixmap.save("screenshot.png")
JavaScript
var widget = waitForObject(objectName);
var pixmap = grabWidget(widget);
pixmap.save("screenshot.png");
Perl
my $widget = waitForObject($objectName);
my $pixmap = grabWidget($widget);
$pixmap->save("screenshot.png");
Ruby
widget = waitForObject(objectName)
pixmap = grabWidget(widget)
pixmap.save("screenshot.png")
Tcl
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.

installEventHandler(eventName, handlerFunctionName);

installEventHandler(className, eventName, handlerFunctionName);

installEventHandler(object, eventName, handlerFunctionName);

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, except for Python, which supports passing a function reference, too), 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:

Crash
This event occurs if the AUT crashes.
DialogOpened
This event occurs when a top-level QDialog is shown.
MainWindowOpened
This event occurs when a top-level QMainWindow is shown.
MessageBoxOpened
This event occurs when a top-level QMessageBox is shown.
Timeout
This event occurs when the Squish response timeout is reached.
ToplevelWidgetOpened
This event occurs when any other kind of top-level widget is shown.

The function named in handlerFunctionName is called with a single argument—the object on which the event occurred.

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

installLazySignalHandler(name, signalSignature, handlerFunctionName);

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.

installSignalHandler(objectOrName, signalSignature, handlerFunctionName);

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

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

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.

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

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.

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

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.

openContextMenu(objectOrName, x, y, modifierState);

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.

openItemContextMenu(objectOrName, itemText, x, y, modifierState);

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.

pressAndHold(objectOrName, x, y);

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

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

[Important]Emulating pressAndHold() for non QML objects

It should be possible to emulate the effect of pressAndHold() by using a combination of the following functions:

For example:

function main()
{
    //...

    mouseMove(waitForObject(":target_object_name"), 5, 5);
    mousePress(waitForObject(":target_object_name"));
    snooze(3);
    mouseRelease(waitForObject(":target_object_name"));

    //...
}

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.

readGesture(gesture-file);

This function opens a gesture file from a test suite directory and returns a GestureBuilder object. This can then be passed to gesture. The specified gesture-file refers to the filename.

scrollTo(objectOrName, position);

This function scrolls the objectOrName 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 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".

setMouseTracking(className, onOrOff);

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

[Note]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 19.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.

setRecordMouseDrag(className, onOrOff);

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

[Note]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 19.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 19.4.1.7) squishrunner.

Example:

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

setWindowState(objectOrName, windowState);

This function sets the state of the given objectOrName window to that specified by the windowState enumeration.

Note that using this function only makes sense for top-level windows.

Valid window state values are: WindowState.Fullscreen, WindowState.Maximize, WindowState.Minimize, and WindowState.Normal.

The form shown above works for Python and JavaScript.

For Perl use this: WindowState::Maximize, etc.

For Ruby use this: WindowState::MAXIMIZE, etc.

For Tcl use this: enum WindowState Maximize, etc.

spinUp(objectOrName);

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

spinDown(objectOrName);

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

startDrag(source_objectOrName, sx, sy);

This function initiates a drag on the source_objectOrName widget starting at position sx and sy (in the source_objectOrName widget's coordinates). The drop can be done using the dropOn function.

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

[Note]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>>".

uninstallEventHandler(eventName, handlerFunctionName);

uninstallEventHandler(className, eventName, handlerFunctionName);

uninstallEventHandler(object, eventName, handlerFunctionName);

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

18.4.1. QWebView Class

Squish provides additional support for the QWebView class in the form of three additional methods.

Object QWebView.clearObjectCache();

This function clears the cache of objects that are being looked up using hierarchical names like DOCUMENT.HTML1.BODY1.DIV2 . (See also clearObjectCache.)

Object QWebView.evalJS(code);

This function evaluates the JavaScript code string in the QWebView's context (i.e., in the context of the active QWebView page). The result of the last statement in the code is returned as a string. (See also How to Use evalJS (Section 17.3.5).)

Object QWebView.retrieveJSObject(code);

This function evaluates the JavaScript code string in the QWebView's context (i.e., in the context of the active QWebView page). The result of the last statement in the code is returned as a primitive value, like a string or number, or a reference to a JsObject Class (Section 18.10.40) in the page. (See also How to Use retrieveJSObject (Section 17.3.6) and retrieveJSObject.)

Boolean QWebView.isPageLoaded();

This function returns true if the page has been completely loaded; otherwise it returns false. A complete and successful load implies that all of the page's objects can potentially be accessed. This function can be used with the waitFor function to wait for a page to be loaded before accessing it from a test script.

Since page loading, HTTP requests, and so on, are asynchronous, even after a call to the isPageLoaded function returns true it is essential that the waitForObject function (or another wait function) is used to ensure that the specific object or objects of interest are ready to be accessed. Also, it may be necessary to pass a longer timeout to the waitForObject function than the default 20 seconds (20 000 milliseconds). (See also How to Synchronize Web Page Loading for Testing (Section 17.3.8).)

QWebView.loadUrl(url);

This function changes the QWebView's current page to the new url.

18.4.2. QML Extension API

Qt applications can dynamically load QML code, including custom QML objects, so it is quite possible that AUTs that use QML will have QML objects that are unknown to Squish. This isn't a problem since Squish can still record and playback interactions with such objects, but will do so in terms of the primitives they are built from (e.g., in terms of Rectanges and Texts), rather than with the actual (logical) item types (e.g., CustomButton).

The QML Extension API introduced with Squish 4.1 makes it possible to make Squish aware of custom QML object types so that recording and playback can work at a high level (i.e., in terms of the custom objects themselves rather than with the primitives that they are built from). Squish comes with a small example that makes use of some of the QML Extension APIs and that shows how to implement custom versions of SquishHook functions: SQUISHDIR/lib/extensions/qt/qml/QtComponentsDesktop.qml.

18.4.2.1. The Format of a QML Extension

QML Extensions are standard QML scripts in .qml files (using the UTF-8 encoding), and using some additional functionality provided by Squish. Here is the structure of a QML extension:

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

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

18.4.2.2. Installing QML Extensions

Squish automatically looks in the SQUISHDIR/lib/extensions/qt/qml directory for QML extension files, so all that is needed to “install” a new QML extension is to move or copy it into this directory. It is also possible add an additional directory for Squish to search for QML extensions: simply set the SQUISH_QML_EXTENSION_PATH environment variable (which you may need to create) to the directory where you want to keep your QML extensions (for example, if you don't have write access to SQUISHDIR/lib/extensions/qt/qml).

18.4.2.3. QML Extension API Documentation

Squish's QML Extension API consists of a single item of type SquishHook. This item provides various properties and functions which are listed below. A custom QML extension can make use of these properties and functions—and in some cases override them. In addition, Squish provides some helper functions to make writing QML extensions easier.

The API uses the QML types and elements specified in the Qt Reference Documentation: qt-project.org/doc/qt-4.8/qdeclarativebasictypes.html and qt-project.org/doc/qt-4.8/qdeclarativeelements.html.

bool isCustomQmlType(item);

This function returns whether the given item of type Item is a custom type. (Every QML item that introduces new properties is considered to be a custom QML type by Qt—and by this function.)

bool isQmlType(item, className);

This function returns whether the given item of type Item inherits the class specified by the className string.

String qmlType(item);

This function returns the given item of type Item's class name if it is a declarative type; otherwise it returns an empty string.

String source(item);

This function returns the given item of type Item's URL if the item was loaded from a local file or remotely; otherwise it returns the item's containing component's URL (which might be an empty string).

String qmlId(item);

This function returns the id for the given item or an empty string if item has no id set.

Item SquishHook.containerFor(item);

This function returns the container the given item of type Item is in (itself of type Item, e.g., a ListView or a GridView) which is normally also the item's parent; otherwise it returns null if the item isn't in a container.

You can implement your own version of this function in your QML extension, in which case for any given item you must return one of the following three values: An Item (possibly of your own custom type) which contains the given item. Or null, if you don't want the given item to have a container (in which case the view will be considered to be the item's container). Or, the special value, unhandled, if you don't want to handle the given item (e.g., because it is a standard Item type that you want Squish to handle), since unhandled tells Squish to handle the item itself.

StringList SquishHook.extraPropertiesFor(item);

This function returns a list of the property names for the given item of type Item that should be taken into account when generating a Squish object name for the item. (This function can be used to achieve the same kind of control over Squish's naming as editing the Qt wrapper descriptor file—for which see, Object Name Generation (Section 19.11)—but with finer control possible since property names can be considered on a per-item basis, not just on a per-type basis.)

You can implement your own version of this function in your QML extension, in which case for any given item you must return either: A list of property names (as an array of strings) whose values should be used to create the Squish object name for the given item. Or, the special value, unhandled, if you don't want to handle the given item (e.g., because it is a standard Item type that you want Squish to handle), since unhandled tells Squish to handle the item itself.

bool SquishHook.isIgnored(item);

This function returns false if the given item of type Item should be taken notice of by Squish—for example, visible and available for picking in the Spy and recorded.

You can implement your own version of this function in your QML extension, in which case for any given item you must return one of the following three values: The value false if you want Squish to take notice of the given item, or true if you want Squish to ignore the item, or the special value, unhandled, if you don't want to handle the given item (e.g., because it is a standard Item type that you want Squish to handle), since unhandled tells Squish to handle the item itself.

bool SquishHook.isItemReady(item);

This function returns true if the given item of type Item is ready to be interacted with, that is, is visible, enabled, and is in a stable state (e.g., it is not being or about to be animated).

You can implement your own version of this function in your QML extension, in which case for any given item you must return one of the following three values: The value true if the given item is ready for interaction, or false the item isn't ready, or the special value, unhandled, if you don't want to handle the given item (e.g., because it is a standard Item type that you want Squish to handle), since unhandled tells Squish to handle the item itself.

int SquishHook.priority

This property holds a priority value for the QML extension and has a default value of 0. Squish accessess QML extensions in priority order from highest to lowest.

You can implement your own version of this property in your QML extension to give your extension a priority value higher than 0, e.g., to increase its priority.

String SquishHook.propertyFor(item, property);

This function returns a property value (as a string) for the given item of type Item's property (specified as a string).

You can implement your own version of this function in your QML extension, in which case for any given item and property you must return either: A string property value, or the special value, unhandled, if you don't want to handle the given item (e.g., because it is a standard Item type that you want Squish to handle), since unhandled tells Squish to handle the item itself.

Note that this function is not called when the object.property("propertyName") function is used inside a test script.

18.4.3. GestureBuilder

Objects of this type hold the touch strokes information needed to replay gesture. An instance of this class is returned by readGesture. Strokes are defined by screen coordinates points, pressure and touch size.

int GestureBuilder.areaWidth

The width of the area in which this gesture is defined. This will be the device or emulator screen width.

int GestureBuilder.areaHeight

The height of the area in which this gesture is defined. This will be the device or emulator screen height.

All GestureBuilder methods listed in the Gesture creation (Section 18.4.3.1) and Gesture manipulation (Section 18.4.3.2) section, return the GestureBuilder object itself, unless specified differently.

18.4.3.1. Gesture creation

This section lists the methods for manually creating a GestureBuilder object.

GestureBuilder(width, height, unit);

GestureBuilder(xml);

Two constructor functions for creating a GestureBuilder object. The width and height are the target screen size. The unit can be either 0 or 1, meaning respectively in pixels or millimeters. The constants GestureBuilder.Pixel and GestureBuilder.MilliMeter can be used as well.

The second constructor function constructs a GestureBuilder object by passing an string containing XML, which should be in the same format as the recorded gesture files.

Object GestureBuilder.addStroke(x, y);

Object GestureBuilder.addStroke(startTime, x, y);

Object GestureBuilder.addStroke(startTime, x, y, pressure);

Object GestureBuilder.addStroke(startTime, x, y, pressure, size);

Starts a new stroke. The whole movement of one finger or pen from touch down to releasing the screen is called a stroke. The touch down coordinate is (x, y). For the non-first stroke, a time offset can be specified in milliseconds using the startTime argument. Strokes cannot be disjointed in time, at least one finger or pen has to be down during the whole gesture. The maximum simultaneous touches is device dependent (See QTouchDevice::maximumTouchPoints()).

Finally, the pressure and size are relative messure values for respectively pen or finger pressure and size. These should be between 0.0 and 1.0 and when omitted defaults to 0.25.

Object GestureBuilder.curveTo(duration, controlX, controlY, endX, endy);

Object GestureBuilder.curveTo(duration, control1X, control1Y, control2X, control2Y, endX, endy);

Adds a bézier curve movement to the latest added stroke in duration milliseconds. The curve starts with the end coordinate of the last added movement or, if none added to the stroke, the stroke touch down coordinate. The end coordinate is specified with endX and endY. One or two so called control points can be used.

Object GestureBuilder.lineTo(duration, endX, endy);

Adds a line movement to the latest added stroke in duration milliseconds. The line starts with the end coordinate of the last added movement or, if none added to the stroke, the stroke touch down coordinate. The end coordinate is specified with endX and endY.

Object GestureBuilder.build();

Creates the gesture from the added strokes and movements. After calling this method, no strokes or movements can be added.

18.4.3.2. Gesture manipulation

Object GestureBuilder.accelerate(factor);

Changes stroke speed given a factor. A factor between 0.0 and 1.0 slows down the gesture, above 1.0 will speed it up.

Object GestureBuilder.rotate(degrees);

Object GestureBuilder.rotate(degrees, originX, originY);

Rotates the strokes. The degrees is the agle in degrees in a counter clockwise direction. The originX and originY define the origin of the rotate operation. If omitted, the area center is taken as origin.

Object GestureBuilder.scale(scale);

Object GestureBuilder.scale(scaleX, scaleY);

Object GestureBuilder.scale(scaleX, scaleY, originX, originY);

Changes the size of the strokes. The scaleX is the scale factor in the horizontal direction and scaleY in the vertical direction. The originX and originY define the origin of the scale operation. If omitted, the area center is taken as origin. When also scaleY is omitted, then the scaling is homogeneous in both directions.

Object GestureBuilder.translate(x, y);

Moves the strokes. The x and y specifies the movement. A positive value for x moves the strokes to the right and a positive value for y moves the strokes downwards.