|
|
Interactivity - Get item(s) |
Declaration
<AMINTERACT ACTIVITY="get_items" WINDOWTITLE="text" WINDOWCLASS="text" WINDOWHANDLE="text" 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" RESULTVARIABLE="text" RESULTDATASET="text" />
Description
Retrieves one or more items from a list, a tree, or a combo box in a window and populates a variable with the caption text of each item. Optionally, populates a dataset with additional information regarding retrieved items.
Practical Usage
Commonly used to select an item in a list, list view, tree view, or combo box control on an application window. Using this activity is superior to using the Interactivity - Move mouse or Input - Send keystrokes activities as it communicates with the target control natively and the application is not required to be in the foreground for the event to occur.
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 |
|---|---|---|---|---|---|
| Populate variable with item name(s) | Text | Yes, if Create and populate dataset is not set | (Empty) | RESULTVARIABLE="theVar" | The name of the existing variable to use to populate with each item's caption text. This parameter is required if the Create and populate database parameter is not set. |
| Create and populate dataset | Text | Yes, if Populate variable with item name(s) is not set | (Empty) | RESULTDATASET="theData" | The name of the dataset to create and populate with information about the retrieved items. See Datasets for more details. This parameter is required if the Populate variable with item name(s) parameter is not set. |
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 is 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 (for example, * 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 is 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 (for example, * 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 is 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 to use with this activity to programmatically
gather accurate information about a user interface for interaction purposes. The available options are:
|
| Browse | Button | No | --- | --- | Provides the option to manually traverse the list of available controls for a window 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 parameter, 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 is now 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, enter the desired value in the Value field. |
| Toolkit | Text | No | (Empty) |
|
If enabled, specifies the toolkit (a set of basic building units for graphical user interfaces) is 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 the object's type (for example, Button, Checkbox, Trackbar) is examined when determining a matching object. If disabled, the type is ignored. |
| Class | Text | No | (Empty) | CLASS=SysTreeView32 | If enabled, specifies the object's class (for example, XTPToolBar, SysTreeView, MDIClient) is examined when determining a matching object. If disabled, the class is ignored. |
| FrameworkId | Text | No | (Empty) | FRAMEWORKID=WPF | If enabled, specifies the object's framework ID (the framework technology used to create the object) is examined when determining a matching object. If disabled, the framework ID is ignored. |
| Name | Text | No | (Empty) | NAME=Cancel | If enabled, specifies that the object's name (a unique identifier for an object) is examined when determining a matching object. If disabled, the name is ignored. |
| AutomationId | Text | No | (Empty) | AUTOMATIONID=System | If enabled, specifies the object's automation ID (a unique identifier for an object) is examined when determining a matching object. If disabled, the automation ID is ignored. |
| Value | Text | No | (Empty) | VALUE=1 | If enabled, specifies the object's value (which usually coincides with the Name property) is examined when determining a matching object. If disabled, the value is ignored. |
| Role | Text | No | (Empty) | ROLE=desktop pane | If enabled, specifies the object's role type (the control type provided by the Java Accessibility bridge) is examined when determining a matching object. If disabled, the role type is ignored. |
| Description | Text | No | (Empty) | DESCRIPTION=JScrollPane | If enabled, specifies the object's description (the description given for an object) is examined when determining a matching object. If disabled, the description is ignored. |
| X | Number | No | (Empty) | X=80 | If
enabled, specifies the object's X coordinate (a given
number of pixels along the horizontal axis of a window starting
from the extreme left side) is examined when determining
a matching object. If disabled, the X coordinate is
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 the object's Y coordinate (a given
number of pixels along the vertical axis of a window starting
from the top-most portion) is examined when determining a
matching object. If disabled, the Y coordinate is 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 the object's pixel width is examined when determining a matching object. If disabled, the pixel width is ignored. |
| Height | Number | No | (Empty) | HEIGHT=421 | If enabled, specifies the object's pixel height is examined when determining a matching object. If disabled, the pixel height is ignored. |
| IndexInParent | Text | No | (Empty) | INDEXINPARENT=1 | If enabled, specifies the object's index in parent number (the numeric identifier of a child object located within a parent object) is examined when determining a matching object. If disabled, the index in parent number is ignored. |
| ParentPath | Text | No | (Empty) | PARENTPATH=50032|50033 | If enabled, specifies the object's parent path (the sequence of control type identifiers that lead to the object) is examined when determining a matching object. If disabled, the parent path is ignored. |
| Occurrence | Number | No | (Empty) | OCCURRENCE=1 | If enabled, specifies the object's occurrence (the numeric identifier of an object, useful when multiple matching objects are found) is examined when determining a matching object. If disabled, the occurrence is ignored. |
Additional Notes
Datasets
A dataset is a multiple column, multiple row container object. This action creates and populates a dataset with the following fields (rows):
| Name | Type | Return Value |
|---|---|---|
| theDataset.Date_modified | Date | Returns the date/time the file was last modified. |
| theDataset.IsSelected | True/False | Determines whether an item is selected. If selected, returns TRUE. Otherwise, returns FALSE. |
| theDataset.Index | Number | The index of the selected items. |
| theDataset.Item_type | Text | Returns the type of file. |
| theDataset.Name | Text | Returns the file name only. For example: If the source is c:\temp\foldername\filename.txt, the file name is FileName.txt. |
| theDataset.Size | Number | Returns the size of the file in kb. |
Example
NOTE:
- 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 retrieves all items from an object.
Copy
<AMVARIABLE NAME="var_Item" VALUE="" />
<AMINTERACT ACTIVITY="get_items" WINDOWTITLE="Program Manager" OBJECTPROPERTIES="Toolkit=WindowsAccessibility,Type=List,Class=SysListView32,Name=Desktop,Value=,X=,Y=" RESULTVARIABLE="var_Item" RESULTDATASET="ds_Items" />