MiniRobotLanguage (MRL)
WRA. Wait-Command
Wait until something in a rectangular area has changed
Intention
These command is just for these cases where all other commands do fail.
RRA. will store a copy (a Screenshot) of the window or a part of it.
WRA. will pause your Script as long as the stored Area "did not change".
This way you can wait until a program GUI reacts, even if you can not read any of the GUI Output in conventional way using other commands.
The first three possible parameters are Color-Tolerance and Hit-Counter.
The fourth Parameter is an optional Timeout in seconds.
Parameter 1 - Color Tolerance:
If there are different graphic cards used, the pixels may not become rendered always in the exactly same way. Therefore the color tolerance gives you the chance to tell the robot "How sensitive" he should be when deciding if a pixel is different or not.
To make this decision, the robot will take the color of both pixels and calculate their "Color distance", that is "How similar the colors are". As a result he will get a number that can vary from 0 to 441673. Next Smart Package Robot will get your tolerance value and check if the calculated color distance is inside the chosen tolerance or not.
Parameter 2 - Hits-Counter:
Imagine a Textbox like this:
You want to wait until there is a text inside, but the blinking cursor should not make your Script react. Now what you tell Smart Package Robot is a "Hit Count" of lets say 100 Pixels.
STW.ct|MyClassName|Sample Application
SCW.nct|1|Edit|{&NOTEXT:}
RRA.
PAU..1
WRA.0|100
ENR.
This makes Smart Package Robot count the changed pixels, and only if she gets more then "Hit Count" she will switch. Otherwise the condition will not become true, even if there are changed pixels (but less).
Parameter 3 - Wait-Timeout:
Imagine there is an Error somewhere in the target application. The reaction you are waiting for will never happen. This could make your script hang forever!
To avoid this, you have an "Timeout Option".
If you write an number here, it is a Timeout-Time in Seconds.
After this time has elapsed, the command will let the robot continue running, even if there has not been the change we have been waiting for.
In this case, the "Timeout Flag" will be set. In the normal case, the timeout flag will be cleared.
STW.ct|MyClassName|Sample Application
SCW.nct|1|Edit|{&NOTEXT:}
RRA.
WRA.0|100
ITO
DBP. Timeout, something went wrong!
ELS.
DBP. All fine Script goes on.
EIF.
ENR.
Built-in Safety Belt
Sometimes windows redraws content that is inside a window, that you might be watching for changes using WRA. To avoid such a Redraw/Refresh to fool your Script that "something has changed", the WRA. command has a built-in safety mechanism.
It will check 3 times within 75 ms, and all three checks need to bring results that do differ from the original Pattern.
Hint: When using RRA.
Here are the modes of operation for RRA.:
' Using RRA. without any Parameter
RRA.
In this case RRA. will Remember the "Client-Area" of the actual Top/Childwindow.
Take this window for example:
In the picture below i have marked the "Client-Area" in yellow color, and the "Non-Client-Area" in Orange Color.
For more infos regarding the "Client" and the "Non-Client Area" see here:
1.8.1 The "Client" and the "Non-Client" Parts of a window
WRA. can be used with graphical or accessible Objects also.
You can also use WRA. with graphical or Accessible Objects, that are no windows.
Like in this example.
Therefore it can also be used in Browser and Office-Programs.
STW.ct|PBWindowClass:0|BCS - Testform
AGR.|&EXACT:Install
MMV.
RRA.
WRA.
RRA.getpos|$$POS
DBP.$$POS
ENR.
Syntax
WRA.[P1][|P2][|P3]
Parameter Explanation
P1 - (optional) numeric/variable contains the Tolerance to be used when checking if a color is different. You can specify the color tolerance as a numeric value from 0 - 441673, or you can specify a percentage from 0% to 100%. If you specify a percentage, just add the % Sign after the number. The color tolerance is the maximum allowed Color-Distance between two colors. The maximum color distance is 441673 that is the distance between black and white. If you omit this parameter, the system will use a zero Tolerance. In this case the colors are equal or not equal.
P2 - (optional) numeric/variable contains the minimum number of "Hits" that are pixels that have to be different to make the decision to become "true".
P3 - (optional) numeric/variable contains the timeout time in seconds. After this time, the command will set the timeout-flag and just let the script go on running. You can ask for the state of the timeout-flag to find out, if a timeout happened or not.
Example
'***********************************
' WRA.-Demo
'***********************************
' You need to start the BCS:-Testform (Sample Apps)
' for this Sample.
' Move the mouse over the checkmark to have the
' Mouseover effect. This will make WRA. to switch.
'
STW.ct|PBWindowClass:0|BCS - Testform
SCW.nct|1|Button|I definitely agree with the License
' Watch the Checkmark
RRA.
' Wait until something changes in that rectangular area
WRA.
ITO.
DBP.Timeout!
EIF.
ENR.
'***********************************
' WRA.-Demo
'***********************************
' You need to start the BCS:-Testform (Sample Apps)
' for this Sample.
'
STW.ct|PBWindowClass:0|BCS - Testform
SCW.nct|1|Button|I definitely agree with
RRA.
WRA.
RRA.getpos|$$POS
DBP.$$POS
ENR.
Remarks
To make sure that "Redrawing Effects" can not fool WRA., WRA. has a built-in 75 ms security mechanism. That means, that there will be 3 checks done within 75 ms.
In these checks, all 25 ms the Area is been compared to the Original Area, and each time the Area must be different from the original Pattern that was captured using RRA.
This is done, to prevent a normal Refresh of a window to be taken as a "Ready Signal".
Only if WRA. is sure, WRA. will switch and let the Script continue running.
While RRA. can actually hold up to 9 Rectangular Areas, there is also a "hidden" tenth box, Box. Nr.0, that you should not use in regular cases. This is the box where the last snaphot from the last call to IRA. / WRA. is internally stored.
Limitations:
-
See also:
• RRA. - Remember Rectangular Area
• IRA. / NRA. - If Rect altered
• 3.6 Using Quadrant-Coordinates
• 1.8.1 The "Client" and the "Non-Client" Parts of a window
• IPC. / NPC. - If-Pixel-Colour