Interactivity - Get selected list item

Declaration

<AMINTERACT ACTIVITY="get_selected_list_item" 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" INDEXVARIABLE="text" ACTION="text (options)" />

Related Topics   

Description

Retrieves the first item, last item, or all items from a list of currently selected (highlighted) items in a list box or list view and populates a variable or dataset with results.

Practical Usage

Used to retrieve the text contents and / or item index of one or more selected (or highlighted) items in a list box or list 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:

  1. Make certain the window that contains the desired control is open and in the foreground (in front of all other open windows).
  2. Drag and release the magnifier icon over the control. If the control is supported by this activity, a green border will appear around it.
  3. 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
Select Text (Options) Yes First selected
  • ACTION="first_selected"
  • ACTION="last_selected"
  • ACTION="all_selected"
 Specifies how selected items should be retrieved. The available options are:
  • Get first selected item - If multiple items are selected, return only the caption text of the first selected item.
  • Get last selected item - If multiple items are selected, return only the caption text of the last selected item.
  • Get all selected items - If multiple items are selected, return the caption text of all items selected in a comma-delimited list.
Column selection --- --- --- --- Determines which columns should be examined during the retrieval process. This is a visual parameter only used at design time, therefore, it contains no properties or markups. The available options are:
  • First column - Only the first column will be examined.
  • All columns in details view - All columns in a details view will be examined.
Store text in variable Text Yes (Empty) RESULTVARIABLE="theVar" The name of an existing variable in which to populate with the caption text of selected items. This parameter is available only if the Column selection parameter is set to First column.
Store index in variable Text No (Empty) INDEXVARIABLE="indexVar" If enabled, specifies the name of an existing variable in which to populate with the index (row number) of the selected items. If multiple items are selected, then multiple indexes will be returned in a comma-delimited list. This parameter is available only if the Column selection parameter is set to First column.
Create and populate dataset Text No (Empty) RESULTDATASET="theData" The name of the dataset to create and populate with information about the retrieved items. For more details, see Additional Notes below. This parameter is available only if the Column selection parameter is set to All columns in details view.

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
  • ACCESSIBILITYENGINE="auto"
  • ACCESSIBILITYENGINE="ui_automation"
  • ACCESSIBILITYENGINE="active"
  • ACCESSIBILITYENGINE="java"
  • ACCESSIBILITYENGINE="ie"
 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:
  • Auto - Starting with UI Automation, Automate detects which accessibility engine to use based on the control's properties.
    NOTE: Some controls may not be compatible with this option and will require one of the other accessibility engine options to be manually selected for best results.
  • UI Automation - UI Automation will be used, which is Microsoft's standard for exposing information about its user interface.
  • Active - Active Accessibility will be used, which uses an older Microsoft engine for exposing information about its user interface.
  • Java - Java Access Bridge will be used, which is a technology that enables certain Java applications and applets to be visible to assistive technologies on Microsoft Windows systems.
  • Internet Explorer - Internet Explorer DOM will be used, which is the Document Object Model used to represent objects in a web page (that is, text, images, headers, links, etc.).
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)
  • TOOLKIT=UIAutomation
  • TOOLKIT=WindowsAccessibility
  • TOOLKIT=JavaAccessibility

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:

  • UI Automation - UIAutomation
  • Active - WindowsAccessibility
  • Java - JavaAccessibility
  • Internet Explorer - WindowsAccessibility
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.

Description

Error Causes

On Error

Additional Notes

Datasets

A dataset is a multiple column, multiple row container object. This activity creates and populates a dataset containing a specific set of fields. The table below describes these fields (assuming the dataset name assigned was theDataset).

Name Type Return Value
theDataset.Label Text Returns the caption name of the item.
theDataset.Index Number Returns which index (row) number the item resides.

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 gets all selected list items from an object.

Copy 
<AMINTERACT ACTIVITY="get_selected_list_item" WINDOWTITLE="Temp" OBJECTNAME="Items View" OBJECTCLASS="DirectUIHWND" OBJECTTYPE="List" CHECKOBJECTNAME="YES" CHECKOBJECTCLASS="YES" CHECKOBJECTTYPE="YES" RESULTVARIABLE="theVar" INDEXVARIABLE="theIndex" ACTION="all_selection" />