diff --git a/python/libcvautomation_funcs.py b/python/libcvautomation_funcs.py index 32528d2..f9f9dee 100644 --- a/python/libcvautomation_funcs.py +++ b/python/libcvautomation_funcs.py @@ -15,6 +15,14 @@ import libcvautomation_funcs If there are any questions, comments, concerns, or suggestions, notify the developer at """ +## \file libcvautomation_funcs.py +# \brief Libcvautomation wrapper for python +# \details This source file is designed to give high-level access to libcvautomation using Python. It was modeled after the Bash wrapper, but allows for access to all the extra features of Python. +# \author Bradlee Speice + +## \package libcvautomation_funcs +# \brief Namespace to contain all of the features needed to use the libcvautomation_funcs wrapper + #------------------------------------------------------------------------------- # Import the libcvautomation library - this should have already been installed #------------------------------------------------------------------------------- @@ -23,10 +31,11 @@ import libcvautomation #------------------------------------------------------------------------------- # Set up the logging options #------------------------------------------------------------------------------- + from sys import _current_frames() #For getting the function that called us import time -def get_caller(): +def _get_caller(): current_frame = sys._current_frames().values()[0] #Current frame caller_frame = current_frame.f_back.f_back #Go back two frames to make sure #we don't get the name of the function that just called us. @@ -35,7 +44,7 @@ def get_caller(): return caller_name outfile = '/dev/null' -def out( message ): +def _log_output( message ): global outfile #Make sure we use the global outfile, #that people can change it if need be @@ -59,7 +68,7 @@ def out( message ): X11_display=None #NULL -def check_display(): +def _check_display(): global X11_display if X11_display is None: @@ -68,7 +77,7 @@ def check_display(): else: return True -def get_display(): #Intended to be unsafe (and a bit faster)- +def _get_display(): #Intended to be unsafe (and a bit faster)- #all wrapper functions should use check_display() explicitly global X11_display return X11_display @@ -76,7 +85,12 @@ def get_display(): #Intended to be unsafe (and a bit faster)- #------------------------------------------------------------------------------- # The following two functions are intended to be used on the front-end #------------------------------------------------------------------------------- - + +## \brief Open a display for use in the libcvautomation_funcs +# \details 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 \ref libcvautomation_funcs::close_display() and then open the new display that you want. +# \param display_name The name of the display to open. The default is to open the first available display, which may not specifically be \c :0. +# \warning You \em must use this function to open a display before any other functions can be used. +# \returns Return \c True if the display was successfully opened, \c False otherwise def open_display( display_name='' ): global X11_display X11_display = libcvautomation.cvaOpenDisplay( display_name ) @@ -86,6 +100,9 @@ def open_display( display_name='' ): else: return False +## \brief Close a display currently in use by libcvautomation_funcs +# \details This closes the currently open display. All functions used after this will fail unless you open another display. Use \ref libcvautomation_funcs::open_display() to open the new display. +# \returns Nothing def close_display(): global X11_display if X11_display is None: @@ -111,20 +128,24 @@ _libcvautomation_error_location.x = _libcvautomation_error_location.y = -1 # Begin the actual wrapper functions #------------------------------------------------------------------------------- +## \brief Press a mouse button down +# \param mouse_button The number of the mouse button to press +# \returns Return \c False if the X11 display was not opened before execution, and \c True otherwise def mouse_down( mouse_button = _mouse_button_default ): - """Press a mouse button down, and leave it down.""" - if check_display(): - out( 'Mouse button down: ' + mouse_button ) + if _check_display(): + _log_output( 'Mouse button down: ' + mouse_button ) libcvautomation.xte_mouseDown( get_display(), mouse_button ) return True else: #Display not open return False +## \brief Release a mouse button +# \param mouse_button The number of the mouse button to release +# \returns Return \c False if the X11 display was not opened before execution, and \c True otherwise def mouse_up( mouse_button = _mouse_button_default ): - """Release a mouse button.""" - if check_display(): - out( 'Mouse button up: ' + mouse_button ) + if _check_display(): + _log_output( 'Mouse button up: ' + mouse_button ) libcvautomation.xte_mouseUp( get_display(), mouse_button ) return True @@ -132,21 +153,28 @@ def mouse_up( mouse_button = _mouse_button_default ): #Display not open return False +## \brief Press and release a mouse button +# \param mouse_button The number of the mouse button to click +# \returns Return \c False if the X11 display was not opened before execution, and \c True otherwise def mouse_click( mouse_button = _mouse_button_default ): key_click "Return" - """Click a mouse button where the mouse is currently located""" - if check_display() - out( 'Mouse button click: ' + mouse_button ) + if _check_display() + _log_output( 'Mouse button click: ' + mouse_button ) libcvautomation.xte_clickMouse( get_display(), mouse_button ) return True else: #Display not open return False +## \brief Click a mouse button at an absolute location +# \details Move the mouse to a location given by an x and y coordinate before clicking +# \param x_coord The X-coordinate to move the mouse to +# \param y_coord The Y-coordinate to move the mouse to +# \param mouse_button The mouse button to click after moving +# \returns Return \c False if the X11 display was not opened before execution, and \c True otherwise def mouse_click_xy( x_coord, y_coord, mouse_button = _mouse_button_default ): - """Click a mouse button at an absolute coordinate""" - if check_display(): - out( 'Mouse button xy click: x=' + str(x_coord) + ' y=' + str(y_coord) + ' mouse_button=' + mouse_button ) + if _check_display(): + _log_output( 'Mouse button xy click: x=' + str(x_coord) + ' y=' + str(y_coord) + ' mouse_button=' + mouse_button ) current_location = libcvautomation.xte_mouseLocation( get_display() ) x_increment = x_coord - current_location.x y_increment = y_coord - current_location.y @@ -159,10 +187,17 @@ def mouse_click_xy( x_coord, y_coord, mouse_button = _mouse_button_default ): #Display not open return False +## \brief Click a mouse button at a relative location +# \details Move the mouse horizontally and vertically by an increment, and then click the mouse +# \param x_inc The increment to move the mouse horizontally +# \note A positive increment moves the mouse right, a negative increment moves the mouse left +# \param y_inc The increment to move the mouse vertically +# \note A positive increment moves the mouse down, a negative increment moves the mouse up +# \param mouse_button The mouse button to click after moving +# \returns Return \c False if the X11 display was not opened before execution, and \c True otherwise def mouse_click_rxy( x_inc, y_inc, mouse_button = _mouse_button_default ): - """Click a mouse button at a location relative to where it currently is at""" - if check_display(): - out( 'Mouse button rxy click: x=' + str(x_inc) + ' y=' + str(y_inc) + ' mouse_button=' + mouse_button ) + if _check_display(): + _log_output( 'Mouse button rxy click: x=' + str(x_inc) + ' y=' + str(y_inc) + ' mouse_button=' + mouse_button ) libcvautomation.xte_hoverMouseRXY( get_display(), x_inc, y_inc ) libcvautomation.xte_clickMouse( get_display(), mouse_button ) @@ -171,13 +206,22 @@ def mouse_click_rxy( x_inc, y_inc, mouse_button = _mouse_button_default ): #Display not open return False +## \brief Click a mouse button on an image inside the root X11 window +# \details For each image in \c image_names, search for it inside the root X11 window. Return once a match has been found, or the timeout value has been exceeded +# \param image_names List of image names to search for +# \param search_method The search method to use when finding each \c image. See \ref libcvautomation_search_methods for more information on how to use the search methods. +# \param tolerance The tolerance to use when finding each \c image. See \ref libcvautomation_search_methods for more information on how to use tolerance. +# \param timeout Wait for \c timeout seconds before giving up the search for \c image_names in the root X11 window. +# \note \c use_wait must be set to \c True for this parameter to have any effect +# \param mouse_button The mouse button to click after finding an image +# \param use_wait Set to \c True to make this function wait \c timeout seconds before giving up finding an image. +# \note If set to \c False, this function will go through the list of \c image_names once before giving up. +# \returns Return \c False if the X11 display was not opened before execution or there were no images found, and \c True otherwise def mouse_click_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 on an image inside the root X11 window""" - if check_display(): - out( 'Mouse button click on image: Images=' + image_names + + mouse_button = _mouse_button_default, use_wait = True): + if _check_display(): + _log_output( 'Mouse button click on image: Images=' + image_names + ' search_method=' + search_method + ' tolerance=' + tolerance + ' timeout=' + _timeout_default + ' mouse_button=' + ' use_wait=' + use_wait + ' use_center=' + use_center) @@ -217,10 +261,12 @@ def mouse_click_image( [image_names], search_method = _search_method_default, return False +## \brief Press and release a mouse button twice +# \param mouse_button The number of the mouse button to click twice +# \returns Return \c False if the X11 display was not opened before execution, and \c True otherwise def mouse_doubleclick( mouse_button = _mouse_button_default ): - """Click a mouse button twice where the mouse is currently located""" - if check_display() - out( 'Mouse button doubleclick: ' + mouse_button ) + if _check_display() + _log_output( 'Mouse button doubleclick: ' + mouse_button ) libcvautomation.xte_clickMouse( get_display(), mouse_button ) return True @@ -229,10 +275,15 @@ def mouse_doubleclick( mouse_button = _mouse_button_default ): return False +## \brief Click a mouse button twice at an absolute location +# \details Move the mouse to a location given by an x and y coordinate before clicking twice +# \param x_coord The X-coordinate to move the mouse to +# \param y_coord The Y-coordinate to move the mouse to +# \param mouse_button The mouse button to click after moving +# \returns Return \c False if the X11 display was not opened before execution, and \c True otherwise def mouse_doubleclick_xy( x_coord, y_coord, mouse_button = _mouse_button_default ): - """Click a mouse button twice at an absolute coordinate""" - if check_display(): - out( 'Mouse button xy doubleclick: x=' + str(x_coord) + ' y=' + str(y_coord) + ' mouse_button=' + mouse_button ) + if _check_display(): + _log_output( 'Mouse button xy doubleclick: x=' + str(x_coord) + ' y=' + str(y_coord) + ' mouse_button=' + mouse_button ) current_location = libcvautomation.xte_mouseLocation( get_display() ) x_increment = x_coord - current_location.x y_increment = y_coord - current_location.y @@ -246,10 +297,17 @@ def mouse_doubleclick_xy( x_coord, y_coord, mouse_button = _mouse_button_default #Display not open return False +## \brief Click a mouse button twice at a relative location +# \details Move the mouse horizontally and vertically by an increment, and then click the mouse twice +# \param x_inc The increment to move the mouse horizontally +# \note A positive increment moves the mouse right, a negative increment moves the mouse left +# \param y_inc The increment to move the mouse vertically +# \note A positive increment moves the mouse down, a negative increment moves the mouse up +# \param mouse_button The mouse button to click after moving +# \returns Return \c False if the X11 display was not opened before execution, and \c True otherwise def mouse_doubleclick_rxy( x_inc, y_inc, mouse_button = _mouse_button_default ): - """Click a mouse button twice at a location relative to where it currently is at""" - if check_display(): - out( 'Mouse button relative xy doubleclick: x=' + str(x_inc) + ' y=' + str(y_inc) + ' mouse_button=' + mouse_button ) + if _check_display(): + _log_output( 'Mouse button relative xy doubleclick: x=' + str(x_inc) + ' y=' + str(y_inc) + ' mouse_button=' + mouse_button ) libcvautomation.xte_hoverMouseRXY( get_display(), x_inc, y_inc ) libcvautomation.xte_clickMouse( get_display(), mouse_button ) libcvautomation.xte_clickMouse( get_display(), mouse_button ) @@ -259,13 +317,23 @@ def mouse_doubleclick_rxy( x_inc, y_inc, mouse_button = _mouse_button_default ): #Display not open return False +## \brief Click a mouse button twice on an image inside the root X11 window +# \details For each image in \c image_names, search for it inside the root X11 window. Return once a match has been found, or the timeout value has been exceeded +# \param image_names List of image names to search for +# \param search_method The search method to use when finding each \c image. See \ref libcvautomation_search_methods for more information on how to use the search methods. +# \param tolerance The tolerance to use when finding each \c image. See \ref libcvautomation_search_methods for more information on how to use tolerance. +# \param timeout Wait for \c timeout seconds before giving up the search for \c image_names in the root X11 window. +# \note \c use_wait must be set to \c True for this parameter to have any effect +# \param mouse_button The mouse button to click after finding an image +# \param use_wait Set to \c True to make this function wait \c timeout seconds before giving up finding an image. +# \note If set to \c False, this function will go through the list of \c image_names once before giving up. +# \returns Return \c False if the X11 display was not opened before execution or no images were found, and \c True otherwise def 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""" - if check_display(): - out( 'Mouse button doubleclick on image: Images=' + image_names + + if _check_display(): + _log_output( 'Mouse button doubleclick on image: Images=' + image_names + ' search_method=' + search_method + ' tolerance=' + tolerance + ' timeout=' + _timeout_default + ' mouse_button=' + ' use_wait=' + use_wait + ' use_center=' + use_center) @@ -309,10 +377,13 @@ def mouse_doubleclick_image( [image_names], search_method = _search_method_defau #Display not open, or no image found return False +## \brief Move the mouse to a given coordinate, and leave it there +# \param x_coord The X-coordinate to move the mouse to +# \param y_coord The Y-coordinate to move the mouse to +# \returns Return \c False if the X11 display was not opened before execution, and \c True otherwise def mouse_hover_xy( x_coord, y_coord ): - """Move the mouse to an absolute coordinate""" - if check_display(): - out( 'Mouse button hover xy: x=' + str(x_coord) + ' y=' + str(y_coord) + ' mouse_button=' + mouse_button ) + if _check_display(): + _log_output( 'Mouse button hover xy: x=' + str(x_coord) + ' y=' + str(y_coord) + ' mouse_button=' + mouse_button ) current_location = libcvautomation.xte_mouseLocation( get_display() ) x_increment = x_coord - current_location.x y_increment = y_coord - current_location.y @@ -324,11 +395,16 @@ def mouse_hover_xy( x_coord, y_coord ): #Display not open return False - +## \brief Move the mouse by a given increment, and leave it there +# \param x_inc The increment to move the mouse horizontally +# \note A positive increment moves the mouse right, a negative increment moves the mouse left +# \param y_inc The increment to move the mouse vertically +# \note A positive increment moves the mouse down, a negative increment moves the mouse up +# \param mouse_button The mouse button to click after moving +# \returns Return \c False if the X11 display was not opened before execution, and \c True otherwise def mouse_hover_rxy( x_inc, y_inc ): - """Move the mouse to a location relative to where it currently is at""" - if check_display(): - out( 'Mouse button hover relative xy: x=': + str(x_inc) + ' y=' + str(y_inc) ) + if _check_display(): + _log_output( 'Mouse button hover relative xy: x=': + str(x_inc) + ' y=' + str(y_inc) ) libcvautomation.xte_hoverMouseRXY( get_display(), x_inc, y_inc ) return True @@ -336,16 +412,24 @@ def mouse_hover_rxy( x_inc, y_inc ): #Display not open return False +## \brief Move the mouse to an image inside the root X11 window +# \details For each image in \c image_names, search for it inside the root X11 window. Return once a match has been found, or the timeout value has been exceeded +# \param image_names List of image names to search for +# \param search_method The search method to use when finding each \c image. See \ref libcvautomation_search_methods for more information on how to use the search methods. +# \param tolerance The tolerance to use when finding each \c image. See \ref libcvautomation_search_methods for more information on how to use tolerance. +# \param timeout Wait for \c timeout seconds before giving up the search for \c image_names in the root X11 window. +# \note \c use_wait must be set to \c True for this parameter to have any effect +# \param use_wait Set to \c True to make this function wait \c timeout seconds before giving up finding an image. +# \note If set to \c False, this function will go through the list of \c image_names once before giving up. +# \returns Return \c False if the X11 display was not opened before execution or no images were found, and \c True otherwise def mouse_hover_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 ): - """Move the mouse to an image inside the root X11 window""" - if check_display(): - out( 'Mouse button click on image: Images=' + image_names + + use_wait = True, use_center = True ): + if _check_display(): + _log_output( 'Mouse button click on image: Images=' + image_names + ' search_method=' + search_method + ' tolerance=' + tolerance + - ' timeout=' + _timeout_default + ' mouse_button=' + - ' use_wait=' + use_wait + ' use_center=' + use_center) + ' timeout=' + _timeout_default + ' use_wait=' + use_wait + + ' use_center=' + use_center) if use_wait: #Loop through all images 'timeout' times, and click on the first match @@ -381,44 +465,53 @@ def mouse_hover_image( [image_names], search_method = _search_method_default, #Display not open or no image found return False - +## \brief Jiggle the mouse in place +# \details Move the mouse right and down 1 pixel, and back. Useful for activating menu entries, etc. +# \returns Return \c False if the X11 display was not opened before execution, and \c True otherwise def mouse_jiggle(): """Jiggle the mouse in place""" - if check_display(): - out( 'Mouse button jiggle' ) + if _check_display(): + _log_output( 'Mouse button jiggle' ) libcvautomation.xte_mouseJiggle( get_display() ) return True else: #Display not open return False - +## \brief Scroll the mouse wheel up +# \details This is the same as pressing mouse button 4 +# \returns Return \c False if the X11 display was not opened before execution, and \c True otherwise def mouse_scroll_up(): - """Scroll the mouse wheel up""" - if check_display(): - out( 'Mouse scroll up' ) + if _check_display(): + _log_output( 'Mouse scroll up' ) libcvautomation.xte_mouseScrollUp( get_display() ) return True else: #Display not open return False +## \brief Scroll the mouse wheel down +# \details This is the same as pressing mouse button 5 +# \returns Return \c False if the X11 display was not opened before execution, and \c True otherwise def mouse_scroll_down(): - """Scroll the mouse wheel down""" - if check_display(): - out( 'Mouse scroll down' ) + if _check_display(): + _log_output( 'Mouse scroll down' ) libcvautomation.xte_mouseScrollDown( get_display() ) return True else: #Display not open return False -def mouse_drag_n_drop( drag_image, drag_to ): - """Drag and drop from one location to another""" - if check_display(): - out( 'Mouse drag and drop: dragging from=' + drag_image + +## \brief Drag and drop one image to another +# \param drag_image The image to drag from +# \param drag_to The image giving the location to drag to +# \param 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 \c False if the X11 display was not opened before execution or an image was not found, and \c True otherwise +def mouse_drag_n_drop( drag_image, drag_to, use_center = True ): + if _check_display(): + _log_output( 'Mouse drag and drop: dragging from=' + drag_image + ' dragging to=' + drag_to ) - successful_hover = mouse_hover_image( drag_image ) + successful_hover = mouse_hover_image( drag_image, use_center=use_center ) if successful_hover: mouse_down( mouse_button=1 ) successful_hover = mouse_hover_image( drag_to ) @@ -430,54 +523,70 @@ def mouse_drag_n_drop( drag_image, drag_to ): #Display not open return False - +## \brief Enter a string of text on the keyboard +# \details 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 \c '!' will produce a \c ! as a keypress. +# \param string The string of text to enter on the keyboard +# \returns Return \c False if the X11 display was not opened before execution, and \c True otherwise def key_string( string ): - """Enter a string of text on the keyboard""" - if check_display(): - out( 'Key string enter: string=' + string ) + if _check_display(): + _log_output( 'Key string enter: string=' + string ) libcvautomation.xte_clickKeyStr( get_display(), string ) return True else: #Display not open return False - +## \brief Press a key down on the keyboard, and leave it down +# \param 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, \c 'a', \c 'b', or something fancy like \c 'space'. +# \note See \ref xtest_key_strings for a full list of accepted key strings. +# \returns Return \c False if the X11 display was not opened before execution, and \c True otherwise def key_down( key_name ): - """Press a key down on the keyboard""" - if check_display(): - out( 'Key button down: key_name=' + key_name ) + if _check_display(): + _log_output( 'Key button down: key_name=' + key_name ) libcvautomation.xte_keyDown( get_display(), key_name ) return True else: #Display not open return False +## \brief Release a key on the keyboard +# \param 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, \c 'a', \c 'b', or something fancy like \c 'space'. +# \note See \ref xtest_key_strings for a full list of accepted key strings. +# \returns Return \c False if the X11 display was not opened before execution, and \c True otherwise def key_up( key_name ): - """Press a key down on the keyboard""" - if check_display(): - out( 'Key button up: key_name=' + key_name ) + if _check_display(): + _log_output( 'Key button up: key_name=' + key_name ) libcvautomation.xte_keyUp( get_display(), key_name ) return True else: #Display not open return False +## \brief Press and release a key on the keyboard +# \param 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, \c 'a', \c 'b', or something fancy like \c 'space'. +# \note See \ref xtest_key_strings for a full list of accepted key strings. +# \returns Return \c False if the X11 display was not opened before execution, and \c True otherwise def key_click( key_name ): - """Press a key down on the keyboard and release it""" - if check_display(): - out( 'Key button click: key_name=' + key_name ) + if _check_display(): + _log_output( 'Key button click: key_name=' + key_name ) libcvautomation.xte_keyDown( get_display(), key_name ) return True else: #Display not open return False +## \brief Get the location of an image on the screen +# \param image_names List of image names to search for in the root X11 window +# \param search_method The search method to use when matching images. See \ref libcvautomation_search_methods for more information on using the \c search_method parameter +# \param tolerance The tolerance to use when matching images. See \ref libcvautomation_search_methods for more informatino on using the \c tolerance parameter +# \param use_center Set to \c True to return the center coordinate of an image. Set to \c 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. def image_location( [image_names], search_method = _search_method_default, tolerance = _tolerance_default, use_center = True ): - """Find the location of an image on screen (don't wait for it to show up)""" - if check_display(): + if _check_display(): location_array = {} - out( 'Locate image (image_location): image_names=' + image_names ) + _log_output( 'Locate image (image_location): image_names=' + image_names ) if use_center: for image in image_names: image_location = libcvautomation.matchSubImage_X11_center( get_display(), image, @@ -494,15 +603,19 @@ def image_location( [image_names], search_method = _search_method_default, #Display not open, but return the same type return {} - - +## \brief Get the location of an image on the screen, waiting for it to show up +# \param image_names List of image names to search for in the root X11 window +# \param search_method The search method to use when matching images. See \ref libcvautomation_search_methods for more information on using the \c search_method parameter +# \param tolerance The tolerance to use when matching images. See \ref libcvautomation_search_methods for more informatino on using the \c tolerance parameter +# \param timeout The time (in seconds) to wait when searching for an image on the root X11 window +# \param use_center Set to \c True to return the center coordinate of an image. Set to \c 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. def wait_for( [image_names], search_method = _search_method_default, tolerance = _tolerance_default, timeout = _timeout_default, - use_wait = True, use_center = True ): - """Find the location of an image on screen (wait for it to show up if it's not immediately available)""" - if check_display(): + use_center = True ): + if _check_display(): location_array = {} - out( 'Locate image (waitfor): image_names=' + image_names ) + _log_output( 'Locate image (wait_for): image_names=' + image_names ) if use_center: for image in image_names: image_location = libcvautomation.waitForImage_location( get_display(), image, @@ -519,9 +632,17 @@ def wait_for( [image_names], search_method = _search_method_default, #Display not open, but return the same type return {} +## \brief Execute a libcvautomation command based on a string +# \details This is a handler for the xte_commandString() function. +# \note Not all commands need all the parameters specified. See \ref xtest_command_strings for more information on how to use this function. +# \param string The command string to execute +# \param mouse_button The mouse button to click, if applicable +# \param search_method The search method to use, if applicable. See \ref libcvautomation_search_methods for more information on how to use the \c search_method parameter +# \param tolerance The tolerance to use, if applicable. See \ref libcvautomation_search_methods for more information on how to use the \c tolerance parameter +# \param 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 \ref mousejiggle don't normally return a value. def 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""" #The return for this function bears a bit of talking about: # A return of (0, 0) or up is a success # A return of (-1, -1) is an error that either the command wasn't successful, or the command wasn't recognized @@ -529,8 +650,8 @@ def command_string( string, mouse_button = _mouse_button_default, search_method # This helps differentiate between errors and functions like key_click that # don't really use a point - if check_display(): - out( 'Command string: string=' + string + ' search_method=' + str(search_method) + + if _check_display(): + _log_output( 'Command string: string=' + string + ' search_method=' + str(search_method) + ' tolerance=' + str(tolerance) + ' timeout=' + str(timeout) ) result_point = libcvautomation.xte_commandString( get_display(), string, mouse_button, search_method, @@ -539,8 +660,3 @@ def command_string( string, mouse_button = _mouse_button_default, search_method else: #Display not open, return an error point return _libcvautomation_error_location - -## \file libcvautomation_funcs.py -# \brief Libcvautomation wrapper for python -# \details This source file is designed to give high-level access to libcvautomation using Python. It was modeled after the Bash wrapper, but allows for access to all the extra features of Python. -# \author Bradlee Speice