Find Window
Finds a window that is not currently being automated and attaches it to the automation context.
Command availability: IBM RPA SaaS and IBM RPA on premises
Description
The command identifies a specific window that is not currently being automated, assigns it to a variable and attaches it to the automation context. Allowing the bot to interact with the identified window.
Script syntax
IBM RPA's proprietary script language has a syntax similar to other programming languages. The script syntax defines the command's syntax in the script file. You can work with this syntax in IBM RPA Studio's Script mode.
findWindow [--useregex(Boolean)] [--title(String)] --regexPattern(String) [--regexOptions(DisplayableRegexOptions)] [--id(String)] [--classname(String)] [--processid(Numeric)] [--processname(String)] [--byparent(Boolean)] [--window(Window)] [--recursive(Boolean)] [--safesearch(Boolean)] [--styles(Nullable<AutomationWindowStyles>)] [--minimumheight(Numeric)] [--minimumwidth(Numeric)] (Window)=value (Numeric)=processId (Boolean)=success
Dependencies
At least one of the following parameters is required:
- Title
- Identifier
- Class Name
- Process Id
- Process Name
- Styles
- Minimum Height
- Minimum Width
Input parameter
The following table displays the list of input parameters available in this command. In the table, you can see the parameter name when working in IBM RPA Studio's Script mode and its Designer mode equivalent label.
Designer mode label | Script mode name | Required | Accepted variable types | Description |
---|---|---|---|---|
Use Regular Expression | useregex |
Optional |
Boolean |
Enable to use a regular expression to find the window. |
Title | title |
Optional |
Text |
Title of the window to be found. |
Regular Expression | regexPattern |
Only when Use Regular Expression is True |
Text |
Regular expression used to search for the window. |
Options | regexOptions |
Optional |
DisplayableRegexOptions |
Filters the search for matches by using the regular expression. See the regexOptions parameter options for more details. |
Identifier | id |
Optional |
Text |
Id of the window to be found. |
Class Name | classname |
Optional |
Text |
Class name of the window to be found. |
Process Id | processId |
Optional |
Number |
Id of the process to which the window belongs. |
Process Name | processname |
Optional |
Text |
Name of the process to which the window belongs. |
Search in attached window | byparent |
Optional |
Boolean |
Enable to allow searching for child windows of an attached window. |
Window | window |
Optional |
Window |
The main window within which to find a child window. |
Recursive | recursive |
Optional |
Boolean |
Enable to search for windows within windows. |
Safe Search | safesearch |
Optional |
Boolean |
Enable to use a higher performance search algorithm. |
Styles | styles |
Optional |
AutomationWindowStyles |
The style of the window to be found. See the styles parameter options for more details. |
Minimum Height | minimumheight |
Optional |
Number |
Minimum height of the window to be found. |
Minimum Width | minimumwidth |
Optional |
Number |
Minimum width of the window to be found. |
regexOptions
parameter options
The following table displays the options available for the regexOptions
input parameter. The table shows the options available when working in Script mode and the equivalent label in the Designer mode.
Designer mode label | Script mode name | Description |
---|---|---|
Compiled | Compiled |
Compile regex expressions instead of interpreting. |
Culture Invariant | CultureInvariant |
Ignore cultural differences in language. |
ECMA Script | ECMAScript |
Interprets ECMA Script expressions. |
Ignore Case | IgnoreCase |
Case-insensitive search. |
Explicit Capture | ExplicitCapture |
The only valid captures are explicitly named or numbered groups of the form (?<name> subexpression ). |
Ignore Pattern Whitespace | IgnorePatternWhitespace |
Ignore whitespace characters, and enable comments after a number sign (#). |
Right To Left | RightToLeft |
Read regex expressions from right to left, or from last to first. |
Singleline | Singleline |
Changes the meaning of the dot (.), which matches every character except . |
Multiline | Multiline |
Allows the caret (^) and dollar sign ($) symbols to match newline characters. |
styles
parameter options
The following table displays the options available for the styles
input parameter. The table shows the options available when working in Script mode and the equivalent label in the Designer mode.
Designer mode label | Script mode name | Description |
---|---|---|
Child | Child |
Indicates that you are looking for a child window within the context of a main window. |
Dialog | Dialog |
Indicates that you are looking for a dialog window. |
Output parameter
Designer mode label | Script mode name | Accepted variable types | Description |
---|---|---|---|
Window | value |
Window |
Returns the found window. |
Process Id | processId |
Number |
Returns the process Id. |
Success | success |
Boolean |
Returns True if the window was successfully found, and False otherwise. |
Example
The following code example demonstrates how to use the Find Window command to locate a Notepad window that was opened by the Launch and Attach Window (launchWindow
)
command.
defVar --name foundWindow --type Boolean
defVar --name Id --type Numeric
launchWindow --executablepath "notepad.exe" Id=processId
findWindow --processid ${Id} foundWindow=success
logMessage --message "Result found the window: ${foundWindow}" --type "Info"
// Displays on the console whether or not the window was found.
Limitations
-
If the command does not find the window, the bot continues manipulating the currently attached window.
-
This command cannot be used with Universal Windows Platform (UWP) apps on Microsoft™ Windows 11 operating system.
-
When you are using the command on a dynamic webpage subject to JavaScript-based modifications in Windows Server 2016, cached elements are not reflecting the updated window elements tree due to Win32 drivers being used in non-Windows applications. Use the Verify enabled (
veryEnabled
) command with the forcerefresh parameter enabled to properly load the window element tree.