This class represents the GUI element in an application. More...

Inheritance diagram for urpa.AppElement:

Public Member Functions
def	send_mouse_click (self, action=default_mouse_action, position=None)
	This method simulates the mouse action specified in its parameter, on the center of the App GUI element. More...

def	send_text (self, text, action=default_text_action, kl=default_kl, focus_action=default_focus_action)
	This method simulates text input - over a GUI element - the pressing and releasing of a key sequence, represented by a string in the "text" parameter. More...

def	send_key (self, text, type=default_key_action, focus_action=default_focus_action)
	This method simulates - over a GUI element - the pressing of a specified key combination. More...

def	send_message (self, message, wparam, lparam)

def	post_message (self, message, wparam, lparam)

def	set_focus (self, focus_action=default_focus_action)
	This method sets the focus on this App GUI element. More...

def	name (self)
	This method returns the value of the "name" attribute of this App GUI element. More...

def	value (self)
	This method returns the value of the "value" attribute of this App GUI element. More...

def	class_name (self)
	This method returns the value of the "class name" attribute of this App GUI element. More...

def	localized_control_type (self)
	This method returns the value of the "localized control type" attribute of this App GUI element. More...

def	control_type (self)
	This method returns the value of the "control type" attribute of this App GUI element. More...

def	bounding_rectangle (self)
	This method returns the absolute coordinates of this GUI element on the desktop in the order left, top, right, bottom. More...

def	size (self)
	This method returns the size of this App GUI element in the order width, height. More...

def	access_key (self)
	This method returns the value of the "access key" attribute of this App GUI element. More...

def	automation_id (self)
	This method returns the value of the "automation ID" attribute of this App GUI element. More...

def	item_type (self)
	This method returns the value of the "item type" attribute of this App GUI element. More...

def	toggle_state (self)
	This method returns the value of the "toggle state" attribute of this App GUI element. More...

def	selected (self)
	This method returns the value of the "selected" attribute of this App GUI element. More...

def	enabled (self)
	This method returns the value of the "enabled" attribute of this App GUI element. More...

def	visual_data (self, rect=None, format="bmp")
	This method creates an image from this App GUI element. More...

def	parent (self)
	This method returns the element parent. More...

def	find_first (self, condition, timeout=default_timeout)
	This method returns the first GUI element that matches the condition parameter and is located in a GUI element subtree with a root representing this App GUI element. More...

def	find_all (self, condition, elements=0, timeout=default_timeout)
	This method returns a list of all GUI elements that match the condition parameter and are located in a GUI element subtree with a root representing this App GUI element. More...

def	find_from_point (self, x, y, condition=None, timeout=default_timeout)
	This method looks for a GUI element matching the condition parameter and located at a virtual point defined by offsetting (via the parameters x, y) the upper left corner of this App GUI element. More...

def	find_first_right_to (self, condition, timeout=default_timeout, height=50, step=30)
	This method looks for a GUI element matching the condition parameter and located to the right of this GUI element. More...

def	find_first_left_to (self, condition, timeout=default_timeout, height=50, step=30)
	This method looks for a GUI element matching the condition parameter and located to the left of this GUI element. More...

def	find_first_down_to (self, condition, timeout=default_timeout, width=50, step=30)
	This method looks for a GUI element matching the condition parameter and located to the bottom of this GUI element. More...

def	find_first_up_to (self, condition, timeout=default_timeout, width=50, step=30)
	This method looks for a GUI element matching the condition parameter and located above this GUI element. More...

def	find_first_visual (self, pattern, region=None, timeout=default_timeout, transformations=None)
	This method looks for a visual GUI element (pattern) in a given region and returns it as a VisualElement object. More...

def	find_all_visual (self, pattern, region=None, elements=0, timeout=default_timeout, transformations=None)
	This method looks for visual GUI elements (patterns) in a given region and returns them as a list of objects VisualElement. More...

Detailed Description

This class represents the GUI element in an application.

An instance of this class can be created by one of the App class methods or by the AppElement.find_first, AppElement.find_all, AppElement.find_from_point, and AppElement.find_first_right_to methods.

Member Function Documentation

◆ access_key()

def urpa.AppElement.access_key ( self )

This method returns the value of the "access key" attribute of this App GUI element.

Returns: Returns a string containing the value of the "access key" attribute of this App GUI element.

◆ automation_id()

def urpa.AppElement.automation_id ( self )

This method returns the value of the "automation ID" attribute of this App GUI element.

Returns: Returns a string containing the value of the "automation ID" attribute of this App GUI element.

◆ bounding_rectangle()

def urpa.AppElement.bounding_rectangle ( self )

This method returns the absolute coordinates of this GUI element on the desktop in the order left, top, right, bottom.

Returns: Returns a tuple containing the absolute coordinates of this GUI element on the desktop in the order left, top, right, bottom.

◆ class_name()

def urpa.AppElement.class_name ( self )

This method returns the value of the "class name" attribute of this App GUI element.

Returns: Returns a string containing the value of the "class name" attribute of this App GUI element.

◆ control_type()

def urpa.AppElement.control_type ( self )

This method returns the value of the "control type" attribute of this App GUI element.

Returns: Returns a string containing the value of the "control type" attribute of this App GUI element.

◆ enabled()

def urpa.AppElement.enabled ( self )

This method returns the value of the "enabled" attribute of this App GUI element.

Returns: Returns True if the GUI element is "enabled". Returns False if the GUI element is not "enabled".

◆ find_all()

def urpa.AppElement.find_all	(	self,
		condition,
		elements = `0`,
		timeout = `default_timeout`
	)

This method returns a list of all GUI elements that match the condition parameter and are located in a GUI element subtree with a root representing this App GUI element.

GUI element subtree searches take place in iterations with a 50 ms delay over the time defined in the timeout parameter. For applications with a large GUI, the processing time per iteration, or the search of a GUI element subtree, may be in the order of seconds. If the number of GUI elements found during a single iteration is non-zero and at the same time equal to or greater than the value specified in the elements parameter, the method returns a list of the AppElement objects found. If the elements parameter is set greater than 0 and the required number of GUI elements is not found by the timeout, the urpa.ElementNotFoundError exception is raised. If the elements parameter is set to 0 and at least one of the required GUI elements is not found by the timeout, the method returns an empty list. If the elements parameter is set to 0, only one iteration is processed.

Parameters

condition	String or Condition GUI element search term.
elements	int The minimum number of GUI elements that must be found within the period defined in the timeout parameter.
timeout	int [ms] Maximum time to retrieve a GUI element. If this parameter is not passed, the default value is applied, i.e. urpa.default_timeout.

Returns: Returns a list of AppElement-type objects

Exceptions

ElementNotFoundError the required number of GUI elements could not be found within the timeout period.

Examples

The example of finding all radio buttons located at https://playground.ultimaterpa.com in Internet Explorer under the GUI element - the "UltimateRPA Playground" pane. The attributes of the GUI elements found are listed in the output console.

# auxiliary class to create more complex conditions
cf = urpa.condition_factory()
# run Internet Explorer
app = urpa.exec_ie_app("https://playground.ultimaterpa.com")
# wait to find the GUI element - the "UltimateRPA Playground" pane
root_element = app.find_first(cf.pane().name(cf.regexp("UltimateRPA Playground")))
# find hyperlinks in the GUI element subtree
found_elements = root_element.find_all(cf.radio_button())
print(found_elements)

◆ find_all_visual()

def urpa.AppElement.find_all_visual	(	self,
		pattern,
		region = `None`,
		elements = `0`,
		timeout = `default_timeout`,
		transformations = `None`
	)

This method looks for visual GUI elements (patterns) in a given region and returns them as a list of objects VisualElement.

Parameters

pattern	string or bytearray, e.g. "img / pattern.bmp" The path to the image in png, bmp format, or the value returned by the visual_data (bytearray) method.
region	a tuple containing four ints, for example (10, 10, 20, 20) or None. Optional argument, set to None by default. The tuple defines (left, top, right, bottom) the coordinates of the rectangle defining the selected region in px. The coordinates are relative to the upper left corner of the GUI element to which the AppElement class instance is tied. The value None means that the region selected is identical in size to the GUI element to which the AppElement class instance is tied.
elements	int The minimum number of visual GUI elements that must be found within the period defined in the timeout parameter.
timeout	int [ms] The maximum time in which visual GUI elements must be retrieved. If this parameter is not passed, the default value is applied, see urpa.default_timeout.
transformations	a transformation object that may contain several operations modifying the source pattern and the region searched. See TransformationFactory.

Returns: Returns a list of VisualElement-type objects

Exceptions

ElementNotFoundError The visual GUI elements required could not be found within the timeout period.

Examples

Example
element = app.find_first(cf.name("Red Rectangle"))
region = (-10, -12, 42, 40)
# Define how many visual GUI elements you wish to find at minimum.
elements = 2
timeout = 60000
tf = urpa.transformation_factory()
# Define the execution of color inversion first and then a 50% threshold.
transformations = tf.colors_inversion().binary_image(0.5)
visuals = element.find_all_visual("img/template.png", region, elements, timeout, transformations)
# Simulate a mouse click over the GUI element most recently found.
visuals[-1].send_mouse_click()

◆ find_first()

def urpa.AppElement.find_first	(	self,
		condition,
		timeout = `default_timeout`
	)

This method returns the first GUI element that matches the condition parameter and is located in a GUI element subtree with a root representing this App GUI element.

GUI element searches take place in iterations with a 50 ms delay. The "depth-first search" method is used to search a GUI element subtree. For applications with a large GUI, the processing time per iteration, or the search of a GUI element subtree, may be in the order of seconds. This method is not practical for identifying GUI elements that only "flash" in the GUI of the controlled application. If the method could not find any matching GUI element, it raises the urpa.ElementNotFoundError exception. Otherwise, the method returns the first matching GUI element, even if multiple GUI elements meet the condition defined in the condition parameter.

Parameters

condition	String or Condition GUI element search term.
timeout	int [ms] Maximum time to retrieve a GUI element. If this parameter is not passed, the default value is applied, i.e. urpa.default_timeout.

Returns: Returns an AppElement-type object

Exceptions

ElementNotFoundError the GUI element required could not be found within the timeout period.

Examples

The example of finding the first radio button located at https://playground.ultimaterpa.com in Internet Explorer under the GUI element - the "UltimateRPA Playground" pane. The attributes of the GUI element found are listed in the output console.

# auxiliary class to create more complex conditions
cf = urpa.condition_factory()
# run Internet Explorer
app = urpa.exec_ie_app("https://playground.ultimaterpa.com")
# wait to find the GUI element - the "UltimateRPA Playground" pane
root_element = app.find_first(cf.pane().name(cf.regexp("UltimateRPA Playground")))
# find a radio button in the GUI element subtree
found_element = root_element.find_first(cf.radio_button())
print(found_element)

◆ find_first_down_to()

def urpa.AppElement.find_first_down_to	(	self,
		condition,
		timeout = `default_timeout`,
		width = `50`,
		step = `30`
	)

This method looks for a GUI element matching the condition parameter and located to the bottom of this GUI element.

GUI element searches take place in iterations with a 50 ms delay over the time specified in the timeout parameter. The GUI element to be found must occur in the same TP window as the GUI element tied to an instance of this class. Prior to finding the element, the TP window is transferred to the foreground. The coordinates of the virtual points in which a GUI element matching the condition parameter is to be found are then calculated over the TP window. The virtual points over which a GUI element matching the condition parameter is to be found have a vertical spacing defined by the step parameter (in pixels). The number of virtual points is determined by the size of the TP window. Specifically, the y-coordinate of each virtual point must be less than the y-coordinate of the lower edge of the TP window tied to the GUI element to be found. At the same time, the y-coordinate of each virtual point must be less than the y-coordinate of the lower edge of this GUI element. The first virtual point always has an y-coordinate offset by 5 pixels to the bottom of the lower edge of this GUI element. The horizontal (x-) coordinate of all virtual points is set to the center of this GUI element and is always the same for all virtual points. If GUI elements over a large number of virtual points meet the condition parameter at the same time, the GUI element closest to this GUI element is returned. If the method could not find the GUI element required, it raises the urpa.ElementNotFoundError exception.

Parameters

condition	String or Condition The search term for the GUI element located below this GUI element.
timeout	int [ms] The maximum time in which a GUI element matching the condition parameter must be retrieved. If this parameter is not passed, the default value is applied, see urpa.default_timeout.
width	int [%] Expresses, as a percentage, the offset of the horizontal coordinate of all virtual points over the TP window from the left edge of the reference GUI element. The width of the reference GUI element is 100%.
step	int [px] Expresses, in pixels, the vertical spacing - over the TP window - of virtual points in which a GUI element matching the condition_down_element parameter is to be found.

Returns: Returns an AppElement-type object

Exceptions

ElementNotFoundError The GUI element required could not be found within the timeout period.

◆ find_first_left_to()

def urpa.AppElement.find_first_left_to	(	self,
		condition,
		timeout = `default_timeout`,
		height = `50`,
		step = `30`
	)

This method looks for a GUI element matching the condition parameter and located to the left of this GUI element.

GUI element searches take place in iterations with a 50 ms delay over the time specified in the timeout parameter. The GUI element to be found must occur in the same TP window as the GUI element tied to an instance of this class. Prior to finding the element, the TP window is brought to the foreground. The coordinates of the virtual points in which a GUI element matching the condition parameter is to be found are then calculated over the TP window. The virtual points over which a GUI element matching the condition parameter is to be found have a horizontal spacing defined by the step parameter (in pixels). The number of virtual points is determined by the size of the TP window. Specifically, the x-coordinate of each virtual point must be less than the x-coordinate of the right edge of the TP window tied to the GUI element to be found. At the same time, the x-coordinate of each virtual point must be less than the x-coordinate of the right edge of this GUI element. The first virtual point always has an x-coordinate offset by 5 pixels to the left of the right edge of this GUI element. The vertical (y-) coordinate of all virtual points is set to the center of this GUI element and is always the same for all virtual points. If GUI elements over a large number of virtual points match the condition parameter at the same time, the GUI element closest to this GUI element is returned. If the method could not find the GUI element required, it raises the urpa.ElementNotFoundError exception.

Parameters

condition	String or Condition The search term for the GUI element located to the left of this App GUI element.
timeout	int [ms] The maximum time in which a GUI element matching the condition parameter must be retrieved. If this parameter is not passed, the default value is applied, see urpa.default_timeout.
height	int [%] Expresses, as a percentage, the offset of the vertical coordinate of all virtual points over the TP window from the top edge of the reference GUI element. The height of the reference GUI element is 100%.
step	int [px] Expresses, in pixels, the horizontal spacing - over the TP window - of virtual points in which a GUI element matching the condition parameter is to be found.

Returns: Returns an AppElement-type object

Exceptions

ElementNotFoundError The GUI element required could not be found within the timeout period.

◆ find_first_right_to()

def urpa.AppElement.find_first_right_to	(	self,
		condition,
		timeout = `default_timeout`,
		height = `50`,
		step = `30`
	)

This method looks for a GUI element matching the condition parameter and located to the right of this GUI element.

GUI element searches take place in iterations with a 50 ms delay over the time specified in the timeout parameter. The GUI element to be found must be available in the same TP window as the GUI element tied to an instance of this class. Prior to finding the element, the TP window is brought to the foreground. The coordinates of the virtual points in which a GUI element matching the condition parameter is to be found are then calculated over the TP window. The virtual points over which a GUI element matching the condition parameter is to be found have a horizontal spacing defined by the step parameter (in pixels). The number of virtual points is determined by the size of the TP window. Specifically, the x-coordinate of each virtual point must be less than the x-coordinate of the right edge of the TP window tied to the GUI element to be found. At the same time, the x-coordinate of each virtual point must be greater than the x-coordinate of the right edge of this GUI element. The first virtual point always has an x-coordinate offset by 5 pixels to the right of the right edge of this GUI element. The vertical (y-) coordinate of all virtual points is set to the center of this GUI element and is always the same for all virtual points. If GUI elements over a large number of virtual points match the condition parameter at the same time, the GUI element closest to this GUI element is returned. If the method could not find the GUI element required, it raises the urpa.ElementNotFoundError exception.

Parameters

condition	String or Condition The search term for the GUI element located to the right of this App GUI element.
timeout	int [ms] The maximum time in which a GUI element meeting the condition parameter must be retrieved. If this parameter is not passed, the default value is applied, see urpa.default_timeout.
height	int [%] Expresses, as a percentage, the offset of the vertical coordinate of all virtual points over the TP window from the top edge of the reference GUI element. The height of the reference GUI element is 100%.
step	int [px] Expresses, in pixels, the horizontal spacing - over the TP window - of virtual points in which a GUI element matching the condition parameter is to be found.

Returns: Returns an AppElement-type object

Exceptions

ElementNotFoundError The GUI element required could not be found within the timeout period.

Examples

The example of finding the nearest text to the right of the "Normal" radio button at https://playground.ultimaterpa.com in Internet Explorer. The attributes of the GUI element found are listed in the output console.

# auxiliary class to create more complex conditions
cf = urpa.condition_factory()
# run Internet Explorer
app = urpa.exec_ie_app("https://playground.ultimaterpa.com")
# wait to find the GUI element - the "Normal" radio button
found_element = app.find_first(cf.radio_button().name("Normal"))
# find the closest text to the right of the GUI element found_element
right_element = found_element.find_first_right_to(cf.text())
# list attributes of the GUI element found
print(right_element)

◆ find_first_up_to()

def urpa.AppElement.find_first_up_to	(	self,
		condition,
		timeout = `default_timeout`,
		width = `50`,
		step = `30`
	)

This method looks for a GUI element matching the condition parameter and located above this GUI element.

GUI element searches take place in iterations with a 50 ms delay over the time specified in the timeout parameter. The GUI element to be found must occur in the same TP window as the GUI element tied to an instance of this class. Prior to finding the element, the TP window is brought to the foreground. The coordinates of the virtual points in which a GUI element matching the condition parameter is to be found are then calculated over the TP window. The virtual points over which a GUI element matching the condition parameter is to be found have a vertical spacing defined by the step parameter (in pixels). The number of virtual points is determined by the size of the TP window. Specifically, the y-coordinate of each virtual point must be less than the y-coordinate of the upper edge of the TP window tied to the GUI element to be found. At the same time, the y-coordinate of each virtual point must be greater than the y-coordinate of the upper edge of this GUI element. The first virtual point always has an y-coordinate offset by 5 pixels above the upper edge of this GUI element. The horizontal (x-) coordinate of all virtual points is set to the center of this GUI element and is always the same for all virtual points. If GUI elements over a large number of virtual points meet the condition parameter at the same time, the GUI element closest to this GUI element is returned. If the method could not find the GUI element required, it raises the urpa.ElementNotFoundError exception

Parameters

condition	String or Condition The search term for the GUI element located above this GUI element.
timeout	int [ms] The maximum time in which a GUI element matching the condition parameter must be retrieved. If this parameter is not passed, the default value is applied, see urpa.default_timeout.
width	int [%] Expresses, as a percentage, the offset of the horizontal coordinate of all virtual points over the TP window from the left edge of the reference GUI element. The width of the reference GUI element is 100%.
step	int [px] Expresses, in pixels, the vertical spacing - over the TP window - of virtual points in which a GUI element matching the condition_down_element parameter is to be found.

Returns: Returns an AppElement-type object

Exceptions

ElementNotFoundError The GUI element required could not be found within the timeout period.

◆ find_first_visual()

def urpa.AppElement.find_first_visual	(	self,
		pattern,
		region = `None`,
		timeout = `default_timeout`,
		transformations = `None`
	)

This method looks for a visual GUI element (pattern) in a given region and returns it as a VisualElement object.

Parameters

pattern	string or bytearray, e.g. "img / pattern.bmp" The path to the image in png, bmp format, or the value returned by the visual_data (bytearray) method.
region	a tuple containing four ints, for example (10, 10, 20, 20) or None. Optional argument, set to None by default. The tuple defines (left, top, right, bottom) the coordinates of the rectangle defining the selected region in px. The coordinates are relative to the upper left corner of the GUI element to which the AppElement class instance is tied. The value None means that the region selected is identical in size to the GUI element to which the AppElement class instance is tied.
timeout	int [ms] The maximum time in which a visual GUI element must be retrieved. If this parameter is not passed, the default value is applied, see urpa.default_timeout.
transformations	a transformation object that may contain several operations modifying the source pattern and the region searched. See TransformationFactory.

Returns: Returns one VisualElement-type object

Exceptions

ElementNotFoundError The visual GUI element required could not be found within the timeout period.

Examples

Example
# First find the AppElement called Red Rectangle.
element = app.find_first(cf.name("Red Rectangle"))
# Define the path to the pattern file.
template_path = "img/template.bmp"
visual = element.find_first_visual(template_path)

◆ find_from_point()

def urpa.AppElement.find_from_point	(	self,
		x,
		y,
		condition = `None`,
		timeout = `default_timeout`
	)

This method looks for a GUI element matching the condition parameter and located at a virtual point defined by offsetting (via the parameters x, y) the upper left corner of this App GUI element.

GUI element searches take place in iterations with a 50 ms delay over the time specified in the timeout parameter. Prior to finding the element, the TP window tied to an instance of this class is brought to the foreground. The coordinates of the virtual point (over which the GUI element is to be found according to the condition parameter) are then calculated by offsetting the absolute coordinates of this GUI element by x, y that have been passed as parameters. If the GUI element over the virtual point meets the condition parameter, it is returned by this method. The two GUI elements, the reference and the one to be found, must appear at the same time in the same TP window. If the condition is None, only the first iteration is executed and the method returns a GUI element on the virtual point position. If the method could not find any matching GUI element, it raises the urpa.ElementNotFoundError exception.

Parameters

x	int [px] The coordinates specifying the horizontal offset, specifically the coordinates defining the virtual point's relative x-axis position on which the GUI element matching the condition parameter must be located.
y	int [px] The coordinates specifying the vertical offset, specifically the coordinates defining the virtual point's relative y-axis position on which the GUI element matching the condition parameter must be located.
condition	String or Condition GUI element search term.
timeout	int [ms] The maximum search time for a GUI element. If no parameter is passed, the default urpa.default_timeout value is used.

Returns: Returns an AppElement-type object.

Exceptions

ElementNotFoundError the GUI element required could not be found within the timeout period.

Examples

The example of finding an image located at https://playground.ultimaterpa.com in Internet Explorer 0 pixels right of and 60 pixels up from the upper left corner of the GUI element representing the "Normal" text. The attributes of the GUI element found are listed in the output console.

# auxiliary class to create more complex conditions
cf = urpa.condition_factory()
# run Internet Explorer
app = urpa.exec_ie_app("https://playground.ultimaterpa.com")
# wait to find the GUI element - the "Normal" text
found_element = app.find_first(cf.text().name("Normal"))
# find the image - the GUI element in the position specified by offsetting (0,60) the upper left corner of the GUI element - "Normal" text
point_element = found_element.find_from_point(0, -60, cf.image())
# list attributes of the GUI element found
print(point_element)

◆ item_type()

def urpa.AppElement.item_type ( self )

This method returns the value of the "item type" attribute of this App GUI element.

Returns: Returns a string containing the value of the "item type" attribute of this App GUI element.

◆ localized_control_type()

def urpa.AppElement.localized_control_type ( self )

This method returns the value of the "localized control type" attribute of this App GUI element.

Returns: Returns a string containing the value of the "localized control type" attribute of this App GUI element.

◆ name()

def urpa.AppElement.name ( self )

This method returns the value of the "name" attribute of this App GUI element.

Returns: Returns a string containing the value of the "name" attribute of this App GUI element.

◆ parent()

def urpa.AppElement.parent ( self )

This method returns the element parent.

If there is no parent, it returns None.

◆ post_message()

def urpa.AppElement.post_message	(	self,
		message,
		wparam,
		lparam
	)

◆ selected()

def urpa.AppElement.selected ( self )

This method returns the value of the "selected" attribute of this App GUI element.

The "selected" attribute represents, for example, the status of "radio button" or "list item" control.

Returns: Returns True if the GUI element is "selected". Returns False if the GUI element is not "selected". Returns None if the GUI element does not support this attribute.

◆ send_key()

def urpa.AppElement.send_key	(	self,
		text,
		type = `default_key_action`,
		focus_action = `default_focus_action`
	)

This method simulates - over a GUI element - the pressing of a specified key combination.

Prior to simulating the pressing of the specified key combination, the TP window tied to the GUI element is transferred to the foreground, and the set_focus() method is automatically invoked over the GUI element tied to an instance of that class. The actual simulation of the pressing of the specified key combination is only tied to the TP window handle, i.e. if the GUI element does not gain or loses focus during the simulation, the simulation will not be executed correctly. While simulating the key action,, first the string from the "text" parameter is divided into individual characters. The delimiter between characters is "+". A sequence is then created that represents key press ("down") and key release ("up") according to the characters in the "text" parameter. For example, the Ctrl+Shift+s combination is broken down into the sequence Ctrl(Down)+Shift(Down)+s(Down)+s(Up)+Shift(Up)+Ctrl(Up). A 100 ms delay is "processed" following the simulation of the press (Down) / release (Up) of each key. If a Hardware simulation mode is set in the "type" parameter, the simulation must take place in the foreground. If a simulation is running in the background, when the "type" parameter is set to Hardware it is automatically transferred to the foreground. When the "type" parameter is set to a Standard value, during a simulation individual characters are converted into virtual-key codes, and the simulation can also run in the background. This method is not suitable for direct text input.

Parameters

text	String A key combination, the pressing of which over a GUI element is to be simulated, e.g. ALT+x. "ALT" "RALT" - right Alt "CTRL" "RCTRL" - right Ctrl "TAB" "ENTER", "RETURN" "BACKSPACE" "ESC", "ESCAPE" "PAUSE" "END" "HOME" "LEFT" "UP" "RIGHT" "DOWN" "INSERT" "DELETE", "DEL" "HELP" "NUMLOCK" "SCROLL" "PGDOWN", "NEXT" "PGUP", "PRIOR" "CLEAR" "SHIFT" "RSHIFT" - right shift "WIN" "RWIN" "APPS" "SPACE" "MULTIPLY" "ADD" "SEPARATOR" "SUBTRACT" "DECIMAL" "DIVIDE" "OEM_MINUS" "OEM_PLUS" "OEM_COMMA" "OEM_PERIOD"
type	String The way in which the keystrokes are to be simulated. Hardware Standard
focus_action	String The way in which control activation is to be simulated. See set_default_focus_action for options.

Exceptions

ValueError the "text" or "type" parameter passed does not have a valid format.

Examples

The example of opening Internet Explorer on the about:blank page, invoking the "Show documents downloaded" dialogue box by simulating the Ctrl+J keyboard shortcut and closing this dialog box by simulating the Alt+Z keyboard shortcut.

app = urpa.exec_ie_app("about:blank")
verify_element = app.find_first(cf.value("about:blank"))
time.sleep(1)
verify_element.send_key("Ctrl+J")
time.sleep(1)
close_element = app.find_first(cf.button().access_key("Alt+Z"))
time.sleep(1)
close_element.send_key("Alt+Z")

◆ send_message()

def urpa.AppElement.send_message	(	self,
		message,
		wparam,
		lparam
	)

◆ send_mouse_click()

def urpa.AppElement.send_mouse_click	(	self,
		action = `default_mouse_action`,
		position = `None`
	)

This method simulates the mouse action specified in its parameter, on the center of the App GUI element.

By default, this method makes an HW left mouse click in the center of the GUI element. Delays in sending individual messages that simulate the mouse action are set to 50 ms.

Parameters

action	String A parameter specifying the type of mouse action that will be simulated over the GUI element. For possible parameter values, see the urpa.set_default_mouse_action method.
position	An optional tuple with 2 int-type elements (left, top). Specifies the mouse click position in the format left, top. The coordinates are relative to the upper left corner of the element.

Examples

The example of opening https://playground.ultimaterpa.com in Internet Explorer, finding an "authentication" GUI element called "Continue" and waiting for 3 seconds, simulating a click on the "Continue" GUI element found, finding the "Success" authentication element.

app = urpa.exec_ie_app("https://playground.ultimaterpa.com")
verify_element = app.find_first("Continue")
time.sleep(3)
verify_element.send_mouse_click("Left")
verify_element_success = app.find_first("Success")

◆ send_text()

def urpa.AppElement.send_text	(	self,
		text,
		action = `default_text_action`,
		kl = `default_kl`,
		focus_action = `default_focus_action`
	)

This method simulates text input - over a GUI element - the pressing and releasing of a key sequence, represented by a string in the "text" parameter.

Prior to simulating the key press and release, the TP window tied to the GUI element is transferred to the foreground, and the set_focus() method is automatically invoked over the GUI element tied to an instance of that class. The actual key press/release simulation is only tied to the TP window handle, i.e. if the GUI element does not gain or loses focus during the simulation, the simulation will not be executed correctly. While simulating the key press and release, first the string from the "text" parameter is divided into individual characters. A sequence is then created that represents key press ("down")and key release ("up") according to the characters in the "text" parameter. For example, the string "Lev" is broken down into the sequence Shift(Down)+l(Down)+l(Up)+Shift(Up)+e(Down)+e(Up)+v(Down)+v(Up). A 100 ms delay is "processed" following the simulation of the press (Down) / release (Up) of each key. If one of the "hw" simulation modes is set in the "type" parameter, the simulation must take place in the foreground. If a simulation is running in the background, when the "type" parameter is set to one of the "hw" values it is automatically transferred to the foreground. When the "type" parameter is set to one of the "standard" values, during a simulation individual characters are converted into virtual-key codes or alt-codes, and the simulation can also run in the background. When the "type" parameter is set to "wm_char", the string from the "text" parameter splits directly into individual characters during the simulation.

Parameters

text	String Text, the writing of which will be simulated over an application tied to a GUI element represented by an instance of this class.
action	String The mode for the simulation of individual keystrokes, represented by a string in the "text" parameter. "hw_alt_code" This option uses the classic decomposition of text characters into Alt-code and their sequential simulation. The Windows API keybd_event() function is invoked over an application tied to a GUI element during the simulation. "hw_scan_virtual" This option draws on the decomposition of characters from the "text" parameter using .xml conversion files from the KeybLayoutTranslate directory. If, for the "kl" parameter, a keyboard layout is set for which there is no KeybLayoutTranslate\00000.xml file, this file needs to be created for that keyboard layout, otherwise the user activity simulation will not work correctly. The keybd_event() function is invoked when simulating the Windows API over an application tied to a GUI element. "standard_alt_code" This option uses the classic decomposition of text characters into Alt-code and their sequential simulation. Messages with WM_KEYDOWN and WM_KEYUP parameters are sent to an application tied to a GUI element via the Windows API PostMessage() function. "standard_scan_virtual" This option draws on the decomposition of characters from the "text" parameter using .xml conversion files from the KeybLayoutTranslate directory. If, for the "kl" parameter, a keyboard layout is set for which there is no KeybLayoutTranslate\00000.xml file, this file needs to be created for that keyboard layout, otherwise the user activity simulation will not work correctly. Messages with WM_KEYDOWN and WM_KEYUP parameters are sent to an application tied to a GUI element via the Windows API PostMessage() function. "wm_char" This option is appropriate when the Keyboard Layout specification is unclear and when characters accessible with different keyboard contexts need to be transferred to an application. Setting this option results only in the direct splitting of the string from the "text" parameter in the simulation. The keyboard layout set in the "kl" parameter is ignored when this simulation mode is used.
kl	String Represents the keyboard layout that is automatically set for an application tied to a GUI element when simulating text input.
focus_action	String The way in which control activation is to be simulated. See set_default_focus_action for options.

Exceptions

ValueError one of the parameters transferred does not have a valid format.

Examples

The example of opening Internet Explorer on the about:blank page, simulating the input of the text https://playground.ultimaterpa.com in the address bar, and going to this page by pressing the Enter key.

app = urpa.exec_ie_app("about:blank")
verify_element = app.find_first(cf.value("about:blank"))
time.sleep(1)
verify_element.send_text("https://playground.ultimaterpa.com")
verify_element.send_key("ENTER")
time.sleep(1)
ready_element = app.find_first(cf.button().name("Continue"))

◆ set_focus()

def urpa.AppElement.set_focus	(	self,
		focus_action = `default_focus_action`
	)

This method sets the focus on this App GUI element.

Parameters

focus_action String The way in which control activation is to be simulated. See set_default_focus_action for options.

◆ size()

def urpa.AppElement.size ( self )

This method returns the size of this App GUI element in the order width, height.

Returns: Returns a tuple containing the size of this App GUI element in the order width, height.

◆ toggle_state()

def urpa.AppElement.toggle_state ( self )

This method returns the value of the "toggle state" attribute of this App GUI element.

The "toggle state" attribute represents the most frequent checkbox check status.

Returns: Returns True if the GUI element is "checked". Returns False if the GUI element is not "checked". Returns None if the GUI element has an indeterminate status or if it does not support this attribute.

◆ value()

def urpa.AppElement.value ( self )

This method returns the value of the "value" attribute of this App GUI element.

Returns: Returns a string containing the value of the "value" attribute of this App GUI element.

◆ visual_data()

def urpa.AppElement.visual_data	(	self,
		rect = `None`,
		format = `"bmp"`
	)

This method creates an image from this App GUI element.

Parameters

rect	a tuple with 4 int-type elements (left, top, right, bottom). Relative coordinates (relative to the upper left corner of the GUI element) to define the clipping. By default, the entire element clipping is used - see bounding_rectangle.
format	String Determines the "bmp" or "png" data format.

Returns: Returns the image in bmp format as a bytearray.

Examples

The example of loading an image using the PIL module (https://python-pillow.org/):

image_data = element_start.visual_data()
image = Image.open(io.BytesIO(image_data))
image.show()

The documentation for this class was generated from the following file:

urpa.py

Public Member Functions

Detailed Description

Member Function Documentation

◆ access_key()

◆ automation_id()

◆ bounding_rectangle()

◆ class_name()

◆ control_type()

◆ enabled()

◆ find_all()

◆ find_all_visual()

◆ find_first()

◆ find_first_down_to()

◆ find_first_left_to()

◆ find_first_right_to()

◆ find_first_up_to()

◆ find_first_visual()

◆ find_from_point()

◆ item_type()

◆ localized_control_type()

◆ name()

◆ parent()

◆ post_message()

◆ selected()

◆ send_key()

◆ send_message()

◆ send_mouse_click()

◆ send_text()

◆ set_focus()

◆ size()

◆ toggle_state()

◆ value()

◆ visual_data()