Drag

3.2.7 Drag

DESCRIPTION

Drag is a combination of Waitfor match and Mouse drag commands. It searches the desktop for a source component by an image, by a solid colour or by a text and drags it to a location specified by relative coordinates or to the target component located by another image search. If the object is not found it exits the script.

The command is fairly similar to the Click one.

SYNOPSIS

Drag <comparison_method> [shift=x:<relativeX>,y:<relativeY>]  [template2=<target_component_template>]  [number2=<target_component_number>]  [timeout=<time>]  [cmparea=<[x:<x>][,y:<y>][,w:<width>][,h:<height>]>]  [number=<component_number>]  [btn=<button>]  [modifiers=<modifiers>]  [count=<number>]  [continue=<true|false>]  [step=<step_name>]  [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 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, 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 source component on the screen to apply the drag 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 (drag 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 start mouse press location relatively from the centre of the target object (since 4.2). This allows to start dragging 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 "Drag image template=button.png move=x:-40 shift=x:100,y:100" will start dragging 40 pixels to the left from the button centre.

btn=<button>

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

modifiers=<modifiers>

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

shift=x:<relativeX>,y:<relativeY>

- Relative coordinates specifying where to drag the component to from its current location. The target (drop) location may be alternatively specified through template2.

template2=<target_component_template>

- The drop component. When specified the command performs an image search using search2 for the specified component and drags the object to its location. The number2 parameter may be used to specify the drop component number if there are more than one on the screen. When template2 is specified the shift parameter should not be present. 

number2=<target_component_number>

- Target component ordinary number. 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 (drop at the first located component). If the number of components found on the screen is lower than the specified number the command exits the script. To be used only together with the template2 parameter.

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 _DRAG_CONNECT variable and uses it as the default value. For example, to make all Drag commands in a script not terminate the script by default set the variable at the beginning to true ("Var _DRAG_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 dragged) 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 _DRAG_WAIT variable with the desired delay, for example, "Var _DRAG_WAIT=1s".

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

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

Drag 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

Drag image template="lever.png" shift="x:100"

 - Find the first lever component on the screen and drag it 100 pixels to the right.

Drag image template="column.png" number="2" template2="column.png" number2="3"

 - Example of swapping of two table columns. The command will locate the second column header in the table and drags it onto the third one. If the column is not found or the number of columns on the screen is lower than three the command will fail the script. 

Drag object tolerance="10" color="0;255;0" max="w:20,h:20" shift="x:50,y:-100"

  - Find a green object which is not greater than 20x20 pixels and drag it 50 pixels rightwards and 100 pixels upwards. Tolerance ensures that the method will find more shades of green.

Drag ocr text="Flower" shift="y:220"

 - Read the text on the screen using OCR and drag the word "Flower" 220 pixels to the bottom.