RPA.Windows library | Robocorp documentation

RPA.Windows

Clear Anchor

Clears control anchor set by Set Anchor

This means that all following keywords accessing elements will use active window or desktop as root element.

Click

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 wait_time:
param locator:	String locator or element object.
	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

Click id:button1 Click id:button2 offset:10,10 ${element}= Click name:SendButton wait_time=5.0

return:	True if close was successful, False if not

Close Window

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

${closed_count} = Close Window Calculator

Control Child Window

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 foreground:
param locator:	string locator or Control element
	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

Control Window subname:"Sage 50" type:Window # actions on the main application window Control Child Window subname:"Test Company" depth:1

Control Window

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 foreground:
param locator:	string locator or Control element
	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

Control Window Calculator Control Window name:Calculator Control Window subname:Notepad Control Window regex:.*Notepad ${window}= Control Window executable:Spotify.exe

Double Click

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 wait_time:
param locator:	String locator or element object.
	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

${element}= Double Click name:ResetButton

Drag And Drop

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 wait_time:
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
	time to wait after drop, default 1.0 seconds

# copying a file, report.html, from source (File Explorer) window Drag And Drop ... name:C:\temp type:Windows > name:report.html type:ListItem ... name:%{USERPROFILE}\Documents\artifacts type:Windows > name:"Items View" ... copy=True

Example:

# moving *.txt files into subfolder within one (File Explorer) window ${source_dir}= Set Variable %{USERPROFILE}\Documents\test Control Window name:${source_dir} ${files}= Find Files ${source_dir}${/}*.txt # first copy files to folder2 FOR ${file} IN @{files} Drag And Drop name:${file.name} name:folder2 type:ListItem copy=True END # second move files to folder1 FOR ${file} IN @{files} Drag And Drop name:${file.name} name:folder1 type:ListItem END

Foreground Window

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

${window}= Foreground Window Calculator

Get Attribute

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 attribute:
param locator:	string locator or Control element
	name of the attribute to get
return:	value of attribute

Examples

${id}= Get Attribute type:Edit name:firstname AutomationId

Get Element

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 search_depth:
param locator:	Locator as a string or as an element object.
	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

*** Tasks *** Set Text Into Notepad Window Windows Run Notepad Control Window subname:Notepad ${element} = Get Element regex:"Text (E|e)ditor" Set Value ${element} note to myself

Example: Python

from RPA.Windows import Windows lib = Windows() lib.windows_run("calc.exe") one_btn = lib.get_element("Calculator > path:2|3|2|8|2") lib.close_window("Calculator")

Get Elements

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 search_depth:
param locator:	Locator as a string or as an element object.
	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

*** Tasks *** Get Headers On Same Level Set Anchor id:DataGrid @{elements} = Get Elements type:HeaderItem FOR ${element} IN @{elements} Log To Console ${element.name} END Get All Calculator Buttons Matching Expression Windows Run Calc Control Window subname:Calc @{buttons} = Get Elements class:Button regex:.*o.* ... siblings_only=${False} Log List ${buttons} ${length} = Get Length ${buttons} Log To Console Number of buttons: ${length}

Get Os Version

Returns the current Windows major version as string.

Examples

${ver} = Get OS Version Log ${ver} # 10

Get Text

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

${date} = Get Text type:Edit name:"Date of birth"

Get Value

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

${value} = Get Value type:DataItem name:column1

Example: Python

from RPA.Windows import Windows lib_win = Windows() text = lib_win.get_value("Rich Text Window") print(text)

List Attributes

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 Windows

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 icon_save_directory:
param icons:	on True dictionary will contain Base64 string of the icon, default False
	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

${windows}= List Windows FOR ${window} IN @{windows} Log Window title:${window}[title] Log Window process name:${window}[name] Log Window process id:${window}[pid] Log Window process handle:${window}[handle] END

Maximize Window

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

${window} = Maximize Window # Current active window Maximize Window executable:Spotify.exe

Middle Click

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 wait_time:
param locator:	String locator or element object.
	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

${element}= Middle Click name:button2

Minimize Window

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

${window} = Minimize Window # Current active window Minimize Window executable:Spotify.exe

Print Tree

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 max_depth:
param locator:	The root of the tree to output.
	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

*** Tasks *** Display Element Structure ${tree} = Print Tree Calculator > path:2|3|2|8 ... return_structure=${True} Log To Console ${tree}

Example: Python

from RPA.Windows import Windows lib = Windows() tree = lib.print_tree("Calculator > path:2|3|2|8", return_structure=True) print(tree)

Restore Window

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

${window} = Restore Window # Current active window Restore Window executable:Spotify.exe

Right Click

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 wait_time:
param locator:	String locator or element object.
	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

${element}= Right Click name:MenuButton

Screenshot

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.

raises ActionNotPossible:
param locator:	String locator or element object.
param filename:	Image file name/path. (can be absolute/relative)
	When the element can't be captured.
returns:	Absolute file path of the taken screenshot image.

Example: Robot Framework

*** Tasks *** Take Screenshots Screenshot desktop desktop.png Screenshot subname:Notepad ${OUTPUT_DIR}${/}notepad.png

Example: Python

from RPA.Windows import Windows lib = Windows() def take_screenshots(): lib.screenshot("desktop", "desktop.png") lib.screenshot("subname:Notepad", "output/notepad.png")

Select

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

System Message: ERROR/3 (<string>, line 17)
Unexpected indentation.

Select id:FontSizeComboBox 22

Example: Python

from RPA.Windows import Windows lib = Windows() def set_notepad_size(): lib.select("id:FontSizeComboBox", "22")

Send Keys

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 wait_time:
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)
	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

Send Keys desktop {Ctrl}{F4} Send Keys keys={Ctrl}{F4} # locator will be NONE, keys sent to desktop Send Keys id:input5 username send_enter=${True} ${element}= Get Element id:pass Send Keys ${element} password send_enter=${True}

Set Anchor

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 Anchor type:Table name:Orders depth:16 FOR ${row} IN RANGE 200 ${number}= Get Value name:number row ${row} Exit For Loop If $number == ${EMPTY} ${sum}= Get Value name:sum row ${row} Log Order number:${number} has sum:{sum} END Clear Anchor

Set Focus

Set view focus to the element defined by the locator.

Arguments

Argument	Type	Default value	Description
locator	WindowsElement, str	null	String locator or element object.

param locator:	String locator or element object.

Examples

Set Focus name:Buy type:Button

Set Global Timeout

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

${old_timeout}= Set Global Timeout 20 ${old_timeout}= Set Global Timeout 9.5

Set Mouse Movement

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

*** Tasks *** Disable Mouse Move ${previous} = Set Mouse Movement ${True} Log To Console Previous mouse simulation: ${previous} (now enabled)

Example: Python

from RPA.Windows import Windows lib_win = Windows() previous = lib_win.set_mouse_movement(True) print(f"Previous mouse simulation: {previous} (now enabled)")

Set Value

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 send_keys_fallback:
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)
	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

*** Tasks *** Set Values In Notepad Set Value type:DataItem name:column1 ab c # Set value to "ab c" # Press ENTER after setting the value. Set Value type:Edit name:"File name:" console.txt enter=${True} # Add newline (manually) at the end of the string. (Notepad example) Set Value name:"Text Editor" abc\n # Add newline with parameter. Set Value name:"Text Editor" abc newline=${True} # Clear Notepad window and start appending text. Set Anchor name:"Text Editor" # All the following keyword calls will use the anchor element as a # starting point, UNLESS they specify a locator explicitly or # Clear Anchor is used. ${time} = Get Time # Clears with append=${False}. (default) Set Value value=The time now is ${time} # Append text and add a newline at the end. Set Value value= and it's the task run time. append=${True} ... newline=${True} # Continue appending and ensure a new line at the end by pressing # the Enter key this time. Set Value value=But this will appear on the 2nd line now. ... append=${True} enter=${True} validator=${None}

Example: Python

from RPA.Windows import Windows lib_win = Windows() locator = "Document - WordPad > Rich Text Window" elem = lib_win.set_value(locator, value="My text", send_keys_fallback=True) text = lib_win.get_value(elem) print(text)

Set Wait Time

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

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 wait_time:
param text:	Text to enter into the Run input field. (e.g. Notepad)
	Time to sleep after the searched app is executed. (3s by default)

Example: Robot Framework

*** Tasks *** Run Notepad Windows Run notepad

Example: Python

from RPA.Windows import Windows lib = Windows() def run_notepad(): lib.windows_run("notepad")

Windows Search

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 wait_time:
param text:	text to enter into search input field
	sleep time after search has been entered (default 3.0 seconds)

Examples

Windows Search Outlook