RPA.Windows
Clears control anchor set by Set Anchor
This means that all following keywords accessing elements will use active window or desktop as root element.
Mouse click on element matching given locator.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WindowsElement, str | null | String locator or element object. |
wait_time | float, None | None | time to wait after click, default is a library wait_time, see keyword Set Wait Time |
timeout | float, None | None | float value in seconds, see keyword Set Global Timeout |
Exception ActionNotPossible is raised if element does not allow Click action.
param locator: | String locator or element object. |
---|---|
param wait_time: | |
time to wait after click, default is a library wait_time, see keyword Set Wait Time | |
param timeout: | float value in seconds, see keyword Set Global Timeout |
return: | WindowsElement object |
Examples
Closes current active window or logs a warning message.
return: | True if close was successful, False if not |
---|
Examples
Closes identified windows or logs the problems.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WindowsElement, str, None | None | String locator or Control element. |
timeout | float, None | None | float value in seconds, see keyword Set Global Timeout |
param locator: | String locator or Control element. |
---|---|
param timeout: | float value in seconds, see keyword Set Global Timeout |
return: | How many windows were found and closed. |
Examples
Get control of child window of the active window by locator.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WindowsElement, str, None | None | string locator or Control element |
foreground | bool | True | True to bring window to foreground |
wait_time | float, None | None | time to wait after activeting a window |
timeout | float, None | None | float value in seconds, see keyword Set Global Timeout |
param locator: | string locator or Control element |
---|---|
param foreground: | |
True to bring window to foreground | |
param wait_time: | |
time to wait after activeting a window | |
param timeout: | float value in seconds, see keyword Set Global Timeout |
return: | WindowsElement object |
Examples
Controls the window defined by the locator.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WindowsElement, str, None | None | string locator or Control element |
foreground | bool | True | True to bring window to foreground |
wait_time | float, None | None | time to wait after activating a window |
timeout | float, None | None | float value in seconds, see keyword Set Global Timeout |
main | bool | True | on True (default) starts the search from desktop level, on False it will continue to search for child elements given the set anchor or current active window |
This means that this window is used as a root element for all the following keywords using locators.
Returns WindowsElement.
param locator: | string locator or Control element |
---|---|
param foreground: | |
True to bring window to foreground | |
param wait_time: | |
time to wait after activating a window | |
param timeout: | float value in seconds, see keyword Set Global Timeout |
param main: | on True (default) starts the search from desktop level, on False it will continue to search for child elements given the set anchor or current active window |
return: | WindowsElement object |
Examples
Double mouse click on element matching given locator.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WindowsElement, str | null | String locator or element object. |
wait_time | float, None | None | time to wait after click, default is a library wait_time, see keyword Set Wait Time |
timeout | float, None | None | float value in seconds, see keyword Set Global Timeout |
Exception ActionNotPossible is raised if element does not allow Click action.
param locator: | String locator or element object. |
---|---|
param wait_time: | |
time to wait after click, default is a library wait_time, see keyword Set Wait Time | |
param timeout: | float value in seconds, see keyword Set Global Timeout |
return: | WindowsElement object |
Examples
Drag and drop the source element into target element.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
source_element | WindowsElement, str | null | |
target_element | WindowsElement, str | null | |
speed | float, None | 1.0 | adjust speed of operation, bigger value means more speed |
copy | bool, None | False | on True does copy drag and drop, defaults to move |
wait_time | float, None | 1.0 | time to wait after drop, default 1.0 seconds |
param source: | source element for the operation |
---|---|
param target: | target element for the operation |
param speed: | adjust speed of operation, bigger value means more speed |
param copy: | on True does copy drag and drop, defaults to move |
param wait_time: | |
time to wait after drop, default 1.0 seconds |
Examples
Example:
Bring the current active window or the window defined by the locator to the foreground.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WindowsElement, str, None | None | string locator or Control element |
param locator: | string locator or Control element |
---|---|
return: | WindowsElement object |
Examples
Get attribute value of the element defined by the locator.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WindowsElement, str | null | string locator or Control element |
attribute | str | null | name of the attribute to get |
param locator: | string locator or Control element |
---|---|
param attribute: | |
name of the attribute to get | |
return: | value of attribute |
Examples
Get a Control Windows element defined by the locator.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WindowsElement, str, None | None | Locator as a string or as an element object. |
search_depth | int | 8 | How deep the element search will traverse. (default 8) |
root_element | WindowsElement, None | None | Will be used as search root element object if provided. |
timeout | float, None | None | After how many seconds (float) to give up on search. (see keyword Set Global Timeout) |
The returned element can be used instead of a locator string for other keywords accepting the locator parameter. Keyword Get Attribute can be used to read element attribute values.
If locator is None, then the returned element will be in this priority:
- root_element if provided.
- Anchor element if that has been previously set with Set Anchor.
- Current active window if that has been set with Control Window.
- Last resort is the "Desktop" element.
param locator: | Locator as a string or as an element object. |
---|---|
param search_depth: | |
How deep the element search will traverse. (default 8) | |
param root_element: | |
Will be used as search root element object if provided. | |
param timeout: | After how many seconds (float) to give up on search. (see keyword Set Global Timeout) |
returns: | The identified WindowsElement object. |
Example: Robot Framework
Example: Python
Get a list of elements matching the locator.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WindowsElement, str, None | None | Locator as a string or as an element object. |
search_depth | int | 8 | How deep the element search will traverse. (default 8) |
root_element | WindowsElement, None | None | Will be used as search root element object if provided. |
timeout | float, None | None | After how many seconds (float) to give up on search. (see keyword Set Global Timeout) |
siblings_only | bool | True | Filter for elements on the same level as the initially found one. Turn it off for a global search. (True by default) |
By default, only the siblings (similar elements on the same level) are taken into account. In order to search globally, turn siblings_only off, but be aware that this will take more time to process. For more details on the rest of parameters, take a look at the Get Element keyword.
param locator: | Locator as a string or as an element object. |
---|---|
param search_depth: | |
How deep the element search will traverse. (default 8) | |
param root_element: | |
Will be used as search root element object if provided. | |
param timeout: | After how many seconds (float) to give up on search. (see keyword Set Global Timeout) |
param siblings_only: | |
Filter for elements on the same level as the initially found one. Turn it off for a global search. (True by default) | |
returns: | A list of matching WindowsElement objects. |
Example: Robot Framework
Returns the current Windows major version as string.
Examples
Get text from Control element defined by the locator.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WindowsElement, str | null | String locator or element object. |
Exception ActionNotPossible is raised if element does not allow GetWindowText action.
param locator: | String locator or element object. |
---|---|
return: | value of WindowText attribute of an element |
Examples
Get the value of the element defined by the provided locator.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WindowsElement, str | null | String locator or element object. |
The ActionNotPossible exception is raised if the identified element doesn't support value retrieval.
param locator: | String locator or element object. |
---|---|
returns: | Optionally the value of the identified element. |
Example: Robot Framework
Example: Python
List all element attributes.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WindowsElement, str | null | string locator or Control element |
param locator: | string locator or Control element |
---|---|
return: | list of element attributes (strings) |
List all window element on the system.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
icons | bool | False | on True dictionary will contain Base64 string of the icon, default False |
icon_save_directory | str, None | None | if set will save retrieved icons into this filepath, by default icon files are not saved |
param icons: | on True dictionary will contain Base64 string of the icon, default False |
---|---|
param icon_save_directory: | |
if set will save retrieved icons into this filepath, by default icon files are not saved | |
return: | list of dictionaries containing information about Window elements |
Examples
Maximize the current active window or the window defined by the locator.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WindowsElement, str, None | None | string locator or element |
param locator: | string locator or element |
---|---|
return: | WindowsElement object |
Examples
Right mouse click on element matching given locator.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WindowsElement, str | null | String locator or element object. |
wait_time | float, None | None | time to wait after click, default is a library wait_time, see keyword Set Wait Time |
timeout | float, None | None | float value in seconds, see keyword Set Global Timeout |
Exception ActionNotPossible is raised if element does not allow Click action.
param locator: | String locator or element object. |
---|---|
param wait_time: | |
time to wait after click, default is a library wait_time, see keyword Set Wait Time | |
param timeout: | float value in seconds, see keyword Set Global Timeout |
return: | WindowsElement object |
Examples
Minimize the current active window or the window defined by the locator.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WindowsElement, str, None | None | string locator or element |
param locator: | string locator or element |
---|---|
return: | WindowsElement object |
Examples
Print a tree of control elements.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WindowsElement, str, None | None | The root of the tree to output. |
max_depth | int | 8 | Maximum depth level. (defaults to 8) |
capture_image_folder | str, None | None | If set, controls' images will be captured in this path. |
log_as_warnings | bool | False | Enables highlighted logs (at the beginning of the log file as warnings) and increases visibility in the output console. |
return_structure | bool | False | A flattened tree with all the elements collated by level will be returned if this is enabled. |
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, starting with the element defined by the provided locator as root. Switch the return_structure parameter to True to get a tree of elements returned as well. (off by default to save memory)
- The printed structure displays a tree prefixed with "depth" - "position" so you know how deep (0 means root) in the tree you are and on what position (1-indexed) the child you're looking for is.
- The returned structure is a dictionary with all the children flattened per depth level. Additionally, these WindowsElement objects contain a relevant locator composed of "root > path" which will help to identify the element in the tree.
Portal example: https://robocorp.com/portal/robot/robocorp/example-windows-element-path
param locator: | The root of the tree to output. |
---|---|
param max_depth: | |
Maximum depth level. (defaults to 8) | |
param capture_image_folder: | |
If set, controls' images will be captured in this path. | |
param log_as_warnings: | |
Enables highlighted logs (at the beginning of the log file as warnings) and increases visibility in the output console. | |
param return_structure: | |
A flattened tree with all the elements collated by level will be returned if this is enabled. | |
returns: | Optionally a dictionary of children per depth level when return_structure is enabled. |
Example: Robot Framework
Example: Python
Window restore the current active window or the window defined by the locator.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WindowsElement, str, None | None | string locator or element |
param locator: | string locator or element |
---|---|
return: | WindowsElement object |
Examples
Right mouse click on element matching given locator.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WindowsElement, str | null | String locator or element object. |
wait_time | float, None | None | time to wait after click, default is a library wait_time, see keyword Set Wait Time |
timeout | float, None | None | float value in seconds, see keyword Set Global Timeout |
Exception ActionNotPossible is raised if element does not allow Click action.
param locator: | String locator or element object. |
---|---|
param wait_time: | |
time to wait after click, default is a library wait_time, see keyword Set Wait Time | |
param timeout: | float value in seconds, see keyword Set Global Timeout |
return: | WindowsElement object |
Examples
Take a screenshot of the element defined by the locator.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WindowsElement, str | null | String locator or element object. |
filename | str, Path | null | Image file name/path. (can be absolute/relative) |
An ActionNotPossible exception is raised if the element doesn't allow being captured.
param locator: | String locator or element object. |
---|---|
param filename: | Image file name/path. (can be absolute/relative) |
raises ActionNotPossible: | |
When the element can't be captured. | |
returns: | Absolute file path of the taken screenshot image. |
Example: Robot Framework
Example: Python
Select a value on the passed element if such action is supported.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WindowsElement, str | null | String locator or element object. |
value | str | null | String value to select on Control element |
The ActionNotPossible exception is raised when the element does not allow the Select action. This is usually used with combo box elements.
param locator: | String locator or element object. |
---|---|
param value: | String value to select on Control element |
returns: | The controlled Windows element. |
Example: Robot Framework
* Settings * Library RPA.Windows
* Tasks * Set Notepad Size
Select id:FontSizeComboBox 22
Example: Python
Send keys to desktop, current window or to Control element defined by given locator.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WindowsElement, str, None | None | Optional string locator or element object. |
keys | str, None | None | The keys to send. |
interval | float | 0.01 | Time between each sent key. (defaults to 0.01 seconds) |
wait_time | float, None | None | Time to wait after sending all the keys. (defaults to library's set value, see keyword Set Wait Time) |
send_enter | bool | False | If True then the {Enter} key is pressed at the end of the sent keys. |
If locator is None then keys are sent to desktop.
Exception ActionNotPossible is raised if element does not allow SendKeys action.
param locator: | Optional string locator or element object. |
---|---|
param keys: | The keys to send. |
param interval: | Time between each sent key. (defaults to 0.01 seconds) |
param wait_time: | |
Time to wait after sending all the keys. (defaults to library's set value, see keyword Set Wait Time) | |
param send_enter: | |
If True then the {Enter} key is pressed at the end of the sent keys. | |
returns: | The element identified through locator. |
Examples
Set anchor to an element specified by the locator.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WindowsElement, str | null | string locator or Control element |
timeout | float, None | None | timeout in seconds for element lookup (default 10.0) |
All following keywords using locators will use this element as a root element. Specific use case could be setting anchor to TableControl element and then getting column data belonging to that TableControl element.
To release anchor call Clear Anchor keyword.
param locator: | string locator or Control element |
---|---|
param timeout: | timeout in seconds for element lookup (default 10.0) |
Examples
Set global timeout for element search. Applies also to Control Window keyword.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
timeout | float | null | float value in seconds |
By default, the library has a timeout of 10 seconds.
param timeout: | float value in seconds |
---|---|
return: | previous timeout value |
Examples
Enable or disable mouse movement simulation during clicks and other actions.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
simulate | bool | null | Decide whether to simulate the move. (OFF by default) |
Returns the previous set value as True/False.
param simulate: | Decide whether to simulate the move. (OFF by default) |
---|---|
returns: | Previous state. |
Example: Robot Framework
Example: Python
Set value of the element defined by the locator.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WindowsElement, str, None | None | String locator or element object. |
value | str, None | None | String value to be set. |
append | bool | False | False for setting the value, True for appending it. (OFF by default) |
enter | bool | False | Set it to True to press the Enter key at the end of the input. (nothing is pressed by default) |
newline | bool | False | Set it to True to add a new line at the end of the value. (no EOL included by default; this won't work with send_keys_fallback enabled) |
send_keys_fallback | bool | True | Tries to set the value by sending it through keys if the main way of setting it fails. (enabled by default) |
validator | Callable, None | Function receiving two parameters post-setting, the expected and the current value, which returns True if the two values match. (by default, the keyword will raise if the values are different, set this to None to disable validation or pass your custom function instead) |
Note: An anchor will work only on element structures where you can rely on the stability of that root/child element tree, as remaining the same. Usually these kind of structures are tables. (but not restricted to)
Note: It is important to set append=${True} if you want 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 to the Set Value keyword for a complete text replacement. (without setting the append flag)
The following exceptions may be raised:
- ActionNotPossible if the element does not allow the SetValue action to be run on it nor having send_keys_fallback=${True}.
- ValueError if the new value to be set can't be set correctly.
param locator: | String locator or element object. |
---|---|
param value: | String value to be set. |
param append: | False for setting the value, True for appending it. (OFF by default) |
param enter: | Set it to True to press the Enter key at the end of the input. (nothing is pressed by default) |
param newline: | Set it to True to add a new line at the end of the value. (no EOL included by default; this won't work with send_keys_fallback enabled) |
param send_keys_fallback: | |
Tries to set the value by sending it through keys if the main way of setting it fails. (enabled by default) | |
param validator: | |
Function receiving two parameters post-setting, the expected and the current value, which returns True if the two values match. (by default, the keyword will raise if the values are different, set this to None to disable validation or pass your custom function instead) | |
returns: | The element object identified through the passed locator. |
Example: Robot Framework
Example: Python
Set library wait time for action keywords.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
wait_time | float | null | float value (in seconds), e.g. 0.1 |
The wait_time is spent after each keyword performing mouse or keyboard action.
Library default wait_time is 0.5
Returns value of the previous wait_time value.
param wait_time: | |
---|---|
float value (in seconds), e.g. 0.1 | |
return: | previous wait value |
Examples
Use Windows Run window to launch an application.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
text | str | null | Text to enter into the Run input field. (e.g. Notepad) |
wait_time | float | 3.0 | Time to sleep after the searched app is executed. (3s by default) |
Activated by pressing Win + R. Then the app name is typed in and finally the "Enter" key is pressed.
param text: | Text to enter into the Run input field. (e.g. Notepad) |
---|---|
param wait_time: | |
Time to sleep after the searched app is executed. (3s by default) |
Example: Robot Framework
Example: Python
Use Windows search window to launch application.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
text | str | null | text to enter into search input field |
wait_time | float | 3.0 | sleep time after search has been entered (default 3.0 seconds) |
Activated by pressing win + s.
param text: | text to enter into search input field |
---|---|
param wait_time: | |
sleep time after search has been entered (default 3.0 seconds) |