# libcvautomation: libcvautomation-xtest.h File Reference

libcvautomation 1.5

- Main Page
- Related Pages
- Classes
- Files

- File List
- File Members

Defines | Functions
libcvautomation-xtest.h File Reference

The source code to access the XTest extension inside libcvautomation. More...

`#include <libcvautomation/libcvautomation.h>`

Go to the source code of this file.

## Defines

#define | IS_CMD(x, y) strncmp( x, y, strlen( y ) ) == 0
| Checks if string `'x'` is in `'y'`.
#define | COMMAND_STR_LEN 512
| Specifies the maximum length of a command string.

## Functions

Bool | xte_XTestSupported (Display *displayLocation)
| Check if the XTest extension is supported.
cvaPoint | xte_mouseLocation (Display *displayLocation)
| Grab the current location of the mouse.
void | xte_clickMouse (Display *displayLocation, int mouseButton)
| Click the mouse in its current location.
void | xte_clickMouseXY (Display *displayLocation, int xLocation, int yLocation, int mouseButton)
| Click the mouse button at an absolute location.
void | xte_clickMouseRXY (Display *displayLocation, int xIncrement, int yIncrement, int mouseButton)
| Click the mouse button at a relative location.
cvaPoint | xte_clickMouseImage (Display *displayLocation, IplImage *subImage, int mouseButton, int searchMethod, int tolerance)
| Click the mouse based on location of an image.
cvaPoint | xte_clickMouseImage_location (Display *displayLocation, const char *fileName, int mouseButton, int searchMethod, int tolerance)
| Click the mouse based on the location of an image from file.
cvaPoint | xte_clickMouseImage_center (Display *displayLocation, IplImage *subImage, int mouseButton, int searchMethod, int tolerance)
| Click the mouse based on center location of an image.
cvaPoint | xte_clickMouseImage_location_center (Display *displayLocation, const char *fileName, int mouseButton, int searchMethod, int tolerance)
| Click the mouse based on the center location of an image from file.
void | xte_hoverMouseXY (Display *displayLocation, int xLocation, int yLocation)
| Move the mouse to a location, but do not click it.
void | xte_hoverMouseRXY (Display *displayLocation, int xIncrement, int yIncrement)
| Move the mouse to a relative location, but do not click it.
cvaPoint | xte_hoverMouseImage (Display *displayLocation, IplImage *subImage, int searchMethod, int tolerance)
| Move the mouse based on location of an image.
cvaPoint | xte_hoverMouseImage_location (Display *displayLocation, const char *filename, int searchMethod, int tolerance)
| Move the mouse based on location of an image from file.
cvaPoint | xte_hoverMouseImage_center (Display *displayLocation, IplImage *subImage, int searchMethod, int tolerance)
| Move the mouse based on center location of an image.
cvaPoint | xte_hoverMouseImage_location_center (Display *displayLocation, const char *fileName, int searchMethod, int tolerance)
| Move the mouse based on the center location of an image from file.
void | xte_mouseDown (Display *displayLocation, int mouseButton)
| Press a mouse button down, and do not release it.
void | xte_mouseUp (Display *displayLocation, int mouseButton)
| Release a mouse button.
void | xte_mouseJiggle (Display *displayLocation)
| Jiggle the mouse in place.
void | xte_mouseScrollUp (Display *displayLocation)
| Scroll the mouse up.
void | xte_mouseScrollDown (Display *displayLocation)
| Scroll the mouse down.
void | xte_clickKey (Display *displayLocation, char *key)
| Press and release a keyboard key.
void | xte_clickKeyStr (Display *displayLocation, char *string)
| Input a string of characters to the X Server.
void | xte_keyDown (Display *displayLocation, char *key)
| Press a key down, but do not release it.
void | xte_keyUp (Display *displayLocation, char *key)
| Release a key.
cvaPoint | xte_waitForImage (Display *displayLocation, IplImage *subImage, int searchMethod, int tolerance, int timeout)
| Wait for an image to show up on screen.
cvaPoint | xte_waitForImage_location (Display *displayLocation, const char *fileName, int searchMethod, int tolerance, int timeout)
| Wait for an image from file to show up on screen.
cvaPoint | xte_commandString (Display *displayLocation, char *commandString, int mouseButton, int searchMethod, int tolerance, int timeout)
| Execute a command where the command is coming from a string.

## Detailed Description

The source code to access the XTest extension inside libcvautomation.

This source file builds in the necessary functionality to drive the X11 server in libcvautomation

Author:
  Bradlee Speice

Definition in file libcvautomation-xtest.h.

## Define Documentation

#define IS_CMD | ( |  | x,
|  |  | y
| ) |  | strncmp( x, y, strlen( y ) ) == 0

Checks if string `'x'` is in `'y'`.

Performs a safe check to see if x is in y - this way, you can check that `"command"` is inside `"command argument"`

## Function Documentation

Bool xte_XTestSupported | ( | Display * | displayLocation | ) |

Check if the XTest extension is supported.

Parameters:

  displayLocation | The Display to check if XTest is supported on

Returns:
  True if XTest is supported, False otherwise

Warning:
  The program using this library is responsible for checking to see if XTest is supported.

cvaPoint xte_mouseLocation | ( | Display * | displayLocation | ) |

Grab the current location of the mouse.

Parameters:

  displayLocation | The Display of which to grab the mouse location from

Returns:
  cvaPoint with the current location of the mouse

void xte_clickMouse | ( | Display * | displayLocation,
|  | int | mouseButton
| ) |  |

Click the mouse in its current location.

Perform a mouse-down and mouse-up event on button `mouseButton`

Parameters:

  displayLocation | The Display of which to click the mouse on
  mouseButton | The mouse button to click

void xte_clickMouseXY | ( | Display * | displayLocation,
|  | int | xLocation,
|  | int | yLocation,
|  | int | mouseButton
| ) |  |

Click the mouse button at an absolute location.

Move the mouse to location (`xLocation`, `yLocation` ) and then click button `mouseButton`

Parameters:

  displayLocation | The Display of which to click the mouse on
  xLocation | The X-coordinate to move the mouse to before clicking
  yLocation | The Y-location to move the mouse to before clicking
  mouseButton | The mouse button to click

void xte_clickMouseRXY | ( | Display * | displayLocation,
|  | int | xIncrement,
|  | int | yIncrement,
|  | int | mouseButton
| ) |  |

Click the mouse button at a relative location.

Move the mouse horizontally `xIncrement` and vertically `yIncrement` before clicking button `mouseButton`

Parameters:

  displayLocation | The Display of which to click the mouse on
  xIncrement | Move the mouse horizontally this many pixels - positive value is motion to the right
  yIncrement | Move the mouse vertically this many pixels - positive value is motion downwards
  mouseButton | The mouse button to click

cvaPoint xte_clickMouseImage | ( | Display * | displayLocation,
|  | IplImage * | subImage,
|  | int | mouseButton,
|  | int | searchMethod,
|  | int | tolerance
| ) |  |

Click the mouse based on location of an image.

Wraps grabbing the X11 root window of `displayLocation`, finding `subImage` in this display, moving the mouse to that location, and then clicking `mouseButton`. The return value can be ignored, the mouse will already have been clicked there.

Parameters:

  displayLocation | The Display of which to click the mouse on
  subImage | The sub image (in IplImage format) to find in the root X11 window
  mouseButton | The mouse button to click
  searchMethod | The search method to use when searching for `subImage` in the root X11 window
  tolerance | The tolerance to use when searching for `subImage` in the root X11 window

See also:
  Libcv Search Methods

Returns:
  The location of where the mouse was clicked. This will be (-1,-1) if there was an error, in which case the mouse will not have been clicked.

cvaPoint xte_clickMouseImage_location | ( | Display * | displayLocation,
|  | const char * | fileName,
|  | int | mouseButton,
|  | int | searchMethod,
|  | int | tolerance
| ) |  |

Click the mouse based on the location of an image from file.

Wraps grabbing the X11 root window of `displayLocation`, finding the sub image from `fileName` in this display, moving the mouse to that location, and then clicking `mouseButton`. The return value can be ignored, the mouse will already have been clicked there.

Parameters:

  displayLocation | The Display of which to click the mouse on
  fileName | The file name from which to load the sub-image
  mouseButton | The mouse button to click
  searchMethod | The search method to use when searching for the sub image in the root X11 window
  tolerance | The tolerance to use when searching for the sub image in the root X11 window

See also:
  Libcv Search Methods

Returns:
  The location of where the mouse was clicked. This will be (-1,-1) if there was an error, in which case the mouse will not have been clicked.

cvaPoint xte_clickMouseImage_center | ( | Display * | displayLocation,
|  | IplImage * | subImage,
|  | int | mouseButton,
|  | int | searchMethod,
|  | int | tolerance
| ) |  |

Click the mouse based on center location of an image.

Wraps grabbing the X11 root window of `displayLocation`, finding the center of `subImage` in this display, moving the mouse to that location, and then clicking `mouseButton`. The return value can be ignored, the mouse will already have been clicked there.

Parameters:

  displayLocation | The Display of which to click the mouse on
  subImage | The sub image (in IplImage format) to find in the root X11 window
  mouseButton | The mouse button to click
  searchMethod | The search method to use when searching for `subImage` in the root X11 window
  tolerance | The tolerance to use when searching for `subImage` in the root X11 window

See also:
  Libcv Search Methods

Returns:
  The location of where the mouse was clicked. This will be (-1,-1) if there was an error, in which case the mouse will not have been clicked.

cvaPoint xte_clickMouseImage_location_center | ( | Display * | displayLocation,
|  | const char * | fileName,
|  | int | mouseButton,
|  | int | searchMethod,
|  | int | tolerance
| ) |  |

Click the mouse based on the center location of an image from file.

Wraps grabbing the X11 root window of `displayLocation`, finding the center location of the sub image from `fileName` in this display, moving the mouse to that location, and then clicking `mouseButton`. The return value can be ignored, the mouse will already have been clicked there.

Parameters:

  displayLocation | The Display of which to click the mouse on
  fileName | The file name from which to load the sub-image
  mouseButton | The mouse button to click
  searchMethod | The search method to use when searching for the sub image in the root X11 window
  tolerance | The tolerance to use when searching for the sub image in the root X11 window

See also:
  Libcv Search Methods

Returns:
  The location of where the mouse was clicked. This will be (-1,-1) if there was an error, in which case the mouse will not have been clicked.

void xte_hoverMouseXY | ( | Display * | displayLocation,
|  | int | xLocation,
|  | int | yLocation
| ) |  |

Move the mouse to a location, but do not click it.

Parameters:

  displayLocation | The Display of which to move the mouse
  xLocation | The X-coordinate of which to move the mouse
  yLocation | The Y-coordinate of which to move the mouse

void xte_hoverMouseRXY | ( | Display * | displayLocation,
|  | int | xIncrement,
|  | int | yIncrement
| ) |  |

Move the mouse to a relative location, but do not click it.

Parameters:

  displayLocation | The Display of which to move the mouse
  xIncrement | How far to move the mouse horizontally. Positive values indicate motion to the right.
  yIncrement | How far to move the mouse vertically. Positive values indicate motion downward.

cvaPoint xte_hoverMouseImage | ( | Display * | displayLocation,
|  | IplImage * | subImage,
|  | int | searchMethod,
|  | int | tolerance
| ) |  |

Move the mouse based on location of an image.

Wraps grabbing the X11 root window of `displayLocation`, finding `subImage` in this display, and then moving the mouse to that location. The return value can be ignored, the mouse will already have been moved there.

Parameters:

  displayLocation | The Display of which to move the mouse on
  subImage | The sub image (in IplImage format) to find in the root X11 window
  searchMethod | The search method to use when searching for `subImage` in the root X11 window
  tolerance | The tolerance to use when searching for `subImage` in the root X11 window

See also:
  Libcv Search Methods

Returns:
  The location of where the mouse was moved. This will be (-1,-1) if there was an error, in which case the mouse will not have been moved.

cvaPoint xte_hoverMouseImage_location | ( | Display * | displayLocation,
|  | const char * | filename,
|  | int | searchMethod,
|  | int | tolerance
| ) |  |

Move the mouse based on location of an image from file.

Wraps grabbing the X11 root window of `displayLocation`, finding the sub image from `fileName` in this display, and then moving the mouse to that location. The return value can be ignored, the mouse will already have been moved there.

Parameters:

  displayLocation | The Display of which to move the mouse on
  filename | The file name from which to load the sub-image
  searchMethod | The search method to use when searching for the sub image in the root X11 window
  tolerance | The tolerance to use when searching for the sub image in the root X11 window

See also:
  Libcv Search Methods

Returns:
  The location of where the mouse was moved. This will be (-1,-1) if there was an error, in which case the mouse will not have been moved.

cvaPoint xte_hoverMouseImage_center | ( | Display * | displayLocation,
|  | IplImage * | subImage,
|  | int | searchMethod,
|  | int | tolerance
| ) |  |

Move the mouse based on center location of an image.

Wraps grabbing the X11 root window of `displayLocation`, finding the center of `subImage` in this display, and then moving the mouse to that location. The return value can be ignored, the mouse will already have been moved there.

Parameters:

  displayLocation | The Display of which to move the mouse on
  subImage | The sub image (in IplImage format) to find in the root X11 window
  searchMethod | The search method to use when searching for `subImage` in the root X11 window
  tolerance | The tolerance to use when searching for `subImage` in the root X11 window

See also:
  Libcv Search Methods

Returns:
  The location of where the mouse was moved. This will be (-1,-1) if there was an error, in which case the mouse will not have been moved.

cvaPoint xte_hoverMouseImage_location_center | ( | Display * | displayLocation,
|  | const char * | fileName,
|  | int | searchMethod,
|  | int | tolerance
| ) |  |

Move the mouse based on the center location of an image from file.

Wraps grabbing the X11 root window of `displayLocation`, finding the center location of the sub image from `fileName` in this display, and then moving the mouse to that location. The return value can be ignored, the mouse will already have been moved there.

Parameters:

  displayLocation | The Display of which to move the mouse on
  fileName | The file name from which to load the sub-image
  searchMethod | The search method to use when searching for the sub image in the root X11 window
  tolerance | The tolerance to use when searching for the sub image in the root X11 window

See also:
  Libcv Search Methods

Returns:
  The location of where the mouse was moved. This will be (-1,-1) if there was an error, in which case the mouse will not have been moved.

void xte_mouseDown | ( | Display * | displayLocation,
|  | int | mouseButton
| ) |  |

Press a mouse button down, and do not release it.

Parameters:

  displayLocation | The Display of which to push a mouse button down
  mouseButton | The mouse button to push down

void xte_mouseUp | ( | Display * | displayLocation,
|  | int | mouseButton
| ) |  |

Release a mouse button.

Parameters:

  displayLocation | The Display of which to release a mouse button
  mouseButton | The mouse button to release

void xte_mouseJiggle | ( | Display * | displayLocation | ) |

Jiggle the mouse in place.

This moves the mouse down and right one pixel, and then back. This may be needed to activate menu items, etc.

Parameters:

  displayLocation | The Display of which to move the mouse

void xte_mouseScrollUp | ( | Display * | displayLocation | ) |

Scroll the mouse up.

This moves the mouse scroll wheel up one rotation, which may be multiple lines. What this really does is click mouse button 4.

Parameters:

  displayLocation | The Display of which to scroll the mouse

void xte_mouseScrollDown | ( | Display * | displayLocation | ) |

Scroll the mouse down.

This moves the mouse scroll wheel down one rotation, which may be multiple lines. What this really does is click mouse button 5.

Parameters:

  displayLocation | The Display of which to scroll the mouse

void xte_clickKey | ( | Display * | displayLocation,
|  | char * | key
| ) |  |

Press and release a keyboard key.

This method allows you to press and release a key, where the key may be `'a'`, `'b'`, or maybe something fancy like `'space'`. Please see XTest Key Strings for a full list of keys.

Parameters:

  displayLocation | The Display of which to click a key
  key | The key to click as a string

See also:
  XTest Key Strings

void xte_clickKeyStr | ( | Display * | displayLocation,
|  | char * | string
| ) |  |

Input a string of characters to the X Server.

Instead of specifying a single character to enter at a time (`'a'`, `'space'`) this function allows you to enter an entire string (`'Hello`, World!') at a time.

Parameters:

  displayLocation | The Display of which to enter a key string on
  string | The key string to input to the X Server

void xte_keyDown | ( | Display * | displayLocation,
|  | char * | key
| ) |  |

Press a key down, but do not release it.

This method allows you to push down a key, where the key may be `'a'`, `'b'`, or maybe something fancy like `'space'`. Please see XTest Key Strings for a full list of keys.

Parameters:

  displayLocation | The Display of which to push down a key
  key | The key to click as a string

See also:
  XTest Key Strings

void xte_keyUp | ( | Display * | displayLocation,
|  | char * | key
| ) |  |

Release a key.

This method allows you to release a key, where the key may be `'a'`, `'b'`, or maybe something fancy like `'space'`. Please see XTest Key Strings for a full list of keys.

Parameters:

  displayLocation | The Display of which to release a key
  key | The key to click as a string

See also:
  XTest Key Strings

cvaPoint xte_waitForImage | ( | Display * | displayLocation,
|  | IplImage * | subImage,
|  | int | searchMethod,
|  | int | tolerance,
|  | int | timeout
| ) |  |

Wait for an image to show up on screen.

This method allows you to search for an image on screen and wait for it to show up - this way you can make sure an image exists, and then respond to it. Also makes error checking easy.

Parameters:

  displayLocation | The Display of which to search for an image
  subImage | The sub image to search for
  searchMethod | The search method to use when searching for `subImage`
  tolerance | The tolerance to use when searching for `tolerance`
  timeout | The time (in seconds) to search for the image

See also:
  Libcv Search Methods

cvaPoint xte_waitForImage_location | ( | Display * | displayLocation,
|  | const char * | fileName,
|  | int | searchMethod,
|  | int | tolerance,
|  | int | timeout
| ) |  |

Wait for an image from file to show up on screen.

This method allows you to search for an image on screen and wait for it to show up - this way you can make sure an image exists, and then respond to it. Also makes error checking easy.

Parameters:

  displayLocation | The Display of which to search for an image
  fileName | The file to load an image from before searching
  searchMethod | The search method to use when searching for `subImage`
  tolerance | The tolerance to use when searching for `tolerance`
  timeout | The time (in seconds) to search for the image

See also:
  Libcv Search Methods

cvaPoint xte_commandString | ( | Display * | displayLocation,
|  | char * | commandString,
|  | int | mouseButton,
|  | int | searchMethod,
|  | int | tolerance,
|  | int | timeout
| ) |  |

Execute a command where the command is coming from a string.

This function allows you to input a command to libcvautomation from a string. For example, to click a mouse button, you would use the `command` 'mouseclick'. Please note that some `command`s may need arguments to the string, and some may use function arguments. See xte_commandString() Command Strings for a full list of command and arguments

Parameters:

  displayLocation | The Display of which to operate on
  commandString | The command string to execute - limit to COMMAND_STR_LEN characters
  mouseButton | The mouse button to click if it is needed by the command being executed
  searchMethod | The search method to use if it is needed by the command being executed
  tolerance | The tolerance to use if it is needed by the command being executed
  timeout | The time in seconds to wait for an image to be displayed when using the `waitfor` command.

See also:
  xte_commandString() Command Strings
  Libcv Search Methods

All Classes Files Functions Defines