Quickstart

Getting started with robocorp.windows is as simple as:

Now, if we put this in a Task/Action Package, we could save a tasks.py file with the following content:

Locators

One of the key concepts in the library are locators. A locator is a string which identifies how to reach a given element to interact with. This string can have multiple entries separated by spaces such as:

<property_name>:"<property value>" <property_name>:"<property value>"

Note: if the <property value> itself doesn't have spaces the " is not needed.

It's also possible to consider the parent/child hierarchy so that multiple matches are done when using >. Example: name:Calculator > class:TextBlock.

Also, it's possible to use or constructs to create more advanced matches. Example: (name:0 or name:Zero) and class:Button. Note: > must always be top-level and may not appear inside an or.

The property names available for matching are:

• name: identifies a target window/control by its name. Example: name:"My Window".

• regex: identifies a target window/control by its name matching using a regexp. Example: regex:".*Calc.*".

• subname identifies a target window/control by its name matching using the in operator. Example: subname:cal".

• class: identifies a target window/control by its class. Example: class:Button, class:TextBlock.

• control (may also be used as type): identifies a target window/control by its type. Example: control:ButtonControl, type:ButtonControl.

• id (may also be used as automationid): identifies a target window/control by its automation id. Example: id:"open button".

• executable: identifies a target window by its executable name (may be the full path or just basename). Example: executable:notepad.exe)

• handle: the target window handle. Example: handle:21345.

• path: identifies a target element by its index-based path traversal from the parent. Example path:2|3|8|2.

• depth: identifies a target element by its depth from the parent. Example depth:2.

It's also possible to get an element and then go deeper in the structure to have the same result.

i.e.: Using:

is the same as:

In general the recommended approach is getting the top-level window of interest with windows.find_window and then getting sub-elements as needed (and if multiple elements have the same parent, first finding the parent and then getting children elements from that parent for faster access).

Note: when querying the information, APIs may have a search_depth or max_depth parameter which can be specified to determine up to which depth a given element may be found. It's not recommended to have a big depth value as bigger depths mean that more items have to be traversed to find an element which can make such searches slower (so, more queries with a shalower depth is recommended over less queries with a bigger depth).

Working with locators in robocorp-windows

The term locator means a string which identifies how to reach an element in the application UI structure.

In the context of robocorp-windows it'll identify how to reach a window or some element inside the window (such as a combo box, text edit, etc).

With robocorp-windows, a basic inspector which can be used to identify the values which can be used in locators as well as testing locators can be used with the inspect() method for some element.

To start from the desktop, the API used would be:

Then, using the select window (activated with s:<optional window-related name> -- i.e.: s:note to filter for windows with note in the name) can be used to inspect elements inside a given window (follow the text prompts to know what's available).

After you have the locator for the window, it's recommended to start from the window directly:

Example with Notepad++:

Usually the most useful approach is then asking for the highlight mouse (activated with m) and then hovering over the element of interest -- after a timeout with the mouse in the same position the related element should be highlighted and the information available to be used to reach it will be printed to the output.

Example:

Hovering over the record button of Notepad++ will print something as:

In this case some valid locators to reach it could be:

• name:"Start Recording"
• control:ButtonControl
• class:ToolbarWindow32 > control:ButtonControl and name:"Start Recording"
• path:5|1|35

Note that it's important to select a locator that will uniquely identify the element (so, for instance the control:ButtonControl may not be ideal because it may match other buttons in the UI).

Also, it's important to note that when a given element is printed, in the inspector you can interact with it to know whether it's actually valid, so, for instance, it's possible to test a locator with:

to see which elements would be selected by it.

For the particular case of Notepad++, you may notice that doing something as h:name:"Start Recording" may fail to actually highlight any element.

In the Notepad++ case this happens because the buttons in the toolbar will only be accessible when the mouse is hovering over the toolbar.

In this case, the code to successfully access it would need to first hover over the toolbar:

Also note that if you're targetting multiple versions of some application, it's possilbe to use more advanced expressions with or and and conditions (by default the and is not needed as a space will mean and implicitly).

For instance, the windows calculator has different ways to reach buttons depending on the Windows version, on some versions the name to reach it would be name:0 or name:Zero. In this case it'd be possible to write a locator such as class:Button and (name:0 or name:Zero).

Special keys

It's possible to send special keys (using the send_keys method) by wrapping the related code below with {} (Example: {Ctrl}, {Enter}).