Windows Convenience API

Windows Convenience Function Parameters

For all of the Windows Convenience API functions that take an objectOrName argument, this argument can be a reference to an object or the name of an object—the object must be (or name) a native Windows object.

Some of the Windows Convenience API 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 mouseButton argument which indicates which mouse button was clicked.

The modifierState can be one or more of the following: Modifier.NoModifier, Modifier.Alt, Modifier.Control, Modifier.Shift. If more than one is used they must be OR-d together, for example, Modifier.Alt|Modifier.Shift. The form shown here works e.g., Modifier::Control, and for Tcl use the enum function, e.g., enum Modifier Control.

The mouseButton can be any one of: MouseButton.NoButton, MouseButton.Wheel, MouseButton.LeftButton, MouseButton.MiddleButton, MouseButton.RightButton. MouseButton.XButton1. MouseButton.XButton2.

The form shown above works for Python and JavaScript.

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

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

For Tcl use this: enum MouseButton LeftButton, etc.

Windows Convenience API Functions and Properties

Here are some quick links to the Windows Convenience API's functions and properties:

chooseFile(path)

This function automates a native file selection dialog. It assumes that a dialog was opened (or is about to open) and then automatically selects the file path specified by path. An empty string can be used to emulate that the file dialog is cancelled.

The function will wait for a dialog to open for at most 3 seconds. If no dialog is opened within 3 seconds, or if the specified path name is too long, an exception is raised.

The duration for which the function will wait for a dialog to open is configurable in the etc\winwrapper.ini configuration file. The setting Native File Dialog Script Call Timeout (ms) can be adjusted to a different threshold.

clickButton(objectOrName)

This function clicks the objectOrName widget which should be the name of a button or a reference to a button object.

clickItem(objectOrName, itemText)

clickItem(objectOrName, itemText, mouseButton)

clickItem(objectOrName, itemText, mouseButton, modifierState)

This function clicks the objectOrName widget's item that has the specified itemText. This will work for any widget that has a text property.

By default MouseButton.LeftButton is used, but this can be changed by specifying the optional mouseButton argument. Similarly a default modifier state of Modifier.NoModifier is used, but this can be changed by specifying the modifierState argument. Note that to specify the modifier, the button must also be specified. See Windows Convenience Function Parameters for which values are valid for the mouseButton argument and for the modifierState argument.

collapse(objectOrName)

If the objectOrName is a tree or tree item, it is collapsed so that none of its child items (if it has any) are visible. If the objectOrName is a combobox, its pop-up list of items is hidden. (See also collapseItem(objectOrName, itemName), expandItem(objectOrName, itemText), and expand(objectOrName).)

collapseItem(objectOrName, itemName)

The objectOrName should be a tree or tree item. It is collapsed so that none of the child items of the item with the specified itemText are visible. (See also expandItem(objectOrName, itemText) and expand(objectOrName).)

doubleClick(objectOrName)

doubleClick(objectOrName, x, y)

doubleClick(objectOrName, x, y, mouseButton)

doubleClick(objectOrName, x, y, mouseButton, modifierState)

This function double-clicks the objectOrName widget.

By default the widget is double-clicked in the middle, but this can be changed by passing widget-relative coordinates, x and y. By default MouseButton.LeftButton is used, but this can be changed by specifying the optional mouseButton argument. Similarly a default modifier state of Modifier.NoModifier is used, but this can be changed by specifying the modifierState argument. Note that to specify the button, the coordinates must also be specified; and to specify the modifier state, the coordinates and the button must also be specified. See Windows Convenience Function Parameters for which values are valid for the mouseButton argument and for the modifierState argument.

doubleClickItem(objectOrName, itemText)

doubleClickItem(objectOrName, itemText, mouseButton)

doubleClickItem(objectOrName, itemText, mouseButton, modifierState)

This function double-clicks the objectOrName widget's item that has the specified itemText. This will work for any widget that has a text property.

By default MouseButton.LeftButton is used, but this can be changed by specifying the optional mouseButton argument. Similarly a default modifier state of Modifier.NoModifier is used, but this can be changed by specifying the modifierState argument. Note that to specify the modifier, the button must also be specified. See Windows Convenience Function Parameters for which values are valid for the mouseButton argument and for the modifierState argument.

dragAndDrop(source_objectOrName, target_objectOrName)

dragAndDrop(source_objectOrName, sx, sy, target_objectOrName)

dragAndDrop(source_objectOrName, target_objectOrName, tx, ty)

dragAndDrop(source_objectOrName, sx, sy, target_objectOrName, tx, ty)

This function performs a drag and drop operation. It begins by initiating a drag on the source_objectOrName widget and then it does the drop on the target_objectOrName widget. By default the drag is from the middle of the source object to the middle of the target object, unless specific coordinates are given, in which case the coordinates are honored.

Either, both, or neither sets of coordinates can be specified. If the source coordinates are given, the drag starts at position sx and sy (in the source_objectOrName widget's coordinates), and if the target coordinates are given the drop occurs at position tx and ty (in the target_objectOrName widget's coordinates).

expand(objectOrName)

If the objectOrName is a tree or tree item, it is expanded to show its child items (if it has any). If the objectOrName is a combobox, its pop-up list of items is shown. (See also expandItem(objectOrName, itemText), collapseItem(objectOrName, itemName), and collapse(objectOrName).)

expandItem(objectOrName, itemText)

The objectOrName should be a tree or tree item. It is expanded to show the item with the specified itemText, and that item's child items (if it has any). (See also collapseItem(objectOrName, itemName) and collapse(objectOrName).)

gesture(objectOrName, touches)

This function plays a gesture. The specified objectOrName can refer to any object that is ready for user interaction. The gesture is replayed relative to the top-left corner of the specified object. The specified touches refers to a GestureBuilder object.

focusedWindow()

This function returns an object reference to the window that has the keyboard focus. (See also setFocusedWindow(objectOrName).)

installEventHandler(eventName, handlerFunctionNameOrReference)

This function installs a global event handler. The script function named or referenced in handlerFunctionNameOrReference, will be called when an event of the eventName type occurs.

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

• Crash: This event occurs if the AUT crashes.
• DialogOpened: This event occurs when a dialog window is opened; a "dialog window" is a window with the (extended) styles DS_MODALFRAME + WS_EX_DLGMODALFRAME + WS_EX_WINDOWEDGE + WS_EX_CONTROLPARENT or DS_SYSMODAL + DS_SETFOREGROUND + WS_EX_TOPMOST + WS_EX_WINDOWEDGE + WS_EX_CONTROLPARENT (styles can be checked with Microsoft's Spy++ tool from Visual Studio).
• MessageBoxOpened: This event is occurs when Squish detects that a dialog window was opened (i.e., the same requirements as given in the explanation of the DialogOpened event apply), but the dialog window also matches a certain structure. The exact structure depends on the particular GUI toolkit but it usually means that the dialog should contain just text and some standard buttons like OK and Cancel.
• Timeout: This event occurs when the Squish response timeout is reached.

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.

mouseClick(objectOrName)

mouseClick(objectOrName, mouseButton)

mouseClick(objectOrName, mouseButton, modifierState)

mouseClick(objectOrName, x, y, mouseButton)

mouseClick(objectOrName, x, y, mouseButton, modifierState)

This function clicks the mouse on the specified objectOrName widget.

If only the objectOrName is specified, then the object is clicked in the middle by the MouseButton.LeftButton. All the other usages require the mouseButton to be specified, optionally preceded by by object-relative coordinates, x and y which say where the click takes place, and optionally followed by a modifierState (which defaults to Modifier.NoModifier if not specified).

See Windows Convenience Function Parameters for which values are valid for the mouseButton argument and for the modifierState argument.

mouseDrag(objectOrName, dx, dy)

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

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

mouseDrag(objectOrName, x, y, dx, dy, mouseButton, modifierState)

This function performs a mouse drag from the objectOrName widget to a position that is horizontally offset by dx pixels and vertically offset by dy pixels from the object's center (or from position x, y in the objectOrName widget's coordinates if these are specified). If you need to specify the mouse button or modifier state but don't want to specify the origin (because the center of the object is sufficient), pass 0 for the x coordinate and for the y coordinate.

By default the mouse is dragged from the middle of the object, but this can be changed by passing object-relative coordinates, x and y. The amount to drag, dx, dy, must be specified. By default MouseButton.LeftButton is used, but this can be changed by specifying the optional mouseButton argument. Similarly a default modifier state of Modifier.NoModifier is used, but this can be changed by specifying the modifierState argument. Note that to specify the modifier, the button must also be specified. See Windows Convenience Function Parameters for which values are valid for the mouseButton argument and for the modifierState argument.

mousePress()

mousePress(mouseButton)

mousePress(mouseButton, modifierState)

mousePress(x, y, mouseButton)

mousePress(x, y, mouseButton, modifierState)

mousePress(objectOrName)

mousePress(objectOrName, mouseButton)

mousePress(objectOrName, mouseButton, modifierState)

mousePress(objectOrName, x, y, mouseButton)

mousePress(objectOrName, x, y, mouseButton, modifierState)

This function performs a mouse press. All the parameters are optional excepting that either both or neither of the coordinates must be present.

If x and y coordinates are given, the press takes place at those coordinates, either relative to the objectOrName object if one is specified, or relative to the current screen otherwise. If no coordinates are given the press takes place on the middle of the objectOrName object if one is specified, or wherever the mouse happens to be otherwise.

By default MouseButton.LeftButton is used, but this can be changed by specifying the optional mouseButton argument. Similarly a default modifier state of no modifiers is used, but this can be changed by specifying the modifierState argument. See Windows Convenience Function Parameters for which values are valid for the mouseButton argument and for the modifierState argument.

mouseRelease()

mouseRelease(mouseButton)

mouseRelease(mouseButton, modifierState)

mouseRelease(x, y, mouseButton)

mouseRelease(x, y, mouseButton, modifierState)

mouseRelease(objectOrName)

mouseRelease(objectOrName, mouseButton)

mouseRelease(objectOrName, mouseButton, modifierState)

mouseRelease(objectOrName, x, y, mouseButton)

mouseRelease(objectOrName, x, y, mouseButton, modifierState)

This function performs a mouse release. All the parameters are optional excepting that either both or neither of the coordinates must be present.

If x and y coordinates are given, the release takes place at those coordinates, either relative to the objectOrName object if one is specified, or relative to the current screen otherwise. If no coordinates are given the release takes place on the middle of the objectOrName object if one is specified, or wherever the mouse happens to be otherwise.

By default MouseButton.LeftButton is used, but this can be changed by specifying the optional mouseButton argument. Similarly a default modifier state of no modifiers is used, but this can be changed by specifying the modifierState argument. See Windows Convenience Function Parameters for which values are valid for the mouseButton argument and for the modifierState argument.

mouseWheel(n)

mouseWheel(n, modifierState)

This function performs a mouse wheel operation, emulating rotation of the vertical wheel of a mouse. The operation happens over the current mouse location. To move the mouse to a desired location, please use the function mouseMove(x, y).

The amount of wheel rotation is specified by the argument n. One n corresponds to one wheel notch which is about 15 degrees or 120 delta units of a mouse wheel event. The positive value of n rotates the wheel in an upward direction (away from the user) and the negative in a downward direction (toward the user).

The keyboard state during a mouse wheel can be specified by using the argument modifierState. See Windows Convenience Function Parameters for which values are valid for this argument.

Object nativeObject

Squish automatically adds a property called nativeObject to every Windows Object's list of properties. The native object provides access to all the underlying object's methods and properties.

For examples of how to use the nativeObject see How to Use the Windows API.

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(objectOrName, touches). The specified gesture-file refers to the filename.

setForegroundWindow(objectOrName)

This function tries to bring the objectOrName window into the foreground, that is, raises it above any overlapping windows if possible.

setFocusedWindow(objectOrName)

This function gives the keyboard focus to the objectOrName window or to the window that contains the objectOrName widget. (See also focusedWindow().)

setValue(objectOrName, integer)

This function sets the value of the, objectOrName editable widget to the given integer value.

This function can be used to set the numeric value in a spinbox, or to set the value of a TrackBar (a slider widget) or of a ScrollBar.

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(keys) function's documentation.)

uninstallEventHandler(eventName, handlerFunctionNameOrReference)

This function uninstalls an event handler that has been previously installed using installEventHandler(eventName, handlerFunctionNameOrReference).

GestureBuilder

Objects of this type hold the touch strokes information needed to replay gesture(objectOrName, touches). An instance of this class is returned by readGesture(gesture-file). 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 and Gesture manipulation section, return the GestureBuilder object itself, unless specified differently.

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

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.

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.