Namespace to contain all of the features needed to use the libcvautomation_funcs wrapper. More...

Classes
class	LibcvImageNotFound
class	LibcvDisplayNotOpen
Functions
def	open_display
	Open a display for use in the libcvautomation_funcs.
def	close_display
	Close a display currently in use by libcvautomation_funcs.
def	mouse_down
	Press a mouse button down.
def	mouse_up
	Release a mouse button.
def	mouse_click
	Press and release a mouse button.
def	mouse_click_xy
	Click a mouse button at an absolute location.
def	mouse_click_rxy
	Click a mouse button at a relative location.
def	mouse_click_image
	Click a mouse button on an image inside the root X11 window.
def	mouse_doubleclick
	Press and release a mouse button twice.
def	mouse_doubleclick_xy
	Click a mouse button twice at an absolute location.
def	mouse_doubleclick_rxy
	Click a mouse button twice at a relative location.
def	mouse_doubleclick_image
	Click a mouse button twice on an image inside the root X11 window.
def	mouse_hover_xy
	Move the mouse to a given coordinate, and leave it there.
def	mouse_hover_rxy
	Move the mouse by a given increment, and leave it there.
def	mouse_hover_image
	Move the mouse to an image inside the root X11 window.
def	mouse_jiggle
	Jiggle the mouse in place.
def	mouse_scroll_up
	Scroll the mouse wheel up.
def	mouse_scroll_down
	Scroll the mouse wheel down.
def	mouse_drag_n_drop
	Drag and drop one image to another.
def	mouse_location
	Get the current location of the mouse.
def	key_string
	Enter a string of text on the keyboard.
def	key_down
	Press a key down on the keyboard, and leave it down.
def	key_up
	Release a key on the keyboard.
def	key_click
	Press and release a key on the keyboard.
def	image_location
	Get the location of an image on the screen.
def	wait_for
	Get the location of an image on the screen, waiting for it to show up.
def	command_string
	Execute a libcvautomation command based on a string.
Variables
	_use_frame_trace = None
string	outfile = '/dev/null'
	_libcvautomation_error_location = libcvautomation.cvaPoint

Detailed Description

Namespace to contain all of the features needed to use the libcvautomation_funcs wrapper.

libcvautomation_funcs.py

This is a high-level wrapper intended to give you easy access to
libcvautomation, while staying flexible and powerful.
This wrapper was designed to be like the Bash wrapper of the
same name, but allows access to the advanced features of Python - 
for example, error handling.
Also, it becomes easy to integrate other systems like dogtail
into the same application test if you want to combine features.

To use:
import libcvautomation_funcs

If there are any questions, comments, concerns, or suggestions,
notify the developer at <bspeice@uncc.edu>

Function Documentation

def libcvautomation_funcs.open_display ( display_name = '' )

Open a display for use in the libcvautomation_funcs.

This opens a display that will be used for every other function in libcvautomation_funcs.py. If you need to open a different display, use libcvautomation_funcs.close_display() and then open the new display that you want.

Parameters:

display_name The name of the display to open. The default is to open the first available display, which may not specifically be :0.

Warning:: You must use this function to open a display before any other functions can be used.

Returns:: Return True if the display was successfully opened, False otherwise

Definition at line 113 of file libcvautomation_funcs.py.

def libcvautomation_funcs.close_display ( )

Close a display currently in use by libcvautomation_funcs.

This closes the currently open display. All functions used after this will fail unless you open another display. Use libcvautomation_funcs.open_display() to open the new display.

Returns:: None

Definition at line 125 of file libcvautomation_funcs.py.

def libcvautomation_funcs.mouse_down ( mouse_button = _mouse_button_default )

Press a mouse button down.

Parameters:

mouse_button The number of the mouse button to press

Returns:: Return False if the X11 display was not opened before execution, and True otherwise

Definition at line 168 of file libcvautomation_funcs.py.

Referenced by mouse_drag_n_drop().

def libcvautomation_funcs.mouse_up ( mouse_button = _mouse_button_default )

Release a mouse button.

Parameters:

mouse_button The number of the mouse button to release

Returns:: Return False if the X11 display was not opened before execution, and True otherwise

Definition at line 179 of file libcvautomation_funcs.py.

Referenced by mouse_drag_n_drop().

def libcvautomation_funcs.mouse_click ( mouse_button = _mouse_button_default )

Press and release a mouse button.

Parameters:

mouse_button The number of the mouse button to click

Returns:: Return False if the X11 display was not opened before execution, and True otherwise

Definition at line 192 of file libcvautomation_funcs.py.

def libcvautomation_funcs.mouse_click_xy	(	x_coord,
		y_coord,
		mouse_button = `_mouse_button_default`
	)

Click a mouse button at an absolute location.

Move the mouse to a location given by an x and y coordinate before clicking

Parameters:

x_coord	The X-coordinate to move the mouse to
y_coord	The Y-coordinate to move the mouse to
mouse_button	The mouse button to click after moving

Returns:: Return False if the X11 display was not opened before execution, and True otherwise

Definition at line 207 of file libcvautomation_funcs.py.

def libcvautomation_funcs.mouse_click_rxy	(	x_inc,
		y_inc,
		mouse_button = `_mouse_button_default`
	)

Click a mouse button at a relative location.

Move the mouse horizontally and vertically by an increment, and then click the mouse

Parameters:

x_inc The increment to move the mouse horizontally

Note:: A positive increment moves the mouse right, a negative increment moves the mouse left

Parameters:

y_inc The increment to move the mouse vertically

Note:: A positive increment moves the mouse down, a negative increment moves the mouse up

Parameters:

mouse_button The mouse button to click after moving

Returns:: Return False if the X11 display was not opened before execution, and True otherwise

Definition at line 230 of file libcvautomation_funcs.py.

def libcvautomation_funcs.mouse_click_image	(	image_names,
		search_method = `_search_method_default`,
		tolerance = `_tolerance_default`,
		timeout = `_timeout_default`,
		mouse_button = `_mouse_button_default`,
		use_wait = `True`
	)

Click a mouse button on an image inside the root X11 window.

For each image in image_names, search for it inside the root X11 window. Return once a match has been found, or the timeout value has been exceeded

Parameters:

image_names	List of image names to search for
search_method	The search method to use when finding each `image`. See Libcv Search Methods for more information on how to use the search methods.
tolerance	The tolerance to use when finding each `image`. See Libcv Search Methods for more information on how to use tolerance.
timeout	Wait for `timeout` seconds before giving up the search for `image_names` in the root X11 window.

Note:: use_wait must be set to True for this parameter to have any effect

Parameters:

mouse_button	The mouse button to click after finding an image
use_wait	Set to `True` to make this function wait `timeout` seconds before giving up finding an image.

Note:: If set to False, this function will go through the list of image_names once before giving up.

Returns:: Return False if the X11 display was not opened before execution or there were no images found, and True otherwise

Definition at line 252 of file libcvautomation_funcs.py.

def libcvautomation_funcs.mouse_doubleclick ( mouse_button = _mouse_button_default )

Press and release a mouse button twice.

Parameters:

mouse_button The number of the mouse button to click twice

Returns:: Return False if the X11 display was not opened before execution, and True otherwise

Definition at line 302 of file libcvautomation_funcs.py.

def libcvautomation_funcs.mouse_doubleclick_xy	(	x_coord,
		y_coord,
		mouse_button = `_mouse_button_default`
	)

Click a mouse button twice at an absolute location.

Move the mouse to a location given by an x and y coordinate before clicking twice

Parameters:

x_coord	The X-coordinate to move the mouse to
y_coord	The Y-coordinate to move the mouse to
mouse_button	The mouse button to click after moving

Returns:: Return False if the X11 display was not opened before execution, and True otherwise

Definition at line 319 of file libcvautomation_funcs.py.

def libcvautomation_funcs.mouse_doubleclick_rxy	(	x_inc,
		y_inc,
		mouse_button = `_mouse_button_default`
	)

Click a mouse button twice at a relative location.

Move the mouse horizontally and vertically by an increment, and then click the mouse twice

Parameters:

x_inc The increment to move the mouse horizontally

Note:: A positive increment moves the mouse right, a negative increment moves the mouse left

Parameters:

y_inc The increment to move the mouse vertically

Note:: A positive increment moves the mouse down, a negative increment moves the mouse up

Parameters:

mouse_button The mouse button to click after moving

Returns:: Return False if the X11 display was not opened before execution, and True otherwise

Definition at line 343 of file libcvautomation_funcs.py.

def libcvautomation_funcs.mouse_doubleclick_image	(	image_names,
		search_method = `_search_method_default`,
		tolerance = `_tolerance_default`,
		timeout = `_timeout_default`,
		mouse_button = `_mouse_button_default`,
		use_wait = `True`,
		use_center = `True`
	)

Click a mouse button twice on an image inside the root X11 window.

For each image in image_names, search for it inside the root X11 window. Return once a match has been found, or the timeout value has been exceeded

Parameters:

image_names	List of image names to search for
search_method	The search method to use when finding each `image`. See Libcv Search Methods for more information on how to use the search methods.
tolerance	The tolerance to use when finding each `image`. See Libcv Search Methods for more information on how to use tolerance.
timeout	Wait for `timeout` seconds before giving up the search for `image_names` in the root X11 window.

Note:: use_wait must be set to True for this parameter to have any effect

Parameters:

mouse_button	The mouse button to click after finding an image
use_wait	Set to `True` to make this function wait `timeout` seconds before giving up finding an image.
use_center	Set to `True` to make this function return the center coordinate of the matched image. Setting to `False` will use the top-left corner.

Note:: If set to False, this function will go through the list of image_names once before giving up.

Returns:: Return False if the X11 display was not opened before execution or no images were found, and True otherwise

Definition at line 367 of file libcvautomation_funcs.py.

def libcvautomation_funcs.mouse_hover_xy	(	x_coord,
		y_coord
	)

Move the mouse to a given coordinate, and leave it there.

Parameters:

x_coord	The X-coordinate to move the mouse to
y_coord	The Y-coordinate to move the mouse to

Returns:: Return False if the X11 display was not opened before execution, and True otherwise

Definition at line 421 of file libcvautomation_funcs.py.

def libcvautomation_funcs.mouse_hover_rxy	(	x_inc,
		y_inc
	)

Move the mouse by a given increment, and leave it there.

Parameters:

x_inc The increment to move the mouse horizontally

Note:: A positive increment moves the mouse right, a negative increment moves the mouse left

Parameters:

y_inc The increment to move the mouse vertically

Note:: A positive increment moves the mouse down, a negative increment moves the mouse up

Returns:: Return False if the X11 display was not opened before execution, and True otherwise

Definition at line 441 of file libcvautomation_funcs.py.

def libcvautomation_funcs.mouse_hover_image	(	image_names,
		search_method = `_search_method_default`,
		tolerance = `_tolerance_default`,
		timeout = `_timeout_default`,
		use_wait = `True`,
		use_center = `True`
	)

Move the mouse to an image inside the root X11 window.

For each image in image_names, search for it inside the root X11 window. Return once a match has been found, or the timeout value has been exceeded

Parameters:

image_names	List of image names to search for
search_method	The search method to use when finding each `image`. See Libcv Search Methods for more information on how to use the search methods.
tolerance	The tolerance to use when finding each `image`. See Libcv Search Methods for more information on how to use tolerance.
timeout	Wait for `timeout` seconds before giving up the search for `image_names` in the root X11 window.

Note:: use_wait must be set to True for this parameter to have any effect

Parameters:

use_wait Set to True to make this function wait timeout seconds before giving up finding an image.

Note:: If set to False, this function will go through the list of image_names once before giving up.

Parameters:

use_center Set to True to make this function return the center coordinate of the matched image. Setting to False will use the top-left corner.

Returns:: Return False if the X11 display was not opened before execution or no images were found, and True otherwise

Definition at line 462 of file libcvautomation_funcs.py.

Referenced by mouse_drag_n_drop().

def libcvautomation_funcs.mouse_jiggle ( )

Jiggle the mouse in place.

Move the mouse right and down 1 pixel, and back. Useful for activating menu entries, etc.

Returns:

Return False if the X11 display was not opened before execution, and True otherwise

Jiggle the mouse in place

Definition at line 511 of file libcvautomation_funcs.py.

def libcvautomation_funcs.mouse_scroll_up ( )

Scroll the mouse wheel up.

This is the same as pressing mouse button 4

Returns:: Return False if the X11 display was not opened before execution, and True otherwise

Definition at line 524 of file libcvautomation_funcs.py.

def libcvautomation_funcs.mouse_scroll_down ( )

Scroll the mouse wheel down.

This is the same as pressing mouse button 5

Returns:: Return False if the X11 display was not opened before execution, and True otherwise

Definition at line 536 of file libcvautomation_funcs.py.

def libcvautomation_funcs.mouse_drag_n_drop	(	drag_image,
		drag_to,
		use_center = `True`
	)

Drag and drop one image to another.

Parameters:

drag_image	The image to drag from
drag_to	The image giving the location to drag to
use_center	Drag and drop the image using the center of the image as the location where the mouse will click and drag to

Returns:: Return False if the X11 display was not opened before execution or an image was not found, and True otherwise

Definition at line 550 of file libcvautomation_funcs.py.

References mouse_down(), mouse_hover_image(), and mouse_up().

def libcvautomation_funcs.mouse_location ( )

Get the current location of the mouse.

This function will return the current location of the mouse as two variables - i.e. `x, y = mouse_location()`. This is a Python-specific function.

Returns:: Two variables for the x and y locations

Definition at line 574 of file libcvautomation_funcs.py.

def libcvautomation_funcs.key_string ( string )

Enter a string of text on the keyboard.

This function will simulate pressing the keys exactly as they are entered - unlike libcvautomation_funcs::key_down, libcvautomation_funcs::key_up, and libcvautomation_funcs::key_click, this function will display exactly what you entered: A string of '!' will produce a ! as a keypress.

Parameters:

string The string of text to enter on the keyboard

Returns:: Return False if the X11 display was not opened before execution, and True otherwise

Definition at line 587 of file libcvautomation_funcs.py.

def libcvautomation_funcs.key_down ( key_name )

Press a key down on the keyboard, and leave it down.

Parameters:

key_name The name of the key to press down. Unlike libcvautomation_funcs::key_string, this command will press a single key corresponding to the string you give it - for example, 'a', 'b', or something fancy like 'space'.

Note:: See XTest Key Strings for a full list of accepted key strings.

Returns:: Return False if the X11 display was not opened before execution, and True otherwise

Definition at line 600 of file libcvautomation_funcs.py.

def libcvautomation_funcs.key_up ( key_name )

Release a key on the keyboard.

Parameters:

key_name The name of the key to release. Unlike libcvautomation_funcs::key_string, this command will press a single key corresponding to the string you give it - for example, 'a', 'b', or something fancy like 'space'.

Note:: See XTest Key Strings for a full list of accepted key strings.

Returns:: Return False if the X11 display was not opened before execution, and True otherwise

Definition at line 613 of file libcvautomation_funcs.py.

def libcvautomation_funcs.key_click ( key_name )

Press and release a key on the keyboard.

Parameters:

key_name The name of the key to click. Unlike libcvautomation_funcs::key_string, this command will press a single key corresponding to the string you give it - for example, 'a', 'b', or something fancy like 'space'.

Note:: See XTest Key Strings for a full list of accepted key strings.

Returns:: Return False if the X11 display was not opened before execution, and True otherwise

Definition at line 626 of file libcvautomation_funcs.py.

def libcvautomation_funcs.image_location	(	image_names,
		search_method = `_search_method_default`,
		tolerance = `_tolerance_default`,
		use_center = `True`
	)

Get the location of an image on the screen.

Parameters:

image_names	List of image names to search for in the root X11 window
search_method	The search method to use when matching images. See Libcv Search Methods for more information on using the `search_method` parameter
tolerance	The tolerance to use when matching images. See Libcv Search Methods for more informatino on using the `tolerance` parameter
use_center	Set to `True` to return the center coordinate of an image. Set to `False` to use the top-left corner of an image

Warning:: Unlike libcvautomation_funcs::wait_for(), this method will not wait for an image to show up before looking for it.

Returns:: A dictionary pairing each image name with a cvaPoint class indicating the location it was found at (a point of (-1, -1) indicates the image was not found), or an empty dictionary if the X11 display was not opened before execution.

Definition at line 642 of file libcvautomation_funcs.py.

def libcvautomation_funcs.wait_for	(	image_names,
		search_method = `_search_method_default`,
		tolerance = `_tolerance_default`,
		timeout = `_timeout_default`,
		use_center = `True`
	)

Get the location of an image on the screen, waiting for it to show up.

Parameters:

image_names	List of image names to search for in the root X11 window
search_method	The search method to use when matching images. See Libcv Search Methods for more information on using the `search_method` parameter
tolerance	The tolerance to use when matching images. See Libcv Search Methods for more informatino on using the `tolerance` parameter
timeout	The time (in seconds) to wait when searching for an image on the root X11 window
use_center	Set to `True` to return the center coordinate of an image. Set to `False` to use the top-left corner of an image

Returns:: A dictionary pairing each image name with a cvaPoint class indicating the location it was found at (a point of (-1, -1) indicates the image was not found), or an empty dictionary if the X11 display was not opened before execution.

Definition at line 670 of file libcvautomation_funcs.py.

def libcvautomation_funcs.command_string	(	string,
		mouse_button = `_mouse_button_default`,
		search_method = `_search_method_default`,
		tolerance = `_tolerance_default`,
		timeout = `_timeout_default`
	)

Execute a libcvautomation command based on a string.

This is a handler for the xte_commandString() function.

Note:: Not all commands need all the parameters specified. See xte_commandString() Command Strings for more information on how to use this function.

Parameters:

string	The command string to execute
mouse_button	The mouse button to click, if applicable
search_method	The search method to use, if applicable. See Libcv Search Methods for more information on how to use the `search_method` parameter
tolerance	The tolerance to use, if applicable. See Libcv Search Methods for more information on how to use the `tolerance` parameter
timeout	The timeout (in seconds) to use, if applicable

Returns:: A cvaPoint class with the following points:
(0, 0) or up indicates a success.
(-1, -1) indicates either the command was not successful, or that the command was not recognized.
(-2, -2) indicates that the command did not need to return anything - For example, commands like Mouse Jiggle don't normally return a value.

Definition at line 701 of file libcvautomation_funcs.py.

Classes

Functions

Variables

Detailed Description

Function Documentation