Checking List View Items' State

Applies to TestComplete 14.93, last modified on September 21, 2021

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.

The Win32ListView object provides special properties that you can use to determine the current state of list view items:

  • wSelected - Returns True if the specified item is selected (that is, appears highlighted in the list view).
  • wFocused - Returns True if the specified item is focused (that is, has the focus rectangle drawn around it). Usually, the focused item is the one that was clicked last.
  • wChecked - Returns True if the specified item is checked and False if its is unchecked.
  • wCut - Returns True if the specified item is marked for a cut-and-paste operation.

All of these properties have parameters that specify the tested item and, if needed, the subitem. These parameters can take the item’s caption or its index (see Addressing List View Items and Subitems). The properties return True if the specified item or subitem is in the corresponding state, and False otherwise.

The following sections provide detailed information on performing some common checks. Note that you can write the this code manually as well as use property checkpoints.

Checking if the Item is Selected

Quite often, you will need to check if a specific item is selected in the list view control. For this kind of check, you can use the Win32ListView.wSelected property. If the specified item is selected, wSelected returns True, otherwise False:

JavaScript, JScript

function Test()
{
  var p, ListView, Item;

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

  if (ListView.wSelected(Item))
    Log.Message("The list view item '" + Item + "' is selected.")
  else
    Log.Message("The list view item '" + Item + "' is not selected.");
}

Python

def Test():

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

  if ListView.wSelected[Item]:
    Log.Message("The list view item '" + Item + "' is selected.")
  else:
    Log.Message("The list view item '" + Item + "' is not selected.")

VBScript

Sub Test
  Dim p, ListView, Item

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

  If ListView.wSelected(Item) Then
    Log.Message("The list view item '" & Item & "' is selected.")
  Else
    Log.Message("The list view item '" & Item & "' is not selected.")
  End If
End Sub

DelphiScript

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

  if ListView.wSelected[Item] then
    Log.Message('The list view item "' + Item + '" is selected.')
  else
    Log.Message('The list view item "' + Item + '" is not selected.')
end;

C++Script, C#Script

function Test()
{
  var p, ListView, Item;

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

  if (ListView["wSelected"](Item))
    Log["Message"]("The list view item '" + Item + "' is selected.")
  else
    Log["Message"]("The list view item '" + Item + "' is not selected.");
}

Note: Do not confuse the selected item and the focused one. The selected item appears highlighted in the list view, whereas the focused item appears with the focus rectangle drawn around it. The focused item is usually the last clicked item. To check if an item is focused, you should use the Win32ListView.wFocused property.

You can quickly determine the selected list view item using the wSelectedItems property of the Win32ListView object. If a single item is selected in the list view, this property returns the item’s caption. If multiple items are selected, wSelectedItems property returns captions of all selected items concatenated together and separated by the wListSeparator characters. For more information, see Getting the Selected List View Item(s).

Getting the Item’s Checked State

List view controls can display check boxes next to items, so that each item can be checked or unchecked. You can determine whether a specific item is checked or unchecked using the Win32ListView.wChecked property:

JavaScript, JScript

function Test()
{
  var p, ListView, Item;

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

  if (ListView.wChecked(Item))
    Log.Message("The list view item '" + Item + "' is checked.")
  else
    Log.Message("The list view item '" + Item + "' is unchecked.");
}

Python

def Test():

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

  if ListView.wChecked[Item]:
    Log.Message("The list view item '" + Item + "' is checked.")
  else:
    Log.Message("The list view item '" + Item + "' is unchecked.")

VBScript

Sub Test
  Dim p, ListView, Item

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

  If ListView.wChecked(Item) Then
    Log.Message("The list view item '" & Item & "' is checked.")
  Else
    Log.Message("The list view item '" & Item & "' is unchecked.")
  End If
End Sub

DelphiScript

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

  if ListView.wChecked[Item] then
    Log.Message('The list view item "' + Item + '" is checked.')
  else
    Log.Message('The list view item "' + Item + '" is unchecked.')
end;

C++Script, C#Script

function Test()
{
  var p, ListView, Item;

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

  if (ListView["wChecked"](Item))
    Log["Message"]("The list view item '" + Item + "' is checked.")
  else
    Log["Message"]("The list view item '" + Item + "' is unchecked.");
}

Check boxes provide alternative selection capabilities in the list view. Therefore, you may need to get the list of checked items, in order to log them or process them in a special way. However, the Win32ListView object does not provide special properties or methods that return the list of checked items. You can accomplish this task by creating a custom routine that performs the following:

  • Iterates through all list view items.
  • Examines the wChecked property value for each item.
  • If an item is checked, appends the item caption to the resulting variable.

The following script includes a sample function that performs these steps and returns the list of checked items in a list view. The script contains two routines:

  • Main - The “main” routine. It obtains the tested application and the list view control on its main form, calls the GetCheckedItems function to get the list of checked items in the list view and posts the items list to the test log.
  • GetCheckedItems - Returns the list of items currently checked in the list view, captions of individual items separated by the Win32ListView.wListSeparator characters. The function has only one parameter - AListView, which specifies the tested list view control.

JavaScript, JScript

function Main ()
{
  var p, ListView, CheckedItems;

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

  ListView.wListSeparator = ", ";
  CheckedItems = GetCheckedItems(ListView);
  Log.Message("Checked items: " + CheckedItems);
}

function GetCheckedItems (AListView)
{
  var arr, i;

  arr = new Array();

  // Iterate though the list view items
  for (i=0; i<AListView.wItemCount; i++)
  {
    // If the item is checked, ...
    if (AListView.wChecked(i))
      // append its caption to the array
      arr.push(AListView.wItem(i));
  }

  // Concatenate array elements together and return the resulting string
  return arr.join(AListView.wListSeparator);
}

Python

def Main ():

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

  CheckedItems = GetCheckedItems(ListView)
  Log.Message("Checked items: " + CheckedItems)


def GetCheckedItems (AListView):

  arr = list()

  # Iterate though the list view items
  for i in range(0, AListView.wItemCount-1):
    # If the item is checked, ...
    if AListView.wChecked[i]:
      # append its caption to the array
      arr.append(AListView.wItem[i])
      
  # Concatenate array elements together and return the resulting string
  return str(arr)

VBScript

Sub Main
  Dim p, ListView, CheckedItems

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

  ListView.wListSeparator = ", "
  CheckedItems = GetCheckedItems(ListView)
  Log.Message("Checked items: " & CheckedItems)
End Sub

Function GetCheckedItems (AListView)
  Dim arr, i, j

  arr = Array ()
  j = 0 ' Counter of array elements

  ' Iterate through the list view items
  For i = 0 To AListView.wItemCount-1
    ' If the item is checked, ...
    If AListView.wChecked(i) Then
      ' append its caption to the array
      Redim Preserve arr (UBound(arr) + 1) ' Increase the array size
      arr(j) = AListView.wItem(i)
      j = j + 1
    End If
  Next

  ' Concatenate array elements together and return the resulting string
  GetCheckedItems = Join (arr, AListView.wListSeparator)
End Function

DelphiScript

function GetCheckedItems (AListView); forward;

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

  ListView.wListSeparator := ', ';
  CheckedItems := GetCheckedItems(ListView);
  Log.Message('Checked items: ' + CheckedItems);
end;

function GetCheckedItems (AListView);
var arr, i, j, n, str : OleVariant;
begin
  arr := CreateVariantArray(-1, -1);

  // Get the indexes of the selected items
  j := 0; // Counter of array elements
  // Iterate through the list view items
  for i:=0 to AListView.wItemCount-1 do
  begin
    // If the item is checked, ...
    if AListView.wChecked[i] then
    begin
      // append its caption to the array
      VarArrayRedim (arr, VarArrayHighBound(arr, 1) + 1); // Increase the array size
      arr[j] := i;
      j := j + 1;
    end;
  end;

  // Compose the list of checked items
  str := '';
  n := VarArrayHighBound(arr, 1);
  for i:=0 to n-1 do
    str := str + AListView.wItem(arr[i]) + AListView.wListSeparator;
  str := str + AListView.wItem(arr[n]);

  // Returns the resulting string
  Result := str;
end;

C++Script, C#Script

function Main ()
{
  var p, ListView, CheckedItems;

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

  ListView["wListSeparator"] = ", ";
  CheckedItems = GetCheckedItems(ListView);
  Log["Message"]("Checked items: " + CheckedItems);
}

function GetCheckedItems (AListView)
{
  var arr, i;

  arr = new Array();

  // Iterate though the list view items
  for (i=0; i<AListView["wItemCount"]; i++)
  {
    // If the item is checked, ...
    if (AListView["wChecked"](i))
      // append its caption to the array
      arr["push"](AListView["wItem"](i));
  }

  // Concatenate array elements together and return the resulting string
  return arr["join"](AListView["wListSeparator"]);
}

See Also

Working With List View Controls
Addressing List View Items and Subitems
wSelected Property (Specific to Win32ListView Controls)
wChecked Property (ListView Controls)
Getting the Selected List View Item(s)

Highlight search results