Windows Applications¶

Warning

These methods are only supported on Windows OS.

Using the methods below, you will be able to interact with the elements of a running application.

To interact with the elements you can use selectors and specific identifiers. The table below defines the selectors that can be used to connect to an application and filter an element.

Info

The attributes and properties of a Windows application can be viewed using spy tools.

Using the BotCity Studio plugin for Visual Studio Code, you have access to the BotCity Windows Inspector, which has specific features for inspecting Windows applications and generating Python code integrated with the development framework.

See more details about Desktop automation and the use of BotCity Windows Inspector in this tutorial.

Selector	Description
class_name	Elements with this window class
class_name_re	Elements whose class matches this regular expression
parent	Elements that are children of this
process	Elements running in this process
title	Elements with this text
title_re	Elements whose text matches this regular expression
top_level_only	Top level elements only (default=True)
visible_only	Visible elements only (default=True)
enabled_only	Enabled elements only (default=False)
best_match	Elements with a title similar to this
handle	The handle of the element to return
ctrl_index	The index of the child element to return
found_index	The index of the filtered out child element to return
predicate_func	A user provided hook for a custom element validation
active_only	Active elements only (default=False)
control_id	Elements with this control id
control_type	Elements with this control type (string; for `UIAutomation` elements)
auto_id	Elements with this automation id (for `UIAutomation` elements)
framework_id	Elements with this framework id (for `UIAutomation` elements)
backend	Back-end name to use while searching (default=None means current active backend)

Backend¶

The backend type refers to the accessibility technology supported by the application. You can choose between two available backends:

Win32
UIA

When to use each one?¶

Win32 is the backend used by default, it is often used for applications: MFC, VB6, VCL, simple WinForms controls and most old legacy applications.

UIA backend is often used for: WinForms, WPF, Store apps, Qt5 and browsers.

Some applications support both types, but they may perform differently when using them. You can use the spy tools as a reference to define which type is most appropriate for your application. See more details at this link.

Connect to an Application¶

You can connect to an instance of an open application. It is possible to use a combination of selectors and also pass the accessibility technology supported by the application (Backend).

Note

In addition to the above selectors, you can also use some specific connection selectors:

process: Process ID of the target
handle: Window handle of the target
path: Path used to launch the target

PythonJava

from botcity.core import Backend

app_path = "<path to the application .exe>"

# Opens the app.
bot.execute(app_path)

# Connecting to the application using the 'path' and 'title' selectors.
bot.connect_to_app(Backend.WIN_32, path=app_path, title="Main Window Title")

// Not yet implemented.

Connecting from a pywinauto instance¶

If you are already using the pywinauto library and have an instance of an application configured in your code, you can use it alongside the BotCity Desktop Framework.

Just pass your Application or WindowSpecification instance related to the application to the app property of the bot.

PythonJava

from botcity.core import DesktopBot, Backend
from pywinauto.application import Application
from pywinauto import Desktop

# Instantiating DesktopBot
bot = DesktopBot()

# Starting the browser using the 'Application' class from pywinauto
chrome_path = 'C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe'
chrome_app = Application(backend='uia').start(
    chrome_path + ' --force-renderer-accessibility ''https://<URL>'
)
# Setting the `app` property of the DesktopBot using this instance created with pywinauto
bot.app =  chrome_app
...


# Getting the reference to the main window of the calculator
calc_app = Desktop(backend="uia").Calculator
# Setting the `app` property of the DesktopBot using this instance created with pywinauto
bot.app =  calc_app

// Not implemented yet.

Tip

If you use this strategy, you will not need to use the connect_to_app method.

Finding Contexts¶

You can search for application windows and contexts, such as a main window or a more specific one.

PythonJava

# Searching for the main window.
main_window = bot.find_app_window(title_re="Main")

# Searching for some specific window.
popup_window = bot.find_app_window(title="Confirmation Window", class_name="ThunderRT6MDIForm")

// Not yet implemented

Finding Elements¶

You can search for application elements using the general context or a previously found parent context.

PythonJava

# Searching for some specific window.
popup_window = bot.find_app_window(title="Confirmation Window", class_name="ThunderRT6MDIForm")

# Searching for the element that is in the context of the found window.
btn_continue = bot.find_app_element(from_parent_window=popup_window, title="Continue", class_name="ThunderRT6CommandButton")

# Performing some operations with the found element.
btn_continue.click()

// Not yet implemented.

Tip

The ease of inspecting and locating element properties directly depends on the application's structure.

In some cases, to maintain control of the main window after an action in a secondary window, it will be necessary to search again for the reference of the main window to regain control over it.

Info

The Windows Applications module is based on the functionalities of the pywinauto library.

See more details about the methods available for each different type of element at this link.