A class representing a general application. More...

Inheritance diagram for urpa.App:

Public Member Functions
def	find_first (self, condition, timeout=default_timeout)
	This method returns the application's first GUI element that meets the conditions defined in the condition parameter. More...

def	find_all (self, condition, elements=0, timeout=default_timeout)
	This method returns a list of all GUI elements meeting the condition parameter. More...

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

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

def	find_first_down_to (self, condition_reference_element, condition_down_element, timeout=default_timeout, width=50, step=30)
	This method looks for a GUI element matching the condition_down_element parameter and located down from the reference GUI element matching the condition_reference_element parameter. More...

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

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

def	close (self, timeout=600)
	This method closes the application tied to the App class process. More...

def	set_auto_close (self, auto_close)
	This method sets the internal App class flag, according to which the automatic (non-)closure of a process tied to an instance of the App class is controlled at the end of the simulation. More...

def	resize_tp_window (self, condition, rect, timeout=default_timeout)
	This method changes the position and size of a TP window associated with a GUI element matching the condition parameter. More...

def	process_id (self)
	This method returns the ID of a process tied to an instance of the App class. More...

def	process_name (self)
	This method returns the name of a process tied to an instance of the App class. More...

Detailed Description

A class representing a general application.

For GUI element searches, the default setting is the UI Automation interface; for a user interaction simulation, HW actions are the default setting. GUI element searches encompass all "visible" TP windows tied to the process of the running application using the "full search" method. If an application (process) runs another application, you need to create a new instance of the App class to correctly search for GUI elements in the new application, e.g. by using the urpa.find_first_app method.

Notes

GUI element searches are faster if they are sufficiently identified by an exact match.

Member Function Documentation

◆ close()

def urpa.App.close	(	self,
		timeout = `600`
	)

This method closes the application tied to the App class process.

This method first searches for all TP windows tied to instances of this class, specifically to the process representing the application. The method then sends the system message WM_CLOSE to all of the TP windows found. In the second processing stage, the method waits to determine whether the process will end within the time defined in the timeout parameter. If a process does not end within the timeout period, it will be killed. When the simulation ends, the method is invoked automatically over all instances of the App class that have the automatic process closure flag set - see the App.set_auto_close method.

Parameters

timeout int [ms] Maximum time given for the standard termination of the application tied to the class process.

Examples

The example of finding Internet Explorer already running and forcing its closure.

appIE = urpa.find_first_ie_app()

appIE.close()

◆ find_all()

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

This method returns a list of all GUI elements meeting the condition parameter.

The method searches, in iterations with a 50 ms delay, for all GUI elements in all "visible" TP windows tied to an instance of the App class, or to an App class process meeting the condition parameter. In each iteration, the complete GUI element trees created from all TP windows are searched. For applications with a large GUI, the processing time per iteration 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 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 greater than 0 and the required number of GUI elements is not found by the timeout, the urpa.ElementNotFoundError exception is raised. This method does not work on the "counter" principle, and cannot be used to "dynamically" display GUI elements, or cannot be used if the individual GUI elements searched for are displayed only "temporarily" in sequential order. 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 entered, 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 at least two radio_buttons at https://playground.ultimaterpa.com in Internet Explorer within 1,000 ms and listing the attributes of the GUI elements found 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 Continue GUI element
verify_element = app.find_first("Continue")
# find at least two radio_button-type GUI elements
elements = app.find_all(cf.radio_button(), 2, 1000)
# list attributes of the GUI elements found
print(elements)

◆ find_first()

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

This method returns the application's first GUI element that meets the conditions defined in the condition parameter.

This method is most often used to validate the correct GUI status of the controlled application after a previous user interaction to find a GUI element over which user interaction is to be simulated.

   Technically, GUI element searches take place over two stages. In the first stage, all TP windows over a process tied to the App class are retrieved.
   GUI elements are then searched for in these "visible" windows according to the condition defined in the condition parameter. GUI element searches take place in iterations with a 50 ms delay.  The "depth-first search" method is used to search a GUI element tree. For applications with a large GUI, the processing time per iteration 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.
   When identifying GUI elements over applications that create subprocesses, you must verify the linkage between the process and the TP window, or the correct identification of the (sub)process that is tied to an instance of the App class.

   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 entered, 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 opening https://playground.ultimaterpa.com in Internet Explorer, finding an "authentication" GUI element called "Continue".

app = urpa.exec_ie_app("https://playground.ultimaterpa.com")

verify_element = app.find_first("Continue")

◆ find_first_down_to()

def urpa.App.find_first_down_to	(	self,
		condition_reference_element,
		condition_down_element,
		timeout = `default_timeout`,
		width = `50`,
		step = `30`
	)

This method looks for a GUI element matching the condition_down_element parameter and located down from the reference GUI element matching the condition_reference_element parameter.

Searches for GUI elements (both "reference" and "down") take place in iterations with a 50 ms delay over the time specified in the timeout parameter. The two GUI elements to be found ("reference" and "down") must appear at the same time in the same TP window. In the first stage of each iteration, the GUI element is initially searched according to the condition_reference_element term (the App.find_first method is used internally to find this GUI element). Once this reference GUI element is found, the TP window tied to it is transferred to the foreground. The width and step parameters are then used to calculate, over the TP window, the coordinates of the virtual points in which a GUI element matching the condition_down_element parameter is to be found. The virtual points over which a GUI element matching the condition_down_element 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 and the step parameter. 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 elements to be searched for. At the same time, the y-coordinate of each virtual point will be greater than the y-coordinate of the lower edge of the reference GUI element. The first virtual point always has a y-coordinate offset by 5 pixels down from the lower edge of the reference GUI element. The horizontal (x-) coordinate of all virtual points is set to the center of the reference GUI element (width = 50) by default and is always the same for all virtual points. If GUI elements over a large number of virtual points match the condition_down_element parameter at the same time, the GUI element closest to the reference GUI element is returned - see the figure below containing the order of virtual points. If the method could not find the GUI element required, it raises the urpa.ElementNotFoundError exception.

Parameters

condition_reference_element	String or Condition Reference GUI element search term.
condition_down_element	String or Condition The search term for the GUI element located below the reference GUI element.
timeout	int [ms] The maximum time in which a GUI element matching the condition_down_element 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.

Examples

The example of finding a button below the "Normal" text 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 - "Normal" text and find the closest button below this GUI element
found_element = app.find_first_down_to(cf.text().name("Normal"),cf.button())
# list attributes of the GUI element found
print(found_element)

◆ find_first_left_to()

def urpa.App.find_first_left_to	(	self,
		condition_reference_element,
		condition_left_element,
		timeout = `default_timeout`,
		height = `50`,
		step = `30`
	)

This method looks for a GUI element matching the condition_left_element parameter and located to the left of the reference GUI element matching the condition_reference_element parameter.

Searches for GUI elements (both "reference" and "left") take place in iterations with a 50 ms delay over the time specified in the timeout parameter. The two GUI elements to be found ("reference" and "left") must appear at the same time in the same TP window. In the first stage of each iteration, the GUI element is initially searched according to the condition_reference_element condition (the App.find_first method is used internally to find this GUI element). Once this reference GUI element is found, the TP window tied to it is transferred to the foreground. The height and step parameters are then used to calculate, over the TP window, the coordinates of the virtual points in which a GUI element matching the condition_left_element parameter is to be found. The virtual points over which a GUI element matching the condition_left_element 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 and the step parameter. Specifically, the x-coordinate of each virtual point must be greater than the x-coordinate of the left edge of the TP window tied to the GUI elements to be searched for. At the same time, the x-coordinate of each virtual point must be less than the x-coordinate of the left edge of the reference GUI element. The first virtual point always has an x-coordinate offset by 5 pixels to the left of the left edge of the reference GUI element. The vertical (y-) coordinate of all virtual points is set to the center of the reference GUI element (height = 50) by default and is always the same for all virtual points. If GUI elements over a large number of virtual points meet the condition_left_element parameter at the same time, the GUI element furthest from the reference GUI element is returned, unless a GUI element is found over the first virtual point 5 px away from the left edge of the reference GUI element - see the figure below. If the method could not find the GUI element required, it raises the urpa.ElementNotFoundError exception.

Parameters

condition_reference_element	String or Condition Reference GUI element search term.
condition_left_element	String or Condition The search term for the GUI element located to the left of the reference GUI element.
timeout	int [ms] The maximum time in which a GUI element matching the condition_left_element parameter must be retrieved. If this parameter is not entered, 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_left_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.

Examples

The example of finding a radio button to the left of the "Normal" text 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 - "normal" text and find a radio button to the left of this GUI element
found_element = app.find_first_left_to(cf.text().name("Normal"),cf.radio_button())
# list attributes of the GUI element found
print(found_element)

◆ find_first_right_to()

def urpa.App.find_first_right_to	(	self,
		condition_reference_element,
		condition_right_element,
		timeout = `default_timeout`,
		height = `50`,
		step = `30`
	)

This method looks for a GUI element matching the condition_right_element parameter and located to the right of the reference GUI element matching the condition_reference_element parameter.

Searches for GUI elements (both "reference" and "right") take place in iterations with a 50 ms delay over the time specified in the timeout parameter. The two GUI elements to be found ("reference" and "right") must appear at the same time in the same TP window. In the first stage of each iteration, the GUI element is initially searched according to the condition_reference_element term (the App.find_first method is used internally to find this GUI element). Once this reference GUI element is found, the TP window tied to it is transferred to the foreground. The height and step parameters are then used to calculate, over the TP window, the coordinates of the virtual points in which a GUI element matching the condition_right_element parameter is to be found. The virtual points over which a GUI element matching the condition_right_element parameter is to be searched 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 and the step parameter. 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 elements to be searched for. At the same time, the x-coordinate of each virtual point must be greater than the x-coordinate of the right edge of the reference GUI element. The first virtual point always has an x-coordinate offset by 5 pixels to the right of the right edge of the reference GUI element. The vertical (y-) coordinate of all virtual points is set to the center of the reference GUI element (height = 50) by default and is always the same for all virtual points. If GUI elements over a large number of virtual points match the condition_right_element parameter at the same time, the GUI element closest to the reference GUI element is returned. If the method could not find the GUI element required, it raises the urpa.ElementNotFoundError exception.

Parameters

condition_reference_element	String or Condition Reference GUI element search term.
condition_right_element	String or Condition The search term for the GUI element located to the right of the reference GUI element.
timeout	int [ms] The maximum time in which a GUI element matching the condition_right_element parameter must be retrieved. If this parameter is not entered, 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_right_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.

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 - "Normal" radio button and find the closest text to the right of this GUI element
found_element = app.find_first_right_to(cf.radio_button().name("Normal"),cf.text())
# list attributes of the GUI element found
print(found_element)

◆ find_first_up_to()

def urpa.App.find_first_up_to	(	self,
		condition_reference_element,
		condition_up_element,
		timeout = `default_timeout`,
		width = `50`,
		step = `30`
	)

This method looks for a GUI element matching the condition_up_element parameter and located above the reference GUI element matching the condition_reference_element parameter.

Searches for GUI elements (both "reference" and "up") take place in iterations with a 50 ms delay over the time specified in the timeout parameter. The two GUI elements to be found ("reference" and "up") must appear at the same time in the same TP window. In the first stage of each iteration, the GUI element is initially found according to the condition_reference_element term (the App.find_first method is used internally to find this GUI element). Once this reference GUI element is found, the TP window tied to it is transferred to the foreground. The width and step parameters are then used to calculate, over the TP window, the coordinates of the virtual points in which a GUI element matching the condition_up_element parameter is to be found. The virtual points over which a GUI element matching the condition_up_element 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 and the step parameter. Specifically, the y-coordinate of each virtual point must be greater than the y-coordinate of the upper edge of the TP window tied to the GUI elements to be found. At the same time, the y-coordinate of each virtual point will be less than the y-coordinate of the upper edge of the reference GUI element. The first virtual point always has a y-coordinate offset by 5 pixels above the upper edge of the reference GUI element. The horizontal (x-) coordinate of all virtual points is set to the center of the reference GUI element (width = 50) by default and is always the same for all virtual points. If GUI elements over a large number of virtual points match the condition_up_element parameter at the same time, the GUI element farthest from the reference GUI element is returned, unless a GUI element is found over the first virtual point 5 px away from the upper edge of the reference GUI element - see the figure below. If the method could not find the GUI element required, it raises the urpa.ElementNotFoundError exception.

Parameters

condition_reference_element	String or Condition Reference GUI element search term.
condition_up_element	String or Condition The search term for the GUI element located above the reference GUI element.
timeout	int [ms] The maximum time in which a GUI element matching the condition_up_element 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_up_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.

Examples

The example of finding a text above the "Continue" 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 - "Continue" button and find a text from this GUI element
found_element = app.find_first_up_to(cf.button().name("Continue"),cf.text())
# list attributes of the GUI element found
print(found_element)

◆ find_from_point()

def urpa.App.find_from_point	(	self,
		condition_reference_element,
		condition,
		x,
		y,
		timeout = `default_timeout`
	)

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

Searches for GUI elements take place in iterations with a 50 ms delay over the time specified in the timeout parameter. In the first stage of each iteration, the reference GUI element is initially found according to the condition defined in the condition_reference_element parameter (the App.find_first method is used internally). Once the reference GUI element is found, the TP window tied to it is transferred 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 the reference GUI element by x, y that are passed as parameters. If the GUI element over the virtual point matches the condition parameter, it is returned by this method. The two GUI elements to be found ("reference" and "condition") must appear at the same time in the same TP window. If the method could not find any matching GUI element, it raises the urpa.ElementNotFoundError exception.

Parameters

condition_reference_element	String or Condition Reference GUI element search term.
condition	String or Condition Main GUI element search term.
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.
timeout	int [ms] The maximum search time for the main 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 above 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 - "Normal" text and find an image - GUI element in the position specified by offsetting (0,-60) the upper left corner of the GUI element - "Normal" text
found_element = app.find_from_point(cf.text().name("Normal"),cf.image(),0, -60)
# list attributes of the GUI element found
print(found_element)

◆ process_id()

def urpa.App.process_id ( self )

This method returns the ID of a process tied to an instance of the App class.

Returns: Returns a (int) number containing the ID of a process tied to an instance of the App class.

Examples

The example of finding Internet Explorer already running and listing its process ID.

appIE = urpa.find_first_ie_app()

print(appIE.process_id())

◆ process_name()

def urpa.App.process_name ( self )

This method returns the name of a process tied to an instance of the App class.

Returns: Returns a string containing the name of a process tied to an instance of the App class.

Examples

The example of finding Internet Explorer already running and listing its process name.

appIE = urpa.find_first_ie_app()

print(appIE.process_name())

◆ resize_tp_window()

def urpa.App.resize_tp_window	(	self,
		condition,
		rect,
		timeout = `default_timeout`
	)

This method changes the position and size of a TP window associated with a GUI element matching the condition parameter.

In the first processing stage, this method searches for a GUI element that matches the condition parameter with the internal use of the method - see App.find_first. The GUI element found is then used to identify the TP window that is tied to it, and to resize it according to the rect parameter.

Parameters

condition	String or Condition. The condition for finding a TP window, or any GUI element found in a TP window.
rect	a tuple with 4 int-type elements (left, top, right, bottom). It defines the new absolute position of a TP window found on the current desktop.
timeout	int [ms]. Maximum possible time to identify a TP window. If this parameter is not passed, the default value is used - see urpa.default_timeout.

Examples

The example of opening Internet Explorer and resizing its TP window.

app = urpa.exec_ie_app("https://playground.ultimaterpa.com")
newPos = (1, 1, 500, 500)
# wait for the page to load correctly and identify the TP window according to the "Continue" button, resize the TP window found
app.resize_tp_window("Continue",newPos)

◆ set_auto_close()

def urpa.App.set_auto_close	(	self,
		auto_close
	)

This method sets the internal App class flag, according to which the automatic (non-)closure of a process tied to an instance of the App class is controlled at the end of the simulation.

By default, this internal flag value is set to True for App class instances (AppIE, AppExcel) created using the urpa.exec_app, urpa.exec_excel_app, or urpa.exec_ie_app methods, and set to False for App class instances (AppIE, AppExcel) created using the urpa.find_first_app, urpa.find_first_excel_app, or urpa.find_first_ie_app methods.

Parameters

auto_close boolean The setting of a new value for the internal class flag that controls the automatic (non-)closure of a process tied to an instance of the class.

Examples

The example of finding Internet Explorer already running and its automatic closure when the script ends.

appIE = urpa.find_first_ie_app()

appIE.set_auto_close(True)

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

urpa.py

Public Member Functions

Detailed Description

Member Function Documentation

◆ close()

◆ find_all()

◆ find_first()

◆ find_first_down_to()

◆ find_first_left_to()

◆ find_first_right_to()

◆ find_first_up_to()

◆ find_from_point()

◆ process_id()

◆ process_name()

◆ resize_tp_window()

◆ set_auto_close()