Loop Tree Control Action

Declaration

<AMLOOP TYPE="TREECONTROL" WINDOWTITLE="text" WINDOWCLASS="text" WINDOWHANDLE="number" OBJECTNAME="text" OBJECTVALUE="text" OBJECTCLASS="text" OBJECTTYPE="text" CHECKOBJECTNAME="yes/no" CHECKOBJECTVALUE="yes/no" CHECKOBJECTCLASS="yes/no" CHECKOBJECTTYPE="yes/no" CHECKOBJECTPOSITION="yes/no" OBJECTXPOS="number" OBJECTYPOS="number" INCLUDE="text" EXCLUDE="text" SORT="text [options]" RESULTVARIABLE="text [variablename]" ITEMLEVELVARIABLE="text [variablename]" ITEMLEVEL="number" RESULTDATASET="text">

See Also

Loop Tree Control Action-Setting Properties, Get Selected Tree Item, Select List Item, Select Tree Item, Select List Item, Get Text, Loop List Control Action

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 some action on all items in a tree view control.

Important: Only standard Windows tree controls will work with the Loop Tree Control Action. Many applications use images or other controls that may act like tree controls but they are not native Windows controls—the Loop Tree Control Action will not work with these controls.

Parameters

General Tab

Populate Variable With Item Text

Variable, Required
MARKUP: RESULTVARIABLE="myvariablename"

Specifies an already existing AutoMate variable that should be populated with the current item from the specified tree control.

General Tab, Object Description

To access these properties, select the target control by dragging the AutoMate icon, and then click the Edit button under Object Description.

Window Title Must Be

Text, Required
MARKUP:
a) WINDOWTITLE="Untitled - Notepad"
b) WINDOWTITLE="*Internet Explorer*"

Specifies the title of the window to act on. The value is not case sensitive. This parameter supports wildcard characters (* and ?). For example "*Internet Explorer*" would include all windows containing Internet Explorer.

Note: A Window title is required because without this parameter, the action would have to search every control of every window on the system, which would take an unacceptable amount of time. To ignore the window title, use a wildcard character (* or ?); if this parameter is left blank, the action assumes it is searching for a window title that is blank.

Window Class Must Be

Text, Required
MARKUP: WINDOWCLASS="Outlook Express Browser Class"

Specifies the class of the window to act on. The value is not case sensitive. This parameter supports wildcard characters (* and ?). For example "*Explore*" would include all window classes containing Explore.

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 a wildcard character (* or ?).

Window Handle Must Be

Number, Optional, Default: 0
MARKUP: WINDOWHANDLE="555735"

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, Optional, Default: NO
MARKUP: CHECKOBJECTTYPE="YES"

When set to YES, specifies that the object type parameter will be used to identify the control. If set to NO, the type of the control is ignored.

Object Type

Text, Optional, Default: (blank)
MARKUP: OBJECTTYPE="TreeStructure"

Specifies the type of control that should be used in the action. Valid only if Object type must be [CHECKOBJECTTYPE] is set to YES.

Object Class Must Be

Yes/No, Optional, Default: NO
MARKUP: CHECKOBJECTCLASS="YES"

When set to YES, specifies that the object class parameter will be used to identify the control. If set to NO, the class of the control is ignored.

Object Class

Text, Optional, Default: (blank)
MARKUP: OBJECTCLASS="SysTreeView32"

Specifies the class of control that should be used in the action. Valid only if Object class must be [CHECKOBJECTCLASS] is set to YES.

Object Name Must Be

Yes/No, Optional, Default: NO
MARKUP: CHECKOBJECTNAME="YES"

When set to YES, specifies that the object name parameter will be used to identify the control. If set to NO, the name of the control is ignored.

Object Name

Text, Optional, Default: (blank)
MARKUP: OBJECTNAME="Cancel"

Specifies the name of the target control. Valid only if Object name must be [CHECKOBJECTNAME] is set to YES.

Object Value Must Be

Yes/No, Optional, Default: NO
MARKUP: CHECKOBJECTVALUE="YES"

When set to YES, specifies that the object value parameter will be used to identify the control. If set to NO, the value of the control is ignored.

Object Value

Text, Optional, Default: (blank)
MARKUP: OBJECTVALUE="1"

Specifies the value of the target control. Valid only if Object value must be [CHECKOBJECTVALUE] is set to YES.

Object Position Must Be

Yes/No, Optional, Default: NO
MARKUP: CHECKOBJECTPOSITION="YES"

When set to YES, specifies that the Position X and Position Y parameters will be used to identify the control. If set to NO, the position of the control is ignored. The X and Y coordinates specified are relative to the window specified in the Window Title [WINDOWTITLE] parameter (not the screen).

Object Position X

Text, Optional, Default: (blank)
MARKUP: OBJECTXPOS="80"

Specifies the X coordinate position of the control relative to the window specified in the Window Title [WINDOWTITLE] parameter. The parameter is ignored if Position must be [CHECKOBJECTPOSITION] is set to NO.

Object Position Y

Text, Optional, Default: (blank)
MARKUP: OBJECTYPOS="90"

Specifies the Y coordinate position of the control relative to the window specified in the Window Title [WINDOWTITLE] parameter. The parameter is ignored if Position must be [CHECKOBJECTPOSITION] is set to NO.

Advanced Tab

Include

Text, Optional, Default: (blank)
MARKUP: INCLUDE="d*"

Specifies a wildcard mask representing the items to include in the loop. For example, specifying D* returns only items that begin with the letter "D".

Exclude

Text, Optional, Default: (blank)
MARKUP: EXCLUDE="z*"

Specifies a wildcard mask representing the items to exclude from the loop. For example, specifying Z* returns no items that begin with the letter "Z".

Loop Exclusively Through Items at Level

Text, Optional, Default: "-1"
MARKUP: 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).

Populate Variable With Item Level

Variable, Optional, Default: (blank)
MARKUP: ITEMLEVELVARIABLE="myvariablename"

Specifies the name of an already existing variable that should be populated with the level of indentation for the current item on the selected tree control.

Create and Populate Dataset

Text, Optional, Default: (blank)
MARKUP: RESULTDATASET="DatasetName"

Specifies the name of a dataset to be created and populated with data from the looped list. In addition to the standard dataset fields, the dataset will contain the following:

Sorting

Text [options], Optional, Default: ("none")
MARKUP: SORT="ascending"

Specifies the sort order to be applied to the values before the loop begins.

The available options are:

Notes

Window Dissection™ Technology

This action contains a subset of Network Automation's unique "Window Dissection Technology".

Click here for more information.

Custom Description

This action includes the Description tab for entering a custom step description.

More on setting custom step description

Standard Error Handling Options

This action also includes the standard Error Causes and On Error failure handling options/tabs.

More on Error Handling Options

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 pressing F2.

More on variables
More on expressions

More on the expression builder

Example

NOTE: The code below can be copied and pasted directly into the Steps pane of the Task Builder.

<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>