robocorp-windows
module robocorp.windows
Module used to interact with native widgets on the Windows OS through UI Automation.
This library can be made available by pinning in your dependencies' configuration.
Functions
get_icon_from_file
Provides the icon stored in the file of the given path.
Returns: A PIL image with the icon image or None if it was not possible to load it.
Example:
Example:
desktop
Provides the desktop element (which is the root control containing top-level windows).
The elements provided by robocorp-windows are organized as: Desktop (root control)WindowElement (top-level windows)ControlElement (controls inside a window)
Returns: The Desktop element.
config
Provides an instance to configure the basic settings such as the default timeout, whether to simulate mouse movements, showing verbose errors on failures, screenshot on error (when running with robocorp-tasks), etc.
Returns: Config object to be used to configure the settings.
Example:
find_window
Finds the first window matching the passed locator.
Args:
-
locator
: This is the locator which should be used to find the window. -
search_depth
: The search depth to find the window (by default == 1, meaning that only top-level windows will be found). -
timeout
: The search for a child with the given locator will be retried until the given timeout (in seconds) elapses. At least one full search up to the given depth will always be done and the timeout will only take place afterwards. If not given the global config timeout will be used. -
wait_time
: The time to wait after finding the window. If not passed the default value found in the config is used. -
foreground
: Whether the found window should be made top-level when found. -
raise_error
: Do not raise and returnNone
when this is set toTrue
and such a window isn't found.
Returns:
The WindowElement
which should be used to interact with the window.
Example:
find_windows
Finds all windows matching the given locator.
Args:
-
locator
: The locator which should be used to find windows (if not given, all windows are returned). -
search_depth
: The search depth to be used to find windows (by default equals 1, meaning that only top-level windows will be found). -
timeout
: The search for a child with the given locator will be retried until the given timeout (in seconds) elapses. At least one full search up to the given depth will always be done and the timeout will only take place afterwards. If not given the global config timeout will be used. Only used ifwait_for_window
is True. -
wait_for_window
: Defines whether the search should keep on searching until a window with the given locator is found (note that if True and no window was found a ElementNotFound is raised).
Returns:
The WindowElement
s which should be used to interact with the window.
Example:
wait_for_condition
A helper function to wait for some condition.
Args:
condition
: The condition to be waited for.timeout
: The time to wait for the condition.msg
: An optional message to be shown in the exception if the condition is not satisfied.
Raises:
TimeoutError
: If the condition was not satisfied in the given timeout.
Example:
Class ControlElement
Class used to interact with a control.
__init__
Properties
automation_id
Returns:
The automation id of the underlying control wrapped in this class (matches the locator automationid
or id
).
Note:
This value is cached when the element is created and even if the related value of the underlying control changes the initial value found will still be returned.
bottom
Returns: The bottom bound of the control (-1 if invalid).
Note:
This value is cached when the element is created and even if the related value of the underlying control changes the initial value found will still be returned. The method
update_geometry()
may be used to get the new bounds of the control.
class_name
Returns:
The class name of the underlying control wrapped in this class (matches the locator class
).
Note:
This value is cached when the element is created and even if the related value of the underlying control changes the initial value found will still be returned.
control_type
Returns:
The control type of the underlying control wrapped in this class (matches the locator control
or type
).
Note:
This value is cached when the element is created and even if the related value of the underlying control changes the initial value found will still be returned.
handle
Returns: The internal native window handle from the control wrapped in this class.
height
Returns: The height of the control (-1 if invalid).
Note:
This value is cached when the element is created and even if the related value of the underlying control changes the initial value found will still be returned. The method
update_geometry()
may be used to get the new bounds of the control.
left
Returns: The left bound of the control (-1 if invalid).
Note:
This value is cached when the element is created and even if the related value of the underlying control changes the initial value found will still be returned. The method
update_geometry()
may be used to get the new bounds of the control.
name
Returns:
The name of the underlying control wrapped in this class (matches the locator name
).
Note:
This value is cached when the element is created and even if the related value of the underlying control changes the initial value found will still be returned.
path
Provides the relative path in which this element was found
Note: this is relative to the element which was used for the find
or find_window
and cannot be used as an absolute path to be used to find the control from the desktop.
rectangle
Returns: A tuple with (left, top, right, bottom) -- (all -1 if invalid).
Note:
This value is cached when the element is created and even if the related value of the underlying control changes the initial value found will still be returned. The method
update_geometry()
may be used to get the new bounds of the control.
right
Returns: The right bound of the control (-1 if invalid).
Note:
This value is cached when the element is created and even if the related value of the underlying control changes the initial value found will still be returned. The method
update_geometry()
may be used to get the new bounds of the control.
top
Returns: The top bound of the control (-1 if invalid).
Note:
This value is cached when the element is created and even if the related value of the underlying control changes the initial value found will still be returned. The method
update_geometry()
may be used to get the new bounds of the control.
ui_automation_control
Provides the Control actually wrapped by this ControlElement. Can be used as an escape hatch if some functionality is not directly covered by this class (in general this API should only be used if a better API isn't directly available in the ControlElement).
width
Returns: The width of the control (-1 if invalid).
Note:
This value is cached when the element is created and even if the related value of the underlying control changes the initial value found will still be returned. The method
update_geometry()
may be used to get the new bounds of the control.
xcenter
Returns: The x position of the center of the control (-1 if invalid).
Note:
This value is cached when the element is created and even if the related value of the underlying control changes the initial value found will still be returned. The method
update_geometry()
may be used to get the new bounds of the control.
ycenter
Returns: The y position of the center of the control (-1 if invalid).
Note:
This value is cached when the element is created and even if the related value of the underlying control changes the initial value found will still be returned. The method
update_geometry()
may be used to get the new bounds of the control.
Methods
click
Clicks an element using the mouse.
Args:
locator
: If given the child element which matches this locator will be clicked.search_depth
: Used as the depth to search for the locator (only used if thelocator
is specified).wait_time
: The time to wait after clicking the element. If not passed the default value found in the config is used.timeout
: The search for a child with the given locator will be retried until the given timeout (in seconds) elapses. At least one full search up to the given depth will always be done and the timeout will only take place afterwards. If not given the global config timeout will be used. Only used iflocator
is passed.
Example:
Click using a locator:
Click customizing wait time after the click:
Make an existing window foreground so that it can be clicked:
Returns: The clicked element.
Note:
The element clicked must be visible in the screen, if it's hidden by some other window or control the click will not work.
Raises:
ActionNotPossible
: if element does not allow the Click action.
double_click
Double-clicks an element using the mouse.
Args:
-
locator
: If given the child element which matches this locator will be double-clicked. -
search_depth
: Used as the depth to search for the locator (only used if thelocator
is specified). -
timeout
: The search for a child with the given locator will be retried until the given timeout (in seconds) elapses. At least one full search up to the given depth will always be done and the timeout will only take place afterwards. If not given the global config timeout will be used. Only used iflocator
is passed. -
wait_time
: The time to wait after double-clicking the element. If not passed the default value found in the config is used.
Example:
Double-click using a locator:
Click customizing wait time after the double-click:
Make an existing window foreground so that it can be double-clicked:
Returns: The clicked element.
Note:
The element clicked must be visible in the screen, if it's hidden by some other window or control the double-click will not work.
Raises:
ActionNotPossible
: if element does not allow the double-click action.
find
This method may be used to find a control in the descendants of this control.
The first matching element is returned.
Args:
-
locator
: The locator to be used to search a child control. -
search_depth
: Up to which depth the hierarchy should be searched. -
timeout
: The search for a child with the given locator will be retried until the given timeout (in seconds) elapses. At least one full search up to the given depth will always be done and the timeout will only take place afterwards. If not given the global config timeout will be used. -
raise_error
: Do not raise and returnNone
when this is set toTrue
and such a window isn't found.
Raises:
ElementNotFound
if an element with the given locator could not befound.
find_many
This method may be used to find multiple descendants of the current element matching the given locator.
Args:
-
locator
: The locator that should be used to find elements. -
search_depth
: Up to which depth the tree will be traversed. -
timeout
: The search for a child with the given locator will be retried until the given timeout (in seconds) elapses. At least one full search up to the given depth will always be done and the timeout will only take place afterwards. If not given the global config timeout will be used. Only used ifwait_for_element
is True. -
search_strategy
: The search strategy to be used to find elements.siblings
means that after the first element is found, the tree traversal should be stopped and only sibling elements will be searched.all
means that all the elements up to the given search depth will be searched. -
wait_for_element
: Defines whether the search should keep on searching until an element with the given locator is found (note that if True and no element was found an ElementNotFound is raised).
Note:
Keep in mind that by default the search strategy is for searching
siblings
of the initial element found (so, by default, after the first element is found a tree traversal is not done and only sibling elements from the initial element are found). Use theall
search strategy to search for all elements.
get_parent
Returns: The parent element for this control.
get_text
Get text from element (for elements which allow the GetWindowText action).
Args:
-
locator
: Optional locator if it should target a child element. -
search_depth
: Used as the depth to search for the locator (only used if thelocator
is specified). -
timeout
: The search for a child with the given locator will be retried until the given timeout (in seconds) elapses. At least one full search up to the given depth will always be done and the timeout will only take place afterwards. If not given the global config timeout will be used. Only used iflocator
is given.
Returns: The window text of the element.
Example:
Raises: ActionNotPossible if the text cannot be gotten from this element.
get_value
Get value from element (usually used with combo boxes or text controls).
Args:
-
locator
: Optional locator if it should target a child element. -
search_depth
: Used as the depth to search for the locator (only used if thelocator
is specified). -
timeout
: The search for a child with the given locator will be retried until the given timeout (in seconds) elapses. At least one full search up to the given depth will always be done and the timeout will only take place afterwards. If not given the global config timeout will be used. Only used iflocator
is given.
Returns: The value of the element.
Example:
Raises: ActionNotPossible if the text cannot be gotten from this element.
has_keyboard_focus
Returns: True if this control currently has keyboard focus.
has_valid_geometry
Returns: True if the geometry of this element is valid and False otherwise.
Note:
This value is based on cached coordinates. Call
update_geometry()
to check it based on the current bounds of the control.
inspect
Starts inspecting with this element as the root element upon which other elements will be found (i.e.: only elements under this element in the hierarchy will be inspected, other elements can only be inspected if the inspection root is changed).
Example:
is_disposed
Returns: True if the underlying control is already disposed and False otherwise.
is_same_as
Args:
other
: The element to compare to.
Returns: True if this elements points to the same element representedby the other control.
iter_children
Iterates over all of the children of this element up to the max_depth provided.
Args:
max_depth
: the maximum depth which should be iterated to.
Returns:
An iterator of ControlElement
which provides the descendants ofthis element.
Note:
Iteration over too many items can be slow. Try to keep the max depth up to a minimum to avoid slow iterations.
log_screenshot
Makes a screenshot of the given element and saves it into the log.html
using robocorp-log
. If robocorp-log
is not available returns False.
Args:
-
level
: The log level for the screenshot. -
locator
: Optional locator if it should target a child element. -
search_depth
: Used as the depth to search for the locator (only used if thelocator
is specified). -
timeout
: The search for a child with the given locator will be retried until the given timeout (in seconds) elapses. At least one full search up to the given depth will always be done and the timeout will only take place afterwards. If not given the global config timeout will be used. Only used iflocator
is given.
Returns:
True if the screenshot was successfuly saved using robocorp-log
and False otherwise.
Example:
Raises: ElementNotFound if the locator was passed but it was not possibleto find the element.
middle_click
Middle-clicks an element using the mouse.
Args:
-
locator
: If given the child element which matches this locator will be middle-clicked. -
search_depth
: Used as the depth to search for the locator (only used if thelocator
is specified). -
timeout
: The search for a child with the given locator will be retried until the given timeout (in seconds) elapses. At least one full search up to the given depth will always be done and the timeout will only take place afterwards. If not given the global config timeout will be used. Only used iflocator
is passed. -
wait_time
: The time to wait after middle-clicking the element. If not passed the default value found in the config is used.
Example:
Middle-click using a locator:
Click customizing wait time after the middle-click:
Make an existing window foreground so that it can be middle-clicked:
Returns: The clicked element.
Note:
The element clicked must be visible in the screen, if it's hidden by some other window or control the middle-click will not work.
Raises:
ActionNotPossible
: if element does not allow the middle-click action.
mouse_hover
Moves the mouse to the center of this element to simulate a mouse hovering.
print_tree
Print a tree of control elements.
A Windows application structure can contain multilevel element structure. Understanding this structure is crucial for creating locators. (based on controls' details and their parent-child relationship)
This method can be used to output logs of application's element structure.
The printed element attributes correspond to the values that may be used to create a locator to find the actual wanted element.
Args:
-
stream
: The stream to which the text should be printed (if not given, sys.stdout is used). -
show_properties
: Whether the properties of each element should be printed (off by default as it can be considerably slower and makes the output very verbose). -
max_depth
: Up to which depth the tree should be printed.
Example:
Print the top-level window elements:
Example:
Print the tree starting at some other element:
right_click
Right-clicks an element using the mouse.
Args:
locator
: If given the child element which matches this locator will be right-clicked.search_depth
: Used as the depth to search for the locator (only used if thelocator
is specified).wait_time
: The time to wait after right-clicking the element. If not passed the default value found in the config is used.timeout
: The search for a child with the given locator will be retried until the given timeout (in seconds) elapses. At least one full search up to the given depth will always be done and the timeout will only take place afterwards. If not given the global config timeout will be used. Only used iflocator
is passed.
Example:
Right-click using a locator:
Click customizing wait time after the right-click:
Make an existing window foreground so that it can be right-clicked:
Returns: The clicked element.
Note:
The element clicked must be visible in the screen, if it's hidden by some other window or control the right-click will not work.
Raises:
ActionNotPossible
: if element does not allow the right-click action.
screenshot
Makes a screenshot of the given element and saves it into the given file.
Args:
-
filename
: The file where the image should be saved. -
img_format
: The format in which the image should be saved (by default detects it from the filename). -
locator
: Optional locator if it should target a child element. -
search_depth
: Used as the depth to search for the locator (only used if thelocator
is specified). -
timeout
: The search for a child with the given locator will be retried until the given timeout (in seconds) elapses. At least one full search up to the given depth will always be done and the timeout will only take place afterwards. If not given the global config timeout will be used. Only used iflocator
is given.
Example:
Returns: The absolute path to the image saved or None if it was not possibleto obtain the screenshot.
Raises: ElementNotFound if the locator was passed but it was not possibleto find the element.
screenshot_pil
Makes a screenshot of the given element and returns it as a PIL image.
Args:
-
locator
: Optional locator if it should target a child element. -
search_depth
: Used as the depth to search for the locator (only used if thelocator
is specified). -
timeout
: The search for a child with the given locator will be retried until the given timeout (in seconds) elapses. At least one full search up to the given depth will always be done and the timeout will only take place afterwards. If not given the global config timeout will be used. Only used iflocator
is given.
Example:
Returns: The PIL image if it was possible to do the screenshot or None ifit was not possible to do the screenshot.
Raises: ElementNotFound if the locator was passed but it was not possibleto find the element.
select
Select a value on the passed element if such action is supported.
Args:
-
value
: value to select on element. -
locator
: If given the child element which matches this locator will be used for the selection. -
search_depth
: Used as the depth to search for the locator (only used if thelocator
is specified). -
timeout
: The search for a child with the given locator will be retried until the given timeout (in seconds) elapses. At least one full search up to the given depth will always be done and the timeout will only take place afterwards. If not given the global config timeout will be used. Only used iflocator
is passed.
Returns: The element used in the selection.
Raises:
ActionNotPossible if the element does not allow the Select
action.
Note:
This is usually used with combo box elements.
Example:
send_keys
Sends the given keys to the element (simulates typing keys on the keyboard).
Args:
keys
: The keys to be sent. Special keys may be sent as {Ctrl}{Alt}{Delete}, etc.
Some examples of valid key combinations are shown below:
-
interval
: Time between each sent key. (defaults to 0.01 seconds) -
send_enter
: IfTrue
then the {Enter} key is pressed at the end of the sent keys. -
locator
: If given the child element which matches this locator will be used to send the keys. -
search_depth
: Used as the depth to search for the locator (only used if thelocator
is specified). -
timeout
: The search for a child with the given locator will be retried until the given timeout (in seconds) elapses. At least one full search up to the given depth will always be done and the timeout will only take place afterwards. If not given the global config timeout will be used. Only used iflocator
is passed. -
wait_time
: The time to wait after sending the keys to the element. If not passed the default value found in the config is used.
Returns: The element to which the keys were sent.
Example:
Raises:
ActionNotPossible
: if the element does not allow the SendKeys action.
set_focus
Sets the view focus to the element (or elemen specified by the locator).
Args:
-
locator
: Optional locator if it should target a child element. -
search_depth
: Used as the depth to search for the locator (only used if thelocator
is specified). -
timeout
: The search for a child with the given locator will be retried until the given timeout (in seconds) elapses. At least one full search up to the given depth will always be done and the timeout will only take place afterwards. If not given the global config timeout will be used. Only used iflocator
is given.
Example:
set_value
Set the value in the element (usually used with combo boxes ortext controls).
Args:
Note:
It is important to set
append=True
to keep the current text in the element. Other option is to read the current text into a variable, then modify that value as you wish and pass it toset_value
for a complete text replacement. (without setting theappend
flag). Returns: The element object identified through the passedlocator
or this element if nolocator
was passed.
Raises:
Example:
Example:
update_geometry
This method may be called to update the cached coordinates of the control bounds.
Class Desktop
The desktop is the control, containing other top-level windows.
The elements provided by robocorp-windows are organized as: Desktop (root control)WindowElement (top-level windows)ControlElement (controls inside a window)
__init__
Properties
automation_id
Returns:
The automation id of the underlying control wrapped in this class (matches the locator automationid
or id
).
Note:
This value is cached when the element is created and even if the related value of the underlying control changes the initial value found will still be returned.
bottom
Returns: The bottom bound of the control (-1 if invalid).
Note:
This value is cached when the element is created and even if the related value of the underlying control changes the initial value found will still be returned. The method
update_geometry()
may be used to get the new bounds of the control.
class_name
Returns:
The class name of the underlying control wrapped in this class (matches the locator class
).
Note:
This value is cached when the element is created and even if the related value of the underlying control changes the initial value found will still be returned.
control_type
Returns:
The control type of the underlying control wrapped in this class (matches the locator control
or type
).
Note:
This value is cached when the element is created and even if the related value of the underlying control changes the initial value found will still be returned.
handle
Returns: The internal native window handle from the control wrapped in this class.
height
Returns: The height of the control (-1 if invalid).
Note:
This value is cached when the element is created and even if the related value of the underlying control changes the initial value found will still be returned. The method
update_geometry()
may be used to get the new bounds of the control.
left
Returns: The left bound of the control (-1 if invalid).
Note:
This value is cached when the element is created and even if the related value of the underlying control changes the initial value found will still be returned. The method
update_geometry()
may be used to get the new bounds of the control.
name
Returns:
The name of the underlying control wrapped in this class (matches the locator name
).
Note:
This value is cached when the element is created and even if the related value of the underlying control changes the initial value found will still be returned.
path
Provides the relative path in which this element was found
Note: this is relative to the element which was used for the find
or find_window
and cannot be used as an absolute path to be used to find the control from the desktop.
rectangle
Returns: A tuple with (left, top, right, bottom) -- (all -1 if invalid).
Note:
This value is cached when the element is created and even if the related value of the underlying control changes the initial value found will still be returned. The method
update_geometry()
may be used to get the new bounds of the control.
right
Returns: The right bound of the control (-1 if invalid).
Note:
This value is cached when the element is created and even if the related value of the underlying control changes the initial value found will still be returned. The method
update_geometry()
may be used to get the new bounds of the control.
top
Returns: The top bound of the control (-1 if invalid).
Note:
This value is cached when the element is created and even if the related value of the underlying control changes the initial value found will still be returned. The method
update_geometry()
may be used to get the new bounds of the control.
ui_automation_control
Provides the Control actually wrapped by this ControlElement. Can be used as an escape hatch if some functionality is not directly covered by this class (in general this API should only be used if a better API isn't directly available in the ControlElement).
width
Returns: The width of the control (-1 if invalid).
Note:
This value is cached when the element is created and even if the related value of the underlying control changes the initial value found will still be returned. The method
update_geometry()
may be used to get the new bounds of the control.
xcenter
Returns: The x position of the center of the control (-1 if invalid).
Note:
This value is cached when the element is created and even if the related value of the underlying control changes the initial value found will still be returned. The method
update_geometry()
may be used to get the new bounds of the control.
ycenter
Returns: The y position of the center of the control (-1 if invalid).
Note:
This value is cached when the element is created and even if the related value of the underlying control changes the initial value found will still be returned. The method
update_geometry()
may be used to get the new bounds of the control.
Methods
close_windows
Closes the windows matching the given locator.
Note that by default the process tree will be force-killed by using the pid
associated to the window. use_close_button
can be set to True to try to close it by clicking on the close button (in this case any confirmation dialog must be explicitly handled).
Args:
-
locator
: The locator which should be used to find windows to be closed. -
search_depth
: The search depth to be used to find windows (by default equals 1, meaning that only top-level windows will be closed). Note that windows are closed by force-killing the pid related to the window. -
timeout
: The search for a window with the given locator will be retried until the given timeout (in seconds) elapses. At least one full search up to the given depth will always be done and the timeout will only take place afterwards (ifwait_for_window
is True). Only used ifwait_for_window
is True. If not given the global config timeout will be used. -
wait_for_window
: If True windows this method will keep searching for windows until a window is found or until the timeout is reached (an ElementNotFound is raised if no window was found until the timeout is reached, otherwise an empty list is returned). -
wait_time
: A time to wait after closing each window. -
use_close_button
: If True tries to close the window by searching for a button with the locator: 'control:ButtonControl name:Close' and clicking on it (in this case any confirmation dialog must be explicitly handled). -
close_button_locator
: Only used ifuse_close_button
is True. This is the locator to be used to find the close button.
Returns: The number of closed windows.
Raises:
ElementNotFound
: if wait_for_window is True and the timeout was reached.
drag_and_drop
Drag and drop the source element into target element.
Args:
source
: Source element for the operation.target
: Target element for the operationspeed
: The speed at which the mouse should move to make the drag (1 means regular speed, values bigger than 1 mean that the mouse should move faster and values lower than 1 mean that the mouse should move slower).hold_ctrl
: Whether theCtrl
key should be hold while doing the drag and drop (on some cases this means that a copy of the item should be done).wait_time
: Time to wait after drop, defaults to 1.0 second.
Example:
find_window
Finds windows matching the given locator.
Args:
-
locator
: The locator which should be used to find a window. -
search_depth
: The search depth to be used to find the window (by default equals 1, meaning that only top-level windows will be found). -
timeout
: The search for a child with the given locator will be retried until the given timeout (in seconds) elapses. At least one full search up to the given depth will always be done and the timeout will only take place afterwards. If not given the global config timeout will be used. -
wait_time
: The time to wait after the windows was found. If not given the global config wait_time will be used. -
foreground
: If True the matched window will be made the foreground window. -
raise_error
: Do not raise and returnNone
when this is set toTrue
and such a window isn't found.
Raises:
ElementNotFound
if a window with the given locator could not be found.
find_windows
Finds windows matching the given locator.
Args:
-
locator
: The locator which should be used to find windows (if not given, all windows are returned). -
search_depth
: The search depth to be used to find windows (by default equals 1, meaning that only top-level windows will be found). -
timeout
: The search for a child with the given locator will be retried until the given timeout (in seconds) elapses. At least one full search up to the given depth will always be done and the timeout will only take place afterwards. If not given the global config timeout will be used. Only used ifwait_for_window
is True. -
wait_for_window
: Defines whether the search should keep on searching until a window with the given locator is found (note that if True and no window was found a ElementNotFound is raised).
Returns:
The WindowElement
s which should be used to interact with the window.
Example:
get_win_version
Windows only utility which returns the current Windows major version.
Returns: The current Windows major version (i.e.: '10', '11').
iter_children
Iterates over all of the children of this element up to the max_depth provided.
Args:
max_depth
: the maximum depth which should be iterated to.
Returns:
An iterator of ControlElement
which provides the descendants ofthis element.
Note:
Iteration over too many items can be slow. Try to keep the max depth up to a minimum to avoid slow iterations.
print_tree
Print a tree of control elements.
A Windows application structure can contain multilevel element structure. Understanding this structure is crucial for creating locators. (based on controls' details and their parent-child relationship)
This keyword can be used to output logs of application's element structure.
The printed element attributes correspond to the values that may be used to create a locator to find the actual wanted element.
Args:
-
stream
: The stream to which the text should be printed (if not given, sys.stdout is used). -
show_properties
: Whether the properties of each element should be printed (off by default as it can be considerably slower and makes the output very verbose). -
max_depth
: Up to which depth the tree should be printed.
Example:
Print the top-level window elements:
Example:
Print the tree starting at some other element:
wait_for_active_window
Waits for a window with the given locator to be made active.
Args:
locator
: The locator that the active window must match.timeout
: Timeout (in seconds) to wait for a window with the given locator to be made active.wait_time
: A time to wait after the active window is found.
Raises: ElementNotFound if no window was found as active until the timeoutwas reached.
Note: if there's a matching window which matches the locator but it's not the active one, this will fail (consider using find_window
for this use case).
windows_run
Use Windows Run window
to launch an application.
Activated by pressing Win + R
. Then the app name is typed in and finally the "Enter" key is pressed.
Args:
text
: Text to enter into the Run input field. (e.g.Notepad
)wait_time
: Time to sleep after the searched app is executed. (1s by default)
windows_search
Use Windows search window
to launch application.
Activated by pressing win + s
.
Args:
text
: Text to enter into search input field (e.g.Notepad
)wait_time
: sleep time after search has been entered (default 3.0 seconds)
Class str
str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str
Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to sys.getdefaultencoding(). errors defaults to 'strict'.
Class WindowElement
Class used to interact with a window.
__init__
Properties
automation_id
Returns:
The automation id of the underlying control wrapped in this class (matches the locator automationid
or id
).
Note:
This value is cached when the element is created and even if the related value of the underlying control changes the initial value found will still be returned.
bottom
Returns: The bottom bound of the control (-1 if invalid).
Note:
This value is cached when the element is created and even if the related value of the underlying control changes the initial value found will still be returned. The method
update_geometry()
may be used to get the new bounds of the control.
class_name
Returns:
The class name of the underlying control wrapped in this class (matches the locator class
).
Note:
This value is cached when the element is created and even if the related value of the underlying control changes the initial value found will still be returned.
control_type
Returns:
The control type of the underlying control wrapped in this class (matches the locator control
or type
).
Note:
This value is cached when the element is created and even if the related value of the underlying control changes the initial value found will still be returned.
executable
Returns: The executable associated to this window (or None if it was not possible to get it).
handle
Returns: The internal native window handle from the control wrapped in this class.
height
Returns: The height of the control (-1 if invalid).
Note:
This value is cached when the element is created and even if the related value of the underlying control changes the initial value found will still be returned. The method
update_geometry()
may be used to get the new bounds of the control.
left
Returns: The left bound of the control (-1 if invalid).
Note:
This value is cached when the element is created and even if the related value of the underlying control changes the initial value found will still be returned. The method
update_geometry()
may be used to get the new bounds of the control.
name
Returns:
The name of the underlying control wrapped in this class (matches the locator name
).
Note:
This value is cached when the element is created and even if the related value of the underlying control changes the initial value found will still be returned.
path
Provides the relative path in which this element was found
Note: this is relative to the element which was used for the find
or find_window
and cannot be used as an absolute path to be used to find the control from the desktop.
pid
Provides the pid of the process related to the Window.
Raises: COMError if the window was already disposed.
rectangle
Returns: A tuple with (left, top, right, bottom) -- (all -1 if invalid).
Note:
This value is cached when the element is created and even if the related value of the underlying control changes the initial value found will still be returned. The method
update_geometry()
may be used to get the new bounds of the control.
right
Returns: The right bound of the control (-1 if invalid).
Note:
This value is cached when the element is created and even if the related value of the underlying control changes the initial value found will still be returned. The method
update_geometry()
may be used to get the new bounds of the control.
top
Returns: The top bound of the control (-1 if invalid).
Note:
This value is cached when the element is created and even if the related value of the underlying control changes the initial value found will still be returned. The method
update_geometry()
may be used to get the new bounds of the control.
ui_automation_control
Provides the Control actually wrapped by this ControlElement. Can be used as an escape hatch if some functionality is not directly covered by this class (in general this API should only be used if a better API isn't directly available in the ControlElement).
width
Returns: The width of the control (-1 if invalid).
Note:
This value is cached when the element is created and even if the related value of the underlying control changes the initial value found will still be returned. The method
update_geometry()
may be used to get the new bounds of the control.
xcenter
Returns: The x position of the center of the control (-1 if invalid).
Note:
This value is cached when the element is created and even if the related value of the underlying control changes the initial value found will still be returned. The method
update_geometry()
may be used to get the new bounds of the control.
ycenter
Returns: The y position of the center of the control (-1 if invalid).
Note:
This value is cached when the element is created and even if the related value of the underlying control changes the initial value found will still be returned. The method
update_geometry()
may be used to get the new bounds of the control.
Methods
close_window
Closes the windows matching the given locator.
Note that by default the process tree will be force-killed by using the pid
associated to this window. use_close_button
can be set to True to try to close it by clicking on the close button (in this case any confirmation dialog must be explicitly handled).
Args:
-
use_close_button
: If True tries to close the window by searching for a button with the locator: 'control:ButtonControl name:Close' and clicking on it (in this case any confirmation dialog must be explicitly handled). -
close_button_locator
: Only used ifuse_close_button
is True. This is the locator to be used to find the close button.
Returns: True if the window was closed by this function and False otherwise.
find_child_window
Find a child window of this window given its locator.
Args:
-
locator
: The locator which should be used to find a child window. -
search_depth
: The search depth to be used to find the window. -
timeout
: The search for a child with the given locator will be retried until the given timeout (in seconds) elapses. At least one full search up to the given depth will always be done and the timeout will only take place afterwards. If not given the global config timeout will be used. -
wait_time
: The time to wait after the window was found. If not given the global config wait_time will be used. -
foreground
: If True the matched window will be made the foreground window. -
raise_error
: Do not raise and returnNone
when this is set toTrue
and such a window isn't found.
Raises:
ElementNotFound
if a window with the given locator could not befound.
Example:
foreground_window
Bring this window to the foreground (note: find_window
makes the window the foreground window by default).
Example:
is_active
Returns: True if this is currently the active window and False otherwise.
is_running
Returns: True if the pid associated to this window is still running and False otherwise.
maximize_window
Maximizes the window.
Returns: True if it was possible to maximize the window and False otherwise.
Example:
minimize_window
Maximizes the window.
Returns: True if it was possible to minimize the window and False otherwise.
Example:
restore_window
Restores the window.
Returns: True if it was possible to restore the window and False otherwise.
Example:
set_window_pos
Sets the window position.
Args:
x
: The x-coordinate of the window.y
: The y-coordinate of the window.width
: The width of the window.height
: The height of the window.
Example:
Exceptions
ActionNotPossible
Action is not possible for the given Control.
ElementDisposed
The existing element was disposed and is no longer available.
ElementNotFound
No matching elements were found.
InvalidLocatorError
The locator specified is invalid.
InvalidStrategyDuplicated
A given strategy is defined more than once in the same level.
ParseError
The locator specified is invalid because it was not possible to parse it properly.