Python API

Windows

class RPA.Desktop.Windows.Windows(backend: str = 'uia')

Windows is a library for managing the Windows operating system.

DEPRECATION WARNING! USE RPA.Windows library instead.

For Windows desktop automation Robocorp recommends the RPA.Windows library.

No further updates will be released for this library and new functionality will continue to be developed in RPA.Windows library.

Running Windows applications

Windows applications can be started in several ways. The library supports the following keywords:

• Open Application (dispatch Office applications)

• Open File (open the file as process which opens the associated application)

• Open Executable (uses pywinauto start)

• Open Using Run Dialog (uses Windows run dialog)

• Open From Search (uses Windows search dialog)

Locators

Locator is used to identify the element for interaction - usually for a mouse click.

Locators can investigated for application once it has been opened by calling the keyword get_windows_elements which can store locator information into JSON file and screenshot of the element into an image file.

Identifying locator

The element needs to be identified by a unique method, for example, “Three” for button 3 in the Calculator application. It can be given either as Three or name:Three.

Possible search criterias:

• name

• class (class_name)

• type (control_type)

• id (automation_id)

• any if none was defined

The current method of inspecting elements on Windows is inspect.exe which is part of Windows SDK.

Keyboard

The keyword send_keys can be used to send keys to the active window. The keyword type_keys sends keys to the active window element.

Special key codes are documented on pywinauto documentation page.

FAQ

17. I see error message AttributeError: module ‘win32com.gen_py.00020813-0000-0000-C000-000000000046x0x1x9’ has no attribute ‘CLSIDToClassMap’

1. From PowerShell run this command: Remove-Item -path $env:LOCALAPPDATATempgen_py -recurse

Examples

Robot Framework

*** Settings ***
Library          RPA.Desktop.Windows
Suite Teardown   Close all applications

*** Tasks ***
Open Calculator using run dialog
    ${result}=              Open using run dialog    calc.exe   Calculator
    ${result}=              Get Window Elements
    Send Keys               5*2=
    ${result}=              Get element             partial name:Display is
    Log Many                ${result}
    ${result}=              Get element rich text   id:CalculatorResults
    Should Be Equal As Strings  ${result}  Display is 10
    ${result}=              Get element rectangle   partial name:Display is
    ${result}=              Is Element Visible      CalculatorResults
    ${result}=              Is Element Enabled      partial name:Display is

Python

from RPA.Desktop.Windows import Windows

win = Windows()

def open_calculator():
    win.open_from_search("calc.exe", "Calculator")
    elements = win.get_window_elements()

def make_calculations(expression):
    win.send_keys(expression)
    result = win.get_element_rich_text('id:CalculatorResults')
    return int(result.strip('Display is '))

if __name__ == "__main__":
    open_calculator()
    exp = '5*2='
    result = make_calculations(exp)
    print(f"Calculation result of '{exp}' is '{result}'")
    win.close_all_applications()

ROBOT_LIBRARY_DOC_FORMAT = 'REST'

ROBOT_LIBRARY_SCOPE = 'GLOBAL'

boot_time_in_seconds_from_epoch() → str

Get machine boot time

Returns

boot time in seconds from Epoch

Example:

${epoch}  Boot Time In Seconds From Epoch

calculate_rectangle_center(rectangle: Any) → Any

Calculate x and y center coordinates from rectangle.

Parameters

rectangle – element rectangle coordinates

Returns

x and y coordinates of rectangle center

Example:

Open Using Run Dialog   calc  Calculator
&{rect}=        Get Element Rectangle    CalculatorResults
${x}  ${y}=     Calculate Rectangle Center   ${rect}

click_type(x: Optional[int] = None, y: Optional[int] = None, click_type: str = 'click') → None

Mouse click on coordinates x and y.

Default click type is click meaning left

Parameters

• x – horizontal coordinate for click, defaults to None

• y – vertical coordinate for click, defaults to None

• click_type – “click”, “right” or “double”, defaults to “click”

Raises

ValueError – if coordinates are not valid

Example:

Click Type  x=450  y=100
Click Type  x=450  y=100  click_type=right
Click Type  x=450  y=100  click_type=double

close_all_applications() → None

Close all applications

Example:

Open Application   Excel
Open Application   Word
Open Executable    notepad.exe   Untitled - Notepad
Close All Applications

connect_by_handle(handle: int, windowtitle: Optional[str] = None, existing_app: bool = False, parse_elements: bool = True) → Any

Connect to application by its handle

Parameters

• handle – handle of the application

• windowtitle – name of the window, defaults to active window if None

• existing_app – set True if selecting window which library has already accessed, default False

• parse_elements – set False to not to parse elements of the window, default True

Example:

${appid}  Connect By Handle  88112

connect_by_pid(app_pid: str, windowtitle: Optional[str] = None) → Any

Connect to application by its pid

Parameters

• app_pid – process id of the application

• windowtitle – name of the window, defaults to active window if None

Example:

${appid}  Connect By PID  3231

drag_and_drop(src: Any, target: Any, src_locator: str, target_locator: Optional[str] = None, handle_ctrl_key: bool = False, drop_delay: float = 2.0, origin: str = 'middle') → None

Drag elements from source and drop them on target.

Please note that if CTRL is not pressed down during drag and drop then operation is MOVE operation, on CTRL down the operation is COPY operation.

There will be also overwrite notification if dropping over existing files.

Parameters

• src – application object or instance id

• target – application object or instance id

• src_locator – elements to move

• handle_ctrl_key – True if keyword should press CTRL down dragging

• drop_delay – how many seconds to wait until releasing mouse drop, default 2.0

Raises

ValueError – on validation errors

Example:

${app1}=        Open Using Run Dialog    explorer.exe{VK_SPACE}C:\workfiles\movethese   movethese
${app2}=        Open Using Run Dialog    wordpad.exe   Document - WordPad
Drag And Drop   ${app1}   ${app2}   regexp:testfile_\d.txt  name:Rich Text Window   handle_ctrl_key=${True}
Drag And Drop   ${app1}   ${app1}   regexp:testfile_\d.txt  name:subdir  handle_ctrl_key=${True}

find_element(locator: str, search_criteria: Optional[str] = None) → Any

Find element from window by locator and criteria.

Parameters

• locator – name of the locator

• search_criteria – criteria by which element is matched

Returns

list of matching elements and locators that were found on the window

Example:

@{elements}   Find Element   CalculatorResults
Log Many  ${elements[0]}     # list of matching elements
Log Many  ${elements[1]}     # list of all available locators

get_app(app_id: Optional[int] = None) → Any

Get application object by id

By default returns active_application application object.

Parameters

app_id – id of the application to get, defaults to None

Returns

application object

Example:

${app1}        Open Application   Excel
&{appdetails}  Get App   ${app1}

get_boot_time(as_datetime: bool = False, datetime_format: str = '%Y-%m-%d %H:%M:%S') → str

Get computer boot time in seconds from Epoch or in datetime string.

Parameters

• as_datetime – if True returns datetime string, otherwise seconds, defaults to False

• datetime_format – datetime string format, defaults to “%Y-%m-%d %H:%M:%S”

Returns

seconds from Epoch or datetime string

Example:

${boottime}  Get Boot Time
${boottime}  Get Boot Time   as_datetime=True
${boottime}  Get Boot Time   as_datetime=True  datetime_format=%d.%m.%Y

get_dialog_rectangle(ctrl: Optional[Any] = None, as_dict: bool = False) → Any

Get dialog rectangle coordinates

If ctrl is None then get coordinates from dialog

Parameters

ctrl – name of the window control object, defaults to None

Returns

coordinates: left, top, right, bottom

Example:

${left}  ${top}  ${right}  ${bottom}=  Get Dialog Rectangle
&{coords}  Get Dialog Rectangle  as_dict=True
Log  top=${coords.top} left=${coords.left}

get_element(locator: str, screenshot: bool = False, open_dialog: bool = True) → Any

Get element by locator.

Parameters

• locator – name of the locator

• screenshot – takes element screenshot if True, defaults to False

• open_dialog – True if dialog should be reopened, default to True

Returns

element if element was identified, else False

Example:

${element}  Get Element  CalculatorResults
${element}  Get Element  Result      screenshot=True

get_element_center(element: dict) → Any

Get element center coordinates

Parameters

element – dictionary of element items

Returns

coordinates, x and y

Example:

@{element}   Find Element  CalculatorResults
${x}  ${y}=  Get Element Center  ${elements[0][0]}

get_element_rectangle(locator: str, as_dict: bool = False) → Any

Get value of element rectangle attribute.

Parameters

• locator – element locator

• as_dict – return values in a dictionary, default False

Returns

(left, top, right, bottom) values if found, else False

Example:

${left}  ${top}  ${right}  ${bottom}=  Get Element Rectangle  CalculatorResults
&{coords}  Get Element Rectangle  CalculatorResults  as_dict=True
Log  top=${coords.top} left=${coords.left}

get_element_rich_text(locator: str) → Any

Get value of element rich text attribute.

Parameters

locator – element locator

Returns

rich_text value if found, else False

Example:

${text}  Get Element Rich Text  CalculatorResults

get_machine_name() → str

Get machine name

Returns

machine name as string

Example:

${machine}  Get Machine Name

get_memory_stats(humanized: bool = True) → dict

Get computer memory stats and return those in bytes or in humanized memory format.

Parameters

humanized – if False returns memory information in bytes, defaults to True

Returns

memory information in dictionary format

Example:

&{mem}     Get Memory Stats
&{mem}     Get Memory Stats   humanized=False

get_open_applications()

Get list of all open applications

Returns a dictionary

Example:

${app1}    Open Application   Excel
${app2}    Open Executable    calc.exe  Calculator
${app3}    Open File          /path/to/myfile.txt
&{apps}    Get Open Applications

get_spaced_string(text)

Replace spaces in a text with pywinauto.keyboard space characters {VK_SPACE}

Parameters

text – replace spaces in this string

Example:

${txt}    Get Spaced String   My name is Bond
# ${txt} = My{VK_SPACE}name{VK_SPACE}is{VK_SPACE}Bond
Send Keys To Input  ${txt}

get_text(locator: str) → dict

Get text from element

Parameters

locator – element locator

Example:

Open Using Run Dialog  calc     Calculator
Type Into    CalculatorResults   11
Type Into    CalculatorResults   55
&{val}       Get Text   CalculatorResults

get_username() → str

Get username of logged in user

Returns

username as string

Example:

${user}  Get Username

get_window_elements(screenshot: bool = False, element_json: bool = False, outline: bool = False) → Any

Get element information about all window dialog controls and their descendants.

Parameters

• screenshot – save element screenshot if True, defaults to False

• element_json – save element json if True, defaults to False

• outline – highlight elements if True, defaults to False

Returns

all controls and all elements

Example:

@{elements}   Get Window Elements
Log Many      ${elements[0]}     # list of all available locators
Log Many      ${elements[1]}     # list of matching elements
@{elements}   Get Window Elements  screenshot=True  element_json=True  outline=True

get_window_list()

Get list of open windows

Window dictionaries contain:

• automation_id

• control_id

• title

• pid

• handle

• is_active

• keyboard_focus

• rectangle

Returns

list of window dictionaries

Example:

@{windows}    Get Window List
FOR  ${window}  IN  @{windows}
    Log Many  ${window}
END

is_element_enabled(locator: str) → bool

Is element enabled.

Parameters

locator – element locator

Returns

True if enabled, else False

Example:

${res}=   Is Element Enabled  CalculatorResults

is_element_matching(itemdict: dict, locator: str, criteria: str, wildcard: bool = False) → bool

Is element matching. Check if locator is found in any field or criteria field in the window items.

Parameters

• itemDict – dictionary of element items

• locator – name of the locator

• criteria – criteria on which to match element

• wildcard – whether to do reg exp match or not, default False

Returns

True if element is matching locator and criteria, False if not

is_element_visible(locator: str) → bool

Is element visible.

Parameters

locator – element locator

Returns

True if visible, else False

Example:

${res}=   Is Element Visible  CalculatorResults

kill_process(process_name: str) → bool

Kill process by name

Parameters

process_name – name of the process

Returns

True if succeeds False if not

Example:

${process}  Process Exists  calc  strict=False
${status}   Kill Process    ${process.name()}

kill_process_by_pid(pid: int) → None

Kill process by pid

Parameters

pid – process identifier

Example:

${process}  Process Exists  calc  strict=False
${status}   Kill Process By PID   ${process.pid}

lock_screen() → None

Put windows into lock mode

Example:

Lock Screen

log_in(username: str, password: str, domain: str = '.') → str

Log into Windows domain with username and password.

Parameters

• username – name of the user

• password – password of the user

• domain – windows domain for the user, defaults to “.”

Returns

handle

Example:

Log In  username=myname  password=mypassword  domain=company

menu_select(menuitem: str) → None

Select item from menu

Parameters

menuitem – name of the menu item

Example:

Open Using Run Dialog   notepad     Untitled - Notepad
Menu Select             File->Print

minimize_dialog(windowtitle: Optional[str] = None) → None

Minimize window by its title

Parameters

windowtitle – name of the window, default None means that active window is going to be minimized

Example:

Open Using Run Dialog  calc     Calculator
Open Using Run Dialog  notepad  Untitled - Notepad
Minimize Dialog    # Current window (Notepad)
Minimize Dialog    Calculator

mouse_click(locator: Optional[str] = None, x: int = 0, y: int = 0, off_x: int = 0, off_y: int = 0, image: Optional[str] = None, method: str = 'locator', ctype: str = 'click', focus: str = 'center', tolerance: Optional[int] = None) → None

Mouse click locator, coordinates, or image

When using method locator,`image` or ocr mouse is clicked by default at center coordinates.

Click types are:

• click normal left button mouse click

• double

• right

Parameters

• locator – element locator on active window

• x – coordinate x on desktop

• y – coordinate y on desktop

• off_x – offset x (used for locator and image clicks)

• off_y – offset y (used for locator and image clicks)

• image – image to click on desktop

• method – one of the available methods to mouse click, default “locator”

• ctype – type of mouse click

• focus – default point for element click is ‘center’, can be set to ‘topleft’ to click top left corner of the element

• tolerance – image matching tolerance between 0 and 1

Example:

Mouse Click  method=coordinates  100   100
Mouse Click  CalculatorResults
Mouse Click  method=image  image=myimage.png  off_x=10  off_y=10  ctype=right
Mouse Click  method=image  image=myimage.png  tolerance=0.8
${elements}  ${other}=     Find Element  class:Button
FOR  ${element}  IN  @{elements}
    Run Keyword If   ${element}[visible]   Mouse Click  ${element}
END
Mouse Click  id:TrickyCheckbox  focus=topleft

mouse_click_coords(x: int, y: int, ctype: str = 'click', delay_time: Optional[float] = None) → None

Click at coordinates on desktop

Parameters

• x – horizontal coordinate on the windows to click

• y – vertical coordinate on the windows to click

• ctype – click type “click”, “right” or “double”, defaults to “click”

• delay – delay in seconds after, default is no delay

Example:

Mouse Click Coords  x=450  y=100
Mouse Click Coords  x=300  y=300  ctype=right
Mouse Click Coords  x=450  y=100  delay=5.0

mouse_click_image(template: str, off_x: int = 0, off_y: int = 0, ctype: str = 'click', tolerance: Optional[float] = None) → None

Click at template image on desktop

Parameters

• image – image to click on desktop

• off_x – horizontal offset from top left corner to click on

• off_y – vertical offset from top left corner to click on

• ctype – type of mouse click

• tolerance – matching tolerance between 0 and 1

Example:

Mouse Click  image=myimage.png  off_x=10  off_y=10  ctype=right
Mouse Click  image=myimage.png  tolerance=0.8

open_application(application: str) → int

Open application by dispatch method

This keyword is used to launch Microsoft applications like Excel, Word, Outlook and Powerpoint.

Parameters

application – name of the application as str

Returns

application instance id

Example:

${app1}    Open Application   Excel
${app2}    Open Application   Word

open_dialog(windowtitle: Optional[str] = None, highlight: bool = False, timeout: int = 10, existing_app: bool = False, wildcard: bool = False, parse_elements: bool = True) → Any

Open window by its title.

Parameters

• windowtitle – name of the window, defaults to active window if None

• highlight – draw outline for window if True, default False

• timeout – time to wait for dialog to appear

• existing_app – set True if selecting window which library has already accessed, default False

• wildcard – set True for inclusive window title search, default False

• parse_elements – set False to not to parse elements of the window, default True

Example:

Open Dialog       Untitled - Notepad
Open Dialog       Untitled - Notepad   highlight=True   timeout=5
Open Dialog       Notepad   wildcard=True

open_executable(executable: str, windowtitle: str, backend: Optional[str] = None, work_dir: Optional[str] = None, wildcard: bool = False) → int

Open Windows executable. Window title name is required to get handle on the application.

Parameters

• executable – name of the executable

• windowtitle – name of the window

• backend – set Windows backend, default None means using library default value

• work_dir – path to working directory, default None

• wildcard – set True for inclusive window title search, default False

Returns

application instance id

Example:

${app1}    Open Executable   calc.exe  Calculator
${app2}    Open Executable   notepad.exe  Notepad   wildcard=True

open_file(filename: str, windowtitle: Optional[str] = None, wildcard: bool = False, timeout: int = 10) → Optional[int]

Open associated application when opening file

Keyword Open Dialog is used if windowtitle is given.

Parameters

• filename – path to file

• windowtitle – name of the window

• wildcard – set True for inclusive window title search, default False

• timeout – time to wait for dialog to appear

Returns

application id or None

Example:

${app1}    Open File   /path/to/myfile.txt

open_from_search(executable: str, windowtitle: str, timeout: int = 10, wildcard: bool = False) → int

Open application using Windows search dialog. Window title name is required to get handle on the application.

Parameters

• executable – name of the executable

• windowtitle – name of the window

• timeout – time to wait for dialog to appear

• wildcard – set True for inclusive window title search, default False

Returns

application instance id

Example:

${app1}    Open From Search  calculator  Calculator
${app2}    Open From Search  notepad  Notepad  wildcard=True

open_using_run_dialog(executable: str, windowtitle: str, timeout: int = 10, wildcard: bool = False) → int

Open application using Windows run dialog. Window title name is required to get handle on the application.

Parameters

• executable – name of the executable

• windowtitle – name of the window

• timeout – time to wait for dialog to appear

• wildcard – set True for inclusive window title search, default False

Returns

application instance id

Example:

${app1}    Open Using Run Dialog  notepad  Untitled - Notepad
${app2}    Open Using Run Dialog  notepad  Notepad    wildcard=True

process_exists(process_name: str, strict: bool = True) → Any

Check if process exists by its name

Parameters

• process_name – search for this process

• strict – defines how match is made, default True which means that process name needs to be exact match and False does inclusive matching

Returns

process instance or False

Example:

${process}  Process Exists  calc
${process}  Process Exists  calc  strict=False

process_id_exists(pid: int) → Any

Check if process exists by its id

Parameters

pid – process identifier

Returns

process instance or False

Example:

${process}  Process ID Exists  4567
Run Keyword If   ${process}  Log  Process exists

put_system_to_sleep() → None

Put Windows into sleep mode

Example:

Put System To Sleep

quit_application(app_id: Optional[int] = None, send_keys: bool = False) → None

Quit an application by application id or active application if app_id is None.

Parameters

• app_id – application_id, defaults to None

• send_keys – if ALT+F4 should be used to quit, default False

Example:

${app1}   Open Application   Excel
${app2}   Open Application   Word
Quit Application  ${app1}

refresh_window()

Get controls and elements for current windows.

Should be called always when window content changes on Windows desktop.

Returns

controls (list) and elements (list)

restore_dialog(windowtitle: Optional[str] = None) → None

Restore window by its title

Parameters

windowtitle – name of the window, default None means that active window is going to be restored

Example:

Open Using Run Dialog  notepad  Untitled - Notepad
Minimize Dialog
Sleep             1s
Restore Dialog
Sleep             1s
Restore Dialog    Untitled - Notepad

screenshot(filename: str, element: Optional[dict] = None, ctrl: Optional[Any] = None, desktop: bool = False, overwrite: bool = True) → None

Save screenshot into filename.

Parameters

• filename – name of the file

• element – take element screenshot, defaults to None

• ctrl – take control screenshot, defaults to None

• desktop – take desktop screenshot if True, defaults to False

• overwrite – overwrite existing image (deprecated, always True)

Example:

@{element}   Find Element  CalculatorResults
Screenshot   element.png   ${elements[0][0]}
Screenshot   desktop.png   desktop=True
Screenshot   desktop.png   desktop=True  overwrite=True

send_keys(keys: str) → None

Send keys into active windows.

Parameters

keys – list of keys to send

Example:

Open Executable  calc.exe  Calculator
Send Keys        2{+}3{=}

send_keys_to_input(keys_to_type: str, with_enter: bool = True, send_delay: float = 0.5, enter_delay: float = 1.5) → None

Send keys to windows and add ENTER if with_enter is True

At the end of send_keys there is by default 0.5 second delay. At the end of ENTER there is by default 1.5 second delay.

Parameters

• keys_to_type – keys to type into Windows

• with_enter – send ENTER if with_enter is True

• send_delay – delay after send_keys

• enter_delay – delay after ENTER

Example:

${txt}    Get Spaced String   My name is Bond, James Bond
Send Keys To Input  ${txt}    with_enter=False
Send Keys To Input  {ENTER}THE   send_delay=5.0  with_enter=False
Send Keys To Input  {VK_SPACE}-{VK_SPACE}END   enter_delay=5.0

set_automation_speed(speed: Speed = Speed.DEFAULT)

Set global automation timings

Parameters

speed – possible values ‘default’, ‘fast’ or ‘slow’

set_windows_backend(backend: str) → None

Set Windows backend which is used to interact with Windows applications

Allowed values defined by SUPPORTED_BACKENDS

Parameters

backend – name of the backend to use

Example:

Set Windows Backend   uia
Open Executable   calc.exe  Calculator
Set Windows Backend   win32
Open Executable   calc.exe  Calculator

switch_to_application(app_id: int) → None

Switch to application by id.

Parameters

app_id – application’s id

Raises

ValueError – if application is not found by given id

Example:

${app1}    Open Application   Excel
${app2}    Open Application   Word
Switch To Application   ${app1}

type_into(locator: str, keys: str, empty_field: bool = False) → None

Type keys into element matched by given locator.

Parameters

• locator – element locator

• keys – list of keys to type

• empty_field – if field should be emptied before typing, default False

Example:

Open Executable  calc.exe  Calculator
Type Into        CalculatorResults  11
Type Into        CalculatorResults  22  empty_field=True

type_keys(keys: str) → None

Type keys into active window element.

Parameters

keys – list of keys to type

Example:

Open Executable  notepad.exe  Untitled - Notepad
Type Keys   My text

wait_for_element(locator: str, use_refreshing: bool = False, search_criteria: Optional[str] = None, timeout: float = 30.0, interval: float = 2.0) → Any

Wait for element to appear into the window.

Can return 1 or more elements matching locator, or raises ElementNotFoundError if element is not found within timeout.

Parameters

• locator – name of the locator

• use_refreshing – wait for element(s) which are not there yet e.g. listbox item or popups, default False

• search_criteria – criteria by which element is matched

• timeout – defines how long to wait for element to appear, defaults to 30.0 seconds

• interval – how often to poll for element, defaults to 2.0 seconds (minimum is 0.5 seconds)

Example:

@{elements}  Wait For Element  CalculatorResults
@{elements}  Wait For Element  Results   timeout=10  interval=1.5