Search Control
Searches and returns an instance of a control in an application.
Description
Returns an instance of a control. The control's instance can be used to reference the same UI element in other commands, removing the necessity of referencing the element separately in every command.
One way of searching for UI elements is through selectors. IBM Robotic Process Automation uses selectors to attach windows to the automation context to interact with the window's internal controls. You can find more information about the selectors on Controls and selectors overview.
Another way of searching for UI elements is using the MSAA technology through the Index path parameter. The Index path is based on Microsoft Active Accessibility (MSAA) technology.
You can use it to reference control's trees generated by MSAA.
For more in-depth information about controls, see the Window Automation section.
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.
searchControl [--window(String)] [--indexedpath(String)] [--id(String)] [--name(String)] [--innertext(String)] [--elementvalue(String)] [--classname(String)] [--controltype(String)] [--index(Numeric)] [--width(Numeric)] [--height(Numeric)] [--timeout(TimeSpan)] (Boolean)=success (Control)=value
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 |
|---|---|---|---|---|
| Window | window |
Optional |
Text, Window |
Title of the window, or the window variable. If the field is left blank, the command searches for the closest window related to the context. |
| Index path | indexedpath |
Optional |
Text |
Control's index path. The path of the tree nodes is separated by a comma and each index corresponds to an element. For example, if the index path is 1, 2, it searches for the first element in the parent tree node,
and for the second element in the child tree node. If the element is found, the command will validate any other selectors used. Otherwise, it uses UIAutomation technology instead of MSAA. This parameter also accepts negative values. If -1 is the value entered, the last element of the tree will be fetched.For more information, see Search Control command enables MSAA support. |
| Id | id |
Optional |
Text |
ID of the control that should be found. |
| Name | name |
Optional |
Text |
Name of the control that should be found. |
| Text | innertext |
Optional |
Text |
Inner text of the control that should be found. |
| Element Value | elementvalue |
Optional |
Text |
Element value of the control that should be found. |
| Class | classname |
Optional |
Text |
Class of the control that should be found. |
| Type | controltype |
Optional |
Text |
Type of the control that should be found. |
| Index | index |
Optional |
Number |
Index of the control that should be found. |
| Control Width | width |
Optional |
Number |
Exact width of the control that should be found. This parameter can't be obtained by the recorder, you must use an external tool in order to obtain it. |
| Control Height | height |
Optional |
Number |
The height of the control that should be found. This parameter can't be obtained by the recorder, you must use an external tool in order to obtain it. |
| Timeout | timeout |
Optional |
Time Span, Number, Text |
Maximum time limit to execute the command. If no value is defined, the execution uses the context timeout defined by the Set Timeout ( setTimeout) command.
If that command is not used on the script, the default timeout is 5 seconds. |
AND logical conjunction with the MSAA Index path parameter always being the first one to be evaluated.Output parameter
| Designer mode label | Script mode name | Accepted variable types | Description |
|---|---|---|---|
| Success | success |
Boolean |
Returns True if the control was found. Otherwise, returns False. |
| Control | value |
Control |
Returns the instance of the control. |
Example
Example 1: An instance of Notepad is launched and attached to a variable. Two selectors obtained using the recorder in order to obtain the control. After the control is successfully obtained, the text file is saved on the Desktop.
defVar --name controlInstance --type Control
defVar --name successSearch --type Boolean
defVar --name desktopPath --type String
defVar --name successSave --type Boolean
defVar --name window --type Window
defVar --name processID --type Numeric
// Gets the desktop path.
getSpecialFolder --folder "Desktop" desktopPath=value
// Launches the Notepad application and attaches it to a variable.
launchWindow --executablepath "C:\\Program Files\\Notepad++\\notepad++.exe" --safesearch window=value processID=processId
// Searches for the control based on selectors. In this case, Name and className.
searchControl --window "${window}" --name Save --classname TextBlock --timeout "01:01:00" successSearch=success controlInstance=value
// Checks if the control was successfully found.
if --left "${successSearch}" --operator "Is_True"
click --selector "Instance" --control ${controlInstance}
endIf
// Saves the file in the desktop.
handleSaveFileDialog --filepath "${desktopPath}\\Example.txt" successSave=success
Example 2: An instance of the Microsoft™ Outlook application is launched and attached to a variable. Using the MSAA technology, the Index path parameter of the New Email button is obtained based
on its position inside the application's control tree. In this case, the index path is 2,2,1 since the button is under the menu bar, and the application. It is the second option in the menu bar, and then the first option in the
ribbon menu. After that, the Click (click ) command will click on the button, opening the New Email window.
defVar --name window --type Window
defVar --name processID --type Numeric
defVar --name searchSuccess --type Boolean
defVar --name controlInstance --type Control
// Launches the Outlook application and attaches it to a variable.
launchWindow --executablepath "C:\\Program Files\\Microsoft Office\\root\\Office16\\OUTLOOK.EXE" --safesearch window=value processID=processId
// Searches for the control based on the index path..
searchControl --window "${window}" --id "3,2,1" searchSuccess=success controlInstance=value
// Clicks on the element relative to the index path.
click --selector "Instance" --control ${controlInstance}