Selecting List View Items in Desktop Windows Applications

Applies to TestComplete 15.69, last modified on November 13, 2024

While testing list view controls, you can use specific properties and methods of the corresponding program object to perform certain actions and obtain data stored in controls. You can call these methods and properties from your keyword tests, as well as from scripts. This topic describes how to work with the needed properties and methods from your scripts. However, when testing a control from your keyword test, you can use the same methods and properties calling them from keyword test operations. For more information, see Keyword Tests Basic Operations.

List view controls provide various navigation possibilities: a user can select individual items by clicking or hot-tracking them with the mouse, or by navigation to it from the keyboard. This topic explains how you can simulate selection of individual and multiple list view items from scripts:

Using the Win32ListView Object Actions

To select a list view item, you can use various actions provided by the Win32ListView object:

  • ClickItem, DblClickItem, ClickItemR and similar actions: Simulate single or double clicks on a specific list view item.
  • SelectItem: Selects the specified list view item, or unselects all items. Unlike ClickItem, the mouse pointer is not moved.
  • HotTrackSelect: Selects a list view item by hovering it with the mouse pointer. Note that hot-tracking is only enabled in list view controls whose wListViewStylesEx.TrackSelect property is true.
  • FocusItem: Focuses the specified list view item without changing the current list view selection. The focused item appears with the focus rectangle drawn around it. Like SelectItem, the FocusItem action does not move the mouse pointer.

All these actions have the Item parameter that specifies the caption or zero-based index of the desired item. Note that it is possible to use wildcards (* and ?) or regular expressions to specify an item’s caption. For more information, see Addressing ListView Items. The ClickItem actions along with HotTrackSelect have two additional parameters: SubItem, which specifies the Item’s subitem to be selected, and Shift, which sets the combination of shift keys (Ctrl, Shift, Alt) to be pressed during the event.

The following example demonstrates how you can use the mentioned actions is scripts:

JavaScript, JScript
Python
VBScript
DelphiScript
C++Script, C#Script
Copy Code

JavaScript, JScript

function Test()
{
  var p, ListView;

  p = Sys.Process("ListViewSample");
  ListView = p.Window("MyWndClass", "Form1").Window("SysListView32");

  // Click some items
  ListView.ClickItem("Item 1");
  ListView.DblClickItem("Item 2");
  // Click a subitem
  ListView.ClickItem("Item 3", "SubItem 3.2");

  // Unselect all items
  ListView.SelectItem(-1);
  // Select an item
  ListView.SelectItem("Item 4");

  // Focus an item
  ListView.FocusItem("Item 6");

  // Select some items by hot-tracking
  // NB: hot-track selection must be enabled
  ListView.HotTrackSelect("Item 5");
  ListView.HotTrackSelect("Item 7");
}

Python

def Test():
  
  p = Sys.Process("ListViewSample")
  ListView = p.Window("MyWndClass", "Form1").Window("SysListView32")

  # Click some items
  ListView.ClickItem("Item 1")
  ListView.DblClickItem("Item 2")
  # Click a subitem
  ListView.ClickItem("Item 3", "SubItem 3.2")

  # Unselect all items
  ListView.SelectItem(-1)
  # Select an item
  ListView.SelectItem("Item 4")

  # Focus an item
  ListView.FocusItem("Item 6")

  # Select some items by hot-tracking
  # NB: hot-track selection must be enabled
  ListView.HotTrackSelect("Item 5")
  ListView.HotTrackSelect("Item 7")

VBScript

Sub Test
  var p, ListView

  Set p = Sys.Process("ListViewSample")
  Set ListView = p.Window("MyWndClass", "Form1").Window("SysListView32")

  ' Click some items
  ListView.ClickItem("Item 1")
  ListView.DblClickItem("Item 2")
  ' Click a subitem
  Call ListView.ClickItem("Item 3", "SubItem 3.2")

  ' Unselect all items
  ListView.SelectItem(-1)
  ' Select an item
  ListView.SelectItem("Item 4")

  ' Focus an item
  ListView.FocusItem("Item 6")

  ' Select some items by hot-tracking
  ' NB: hot-track selection must be enabled
  ListView.HotTrackSelect("Item 5")
  ListView.HotTrackSelect("Item 7")
End Sub

DelphiScript

procedure Test;
var p, ListView : OleVariant;
begin
  p := Sys.Process('ListViewSample');
  ListView := p.Window('MyWndClass', 'Form1').Window('SysListView32');

  // Click some items
  ListView.ClickItem('Item 1');
  ListView.DblClickItem('Item 2');
  // Click a subitem
  ListView.ClickItem('Item 3', 'SubItem 3.2');

  // Unselect all items
  ListView.SelectItem(-1);
  // Select an item
  ListView.SelectItem('Item 4');

  // Focus an item
  ListView.FocusItem('Item 6');

  // Select some items by hot-tracking
  // NB: hot-track selection must be enabled
  ListView.HotTrackSelect('Item 5');
  ListView.HotTrackSelect('Item 7');
end;

C++Script, C#Script

function Test()
{
  var p, ListView;

  p = Sys["Process"]("ListViewSample");
  ListView = p["Window"]("MyWndClass", "Form1")["Window"]("SysListView32");

  // Click some items
  ListView["ClickItem"]("Item 1");
  ListView["DblClickItem"]("Item 2");
  // Click a subitem
  ListView["ClickItem"]("Item 3", "SubItem 3.2");

  // Unselect all items
  ListView["SelectItem"](-1);
  // Select an item
  ListView["SelectItem"]("Item 4");

  // Focus an item
  ListView["FocusItem"]("Item 6");

  // Select some items by hot-tracking
  // NB: hot-track selection must be enabled
  ListView["HotTrackSelect"]("Item 5");
  ListView["HotTrackSelect"]("Item 7");
}

Simulating Keyboard Shortcuts

It is possible to navigate through list view controls using keyboard shortcuts. For instance, the Home key press selects the first item, End selects the last item, arrow keys select the next item in the corresponding direction, and so on. To send keypresses to the list view control, you can use the Keys action:

JavaScript, JScript
Python
VBScript
DelphiScript
C++Script, C#Script
Copy Code

JavaScript, JScript

// Select the 1st item
ListView.Keys("[Home]");

Python

# Select the 1st item
ListView.Keys("[Home]")

VBScript

' Select the 1st item
ListView.Keys("[Home]")

DelphiScript

// Select the 1st item
ListView.Keys('[Home]');

C++Script, C#Script

// Select the 1st item
ListView["Keys"]("[Home]");

In addition, list view controls support the incremental search feature. That is, pressing any printing character selects an item whose caption starts with this character. Pressing the same character again selects a successive item that starts with this character, and so on. This way, you can select a list view item by “typing” its caption:

JavaScript, JScript
Python
VBScript
DelphiScript
C++Script, C#Script
Copy Code

JavaScript, JScript

function Test()
{
  var p, ListView;

  p = Sys.Process("ListViewSample");
  ListView = p.Window("MyWndClass", "Form1").Window("SysListView32");

  // Select Item2
  ListView.Keys("Item2");
  // Select Item4
  ListView.Keys("Item4");
}

Python

def Test():

  p = Sys.Process("ListViewSample")
  ListView = p.Window("MyWndClass", "Form1").Window("SysListView32")

  # Select Item2
  ListView.Keys("Item2")
  # Select Item4
  ListView.Keys("Item4")

VBScript

Sub Test
  Dim p, ListView

  Set p = Sys.Process("ListViewSample")
  Set ListView = p.Window("MyWndClass", "Form1").Window("SysListView32")

  ' Select Item2
  ListView.Keys("Item2")
  ' Select Item4
  ListView.Keys("Item4")
End Sub

DelphiScript

procedure Test;
var p, ListView : OleVariant;
begin
  p := Sys.Process('ListViewSample');
  ListView := p.Window('MyWndClass', 'Form1').Window('SysListView32');

  // Select Item2
  ListView.Keys('Item2');
  // Select Item4
  ListView.Keys('Item4');
end;

C++Script, C#Script

function Test()
{
  var p, ListView;

  p = Sys["Process"]("ListViewSample");
  ListView = p["Window"]("MyWndClass", "Form1")["Window"]("SysListView32");

  // Select Item2
  ListView["Keys"]("Item2");
  // Select Item4
  ListView["Keys"]("Item4");
}

Note: In list view controls that display check boxes, pressing the Space key toggles the selected item’s checked state. So, if the target item’s caption includes the space character, you should only use this approach if the text preceding the space character is enough to identify the item in the list view.
Selecting Multiple Items

If a list view control supports multiple selection, you can select several items at a time using Ctrl- and Shift-clicks. Clicking an item while holding the Ctrl key toggles its selected state, that is, adds it to or removes from the current selection. A Shift-click on an item selects the range of items between the previously selected item and the clicked item.

To simulate a click on an item with the Ctrl key pressed, use the Win32ListView.ClickItem action with the Shift parameter set to skCtrl. If you want to Shift-click an item, set the Shift parameter to skShift:

JavaScript, JScript
Python
VBScript
DelphiScript
C++Script, C#Script
Copy Code

JavaScript, JScript

function Test()
{
  var p, ListView;

  // Obtain the ListView control
  p = Sys.Process("ListViewSample");
  ListView = p.Window("MyWndClass", "Form1").Window("SysListView32");

  // Select a range of items
  ListView.ClickItem("Item 2", 0);
  ListView.ClickItem("Item 5", 0, skShift);
  // Unselect Item 4
  ListView.ClickItem("Item 4", 0, skCtrl);
  // Add Item 7 to the selection
  ListView.ClickItem("Item 7", 0, skCtrl);
}

Python

def Test():

  # Obtain the ListView control
  p = Sys.Process("ListViewSample")
  ListView = p.Window("MyWndClass", "Form1").Window("SysListView32")

  # Select a range of items
  ListView.ClickItem("Item 2", 0)
  ListView.ClickItem("Item 5", 0, skShift)
  # Unselect Item 4
  ListView.ClickItem("Item 4", 0, skCtrl)
  # Add Item 7 to the selection
  ListView.ClickItem("Item 7", 0, skCtrl)

VBScript

Sub Test
  Dim p, ListView

  ' Obtain the ListView control
  Set p = Sys.Process("ListViewSample")
  Set ListView = p.Window("MyWndClass", "Form1").Window("SysListView32")

  ' Select a range of items
  ListView.ClickItem("Item 2")
  Call ListView.ClickItem("Item 5", , skShift)
  ' Unselect Item 4
  Call ListView.ClickItem("Item 4", , skCtrl)
  ' Add Item 7 to the selection
  Call ListView.ClickItem("Item 7", , skCtrl)
End Sub

DelphiScript

procedure Test;
var p, ListView : OleVariant;
begin
  // Obtain the ListView control
  p := Sys.Process('ListViewSample');
  ListView := p.Window('MyWndClass', 'Form1').Window('SysListView32');

  // Select a range of items
  ListView.ClickItem('Item 2', 0);
  ListView.ClickItem('Item 5', 0, skShift);
  // Unselect Item 4
  ListView.ClickItem('Item 4', 0, skCtrl);
  // Add Item 7 to the selection
  ListView.ClickItem('Item 7', 0, skCtrl);
end;

C++Script, C#Script

function Test()
{
  var p, ListView;

  // Obtain the ListView control
  p = Sys["Process"]("ListViewSample");
  ListView = p["Window"]("MyWndClass", "Form1")["Window"]("SysListView32");

  // Select a range of items
  ListView["ClickItem"]("Item 2", 0);
  ListView["ClickItem"]("Item 5", 0, skShift);
  // Unselect Item 4
  ListView["ClickItem"]("Item 4", 0, skCtrl);
  // Add Item 7 to the selection
  ListView["ClickItem"]("Item 7", 0, skCtrl);
}

In list view controls that support hot-track selection, you can also select multiple items using the HotTrackSelect action:

JavaScript, JScript
Python
VBScript
DelphiScript
C++Script, C#Script
Copy Code

JavaScript, JScript

function Test()
{
  var p, ListView;

  // Obtain the ListView control
  p = Sys.Process("ListViewSample");
  ListView = p.Window("MyWndClass", "Form1").Window("SysListView32");

  // Select a range of items
  ListView.HotTrackSelect("Item 2", 0);
  ListView.HotTrackSelect("Item 5", 0, skShift);
  // Unselect Item 4
  ListView.HotTrackSelect("Item 4", 0, skCtrl);
  // Add Item 7 to the selection
  ListView.HotTrackSelect("Item 7", 0, skCtrl);
}

Python

def Test():

  # Obtain the ListView control
  p = Sys.Process("ListViewSample")
  ListView = p.Window("MyWndClass", "Form1").Window("SysListView32")

  # Select a range of items
  ListView.HotTrackSelect("Item 2", 0)
  ListView.HotTrackSelect("Item 5", 0, skShift)
  # Unselect Item 4
  ListView.HotTrackSelect("Item 4", 0, skCtrl)
  # Add Item 7 to the selection
  ListView.HotTrackSelect("Item 7", 0, skCtrl)

VBScript

Sub Test
  Dim p, ListView

  ' Obtain the ListView control
  Set p = Sys.Process("ListViewSample")
  Set ListView = p.Window("MyWndClass", "Form1").Window("SysListView32")

  ' Select a range of items
  ListView.HotTrackSelect("Item 2")
  Call ListView.HotTrackSelect("Item 5", , skShift)
  ' Unselect Item 4
  Call ListView.HotTrackSelect("Item 4", , skCtrl)
  ' Add Item 7 to the selection
  Call ListView.HotTrackSelect("Item 7", , skCtrl)
End Sub

DelphiScript

procedure Test;
var p, ListView : OleVariant;
begin
  // Obtain the ListView control
  p := Sys.Process('ListViewSample');
  ListView := p.Window('MyWndClass', 'Form1').Window('SysListView32');

  // Select a range of items
  ListView.HotTrackSelect('Item 2', 0);
  ListView.HotTrackSelect('Item 5', 0, skShift);
  // Unselect Item 4
  ListView.HotTrackSelect('Item 4', 0, skCtrl);
  // Add Item 7 to the selection
  ListView.HotTrackSelect('Item 7', 0, skCtrl);
end;

C++Script, C#Script

function Test()
{
  var p, ListView;

  // Obtain the ListView control
  p = Sys["Process"]("ListViewSample");
  ListView = p["Window"]("MyWndClass", "Form1")["Window"]("SysListView32");

  // Select a range of items
  ListView["HotTrackSelect"]("Item 2", 0);
  ListView["HotTrackSelect"]("Item 5", 0, skShift);
  // Unselect Item 4
  ListView["HotTrackSelect"]("Item 4", 0, skCtrl);
  // Add Item 7 to the selection
  ListView["HotTrackSelect"]("Item 7", 0, skCtrl);
}

See Also

Working With List View Controls in Desktop Windows Applications
ClickItem Action (Specific to Win32 ListView and Infragistics UltraListView Controls)
DblClickItem Action (Specific to Win32 ListView and Infragistics UltraListView Controls)
SelectItem Action (Specific to Win32ListView Controls)
FocusItem Action (ListView Controls)

Highlight search results