MiniRobotLanguage (MRL)
NAV. Command
Navigate in Dialog
Intention
This command locates screen-elements relative to another element. It is used most often in WEB-based GUI's (GUI = Graphical User Interface). But it can also be used in typical windows-based GUIs.
It is used to locate elements that can hardly be located in conventional, direct way. Here is an example. Take a look on the two textboxes inside the Internet Explorer (see picture below).
Why are these textboxes hard to locate?
Normally we locate an element by describing it to the robot. We say "Look for an element with the Name XY". As you see, these textboxes are empty. They may not have a valid name or a value parameter.
Then the only chance we have to grab such nameless boxes, would be, by using the role-parameter. Still there is a risk that if there are many elements with the same role, on a more or less dynamic WEB-Site (changes may happen), that we would locate not the right element.
Here is when the NAV. command takes is place. NAV. takes a special property to describe an element. NAV. looks "Where is it? How far is it from another element? "
Using NAV. we do like this:
1. Locate the window
2. locate an object we can safely locate, near the object we want to locate finally
3. use NAV. to navigate from the Object we have to the Object we want.
In this case we would like to locate the Textbox.We do like this:
1. Locate the window
STW.ct|IEFrame|Login - Windows Internet Explorer
SCW.ct|Internet Explorer_Server|{&NOTEXT:}
2. Locate an object that we can describe
SAO.rn|42|User / Nutzername
3. NAV.igate to the Object that we really want
NAV.R|r
Here is the complete sample script:
STW.ct|IEFrame|Login - Windows Internet Explorer
SCW.ct|Internet Explorer_Server|{&NOTEXT:}
SAO.rn|42|User / Nutzername
NAV.R|r
MMV.
How does it work?
Let me tell you that NAV. is technically the most complex command we have built into the robot. Therefore you may need some time to understand its usage and all of its features.
This command localizes a specified Object in a Child-Window or Top-Window and sets the actual point into its center.
Please note that you need to localize a Element before, using SAO. Please note that NAV can be quite slow when being used on complex applications and slow Computers.
For example, an Login Page in the Internet Explorer:
After you localized an unique Element (for Example the Text "Login") using SAO.
STW.c|ieframe
SAO.n|Login
You want to locate the empty Textbox at the Left side from that, to type the Login-Name in there. While it may be at the left side of the Text, the Center-Point of the Element is likely to be below of the one which is actually selected. Therefore we use a NAV.-Direction of "LD" (Left or Down).
If you want - for example in a Toolbar - to localize an equal element which is exactly right or down to a unique, already located element, you can use only one of these: "R" or "D".
The 8 possible Directions are:
- (A)ll (All 4 directions)
- (L)eft
- (R)ight
- (U)p
- (D)own
and all 4 possible Combinations of them.
Additionally there are:
- LA (Left-All) as a short replacement for: LUD
- RA (Right-All) as a short replacement for: RUD
- UA (Up-All) as a short replacement for: ULR
- DA (Down-All) as a short replacement for: DLR
You can also use the "N" to jump to the next Element. Example:
STW.c|ieframe
SAO.n|Login
NAV.RN|DR|4
This one would jump to the 4'th next Element on the Down/Right Side. The 4'th next is the Element which Center-Point (!) is the 4'th next on that side.
Using NAV., you can easily NAVIGATE to any Element in a Browser Window, by first using SAO. to get an unique Element. Then secondly use NAV. to get where you want.
To see which Element has which Number/Distance use A- with Parameter 8:
STW.c|ieframe
SAO.n|Login
NAV.RNA|DR|4|11
To get the nearest Element just use:
STW.c|ieframe
SAO.n|Login
NAV.q|edit
or to get the 3rd nearest Element which is a "edit-control" use
STW.t|Basic
SAO.n|Up
MPO.
NAV.Nq|3|edit
MMV.
END.
Most important with using NAV. is:
• the Concept of the 8- Directions,
• the Element borderline
• the distance between two element borders and
• the Element-Center-Point and
• the distance between two Elements Center-Points
Hint:
1. When you note that an Object that is there, is not found, you possibly need to use the "u" Options.
2. In regular Mode, NAV. will calculate the distance between elements from borderline to borderline.
3. 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
4. You can NAV.igate from any Object to another Object. This includes Objects that have been found using the NAV. command. You can use as many NAV. commands as you want.
NAV.uRKrn|LA|$$NAM|42|Date Qualified
NAV.uRKrn|d|$$NAM|42|:
Syntax:
NAV.[prototypes|][Data|...]
Parameter Explanation:
Prototype-Field:
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.)
P - (-) switch from Border- (default) to Middlepoint-Distance
R - (s) DiRection in which to search (up, down etc.). Give
direction in big letters, U,D,L,R, A and Combinations of
two letters.
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) state (v) muss exact stimmen
t - (v) TID
u - (-) invisible auch enumerieren (ist unabhängig vom state)
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
z - (-) search only depth of last found SAO.-Object
Example:
' Simple NAV-Example
STW.t|Basic
SAO.n|Up
MPO.
NAV.R|D
MMV.
NAV.R|D
MMV.
NAV.R|RD
MMV.
NAV.R|U
MMV.
MBX.!
END.
' This Example will find a text in the Browser
' and move the Mouse to the control below.
'
DBM.2
JNF.Move-Console.txt
: §§TXT=Google-Suchen
STW.t|Google&AND:Explorer
MPO.
SAO.n|bilder
MMV.
PAU.1
' Navigate to the first Element in the "down-right" direction
' Display (A/1) Elements inverse and with distance-numbers.
' Use only Group 1 Elements ( V/1 - recommended).
NAV.RNAV|DR|1|11|1
MMV.
MBX.!
END.
Remarks:
Please always use E if you do not need the Object for further NAV./SAO-Commands.
Otherwise small amounts of Memory may not be free'd by the system.
When you note that an Object that is there, is not found, you possibly need to use the "u" Options.
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.
You can currently not navigate more far then 20 Elements away from an element.
Using this commands on WEB-Sites that do just load/rebuild internal structures may lead to all sorts of crashes.
See also:
• SAO. - Search Accessible Object
• MOS. - Mouseless Object Select