Mouse

3.1.6 Mouse

DESCRIPTION

Mouse - Perform a mouse event. This command can automate a wide range of mouse actions such as a mouse pointer movement, mouse click, press, release, drag and mouse wheel events. The command also supports custom drags composed of a sequence of mouse press, mouse move and mouse release events (since 2.0.2). Should you see any composed events (clicks, drags) fail, please see the Mouse command preferences for calibration parameters.

The current mouse pointer coordinates are available in the script through the _MOUSE_X and _MOUSE_Y dynamic variables (since version 2.1).

SYNOPSIS

mouse [<modifier_1>+...+<modifier_N>+]<event_id> [btn=<button_name>] [modifiers=<modifier_1>+...+<modifier_N>] [to=[x:<x>][,y:<y>]] [from=[x:<x>][,y:<y>]]  [center=[x:<x>][,y:<y>]]  [start=<number>]  [end=<number]  [count=<number>] [wait=<time>]
* Red colour indicates obligatory parameters

OPTIONS

modifier

- Any combination of modifiers Shift, Alt and Ctrl separated by the plus '+' sign, e.g. 'Ctrl+Alt+Shift'.

event_id


- Supported events are:

    • "move", a mouse pointer move from the optional destination to the target point,
    • "click", one or more clicks at the target point using the specified mouse button,
    • "press", a mouse button press (without release),
    • "release", a mouse button release (logically requires a preceding press event),
    • "drag", mouse drag from the optional destination to the target point using the specified mouse button,
    • "swipe", a mouse drag with adjusted timing for devices with a touch display (such as Android or iOS devices),
    • "wheelup", one or more mouse wheel rotation steps upwards (wheel rotating away from user),
    • "wheeldown", one or more mouse wheel rotation steps downwards (wheel rotating towards user),
    • "pinch", one or more pinch events where two fingers move towards a shared center point on a touch screen (also known as "pinch close"). This event is supported just on certain environments, for example on Apple iOS devices running the T-Plan Server connected over the iOS Mirror connection type,
    • "zoom", one or more zoom events where two fingers move away from a shared centre point on a touch screen (also known as "pinch open"). This event is supported just on certain environments, for example on Apple iOS devices running the T-Plan Server connected over the iOS Mirror connection type.

btn

- This parameter is used to identify the mouse button to click, press, release or drag with. Allowed values are "left", "middle" and "right".

modifiers

- This parameter provides an alternative way of specifying the mouse event modifiers (the other way is to place modifiers before the event ID). The value may be any combination of Shift, Alt and Ctrl separated by the plus '+' sign, e.g. "Ctrl+Alt+Shift". If modifiers are specified with the event ID as well, this parameter prevails.

to=[x:<x>][,y:<y>]

- The target coordinates.

    • If the event is "move" they define where to move the mouse pointer (target point).
    • If the event is "click", "press", "release", "wheelup" or "wheeldown" the mouse pointer will be first moved to this location and then the associated action is performed.
    • If the action is "drag" or "swipe" the mouse pointer will be dragged from its actual position (or from the position specified by the from option) to this target location.

The coordinates have the format of 'x:<x>,y:<y>', where each coordinate can be specified in pixels (e.g. 'x:225') or as a percentage (e.g. 'x:23%'). If x or y is omitted, the current mouse pointer location will be used to determine the missing coordinate.

from=[x:<x>][,y:<y>]

- Start coordinates.

  • If the action is "drag" or "swipe" the mouse pointer will be dragged from this position to the coordinates specified by the to option.
  • If the event is "click", "press", "release", "wheelup" or "wheeldown", this parameter will be ignored.

The coordinates have the format of 'x:<x>,y:<y>', where each coordinate can be specified in pixels (e.g. 'x:225') or relatively as a percentage (e.g. 'x:23.5%'). Relative coordinates are rounded if they are not an integer. If x or y is omitted, the current mouse pointer location will be used to determine the missing coordinate.

center=[x:<x>][,y:<y>]

- The pinch/zoom center point (optional). It is used only for the "pinch" and "zoom" actions. If the parameter is omitted the action will default to the screen centre.

The coordinates have the format of 'x:<x>,y:<y>', where each coordinate can be specified in pixels (e.g. 'x:225') or relatively as a percentage (e.g. 'x:23.5%'). Relative coordinates are rounded if they are not an integer. If x or y is omitted, the current mouse pointer location will be used to determine the missing coordinate.

start=<number> end=<number>

- The pinch/zoom start and end distances. It is used only for the "pinch" and "zoom" actions. The parameters must be always specified together. If they are omitted the action will calculate default values based on the center point position and the current screen size.

The distances specify how many pixels the fingers are apart at the beginning ("start") and the end ("end") of the gesture.
When the event is "pinch" the start distance must be naturally greater than the end one, because the fingers move closer to each other.
The "zoom" event requires the opposite setting. The distances must be specified in a way that the fingers don't get too close to each other (30 pixels at a minimum) or closer than 10 pixels to the screen borders. 

count=<number>

- How many times the mouse event should be performed. The default value is 1. This value makes sense only with the click, wheel, pinch and zoom events and it is ignored by other event types.

wait=<time>

- Time to wait after the events are sent. It has the same effect as if the following command was 'Wait <time>'. The value must be either a number of milliseconds or valid time value. The default value is 0 (don't wait). Scripts may set the default value through populating of the _MOUSE_WAIT variable with the desired delay, for example "Var _MOUSE_WAIT=1s".

RETURNS
The command returns 0 (zero) on success or 1 when it fails, for example for an I/O error.

EXAMPLES
Mouse click count=2

- Perform a mouse double click at the current mouse pointer coordinates.

Mouse move to=x:25,y:122

- Move the mouse pointer to the given coordinates

Mouse move to=x:{_MOUSE_X}+50

- Move the mouse pointer 50 pixels to the right from its current position.

Mouse drag from=x:10%,y:450 to=x:22.5%,y:450 wait=2s

- Drag the mouse pointer from the given start position to the destination position and wait for two seconds. The x coordinate is given in the relative form. If your display resolution is e.g. 800x600 pixels, the 'x:10%' will be equal to 'x:60' and 'x:22.5%' will be 'x:135'.

Mouse swipe from=x:161,y:124 to=x:161,y:226


- Swipe the touch screen from the start position to the destination one.

Compareto "icon.png" method=search onfail="Exit 1"
Mouse move to=x:{_SEARCH_X}+10,y:{_SEARCH_Y}+10
Mouse press 
Mouse move to=x:{_SEARCH_X}+110 wait=500
Mouse release

- Example of a "composed drag" applied to an object located through image comparison. The script first searches the desktop for an object represented by the icon.png template. If it is found, the mouse pointer is moved to the area (plus ten pixels in each direction) and the object is dragged 100 pixels to the right using a sequence of press, move and release events.

Mouse pinch

- Pinch the screen. If the current connection supports pinch it will zoom out the current application.

Mouse zoom center=x:220,y:450 start=125 end=180

- Zoom in the screen. If the current connection supports pinch it will zoom in the current application. The command uses a custom center point and start and end distances.