MiniRobotLanguage (MRL)
SAO. Command
Search Accesible Object
Intention
This command localizes a specified Acc.-Object in a Child-Window or Top-Window and sets the actual point into the object center.
You can see Acc-Objects in the Acc.-Inspector.Let us see an example from a WEB-Site in the Internet Explorer:
In the picture below you will see the resulting Display in the Acc.-Inspector.
The most important parameters for SAO. are:
"name", "role" and "value". In most cases you can ignore the other parameters.
Now we'll take the above picture from the Acc.-Analyzer, and make the code for it.
Using SAO. we do best locate a Top- and a child-window. Like this:
STW.ct|IEFrame|Theo Gottwald&ANDTHEN: - Windows Internet Explorer
SCW.ct|Shell DocObject View|{&NOTEXT:}
SAO.rv|40|google&ANDTHEN:nwshp
MMV.
ENR.
In some cases this may not be possible, or will not work. Then we can use SAO. just on the Top-Window:
STW.ct|IEFrame|Theo Gottwald&ANDTHEN: - Windows Internet Explorer
SAO.rv|40|google&ANDTHEN:nwshp
MMV.
ENR.
Which may be a bit slower in execution times, depending on the overall complexity of the WEB-/Office program.
Hints:
It is important, that you localize a window before using SAO.
Unlike AGR., SAO. uses the 1.4. The Prototype Parameter System. Before using SAO. please read that chapter in the help.
SAO. supports 3.2 Standard-Search Pattern and they can help you to better define the things you look for. See example above "google&ANDTHEN:nwshp".
Please note that SAO can be quite slow when being used on complex applications and slow Computers.
Use the Acc.-Inspector in the Editor to get the necessary parameter data.
Hint:
1. When you note that an Object that is there, is not found, you possibly need to use the "u" Options.
2. When you reach the wrong Object, try using the "g" Prototoype and the Number "&H8000". This will exclude invisible targets.
SAO.grnvo|&H8000|42|×|adpubcomb&ANDTHEN:#close|nowin
3. If you can not safely locate a Object directly, use the NAV. Command to navigate to the Object.
Syntax
SAO.P1[|P2...|Px]
Parameter Explanation
P1 - Prototypes
A - (n) search only Elements of Group: X (0.1.2.3)
0 = default (is internally change to 3)
these values can be added:
1 - only Objects,
2 - only Simple Elements add
4 - display Objects while searching.
8 - paint Elements,
16 - selective debug info (only found matches).
B - (var) Variable will contain the actual
Acc-Object-Handle (LPAcc)
C - (var) Variable will contain the Object-Rectangle
D - (n) maximum Search-Depth
E - (-) close Acc-Object-Handle (LPAcc) after Operation
F - (var) Variable will contain the window handle of the
localized object
G - (-) Start Search at the Top-Object.
H - (n) Handle (Input Window-Handle) instead of last
Acc-Object-Handle (LPAcc). Counterpart to "L"
K - (var) Variable, set to 0/1 to indicate if the Object
could be localized.
L - Input-Values Acc-Object-Handle (LPAcc), counterpart to "H"
M - Variable with Object Middlepoint.
N - (v) Number of the Object to search for.
1st fitting, 2nd, 3rd ... etc.)
T - (-) Start Search from the Top-Window.
U - (n) minimale Suchtiefe
If H and L are not explicitly specified, the actual window
and option H is choosen.
V - (n) Role-group (1 - Control, 2 - Background)
a - (s) defaultAction (string)
b - (n) helptopic-id
c - (n) child-id
d - (s) Description (s)
e - (n) state AND (these states must be set, there can be
others set as well)
f - (s) helpfile (string)
g - (n) state (these states must NOT be set, others may be set)
h - (n) window-handle from Acc-Object-Handle (LPAcc)
i - (n) "iac"-tree-depth
j - (s) help-string
k - (s) keybrd shortcut
m - (s) helptopic
n - (s) name (s)
o - (l) On not found goto Label.
p - (n) PID
q - (s) window-class
r - (n) role (v)
s - (n) states (v) must match exactly
t - (v) TID
u - (-) include invisible objects (is state independent)
v - (s) value (s)
w - (n.fp) Waiting-Time to wait for appearance of the Element
x - (v) Number in Tree-Level
y - (-) must be linked
P2-Px
- Data(s)
Example
' This Example will find an item in the XP-Quickstart
' and move the Mouse there
VAR.$$NAM=Internet
STW.c|shell_traywnd
SAO.nKAN|$$NAM|$$ERG|3|2
PRT.Item was found (0-NO, 1 -YES)$crlf$ Answer =$$ERG
MMV.
DMP.
Remarks
Please use the prototype E if you do not need the Object for further SAO./NAV.-Commands. Otherwise small amounts of Memory may not be free'd by the system.
You can not use this command to wait for a WEB-Site to be opened.
Using the command on a WEB-Site that is going to be opened, may result in a unrecoverable crash of the robot program.
You can specify multiple Roles, they must be separated by ",".
Any of these will be valid.
If you specify a "#" before the Role-Parameter, it will mean "Role-Group" and specifies any of the following:
0: unknown
1: User-bedienbare Controls
2: Panels, Client und Background
4: Borders etc.
8: Window-Controls (Titlebar, Minimize etc.)
16: Scrollbars
32: Spezial, Cursor, Sound etc.
Limitations:
This command can be slow on complex applications.
Wrong usage may lead to steadily decreasing memory.
Using this commands on WEB-Sites that do just load/rebuild internal structures may lead to all sorts of crashes.
See also:
• MOS. - Mouseless Object Select