Wait for Image Change
Verb: waitImageChange
Available from: <Standard>
Expects an image to change, by analyzing and recognizing changes between images, on a screen or in a user interface control.
Controls are, on Windows, elements that allow the user to interact with an application. Controls can be buttons, data entry fields, menus and various other elements.
You can use this command to leverage surface automation capabilities to your script. For more information, see Actions for surface automation.
Syntax
waitImageChange [--searchonscreen(Boolean)] [--waitsettle(Boolean)] --similarity(Numeric) --timeout(TimeSpan) --interval(TimeSpan) [--region(Rectangle)] --selector(ControlSelectors) [--forcerefresh(Boolean)] --id(String) --name(String) --innertext(String) --tagname(String) --xpath(String) --classname(String) --elementvalue(String) --controltype(Nullable<ControlTypes>) --index(Numeric) --control(Control) [--usetable(Boolean)] [--searchbycolumn(Boolean)] --searchcolumn(String) --searchvalue(String) --returncolumn(String) --row(Numeric) (Boolean)=value
Inputs
| Script | Designer | Required | AcceptedTypes | Description |
|---|---|---|---|---|
| --searchonscreen | Search on Screen | Optional | Boolean | When enabled, it searches for the image on the entire screen. |
| --waitsettle | Wait for Changes to Stop | Optional | Boolean | When enabled, wait until any change is made. |
| --similarity | Similarity Degree | Required | Number | Degree of similarity, as a percentage, when comparing each screen image check or user interface control, to see if there has been a change.
The numerical expression used ranges from 0 to 100. These values correspond to the percentage of 0 to 100% of the image's fidelity. |
| --timeout | Timeout | Required | Time Span | Maximum waiting time to find the image on the screen or in a user interface control.
If no value is defined in the parameter of type timeout, the execution uses the context time defined by the Set Timeout command. If the script does not use this command, the default time is 5 seconds. |
| --interval | Interval | Required | Time Span | Time interval between analyzes performed on the screen or in the user interface control. |
| --region | Region | Optional | Rectangle | Rectangle indicating the region used to analyze and recognize the image.
The rectangle type variable consists of four numbers separated by a comma, corresponding to the values of the sides of the rectangle. |
| --selector | Selector | Required | ControlSelectors | Type of selector used to identify user interface controls. Options:
It is possible to use the IBM RPA Studio's recorder to map the controls and obtain the necessary information from the “Selector” parameter, in addition to inserting commands in the autocomplete script this parameter. The recorder is available in the upper toolbar on the platform. |
| --forcerefresh | Update Screen Cache | Optional | Boolean | Reads the screen again, before executing the command, to identify new elements.
This identification is necessary for the command to work, in case there is any change on the screen. |
| --id | Id | Only whenSelector is Id, IdAndName | Text | User interface control id. |
| --name | Name | Only whenSelector is Name, NameAndValue, IdAndName, TypeAndName | Text | Name of the user interface control. |
| --innertext | Text | Only whenSelector is InnerTextAndTag | Text | Internal text of the user interface control. |
| --tagname | Element Type | Only whenSelector is InnerTextAndTag | Text | Type of the element or tag.
Example: “button”, “text box”. |
| --xpath | XPath | Only whenSelector is XPath | Text | XPath of the user interface control. |
| --classname | Class | Only whenSelector is ClassAndValue, ClassName | Text | User interface control class. |
| --elementvalue | Element Value | Only whenSelector is ClassAndValue, NameAndValue | Text | Current value of the user interface control. |
| --controltype | Type | Only whenSelector is TypeAndIndex, TypeAndName | ControlTypes | Type of UI control. Options:
|
| --index | Index | Only whenSelector is TypeAndIndex | Number | Index of the user interface control. |
| --control | Control | Only whenSelector is Instance | Control | Control instance.
This variable is obtained using the command Search Control. |
| --usetable | Element in Table | Optional | Boolean | When enabled, searches for an element within the table. |
| --searchbycolumn | Search by Column | Optional | Boolean | When enabled, searches for the element through the column, not by row. |
| --searchcolumn | Column | Only whenElement in Table is True | Text | Name or number of the column from which the element must be obtained. |
| --searchvalue | Value | Only whenSearch by Column is True | Text | Value used to find the element in the table. |
| --returncolumn | Return Column | Only whenSearch by Column is True | Text | Column that contains the control. |
| --row | Row | Only whenSearch by Column is False | Number | Table row from which the element is obtained. |
Outputs
| Script | Designer | AcceptedTypes | Description |
|---|---|---|---|
| value | Result | Boolean | Returns "True" if there is a change to the image on the screen or in the user interface control, or "False" if there is no change. |
Example
The Launch and Attach Window command is used to open a Windows CMD window. Then, the Wait for Image Change command is used to analyze and recognize if there were any changes made to the image of the CMD control. After that, a check is carried out: if there were changes to the image, the command "cls" is typed in the CMD to clear the content, with the application being closed.
defVar --name cmdWindow --type Window
defVar --name cmdWindowId --type Numeric
defVar --name imageChanged --type Boolean
launchWindow --executablepath "C:\\Windows\\System32\\cmd.exe" cmdWindow=value cmdWindowId=processId
focusWindow --window ${cmdWindow}
typeText --text "ipconfig/all"
keyboard --type "KeyPress" --key "Return"
// Wait for the image change.
waitImageChange --similarity 100 --timeout 00:00:05 --interval 00:00:05 --selector "XPath" --xpath "/root" imageChanged=value
if --left "${imageChanged}" --operator "Is_True"
focusWindow --window ${cmdWindow}
typeText --text cls
keyboard --type "KeyPress" --key "Return"
closeWindow --window ${cmdWindow}
endIf
logMessage --message "Image has Changed: ${imageChanged}" --type "Info"
// The execution of the command returns the following output:
// Image has Changed: True.
Remarks
It is possible to use the IBM RPA Studio's recorder to obtain the following information: