Loop - Tree Control
Declaration
<AMLOOP ACTIVITY="treecontrol" WINDOWTITLE="text (options)" ACCESSIBILITYENGINE="text (options)" OBJECTPROPERTIES="Toolkit="text (options)", Type=,Class=,Name=,Value=,X=,Y=" INCLUDE="text" EXCLUDE="text" SORT="text (options)" RESULTVARIABLE="text" RESULTDATASET="text">
Description: Loops through the items of a tree view. The variable specified is updated with the current item text. With each successive loop, the next item is retrieved. The loop ends after all the elements have been browsed or when a Break is encountered.
Practical Usage
Used to perform actions on all items in a tree view control.
General Properties
|
Property |
Type |
Required |
Default |
Markup |
Description |
|---|---|---|---|---|---|
|
Populate Variable with Item Text |
Text |
Yes |
(Empty) |
RESULTVARIABLE="varname" |
The variable that should be populated with the current item from the specified tree control. |
|
After selecting the target control by dragging the icon to the desired object, the "Object Description" section will be populated with the characteristics of the control. Click the Edit button to access/edit the following properties: |
|||||
|
Window Title must be |
Text |
Yes |
(Empty) |
WINDOWTITLE="Microsoft |
If enabled, specifies the title of the Window that the control search should be restricted to. This value is case-insensitive. A Window title is required because without this parameter the action would have to search every control of every single Window on the system which would take an unacceptable amount of time. This parameter supports wildcards (* and ?), for example "*Internet Explorer* would include all Windows containing that text. NOTE: If this parameter is left blank, the action assumes it is searching for a Window title that is blank - to ignore the Window title, use *. |
|
Window Class must be
|
Text |
No |
(Empty) |
WINDOWCLASS="Outlook Express Browser Class" |
If enabled, specifies the class of the Window to act on. This value is case-insensitive. This parameter supports wildcards (* and ?), for example "*Internet Explorer* would include all window classes containing that text. NOTE: If this parameter is left blank, the action assumes it is searching for a Window class that is blank - to ignore the WIndow class, use *. |
|
Window Handle must be |
Number |
No |
(Empty) |
WINDOWHANDLE="555735" |
If enabled, specifies the handle of the Window to act on. If set to 0 or omitted, this parameter is ignored. |
|
Object type must be |
Yes/No |
Yes |
Yes |
CHECKOBJECTTYPE="YES" |
If set to YES, specifies that the type parameter will be checked against the control when determining a matching control. If set to NO the type of the control is ignored. NOTE: This action requires an object type, therefore, this parameter must be set to YES. |
|
Object type (Text-box) |
Text |
Yes |
(Empty) |
OBJECTTYPE="PushButton" |
Specifies the type of control that should be acted on. This parameter is ignored if the Object type must be parameter is set to NO. |
|
Object class must be |
Yes/No |
No |
No |
CHECKOBJECTCLASS="YES" |
If set to YES, specifies that the class parameter will be checked against the control when determining a matching control. If set to NO the class of the control is ignored. |
|
Object class (text-box) |
Text |
No |
(Empty) |
OBJECTCLASS="SysTreeView32" |
Specifies the class of the control that should be acted on. This parameter is ignored if the Object class must be parameter is set to NO. |
|
Object name must be |
Yes/No |
No |
No |
CHECKOBJECTNAME="YES" |
If set to YES, specifies that the name parameter will be checked against the control when determining a matching control. If set to NO, the name of the control is ignored. |
|
Object name (text-box) |
Text |
No |
(Empty) |
OBJECTNAME="Cancel" |
Specifies the name of control that should be checked/unchecked/toggled. This parameter is ignored if the Object name must be parameter is set to NO. |
|
Object value must be |
Yes/No |
No |
No |
CHECKOBJECTNAME="YES" |
If set to YES, specifies that the value parameter will be checked against the control when determining a matching control. If set to NO, the value of the control is ignored. |
|
Object value (text-box) |
Text |
No |
(Empty) |
OBJECTVALUE="1" |
Specifies the value of control that should be acted on. This parameter is ignored if the Object value must be parameter is set to NO. |
|
Object position must be |
Yes/No |
No |
No |
CHECKOBJECTPOSITION="YES" |
If set to YES, specifies that the X and Y coordinates will be checked against the position of the control when determining a matching control. If set to NO, the position of the control is ignored. NOTE: The X and Y coordinates specified are relative to the Window specified in the Window Title Parameter (not the screen). |
|
Position X |
Text |
No |
(Empty) |
OBJECTXPOS="80" |
Specifies the X coordinate position of the control relative to the Window specified in the Window title must be parameter. To specify variable coordinates, use wildcard characters (e.g., * or ?). This parameter is ignored if the Object position must be parameter is set to NO. |
|
Position Y |
Text |
No |
(Empty) |
OBJECTYPOS="90" |
Specifies the Y coordinate position of the control relative to the Window specified in the Window title must be parameter. To specify variable coordinates, use wildcard characters (e.g., * or ?). This parameter is ignored if the Object position must be parameter is set to NO. |
Advanced Parameters
|
Property |
Type |
Required |
Default |
Markup |
Description |
|---|---|---|---|---|---|
|
Include Windows |
Text |
No |
(Empty) |
INCLUDE="*Explorer" |
Indicates a wildcard mask representing the items to include in the loop. Asterisk (*) or question mark (?) can be used as wildcard characters. For example, specifying D* returns only items that begin with the letter "D". |
|
Exclude Windows |
Text |
No |
(Empty) |
EXCLUDE="*Explorer" |
Specifies a wildcard mask representing the items to exclude from the loop. Asterisk (*) or question mark (?) can be used as wildcard characters. For example, specifying Z* returns no items that begin with the letter "Z". |
|
Loop Exclusively Through Items at Level |
Yes/No |
No |
No |
ITEMLEVEL="2" |
Specifies an indent level that should be looped through exclusive of all other levels of the tree. Omitting this parameter or specifying -1 causes the action to Loop through all levels (default). NOTE: Specify 0 for root level |
|
Populate Variable with Item Level |
Text |
No |
Disabled |
WITEMLEVELVARIABLE="Var1" |
If enabled, indicates the name the variable that should be populated with the level of indentation for the current item on the selected tree control. NOTE: Specify 0 for root level |
|
Create and Populate Dataset |
Text |
No |
Disabled |
RESULTDATASET="theDataset" |
If enabled, indicates the name of a dataset to be created and populated with data about the looped items. In addition to the standard dataset fields, this dataset contains specific fields which are listed below. |
|
Sorting |
Text (options) |
No |
None |
SORT="ascending" |
Specifies whether a sort order should be applied to the window titles before loop begins. The available options are:
|
Datasets
A dataset is a multiple column, multiple row container object. This action creates a dataset table with the information listed below (assuming the dataset name selected is the Dataset):
|
Name |
Data Type |
Return Value |
|---|---|---|
|
theDataset.Level |
Number |
Returns the level of the current node |
|
theDataset.Text |
Text |
Returns the caption text of the current node |
|
theDataset.Index |
Number |
Returns the index of the current node (0 based) |
|
theDataset.ParentText |
Text |
Returns the caption text of the node's parent (returns nothing if there is no parent) |
|
theDataset.ParentIndex |
Number |
Returns the index of the current node's parent. |
|
theDataset.IsExpanded |
Boolean |
returns true if the node has children and is in an expanded state. |
Window Dissection™ Technology
This action contains a subset of Network Automation's unique "Window Dissection Technology".
Variables and Expressions
All text fields allow the use of expressions, which can be entered by surrounding the expression in percentage signs (example: %MYVARIABLE%, %Left('Text',2)%). To help construct these expressions, you can open Expression Builder from these fields by pressingF2.
More on
variables
More on expressions
More on the expression builder
Example
The sample AML code below can be copied and pasted directly into the Steps panel of the Task Builder.
Description: This sample task loops through a particular tree control and speaks each item found during each iteration.
<AMVARIABLE NAME="VariableName1"></AMVARIABLE> <AMVARIABLE NAME="VariableName2"></AMVARIABLE> <AMSPEAK ENGINE="automatic">These are the items on the list </AMSPEAK> <AMLOOP TYPE="TREECONTROL" WINDOWTITLE="Desktop" OBJECTCLASS="SysTreeView32" OBJECTTYPE="TreeStructure" CHECKOBJECTCLASS="YES" CHECKOBJECTTYPE="YES" CHECKOBJECTPOSITION="YES" OBJECTXPOS="4" OBJECTYPOS="143" EXCLUDE="*04*" SORT="ascending" RESULTVARIABLE="VariableName1" ITEMLEVELVARIABLE="VariableName2" ITEMLEVEL="1" RESULTDATASET="DatasetName"> <AMSPEAK ENGINE="automatic">%VariableName1%</AMSPEAK> </AMLOOP> |