Commit initial python libcvautomation_funcs wrapper

python/libcvautomation_funcs.py

@@ -68,7 +68,7 @@ def check_display():
 	else:
 		return True
 
-def get_display(): #Intended to be unsafe -
+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
@@ -80,7 +80,11 @@ def get_display(): #Intended to be unsafe -
 def open_display( display_name='' ):
 	global X11_display
 	X11_display = libcvautomation.cvaOpenDisplay( display_name )
-	out( 'Opened display with name: ' + display_name )
+	if X11_display not is Nothing:
+		out( 'Opened display with name: ' + display_name )
+		return True
+	else:
+		return False
 
 def close_display():
 	global X11_display
@@ -97,80 +101,421 @@ def close_display():
 #-------------------------------------------------------------------------------
 
 _search_method_default=0
-_tolerance_default=2250000
+_tolerance_default=2250000 #Acceptable values are INT_MIN to INT_MAX
+_timeout_default=5
+_libcvautomation_error_location = libcvautomation.cvaPoint
+_libcvautomation_error_location.x = _libcvautomation_error_location.y = -1
 
 #-------------------------------------------------------------------------------
 #  Begin the actual wrapper functions
 #-------------------------------------------------------------------------------
 
 def mouse_down( mouse_button = 1 ): #Default left-click
-	pass
+	"""Press a mouse button down, and leave it down."""
+	if check_display():
+		out( 'Mouse button down: ' + mouse_button )
+		libcvautomation.xte_mouseDown( get_display(), mouse_button )
+		return True
+	else:
+		#Display not open
+		return False
 
 def mouse_up( mouse_button = 1 ): #Default left-click
-	pass
+	"""Release a mouse button."""
+	if check_display():
+		out( 'Mouse button up: ' + mouse_button )
+		libcvautomation.xte_mouseUp( get_display(), mouse_button )
+
+		return True
+	else:
+		#Display not open
+		return False
 
 def mouse_click( mouse_button = 1 ): #Default left-click
-	pass
+	"""Click a mouse button where the mouse is currently located"""
+	if check_display()
+		out( 'Mouse button click: ' + mouse_button )
+		libcvautomation.xte_clickMouse( get_display(), mouse_button )
+		return True
+	else:
+		#Display not open
+		return False
 
 def mouse_click_xy( x_coord, y_coord, mouse_button = 1 ):
-	pass
+	"""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 )
+		current_location = libcvautomation.xte_mouseLocation( get_display() )
+		x_increment = x_coord - current_location.x
+		y_increment = y_coord - current_location.y
+
+		libcvautomation.xte_hoverMouseRXY( get_display(), x_increment, y_increment )
+		libcvautomation.xte_clickMouse( get_display(), mouse_button )
+
+		return True
+	else:
+		#Display not open
+		return False
 
 def mouse_click_rxy( x_inc, y_inc, mouse_button = 1 ):
-	pass
+	"""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 )
+		libcvautomation.xte_hoverMouseRXY( get_display(), x_inc, y_inc )
+		libcvautomation.xte_clickMouse( get_display(), mouse_button )
+
+		return True
+	else:
+		#Display not open
+		return False
+
+def mouse_click_image( [image_names], search_method = _search_method_default,
+						tolerance = _tolerance_default, timeout = _timeout_default,
+						mouse_button = 1, 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 + 
+				' search_method=' + search_method + ' tolerance=' + tolerance +
+				' timeout=' + _timeout_default + ' mouse_button=' +
+				' use_wait=' + use_wait + ' use_center=' + use_center)
+
+		if use_wait:
+			#Loop through all images 'timeout' times, and click on the first match
+			loop_check = 0
+			while loop_check < timeout:
+				for image in image_names:
+					if use_center:
+						image_location = libcvautomation.xte_clickMouseImage_location_center( get_display(),
+											image, mouse_button, search_method, tolerance )
+					else:
+						image_location = libcvautomation.xte_clickMouseImage_location( get_display(),
+											image, mouse_button, search_method, tolerance )
+
+					if image_location != _libcvautomation_error_location
+						#We've found our image, break out of the for loop and while loop
+						return True
+
+				loop_check += 1
+		else:
+			#Just cycle through the images once
+			for image in image_names:
+				if use_center:
+					image_location = libcvautomation.xte_clickMouseImage_location_center( get_display(),
+											image, mouse_button, search_method, tolerance )
+				else:
+					image_location = libcvautomation.xte_clickMouseImage_location( get_display(),
+											image, mouse_button, search_method, tolerance )
+
+				if image_location != _libcvautomation_error_location
+					#We've found our image, break out of the for loop
+					return True
+	else:
+		#Display not open or no image found
+		return False
 
-def mouse_click_image( [image_names] ):
-	pass
 
 def mouse_doubleclick( mouse_button = 1 ):
-	pass
+	"""Click a mouse button twice where the mouse is currently located"""
+	if check_display()
+		out( 'Mouse button doubleclick: ' + mouse_button )
+		libcvautomation.xte_clickMouse( get_display(), mouse_button )
+
+		return True
+	else:
+		#Display not open
+		return False
+
 
 def mouse_doubleclick_xy( x_coord, y_coord, mouse_button = 1 ):
-	pass
+	"""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 )
+		current_location = libcvautomation.xte_mouseLocation( get_display() )
+		x_increment = x_coord - current_location.x
+		y_increment = y_coord - current_location.y
+
+		libcvautomation.xte_hoverMouseRXY( get_display(), x_increment, y_increment )
+		libcvautomation.xte_clickMouse( get_display(), mouse_button )
+		libcvautomation.xte_clickMouse( get_display(), mouse_button )
+
+		return True
+	else:
+		#Display not open
+		return False
 
 def mouse_doubleclick_rxy( x_inc, y_inc, mouse_button = 1 ):
-	pass
+	"""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 )
+		libcvautomation.xte_hoverMouseRXY( get_display(), x_inc, y_inc )
+		libcvautomation.xte_clickMouse( get_display(), mouse_button )
+		libcvautomation.xte_clickMouse( get_display(), mouse_button )
 
-def mouse_doubleclick_image( [image_names] ):
+		return True
-	pass
+	else:
+		#Display not open
+		return False
+
+def mouse_doubleclick_image( [image_names], search_method = _search_method_default,
+						tolerance = _tolerance_default, timeout = _timeout_default,
+						mouse_button = 1, 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 + 
+				' search_method=' + search_method + ' tolerance=' + tolerance +
+				' timeout=' + _timeout_default + ' mouse_button=' +
+				' use_wait=' + use_wait + ' use_center=' + use_center)
+
+		if use_wait:
+			#Loop through all images 'timeout' times, and click on the first match
+			loop_check = 0
+			while loop_check < timeout:
+				for image in image_names:
+					if use_center:
+						image_location = libcvautomation.xte_clickMouseImage_location_center( get_display(),
+											image, mouse_button, search_method, tolerance )
+					else:
+						image_location = libcvautomation.xte_clickMouseImage_location( get_display(),
+											image, mouse_button, search_method, tolerance )
+
+					if image_location != _libcvautomation_error_location
+						#Make sure to click twice once we've found the image
+						#Technically assumes that the system mouse timeout is less than
+						#the time it takes to do two boolean compares - I think this is pretty safe
+						libcvautomation.xte_clickMouse( get_display(), mouse_button )
+						#We've found our image, break out of the for loop and while loop
+						return True
+
+				loop_check += 1
+		else:
+			#Just cycle through the images once
+			for image in image_names:
+				if use_center:
+					image_location = libcvautomation.xte_clickMouseImage_location_center( get_display(),
+											image, mouse_button, search_method, tolerance )
+				else:
+					image_location = libcvautomation.xte_clickMouseImage_location( get_display(),
+											image, mouse_button, search_method, tolerance )
+
+				if image_location != _libcvautomation_error_location
+					#We've found our image, break out of the for loop
+					return True
+
+	else:
+		#Display not open, or no image found
+		return False
 
 def mouse_hover_xy( x_coord, y_coord ):
-	pass
+	"""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 )
+		current_location = libcvautomation.xte_mouseLocation( get_display() )
+		x_increment = x_coord - current_location.x
+		y_increment = y_coord - current_location.y
+
+		libcvautomation.xte_hoverMouseRXY( get_display(), x_increment, y_increment )
+
+		return True
+	else:
+		#Display not open
+		return False
+
 
 def mouse_hover_rxy( x_inc, y_inc ):
-	pass
+	"""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) )
+		libcvautomation.xte_hoverMouseRXY( get_display(), x_inc, y_inc )
+
+		return True
+	else:
+		#Display not open
+		return False
+
+def mouse_hover_image( [image_names], search_method = _search_method_default,
+						tolerance = _tolerance_default, timeout = _timeout_default,
+						mouse_button = 1, 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 + 
+				' search_method=' + search_method + ' tolerance=' + tolerance +
+				' timeout=' + _timeout_default + ' mouse_button=' +
+				' use_wait=' + use_wait + ' use_center=' + use_center)
+
+		if use_wait:
+			#Loop through all images 'timeout' times, and click on the first match
+			loop_check = 0
+			while loop_check < timeout:
+				for image in image_names:
+					if use_center:
+						image_location = libcvautomation.xte_hoverMouseImage_location_center( get_display(),
+											image, mouse_button, search_method, tolerance )
+					else:
+						image_location = libcvautomation.xte_hoverMouseImage_location( get_display(),
+											image, mouse_button, search_method, tolerance )
+
+					if image_location != _libcvautomation_error_location
+						#We've found our image, break out of the for loop and while loop
+						return True
+
+				loop_check += 1
+		else:
+			#Just cycle through the images once
+			for image in image_names:
+				if use_center:
+					image_location = libcvautomation.xte_hoverMouseImage_location_center( get_display(),
+											image, mouse_button, search_method, tolerance )
+				else:
+					image_location = libcvautomation.xte_hoverMouseImage_location( get_display(),
+											image, mouse_button, search_method, tolerance )
+
+				if image_location != _libcvautomation_error_location
+					#We've found our image, break out of the for loop
+					return True
+	else:
+		#Display not open or no image found
+		return False
 
-def mouse_hover_image( [image_names] ):
-	pass
 
 def mouse_jiggle():
-	pass
+	"""Jiggle the mouse in place"""
+	if check_display():
+		out( 'Mouse button jiggle' )
+		libcvautomation.xte_mouseJiggle( get_display() )
+		return True
+	else:
+		#Display not open
+		return False
+
 
 def mouse_scroll_up():
-	pass
+	"""Scroll the mouse wheel up"""
+	if check_display():
+		out( 'Mouse scroll up' )
+		libcvautomation.xte_mouseScrollUp( get_display() )
+		return True
+	else:
+		#Display not open
+		return False
 
 def mouse_scroll_down():
-	pass
+	"""Scroll the mouse wheel down"""
+	if check_display():
+		out( '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 ):
-	pass
+	"""Drag and drop from one location to another"""
+	if check_display():
+		out( 'Mouse drag and drop: dragging from=' + drag_image +
+			' dragging to=' + drag_to )
+		successful_hover = mouse_hover_image( drag_image )
+		if successful_hover:
+			mouse_down( mouse_button=1 )
+			successful_hover = mouse_hover_image( drag_to )
+			mouse_up( mouse_button=1 )
+
+		#Return True if both hovers are successful, False otherwise
+		return successful_hover
+	else:
+		#Display not open
+		return False
+
 
 def key_string( string ):
-	pass
+	"""Enter a string of text on the keyboard"""
+	if check_display():
+		out( 'Key string enter: string=' + string )
+		libcvautomation.xte_clickKeyStr( get_display(), string )
+		return True
+	else:
+		#Display not open
+		return False
+
 
 def key_down( key_name ):
-	pass
+	"""Press a key down on the keyboard"""
+	if check_display():
+		out( 'Key button down: key_name=' + key_name )
+		libcvautomation.xte_keyDown( get_display(), key_name )
+		return True
+	else:
+		#Display not open
+		return False
 
 def key_up( key_name ):
-	pass
+	"""Press a key down on the keyboard"""
+	if check_display():
+		out( 'Key button up: key_name=' + key_name )
+		libcvautomation.xte_keyUp( get_display(), key_name )
+		return True
+	else:
+		#Display not open
+		return False
 
 def key_click( key_name ):
-	pass
+	"""Press a key down on the keyboard and release it"""
+	if check_display():
+		out( 'Key button click: key_name=' + key_name )
+		libcvautomation.xte_keyDown( get_display(), key_name )
+		return True
+	else:
+		#Display not open
+		return False
 
-def image_location( [image_names] ):
+def image_location( [image_names], search_method = _search_method_default,
-	pass
+						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():
+		location_array = {}
+		out( '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,
+									search_method, tolerance )
+				location_array += [image, image_location]
+		else:
+			for image in image_names:
+				image_location = libcvautomation.matchSubImage_X11( get_display(), image,
+									search_method, tolerance )
+				location_array += [image, image_location]
 
-def waitfor( [image_names] ):
+		return location_array
-	pass
+	else:
+		#Display not open, but return the same type
+		return {}
+
+
+
+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():
+		location_array = {}
+		out( 'Locate image (waitfor): image_names=' + image_names )
+		if use_center:
+			for image in image_names:
+				image_location = libcvautomation.waitForImage_location( get_display(), image,
+										search_method, tolerance, timeout )
+				location_array += [image, image_location]
+		else:
+			for image in image_names:
+				image_location = libcvautomation.waitForImage_location_center( get_display(), image,
+										search_method, tolerance, timeout )
+				location_array += [image, image_location]
+		
+		return location_array
+	else:
+		#Display not open, but return the same type
+		return {}
 
 ## \file libcvautomation_funcs.py
 # \brief Libcvautomation wrapper for python