# libcvautomation: Appendix of Wrapper Functions and Environment Variables

libcvautomation 1.5

- Main Page
- Related Pages
- Classes
- Files

Appendix of Wrapper Functions and Environment Variables

## Environment Variables

### Search Method

     SEARCH_METHOD

This controls how each of the functions searches for an image. See Libcv Search Methods for more instruction on how to use this option.

### Tolerance

     TOLERANCE
     USE_SANE_TOLERANCE

These control how tolerant each function is when searching for an image. Acceptable values are anywhere between `INT_MIN` to `INT_MAX`. See Libcv Search Methods for more information on how the tolerance values work. Additionally, the cva-input and cva-match programs (which this wrapper depends on) implement a "sane-tolerance" option. This allows you to set a tolerance between 1 - 100, where: \( 1 \approx 0 \), and \( 100 \approx INT\_MAX \) By default, functions will not use sane tolerance. To make the functions search using sane tolerance, set

     USE_SANE_TOLERANCE="yes"

### Center

     USE_CENTER

This controls whether each function will return a value based on the center of the sub-image, rather than the top-left corner. By default, functions will use center-based matching. To make the functions use the top-left corner, set

     USE_CENTER=""

### Wait

     USE_WAIT
     TIMEOUT

These control how the "waitfor" function is used. By default, all image-matching functions will wait for an image to appear, and then click on it. This way, it won't click randomly if it can or can't find an image, and provides very easy error recognition. The functions will wait for a period of `TIMEOUT` seconds before complaining. To disable waiting before performing an action, set

     USE_WAIT=""

Warning:
  Without setting a tolerance value, the waitfor function becomes totally useless, as the first search will always find an image. `Make sure to set the tolerance` (or just leave it as the default value in the wrapper).

### Output and Debugging

     OUTFILE
     ERRFILE

These files control the reporting of libcvautomation_funcs. The wrapper generates a decent amount of output to help in debugging application tests, and by default these get redirected to /dev/null. To instead redirect them to a file, you can do something like this:

     OUTFILE=`mktemp`; echo "Logfile: " $OUTFILE
     ERRFILE=`mktemp`; echo "Error file: " $ERR_FILE

This will redirect the output and error output to a file you own, and inform you of what that file is.

## Functions

### Click the mouse

     mousedown [mouse-button]

Push the mouse button down where it is currently located, and leave it down. Optionally specify a mouse button to push down

     mouseup [mouse-button]

     click [mouse-button]

Release the mouse button Optionally specify a mouse button to release

     click_xy <x-coordinate> <y-coordinate> [mouse-button]

Click the mouse on an absolute point on screen Optionally specify a mouse button to click

Note:
  The actual process is to move the mouse to the given location, then click there.

     clickr_xy <x-increment> <y-increment> [mouse-button]

Click the mouse on the screen relative to where the mouse is at Optionally specify a mouse button to click

Note:
  The actual process is to move the mouse the given distance, then click there.
  Also, note that a positive `x-increment` moves the mouse to the right, and a positive `y-increment` moves the mouse down.

     click_i <filename> [filename-2] ... [filename-n]

Click the mouse on a screenshot from `filename` Optionally specify multiple files to search in.

Note:
  This is affected by the `CENTER`, `TOLERANCE`, and `SEARCH_METHOD` variables. See Environment Variables for more information on these.

     doubleclick [mouse-button]

Click the mouse twice Optionally specify a mouse button to click

     doubleclick_xy [mouse-button]

Click the mouse twice on an absolute point on screen Optionally specify a mouse button to click

Note:
  The actual process is to move the mouse to the given location, then click there.

     doubleclick_i <filename> [filename-2] ... [filename-n]

Click the mouse twice on a screenshot from `filename` Optionally specify multiple files to search in.

Note:
  This is affected by the `CENTER`, `TOLERANCE`, and `SEARCH_METHOD` variables. See Environment Variables for more information on these.

### Move the mouse

     hover_xy <x-coordinate> <y-increment>

Move the mouse to a location on screen using absolute positioning

     hoverr_xy <x-increment> <y-increment>

Move the mouse to a location on screen using relative positioning

Note:
  Note that a positive `x-increment` moves the mouse to the right, and a positive `y-increment` moves the mouse down.

     hover_i <filename> [filename-2] ... [filename-n]

Move the mouse to a location on screen based on screenshot Optionally specify multiple files to search in.

Note:
  This is affected by the `CENTER`, `TOLERANCE`, and `SEARCH_METHOD` variables. See Environment Variables for more information on these.

     jiggle_mouse

Very simple wrapper to move the mouse 1 pixel right and 1 pixel down - useful for activating menu items.

     mouse_scrollu

Scroll the mouse wheel up one

     mouse_scrolld

Scroll the mouse wheel down one

     dragndrop

Drag one image to another - i.e. drag a file to a folder.

Warning:
  This function accepts only two arguments unlike other image functions - the first argument is the image to drag, the second is the image to drag to.

### Find an Image

     image_location <filename>

Get the location of an image on screen

Note:
  This is affected by the `CENTER`, `TOLERANCE`, and `SEARCH_METHOD` variables. See Environment Variables for more information on these.

     waitfor <filename>

Wait for an image to display on screen, and then return

Note:
  This is affected by the `TOLERANCE`, `SEARCH_METHOD`, and `TIMEOUT` variables. See Environment Variables for more information on these.

### Click the keyboard

     key_str "<string>"

Enter a string of characters on the keyboard rather than a single character at a time.

Warning:
  This function does not accept key strings like "Space" as `key_down`, `key_up`, and `key_click` do. If you pass in "Space", that is exactly what will be typed.

     key_down "<key-name>"

Press a key down and leave it down

Note:
  This function accepts special keys like "Space" - see XTest Key Strings for a full list of characters allowed.

     key_up "<key-name>"

Release a key

Note:
  This function accepts special keys like "Space" - see XTest Key Strings for a full list of characters allowed.

     key_click "<key-name>"

Press a key down and then release it immediately after

Note:
  This function accepts special keys like "Space" - see XTest Key Strings for a full list of characters allowed.

### Useful extras

     run_process "<process-name>"

Start a process on the system, background it, and return the PID of the created process.

     is_running "<process-name>"

     is_running "<process-id>"

Check if a program name or PID is currently running

     notify "<string_to_display>"

Display a notification to the user, and wait for a response

Warning:
  Uses `zenity` - if `zenity` isn't available, will return an error without pausing, and will not display anything.

All Classes Files Functions Defines