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. Used to perform actions on all items in a tree view control.
|
|
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. |
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 theDataset):
|
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. |
Declaration
<AMLOOP TYPE="TREECONTROL" WINDOWTITLE="text" OBJECTCLASS="text" OBJECTTYPE="text" CHECKOBJECTCLASS="YES/NO" CHECKOBJECTTYPE="YES/NO" CHECKOBJECTPOSITION="YES/NO" OBJECTXPOS="number" OBJECTYPOS="number" EXCLUDE="text" SORT="text(options)" RESULTVARIABLE="text" ITEMLEVELVARIABLE="text" ITEMLEVEL="number" RESULTDATASET="text">
Example
<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>
See Also: Loop, Loop Files, Loop Windows, Loop Expression, Loop Dataset, Loop List, Loop List Control, Loop Tree Control
To set Loop Tree Control properties
In the Available Actions pane, open the Loop folder and double-click the Loop Tree Control action or drag it into the Steps pane.
In the Populate variable with item text box, select the variable to populate.
Open the window that contains the control, and display the tree control you want to use.
Drag the icon from the Loop Tree Control dialog box into the tree control. A black outline appears around the tree control when it is selected. When you release the mouse, the dialog box is automatically populated with the tree control specifications.
To change any of the tree control specifications, click Edit and then edit the specifications as needed.
Click the Advanced tab and enter the properties as follows:
Use either Include items or Exclude items to enter all or part of the tree items that you want to include or ignore. You can use asterisk (*) and question mark (?) as wildcard characters. If you make entries in the Include items box, all items that do not match your entries will be ignored. If you make entries in the Exclude items box, only the specified items will be ignored and all others will be included.
If you want specify a single level of the tree to be included, select Loop exclusively through items at level, and then enter the level in the box below. Zero is root level.
If you want to populate a variable with the tree level for each item, select the variable in the Populate variable with item level box. The variable must be created in an earlier step using the Create Variable action.
To populate a dataset with the tree control data, select Create and populate dataset and enter a name for the dataset in the box. (Dataset names must be alphanumeric, begin with a letter, and contain no spaces.) The dataset fields will show the index, level, and text of the current node, as well as the parent index and text. Additionally, an IsExpanded field shows whether or not the node has children and is expanded.
If you want the items looped in ascending or descending alphabetical order, make your selection in the Sorting box. By default, items are looped in the order they appear in the tree structure.
To set the Description tab properties, refer to Description Tab Options.
To set the Error Causes and On Error tab properties, refer to Step Error Handling.
When finished, click OK to save settings and close the properties dialog box.
To auto-indent after all steps are added
In the Steps pane, hold down SHIFT and click the first and last steps in the block so that the complete block of steps is selected.
Click Format 
.
|
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 Edit to access/edit the following properties: |
|||||
|
Window Title must be |
Text |
Yes |
(Empty) |
WINDOWTITLE="Microsoft Internet Explorer" |
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 (i.e. * 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 (i.e. * or ?). This parameter is ignored if the Object position must be parameter is set to NO. |
|
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:
|
The Description tab allows you to customize the text description of any step as it appears in the Task Builder's Steps Pane.
More on setting custom step description
The Error Causes tab allows you to select/omit specific errors that should cause a particular step to fail.
More on Error Causes properties
The On Error tab allows you to determine what the task should do if a particular step encounters an error.
More about On Error properties
This action includes the Description tab for entering a custom step description.
More on setting custom step description
This action also includes the standard Error Causes and On Error failure handling options/tabs.
More on Error Handling Options
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.
