Moveto

3.2.13 MoveTo

DESCRIPTION

Similar to the Click command, MoveTo is a combination of Waitfor match and Mouse move commands. It searches the desktop for a component image, a solid colour object or a text and moves the mouse pointer to it. If the object is not found it exits the script.

SYNOPSIS

MoveTo <comparison_method>  [timeout=<time>]  [cmparea=<[x:<x>][,y:<y>][,w:<width>][,h:<height>]>]  [number=<component_number>]  [modifiers=<modifiers>]  [wait=<time>]  [<method specific options>]
* Red colour indicates obligatory parameters

comparison_method

- Supported methods are:

    • 'image' - search for a component by the image or an image collection using the search2 method,
    • 'object' - search for a component by its colour using the object method,
    • 'ocr' - recognize text on the screen using OCR (the tocr method) and find the specified string or pattern.

COMMON OPTIONS

timeout=<time>

- Timeout specifying how long to wait for the component to appear on the screen at a maximum. The value must be either a number of milliseconds or valid time value. The default value is 30 seconds.

cmparea=[x:<x>][,y:<y>][,w:<width>][,h:<height>]

- The rectangular area of the desktop to limit the comparison to. If you omit this parameter the whole remote desktop will be processed. The area coordinates have the format of 'x:<x>,y:<y>,w:<width>,h:<height>', where each coordinate can be specified in pixels (for example. "x:225") or as a percentage ("x:23%"). If any of x, y, width or height are omitted the app will use the full-screen values to determine the missing parameters (x:0, y:0, w:<screen_width>, h:<screen_height>).

number=<component_number>

- The number of the component on the screen to move the mouse to. Components (objects) located on the screen are sorted in the reading order, from the top to the bottom and from the left to the right. The default value is 1 (click the first located component). If the number of components found on the screen is lower than the specified number the command exits the script.

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

- Specifies the move location relatively from the centre of the target object. This allows to move the mouse to a nearby location instead of the object itself. If the comparison method is an image the parameter overrides the image click point and uses the image centre as the base point. For example, the command of "MoveTo image template=button.png move=x:-40" will move the pointer 40 pixels to the left from the button centre.

modifiers=<modifiers>

- The mouse event modifiers (optional). The value may be any combination of Shift, Alt and Ctrl separated by the plus '+' sign, e.g. "Ctrl+Alt+Shift".

continue=<number>

- The value of true will not terminate the script if the object is not found. The default value is false (terminate on failure). The command also observes the value of the _MOVETO_CONNECT variable and uses it as the default value. For example, to make all MoveTo commands in a script not terminate the script by default set the variable at the beginning to true ("Var _MOVETO_CONTINUE=true").

step=<step_name>

- Simple integration with the Step command. When specified it creates a test step of the given name with the result of pass (object found and the mouse pointer was moved to it) or fail (object not found).

wait=<time>

- Time to wait after the move gets completed. It has the same effect as if the following command was 'Wait <time_in_ms>'. 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 _MOVETO_WAIT variable with the desired delay, for example "Var _MOVETO_WAIT=1s".

Moveto image template=<image_collection> [passrate=<pass_rate_in_%>]  [<search2_specific_params>] [<common options>]

* Red colour indicates obligatory parameters

SPECIFIC OPTIONS - IMAGE

template=<image_collection>

- An image collection - one or more image file names or folders with images separated by a semicolon (';') to be compared to the remote desktop image. On Linux/Unix make sure the file name doesn't contain semicolon because the list would be incorrectly parsed. File names can be either relative (e.g. img.png) or absolute (e.g. /root/report/img.png). If you use a relative path, the image will be searched in the directory defined by the _TEMPLATE_DIR variable. Supported image formats are subject to the Java version. Java 1.6 supports at least PNG, JPG, GIF and BMP.

Template images will be compared with the remote desktop image in the specified list order. If a template comparison produces a positive result (either match or mismatch depending on the specified event), the condition is considered to be met and the command finishes with an exit code of 0 and skips any remaining templates in the list. Predefined variable _COMPARETO_TEMPLATE_INDEX may be then used to determine the index of the matching template image. See image comparison specific variables for a complete list of supported variables.

passrate=<pass_rate_in%>_

- The pass rate for image comparison. It must be a number between 0 and 100 which may optionally be followed by the percentage character (for example "passrate=95" or "passrate=95%"). If this parameter is omitted the default search2 pass rate of 50% will be used.

search2_specific_params

- Any parameters supported by the search2 comparison method (optional).

Moveto object  [<object_specific_options>]  [<common options>]

SPECIFIC OPTIONS - OBJECT

object_specific_params

- Any parameters supported by the object comparison method (optional). It is typically necessary to specify at least the object colour.

Moveto ocr  [<tocr_specific_options>]  [<common options>]

SPECIFIC OPTIONS - OCR

tocr_specific_options

- Any parameters supported by the tocr comparison method. It is necessary to specify the target text to move to either through the text or pattern options.

RETURNS

The command always returns 0 on success or exits the script on failure returning the error code from the specified comparison method.

EXAMPLES

Moveto image template="google_button.png" number="2"

 - Move to the centre of the second button specified by the google_button.png image on the screen. If the button is not found or the number of buttons on the screen is lower than two the command will fail the script.  

Moveto object tolerance="10" color="255;0;0" max="w:20"

 - Find a red object not wider than 20 pixels and move the mouse pointer to its centre. The tolerance ensures that the method will find more shades of red.

Moveto ocr text="Cancel" distance="1"

 - Read the text on the screen using OCR and move to the first word of "Cancel". The distance ensures that the word will be found even if the OCR engine omits or fails to recognize a single character, for example, "Cencel" etc.