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 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. For Perl use this: Qt::LeftButton, etc. For Ruby use this: Qt::LEFT_BUTTON, etc. For Tcl use this: enum Qt LeftButton, etc.

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 Test Suite Settings view (Section 8.2.16)'s Environment section.

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

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

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.

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 (Section 5.2.6.6).

This function clicks the specified objectOrName button.

This function clicks the mouse on the item with the specified itemOrIndex 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 itemOrIndex is a string with the format row/column, e.g., "4/21". For the tree views the itemOrIndex is a list of segments separated by the "." character. Each segment may optionally contain a _X suffix where X is interpreted as 1-base occurrence index. If any of the involved tree items contains the ".","_" or "\" characters in its text, these characters need to be escaped in the itemOrIndex as "\.", "\_" and "\\" respectively in order to avoid being iterpreted as special characters. (Note that the script interpreter may require additional escaping for the "\" character.) The sequence of the segments corresponds to the tree path of the returned item. For example the "Item1.Sub\.ItemX_3.Leaf" finds an item with text "Leaf" that is a direct child of the third item with the text "Sub.ItemX" among the children of the root node with text "Item1". For other views it is the relevant item's text.

The click is made at position x and y (in the itemOrIndex 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 double-taps on the objectOrName widget.

If x and y arguments (in the objectOrName widget's coordinates) have been provided, the taps will happen there, otherwise replay will happen at the center of the widget.

If the modifiers argument has been provided, the taps will happen with keyboard modifiers pressed, otherwise replay will happen without any keyboard modifiers being pressed.

Tapping is supported on objects of type QQuickItem and QWindow.

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

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

Gesture replay is supported on objects of type QWindow and QWidget.

This function takes a screenshot of the object window (or widget) and returns the image as an AUT-side 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.

The screenshot can easily be saved to a location relative to the AUT's current working directory. 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");

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

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

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 can be passed as a string or 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.

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

	QML Signal handlers
	When defining signal handlers of QML signals, the argument types still must be the C++ types. In particular, this means that for a real QML argument, one must use the C++ double type, and for a string QML type, one must use QString.

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

This function clicks the mouse on the specified objectOrName widget with a fixed delay of about one second between pressing and releasing the mouse button. Apart from the delay this function behaves identical to mouseClick, see mouseClick for more details.

The longMouseClick function is supported on objects of type QQuickItem and QWindow.

This function performs a mouse drag operation with a fixed delay of about one second between pressing the mouse button and starting to move the mouse cursor. Apart from the delay this function behaves identical to mouseDrag, see mouseDrag for more details.

The longMouseDrag function is supported on objects of type QQuickItem and QWindow.

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.

If only the objectOrName is specified, then the object is clicked in the middle by the Qt::LeftButton button and with no keyboard modifiers pressed.

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 longMouseDrag when the mouse drag needs to be executed "more slowly", with more delay in between the individual steps of the drag.

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

This function performs a mouse wheel operation, emulating rotation of the horizontal and/or vertical wheel of a mouse. Replay happens on the specified objectOrName object at position x and y (in the objectOrName objects's coordinates), using the specified xdegrees and ydegrees values for the amount of wheel rotation.

The mouseWheel function is supported on objects of type QQuickItem and QWindow.

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—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 pressAndHold function is supported on objects of type QDeclarativeItem.

pressAndHold() for other object types

For objects of type QQuickItem either longMouseClick or longMouseDrag can be used. For other objects it should be possible to emulate the effect of pressAndHold() by using a combination of the following functions: snooze mouseMove mousePress mouseRelease 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.

This function returns the QQmlContext for the object, or 0 if no context has been set. This is equivalent to calling the C++ function QQmlEngine::contextForObject. A QML Context is a container for properties and allows data to be exposed to QML from C++. For an example of its use, see this blog post.

Returns the QQmlEngine associated with object, if any. This is equivalent to QQmlEngine::contextForObject(object)->engine(), but more efficient. The QQmlEngine class provides an environment for instantiating QML components.

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.

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 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 method changes the keyboard input focus to the object specified by objectOrName.

Changing the keyboard input focus is currently supported on objects of type QQuickItem, QWidget and QWindow.

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

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.

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.

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

This function taps on the specified objectOrName widget. The x and y coordinates as well as the modifiers keyboard modifiers are optional. If they are not specified, the tap is made in the center of the widget using no keyboard modifiers. On the other hand, if the additional coordinate parameters are given, the tap is made at position x and y (in the objectOrName widget's coordinates).

Tapping is supported on objects of type QQuickItem, QWindow and QWidget.

This function performs a touch-based drag operation. It initiates a touch drag of the specified objectOrName widget starting at position x and y (in the objectOrName widget's coordinates). The objectOrName widget is dragged by dx pixels horizontally and by dy pixels vertically.

If specified, the keyboard modifiers provided in modifiers are set while performing the drag.

If specified, the number of milliseconds provided in delayAfterPress is waited before the drag starts.

Touch-based dragging is supported on objects of type QQuickItem and QWindow.

This function performs a touch-based press operation. It replays a touch press on the specified objectOrName widget at position x and y (in the objectOrName widget's coordinates).

If specified, the keyboard modifiers provided in modifiers are set while performing the operation.

Since the object and Qt itself rely on press and release operations to always happen in pairs a call to touchPress should always be paired with a call to touchRelease to ensure a consistent state. For most cases using just tapObject is sufficient.

A single touch press can be performed on objects of type QQuickItem and QWindow.

This function performs a touch-based release operation. It replays a touch release on the specified objectOrName widget at position x and y (in the objectOrName widget's coordinates).

If specified, the keyboard modifiers provided in modifiers are set while performing the operation.

Since the object and Qt itself rely on press and release operations to always happen in pairs a call to touchRelease should always be preceded by a call to touchPress to ensure a consistent state. For most cases using just tapObject is sufficient.

A single touch release can be performed on objects of type QQuickItem and QWindow.

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

Unlike nativeType, type() treats Ctrl and Command as the same key on all platforms. This means that you can write type("<Ctrl+c>") in a test script and it will result in Ctrl+r on Linux and Windows and in Command+r on macOS. In turn, to make Squish press the actual Ctrl key on macOS, you need to use Qt terminology: type("<Meta+r>").

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

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

This function uninstalls a signal handler that has been previously installed using installSignalHandler.

This function uninstalls a signal handler that has been previously installed using installLazySignalHandler.

This function waits for Qt (not Unix!) signal to be emitted by the given object. The object is a reference to object and can be obtained from one of the functions returning object references (e.g. waitForObject or findObject. The signalSignature must be a string, and contain the exact signature used in C++ with no parameter names (see installSignalHandler for examples of valid signatures). The duration of the waiting loop is defined by the testSettings.waitForObjectTimeout property or if the optional timeoutMSec parameter is used, that many milliseconds. If the signal doesn't arrive within the given timeout, (catchable) RuntimeError exception is raised.

waitForSignal(waitForObject(names.window_Window), "titleChanged()")

waitForSignal(waitForObject(names.windowWindow), "titleChanged()")

waitForSignal(waitForObject($Names::window_window), "titleChanged()");

waitForSignal(waitForObject(Names::Window_Window), "titleChanged()")

invoke waitForSignal [waitForObject $names::window_Window] "titleChanged()"

6.4.2. QML Extension API

Table of Contents

6.4.2.1. The Format of a QML Extension

6.4.2.2. Installing QML Extensions

6.4.2.3. QML Extension API Documentation

Qt applications that utilize QtQuick 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. Rectangle or Text items), 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 a SquishHook for a custom Calculator Button type: SQUISHDIR/examples/qt5/calqlatr/extension/Calqlatr.qml.

Squish  also includes a more substantial QML Extension for support of QtQuick Controls, located in SQUISHDIR/lib/extensions/qt/qtquick/ControlsExt.qml.

6.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. For QtQuick 1.x the structure of a Squish QML extension looks like this:

JavaScript

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

SquishHook {
    // extension code...
}

For QtQuick 2.x the basic structure of a   QML extension is:

JavaScript

import QtQuick 2.0
import com.froglogic.squish.qtquick 0.1

SquishHook {
    // extension code...
}

6.4.2.2. Installing QML Extensions

Squish automatically looks in the SQUISHDIR/lib/extensions/qt/qml directory for extension files targeting QtQuick 1.x and into the SQUISHDIR/lib/extensions/qt/qtquick directory for QtQuick 2.x extension files. All that is needed to “install” a new QML extension is to move or copy it into one of these directories. It is also possible add an additional directory for Squish to search for QML extensions: Set the SQUISH_QML_EXTENSION_PATH environment variable (which you may need to create) to the directory where you want to keep your QtQuick 1.x QML extensions. For QtQuick 2.x rather set the SQUISH_QTQUICK_EXTENSION_PATH environment variable to the directory where you keep your QML extensions.

6.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 QtQuick 1.x API uses the QML types and elements specified in the Qt 4.8 Reference Documentation: doc.qt.io/qt-4.8/qdeclarativebasictypes.html and doc.qt.io/qt-4.8/qdeclarativeelements.html.

The QtQuick 2.x API uses the QML types and elements specified in the Qt 5.x Reference Documentation: doc.qt.io/qt-5/qml-qtquick-item.html and doc.qt.io/qt-5/qtqml-typesystem-basictypes.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.

bool itemHasContents(item);

	QtQuick 2.x specific
	This function is only available in QtQuick 2.x QML Extensions.

This function returns whether the given item of type Item has the QQuickItem::ItemHasContents flag set. This is a helper function to access this particular flag from within QML. It can serve as a hint whether an item should be ignored by default. See also doc.qt.io/qt-5/qquickitem.html#Flag-enum.

String qmlId(item);

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

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

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 7.12)—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 accesses 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);

	QtQuick 1.x specific
	This function is only available in QtQuick 1.x QML Extensions.

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.