MiniRobotLanguage (MRL)
RRA. Command
Remember / store / administrate Rectangular Areas
Intention
RRA. remembers an defined Area. Later you can check if the Area has changed in any way using IRA. or WRA.
RRA. can remember several Areas and check if any of these is currently available, use the advanced RRA. -Options together with IRA. or WRA. for this.
RRA. can save and load Rectangular Regions into files. This way your Script can check for predefined graphical Patterns. As IRA. allows to specify a Color-Tolerance, there is no need to have a "Perfect Match" on the target side. You will just need to use the right values.
RRA. can store 9 Rectangular Pattern into 9 boxes. For this you can specify the number of the box, that you wish to use. In case you do not specify a number, Box Nr.1 is the Standard Box that is been used in all operations of IRA. or WRA. etc..
RRA. has features to manipulate those boxes and their content. Using these features, your target should be to move the Rect-Pattern that you need, into Box Nr.1 because this is where the WRA. and the IRA. can use it.
What is it good for?
Take for example a Form (Class "Sunawt" for example), where the robot is unable to detect if a button has appeared or not.
The Installation-Program is running an undefined time, when it ends, that button appears. You can see it, but the robot may under seldom circumstances be unable to see that button.
Now comes RRA. and WRA.
These commands are just for these cases where all other commands do fail.
RRA. will store a copy of the window or a part of it.
WRA. will hold your Script as long as "it did not change". Until something happens.
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
RRA. can be used with graphical or accessible Objects also.
You can also use RRA. 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.
RRA.getpos|$$POS
DBP.$$POS
ENR.
Always specify a window or Rectangle directly before the RRA. command
' Right.
STW.ct|Chrome_WidgetWin| - Google Chrome
RRA.w20,552,22,552
WRA.
' This will locate an Actual Point somewhere
WLC.w270,821,971,821|&H0
RRA.clear
' Wrong.
' Thats why this has no more window
' Therefore it would use the Desktop-Window at these coordinates
' Thats why you should always use STW. / SCW. directly before the RRA.
RRA.w20,552,22,552
WRA.
' To watch an Edit-Control for getting the input Focus you could use:
%Loc_Edit
RRA.Client
WRA.
' This would include the Edges of the window in the case of an edit-box
%Loc_Edit
RRA.Window
WRA.
' This will show the coordinates of the window that is watched (Screen coords)
%Loc_Edit
RRA.Client
RRA.XSize|$$XSA
RRA.YSize|$$YSA
RRA.XPos|$$XPO
RRA.YPos|$$YPO
DBP.$$XSA,$$YSA-$$XPO,$$YPO
WRA.
Syntax
RRA.[P1][|P2][|P3]
Parameter Explanation
P1 - (optional) can be an prototype or screen coordinates of a rectangle.
If you use RRA. without any parameter, the actual window is been used. It can be a Top- or a child-window. If a Top-Window is used, RRA. tries to only remember the Client-Area of the window. This excludes the window borders.
Using a Rectangle in screen coordinates. Example(s):
' If you just write coordinates, these will be interpreted
' as screen coordinates:
RRA.100,150,200,200
' If you specify 3 coordinates only, y2 will be assumed to
' be eqal to x2
RRA.100,150,200
You can specify in which "box" you want the area to be stored. Just use P2 for this:
RRA.(rect)|$$NUM
You can specify a "w" infront of the coordinates to have window coordinates used.
RRA.w10,20,30,40|$$NUM
Prototypes:
The following Prototypes are currently implemented:
Clear - clear all Boxes from 1 - 9.
RRA.Clear
' Will just clear the specified Box:
RRA.Clear|$$NUM
Client - Use last localized Top or Childwindow-Borders
RRA.Client
Window - use Borders from last localized Element to fill Box(1)
RRA.Window
ToVar - this will store Box(P2) into a variable.
P2 is the number of the box to use. P3 is the Variable-Name where things will be stored.
RRA.toVar|$$NUM|$$VAR
FromVar - this will restore the Data from a variable into the Box(P2), It is for use, together with "ToVar". P2 is the number of the target box to use.
P3 is the Variable with the Area-Data, that was created using "ToVar"..
RRA.toVar|$$NUM|$$VAR
RRA.fromVar|$$NUM|$$VAR
Swap - this will exchange the contents of Box(1) with the content of Box($$NUM).
RRA.Swap|$$NUM
if you specify a second parameter, the content of these two boxes will be exchanged.
RRA.swap|$$NUM|$$NUA
Get - copies Box Nr. $$NUM into Box(1). Box(1) is is been overwritten. Box($$NUM) is still available.
RRA.get|$$NUM
Store - Backup-Copy Box(1)->Box($$NUM)
RRA.store|$$NUM
RemPos - Use Rempos, the locate another Element. The stored Rect will be applied to the coordinates of this new element.
This will remove the positional information from the rectangle in box Nr. $$NUM.
In case the window was moved, the the position information is not more accurate, because its stored in screen coordinates. This way you can mark the positional Informations as "invalid". The rectangular data can still be used, if a new position is given. If you omit $$NUM then box Nr.1 is used.
RRA.rempos|$$NUM
NewPos - Set a new position to an existing Box: Use Screen-coordinates, You can only change the position but never the size of a stored Area.
RRA.NewPos|$$NAM|$$XPO|$$YPO
GetPos - get the Position-Data (in screen coordinates) of the stored Area in Box(1) into Variable $$VAR. Format is X-Pos,Y-Pos.
RRA.GetPos|$$RES[|$$NUM]
XPos - get the X-Position of the (upper left corner of the) Area in Box Nr.1 into Variable $$VAR.
RRA.XPos|$$RES
YPos - get the Y-Position of the (upper left corner of the) Area in Box Nr.1 into Variable $$VAR.
RRA.YPos|$$RES
Size - get the size of the stored Area in Box(1) into Variable $$VAR. Format is X-Size,Y-Size.
RRA.size|$$RES
XSize - get the X-Size of the stored Area in Box(1) into Variable $$VAR.
RRA.xsize|$$RES
YSize - get the Y-Size of the stored Area in Box(1) into Variable $$VAR.
RRA.ysize|$$RES
P2, P3, P4 - (optional) - content of these parameters depend on the prototype in P1.
Example
'***********************************
' RRA./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.
ENR.
'***********************************
' RRA.-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.
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:
• 3.6 Using Quadrant-Coordinates
• 1.8.1 The "Client" and the "Non-Client" Parts of a window
• CST. - Coordinate System Transform
• GRM. - Get Rect Middle-Point
• IPC. / NPC. - If-Pixel-Colour