Click

3.2.3 Click

DESCRIPTION

Click is a combination of Waitfor match and Mouse click commands. It searches the desktop for a component image, a solid colour object or a text and clicks it. If the object is not found it exits the script.

SYNOPSIS

Click <comparison_method>  [timeout=<time>]  [cmparea=<[x:<x>][,y:<y>][,w:<width>][,h:<height>]>]  [number=<component_number>]  [btn=<button>]  [modifiers=<modifiers>]  [count=<number>]  [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, T-Plan Robot 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 apply the click 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 click location relatively from the centre of the target object (since 4.2). This allows clicking 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 "Click image template=button.png move=x:-40" will click 40 pixels to the left from the button centre.

btn=<button>

- The mouse button to click. Allowed values are "left", "middle" and "right".

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

count=<number>

- How many times to click. The default value is 1.

continue=<number>

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

step=<step_name>

- Simple integration with the Step command (since 4.2). When specified it creates a test step of the given name with the result of pass (object found and clicked) or fail (object not found).

wait=<time>

- Time to wait after the click. 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 _CLICK_WAIT variable with the desired delay, for example "Var _CLICK_WAIT=1s".

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

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

Click 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 apply the click 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

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

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

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

 - Click an object which is red and its width is not greater than 20 pixels. Tolerance ensures that the method will find more shades of red.

Click ocr text="Cancel" distance="1"

 - Read the text on the screen using OCR and click the word "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, "Cancel" etc.