MiniRobotLanguage (MRL)
IRC. / NRC. Conditional Statement
If Rectangular Area Color
Intention
Conditional Statement.
Test if an defined Color is been found inside a defined rectangular area. The Scanning is done from left to right, and top to bottom.
The first point that fits the criteria is been returned. Then you can move the mouse to that point - for example.
Or, test colors inside a defined rectangular area, if they do not match a defined color. This is done using the "!" Operator.
IRC. can also be used to locate an colored object in a window. For example if you have a graphics with red dots somewhere in a window, you can use IRC. to locate such a red dot. This can be done, because IRC. leaves you the Screen-Coordinates of the first found pixel on the Stack.
Important: Color-Operations are often troublesome because colors may not match exactly. Therefore this command provides you with a "Color Tolerance" Option.
Also you have the choice of using a "negative version" which will just check that colors do NOT match a given color/tolerance. And you can combine all this, with the resolution independent SPR 3.6 Using Quadrant-Coordinates to make your Scripts run as compatible as possible.
The four parameters are line-coordinates, Color, Color-Tolerance and Hit-Counter.
Parameter 1 - Line-Coordinates:
The Line is defined by a Start- and and Endpoint. Using the following Format:
IRC.x1,y1,x2,y2
Instead of using Screen-Coordinates, you should prefer to use Coordinates of the last located window/object.
This is done by prefixing the coordinates with a letter. You can use:
"w" - Any window (Top- or Child-Window) that was last located
"t" - last located Top-Window
"c" - use Client-Coordinates of tzhe specified window. If no window is specified "w" is used as default.
"o" - use the last defined Object-Coordinates (window, Accessible Object or graphical Object).
You can combine the letters as far as it makes sense:
"wc" - use last windows Client-Coordinates
"tc" - use last Top-windows Client-Coordinates
at this place you can add 2 Special Characters:
"@" - Enable Debug Option. Using this special Character will open a Window that shows the part of the Screen that is used for the Command. Be careful, when using WRC. with this Option, as it will of course run in a Loop.
"#" - this Option will reduce the Border of the Target Area by 2 Pixels in all directions.
"##" - using multiple "#" will reduce the Border of the Target Area by 2 Pixels times the number of "#" in all directions. If you use "##" it will decrease the target size by 4 Pixel.
"#8" - using "#" followed by a numeric value, the border of the Target Rectangle will be decreased by the given Amount of Pixels. In this case the border would be decreased by 8 Pixels, from any direction.
You can omit the Quadrant coordinates and just write (using any of the letters from above):
ILC.w
Then internally the command will complete the target with
ILC.w{A1,D4}
As always, if you omit y2 then y2 is assumed to be equal to y1.
IRC.x1,y1,x2[,y2]
If you omit the coordinates, the last located window or other object-rectangle is been taken, and the line goes from the upper-left to the lower-right corner.
General Usage is as simple as:
STW.ct|MyClassName|Sample Application
'SCW.nct|1|Edit|{&NOTEXT:}
:again
PAU..1
IRC.|&H00|0|41
DMP.6
MBX.!
ELS.
GTO.again
EIF.
:over
ENR.
Using local (window-) coordinates:
If you prefix the coordinates with a "w" then they will be interpreted as local window coordinates. Like in this example:
STW.ct|MyClassName|Sample Application
SCW.nct|1|Edit|{&NOTEXT:}
MMV.
:again
PAU..1
IRC.w1,1,10,10|!&HFFFFFF|0|32
GTO.over
ELS.
DMP.6
GTO.again
EIF.
:over
DMP.6
MBX.Ready
ENR.
' Scan the complete window to find this color
STW.ct|Chrome_WidgetWin| - Google Chrome
IRC.|&H723132
$$XPO=$$000
$$YPO=$$000
MMV.$$XPO,$$YPO
ELS.
MBX.No
EIF.
' Scan only a small box inside a window to find this color
STW.ct|Chrome_WidgetWin| - Google Chrome
IRC.w459,490,461,493|&HB3B3B3
$$XPO=$$000
$$YPO=$$000
MMV.$$XPO,$$YPO
ELS.
MBX.No
EIF.
Parameter 2 - Color:
If this color is found along the defined Line then the decision will switch to "true".
Colors can most easily be described as a HEX-Number, like this example:
&HFFEE22
&HRRGGBB
If you prefix the color-parameter with a "!" (NOT Operator) then the command will count all Pixels that do NOT have that defined color and tolerance.
Please note that this is different from the NLC.-command, which gives you additional options.
Parameter 3 - 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 4 - 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 12 Pixels.
This Script will switch, after you really typed "88888888" into the first, left textbox.
STW.ct|MyClassName|Sample Application
SCW.nct|1|Edit|{&NOTEXT:}
:again
PAU..1
IRC.|0|0|12
GTO.over
ELS.
GTO.again
EIF.
:over
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).
The "negative Mode" using the "!" NOT Operator
Instead of counting the Pixels that do have a defined color, you can also do the opposite.
You can count the Pixel that do NOT have that defined color.
This is done, by prefixing the "Color-Parameter" with a !.
Like in this example.
STW.ct|MyClassName|Sample Application
SCW.nct|1|Edit|{&NOTEXT:}
:again
PAU..1
IRC.|!&HFFFFFF|0|12
GTO.over
ELS.
DMP.6
GTO.again
EIF.
:over
ENR.
The Stack when using IRC.
In case of success, IRC. will leave four values on the stack. As you can see below, these are:
TOS: X-Position of first found Hit
001: Y-Position of first found Hit
002: Color of first found Hit
003: Number of found Pixel meeting the condition
And there is NRC.
NRC. is the negative version "If Not Rect Color".
Syntax
IRC.[w][P1][|P2][|P3][|P4]… ELS. … EIF.
Parameter Explanation
P1 - (optional) Upper-Left and lower right Coordinate Point of the rectangle. There are different possible Formats for these Coordinates. With out the leading "w", these are Screen-Coordinates.
Its best practice, to prefer Child-Window-relative coordinates:
IRC.w18,56,153,57|$$COL|$$TOL
You can simply specify the coordinates In this format:
IRC.x1,y1,x2,y2
a real example would be:
IRC.10,15,100,200
Or you can specify a Rectangle, using Numbers like:
IRC.10,15,100
then y2 is assumed to be the same as y1.
This will tell the command that we want to use the Quadrant in the last located window (child- or Topwindow).
You can use:
"w" - Any window (Top- or Child-Window) that was last located
"t" - last located Top-Window
"c" - use Client-Coordinates of tzhe specified window. If no window is specified "w" is used as default.
"o" - use the last defined Object-Coordinates (window, Accessible Object or graphical Object).
You can combine the letters as far as it makes sense:
"wc" - use last windows Client-Coordinates
"tc" - use last Top-windows Client-Coordinates
at this place you can add 2 Special Characters:
"@" - Enable Debug Option. Using this special Character will open a Window that shows the part of the Screen that is used for the Command. Be careful, when using WRC. with this Option, as it will of course run in a Loop.
"#" - this Option will reduce the Border of the Target Area by 2 Pixels in all directions.
"##" - using multiple "#" will reduce the Border of the Target Area by 2 Pixels times the number of "#" in all directions. If you use "##" it will decrease the target size by 4 Pixel.
"#8" - using "#" followed by a numeric value, the border of the Target Rectangle will be decreased by the given Amount of Pixels. In this case the border would be decreased by 8 Pixels, from any direction.
You can omit the Quadrant coordinates and just write (using any of the letters from above):
ILC.w
Then internally the command will complete the target with
ILC.w{A1,D4}
If omitted the Rectangle from the last localized Object or window is taken, same as "W".
P2 - (optional) numeric/variable contains the color value to scan for.
P3 - (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 just "equal or not equal".
P4 - (optional) numeric/variable contains the minimum number of "Hits" that are pixels that have to be different to make the decision to become "true".
IRC.'s can be nested to unlimited Depth, and they can also enclose Sub-Program Calls or FEX. (Enumerations) to unlimited Depth.
Example
'***********************************
' IRC.-Sample
'***********************************
' Use "Sample Application"
' Click into the left Edit-Field
' and enter a large number
' to end the Loop
STW.ct|MyClassName|Sample Application
SCW.nct|1|Edit|{&NOTEXT:}
MMV.
:again
PAU..1
IRC.|!&HFFFFFF|0|120
GTO.over
ELS.
DMP.6
GTO.again
EIF.
:over
DMP.6
MBX.Ready
ENR.
Remarks
-
Limitations:
-
See also:
• ! Smart Package Robot 's Pixel-Operations
• RRA. - Remember Rectangular Area
• IRA. / NRA. - If Rect altered
• WRA. - Wait Rect-Area Altered
• 1.8.1 The "Client" and the "Non-Client" Parts of a window
• IPC. / NPC. - If-Pixel-Colour