Loop - Tree control |
Declaration
<AMLOOP ACTIVITY="treecontrol" WINDOWTITLE="text (options)" ACCESSIBILITYENGINE="text (options)" OBJECTPROPERTIES="Toolkit=text,Type=text,Class=text,FrameworkId=text,Name=text,AutomationId=text,Value=text,Role=text,Description=text,X=number,Y=number,Width=number,Height=number,IndexInParent=text,ParentPath=text,Occurrence=number" 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.
Parameters
General
This activity comprises Automate's Window Dissection technology to facilitate the discovery of existing window objects and controls. To select the target control:
- Make certain the window that contains the desired control is open and in the foreground (in front of all other open windows).
- Drag and release the magnifier icon over the control. If the control is supported by this activity, a green border will appear around it.
- Upon release, the Edit portion of the editor is populated with identified control properties. Individual properties can be enabled / disabled and their values can be further modified. The values for all disabled properties will be lost at the time the activity is saved.
Property | Type | Required | Default | Markup | Description |
---|---|---|---|---|---|
Store item text in variable | Text | Yes | (Empty) | RESULTVARIABLE="varname" | The variable that should be populated with the current item from the specified tree control. |
Edit
Property | Type | Required | Default | Markup | Description |
---|---|---|---|---|---|
By window title | Text | Yes | (Empty) | WINDOWTITLE="Microsoft Internet Explorer" | If enabled, specifies the title of the window that the control search should be restricted to. If disabled, this parameter is ignored. Click the down arrow to select a title from the drop-down list that appears, or enter a title manually in the provided text box. This parameter supports wildcard characters (that is, * and ?). For example, entering *Internet Explorer* would restrict the search to only windows containing the text "Internet Explorer" in its title. |
By window class | Text | No | (Empty) | WINDOWCLASS="Outlook Express Browser Class" | If enabled, specifies the class of the window that the control search should be restricted to. If disabled, this parameter is ignored. Click the down arrow to select a window class from the drop-down list that appears, or enter a window class manually in the provided text box. This parameter supports wildcard characters (that is, * and ?). For example, entering *Internet Explorer* would restrict the search to only window classes containing the text "Internet Explorer." |
By window handle | Number | No | (Empty) | WINDOWHANDLE="555735" | If enabled, specifies the handle of the window that the control search should be restricted to. If disabled or set to 0, this parameter is ignored. Use this parameter as a way to distinguish a particular window from other instances containing an identical title / class. |
Accessibility engine | Text (options) | No | Auto |
| The
accessibility engine that this activity will use to programmatically
gather accurate information about a user interface in order to
interact with it. The available options are:
|
Browse | Button | No | -- | -- | Provides the option to manually traverse the list of available controls for a window that was selected either by the magnifier icon, or manually by the By window title property. In some cases, the desired control cannot be selected using the magnifier icon. If this occurs, use the magnifier icon to select any control, and then click Browse. Select the desired control from the list in the Object Browser, and then click OK. The Object properties for the selected control will now be populated. Controls can also be selected without the aid of the magnifier icon by enabling the By window title property, and then manually selecting the window the desired control is located in from the list. After selecting a window, click Browse. Select the desired control from the list in the Object Browser, and then click OK. The Object properties for the selected control will now be populated. NOTE: It is not recommended to select a control without using the magnifier icon. Doing so may result in selecting a control that isn't supported by this activity and cause the step to fail when attempting to run it. |
Object properties | Text | No | (Varies) | OBJECTPROPERTIES="Toolkit =WindowsAccessibility,Type=data, Class=DockingPane,Name=Line, Value=text,X=300,Y=200" | Contains standard Window Dissection parameters used to describe objects, controls, or text inside a window. This section can be used to define additional characteristics in order to precisely designate a window or matching object. To enable / disable a specific property, check or uncheck its associated check box. To modify the value of a specific property simply enter the desired value in the Value field. |
Toolkit | Text | No | (Empty) |
| If enabled, specifies that the toolkit (a set of basic building units for graphical user interfaces) will be examined when determining a matching object. If disabled, the toolkit will be ignored. The toolkit that appears is based on the Accessibility engine used:
|
Type | Text | No | (Empty) | TYPE=PushButton | If enabled, specifies that the object's type (that is, Button, Checkbox, Trackbar) will be examined when determining a matching object. If disabled, the type will be ignored. |
Class | Text | No | (Empty) | CLASS=SysTreeView32 | If enabled, specifies that the object's class (that is, XTPToolBar, SysTreeView, MDIClient) will be examined when determining a matching object. If disabled, the class will be ignored. |
FrameworkId | Text | No | (Empty) | FRAMEWORKID=WPF | If enabled, specifies that the object's framework ID (the framework technology used to create the object) will be examined when determining a matching object. If disabled, the framework ID will be ignored. |
Name | Text | No | (Empty) | NAME=Cancel | If enabled, specifies that the object's name (a unique identifier for an object) will be examined when determining a matching object. If disabled, the name will be ignored. |
AutomationId | Text | No | (Empty) | AUTOMATIONID=System | If enabled, specifies that the object's automation ID (a unique identifier for an object) will be examined when determining a matching object. If disabled, the automation ID will be ignored. |
Value | Text | No | (Empty) | VALUE=1 | If enabled, specifies that the object's value (which usually coincides with the Name property) will be examined when determining a matching object. If disabled, the value will be ignored. |
Role | Text | No | (Empty) | ROLE=desktop pane | If enabled, specifies that the object's role type (the control type provided by the Java Accessibility bridge) will be examined when determining a matching object. If disabled, the role type will be ignored. |
Description | Text | No | (Empty) | DESCRIPTION=JScrollPane | If enabled, specifies that the object's description (the description given for an object) will be examined when determining a matching object. If disabled, the description will be ignored. |
X | Number | No | (Empty) | X=80 | If
enabled, specifies that the object's X coordinate (a given
number of pixels along the horizontal axis of a window starting
from the extreme left side) will be examined when determining
a matching object. If disabled, the X coordinate will be
ignored. NOTE: The X and Y coordinates are relative to the specified window as
opposed to the screen. |
Y | Number | No | (Empty) | Y=90 | If
enabled, specifies that the object's Y coordinate (a given
number of pixels along the vertical axis of a window starting
from the top-most portion) will be examined when determining a
matching object. If disabled, the Y coordinates will be ignored.
NOTE: The X and Y coordinates are relative to the specified window as
opposed to the screen. |
Width | Number | No | (Empty) | WIDTH=711 | If enabled, specifies that the object's pixel width will be examined when determining a matching object. If disabled, the pixel width will be ignored. |
Height | Number | No | (Empty) | HEIGHT=421 | If enabled, specifies that the object's pixel height will be examined when determining a matching object. If disabled, the pixel height will be ignored. |
IndexInParent | Text | No | (Empty) | INDEXINPARENT=1 | If enabled, specifies that the object's index in parent number (the numeric identifier of a child object located within a parent object) will be examined when determining a matching object. If disabled, the index in parent number will be ignored. |
ParentPath | Text | No | (Empty) | PARENTPATH=50032|50033 | If enabled, specifies that the object's parent path (the sequence of control type identifiers that lead to the object) will be examined when determining a matching object. If disabled, the parent path will be ignored. |
Occurrence | Number | No | (Empty) | OCCURRENCE=1 | If enabled, specifies that the object's occurrence (the numeric identifier of an object, useful when multiple matching objects are found) will be examined when determining a matching object. If disabled, the occurrence will be ignored. |
Advanced
Property | Type | Required | Default | Markup | Description |
---|---|---|---|---|---|
Include items | Text | No | (Empty) | 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 items | Text | No | (Empty) | 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 on 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. |
Store item level in variable | Text | No | Disabled | ITEMLEVELVARIABLE="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 | (Empty) | RESULTDATASET="DatasetName" | Specifies the name of a dataset to be created and populated with data from the looped list. The dataset will contain a column for each column in the list control plus an index column for the index number of the list item. |
List presorting | Text (options) | No | None |
| Specifies the sort order to be applied to the
values before the loop begins. The available options are:
|
Additional Notes
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 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. |
Example
- The sample AML code below can be copied and pasted directly into the Steps Panel of the Task Builder.
- Parameters containing user credentials, files, file paths, and/or other information specific to the task must be customized before the sample code can run successfully.
Description
This sample task loops through a particular tree control and speaks each item found during each iteration.
<AMVARIABLE NAME="VariableName1" VALUE="" />
<AMVARIABLE NAME="VariableName2" VALUE="" />
<AMSPEECH TEXT="These are the items on the list" VOLUME="100" SPEED="50" />
<AMLOOP ACTIVITY="treecontrol" WINDOWTITLE="Desktop" ACCESSIBILITYENGINE="active" OBJECTPROPERTIES="Type=TreeStructure,Name=,Value=,Class=SysTreeView32,X=4,Y=143" EXCLUDE="*04*" SORT="ascending" RESULTVARIABLE="VariableName1" RESULTDATASET="DatasetName" ITEMLEVELVARIABLE="VariableName2" />
<AMSPEECH VOLUME="100" SPEED="50">%VariableName1%</AMSPEECH>
<AMLOOP ACTIVITY="end" />