In Windows XP, standard list view controls have new features intended for more effective information representation. One of these features is in grouping, which means visual grouping of logically related items. List view controls can display groups in the Icons, Small Icons, Tile and Report view modes. In the List mode, groups are not displayed though information about them is still available.

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.

TestComplete lets you work with list view groups in your tests and provides a special program object called Win32ListViewGroup for this. This object contains various information about the group, such as its identifier, the header and footer text, images and so on. See the object description to learn which information it provides.

To obtain a Win32ListViewGroup in tests, you can use the wGroups or wGroup property of the Win32ListView object. The wGroups property returns a list view group by its index or ID, and wGroup lets you obtain a group that contains a specific item. In addition, the Win32ListView object provides the wGroupCount property that holds the total number of groups in a list view. You can use this property along with wGroups to iterate through the list view groups.

Two notes:

Since list view grouping was introduced in Windows XP, the Win32ListView.wGroup, wGroups and wGroupCount properties and the Win32ListViewGroup object are available only in Windows XP and later operating systems.
The mentioned properties function properly only if the application uses a manifest that references the Common Controls library (ComCtl32.dll) v.6 or later.

The following script demonstrates how you can work with groups in list view controls:

JavaScript

function Main()
{
  var p, ListView;

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

  // Post the captions of list view groups to the log
  if (ListView.wGroupCount > 0)
  {
    Log.Message("List view groups:");
    for (let i=0; i<ListView.wGroupCount; i++)
      Log.Message(ListView.wGroups(i, true).Header);
  }

  // Obtain groups that contain some items
  Log.Message("The list view item 'Item 1' belongs to the '" +
              GetGroupName(ListView, "Item 1") + "' group.");
  Log.Message("The list view item 'Item 5' belongs to the '" +
              GetGroupName(ListView, "Item 5") + "' group.");
}

function GetGroupName (AListView, AItem)
{
  // Get the group that contains AItem
  let Group = AListView.wGroup(AItem);
  // Return the group's caption
  if (!strictEqual(Group, null))
    return Group.Header;
  else
    return null;
}

JScript

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

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

  // Post the captions of list view groups to the log
  if (ListView.wGroupCount > 0)
  {
    Log.Message("List view groups:");
    for (i=0; i<ListView.wGroupCount; i++)
      Log.Message(ListView.wGroups(i, true).Header);
  }

  // Obtain groups that contain some items
  Log.Message("The list view item 'Item 1' belongs to the '" +
              GetGroupName(ListView, "Item 1") + "' group.");
  Log.Message("The list view item 'Item 5' belongs to the '" +
              GetGroupName(ListView, "Item 5") + "' group.");
}

function GetGroupName (AListView, AItem)
{
  // Get the group that contains AItem
  var Group = AListView.wGroup(AItem);
  // Return the group's caption
  if (Group != null)
    return Group.Header;
  else
    return null;
}

Python

def Main():

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

  # Post the captions of list view groups to the log
  if ListView.wGroupCount > 0:
    Log.Message("List view groups:")
    for i in range (0, ListView.wGroupCount-1):
      Log.Message(ListView.wGroups[i, True].Header)

  # Obtain groups that contain some items
  Log.Message("The list view item 'Item 1' belongs to the '" + \
              GetGroupName(ListView, "Item 1") + "' group.")
  Log.Message("The list view item 'Item 5' belongs to the '" + \
              GetGroupName(ListView, "Item 5") + "' group.")

def GetGroupName (AListView, AItem):
  # Get the group that contains AItem
  Group = AListView.wGroup[AItem]
  # Return the group's caption
  if (Group != None):
    return Group.Header
  else:
    return None

VBScript

Sub Main
  Dim p, ListView, i

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

  ' Post the captions of list view groups to the log
  If ListView.wGroupCount > 0 Then
    Log.Message("List view groups:")
    For i = 0 To ListView.wGroupCount-1
      Log.Message(ListView.wGroups(i, True).Header)
    Next
  End If

  ' Obtain groups that contain some items
  Log.Message("The list view item 'Item 1' belongs to the '" & _
              GetGroupName(ListView, "Item 1") & "' group.")
  Log.Message("The list view item 'Item 5' belongs to the '" & _
              GetGroupName(ListView, "Item 5") & "' group.")
End Sub

Function GetGroupName (AListView, AItem)
  Dim Group
  ' Get the group that contains AItem
  Set Group = AListView.wGroup(AItem)
  ' Return the group's caption
  If Not (Group Is Nothing) Then
    GetGroupName = Group.Header
  Else
    GetGroupName = Empty
  End If
End Function

DelphiScript

function GetGroupName (AListView, AItem);
var Group : OleVariant;
begin
  // Get the group that contains AItem
  Group := AListView.wGroup[AItem];
  // Return the group's caption
  if Group <> nil then
    Result := Group.Header
  else
    Result := nil;
end;

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

  // Post the captions of list view groups to the log
  if ListView.wGroupCount > 0 then
  begin
    Log.Message('List view groups:');
    for i:=0 to ListView.wGroupCount-1 do
      Log.Message(ListView.wGroups[i, true].Header)
  end;

  // Obtain groups that contain some items
  Log.Message('The list view item ''Item 1'' belongs to the ''' +
              aqConvert.VarToStr(GetGroupName(ListView, 'Item 1')) + ''' group.');
  Log.Message('The list view item ''Item 5'' belongs to the ''' +
              aqConvert.VarToStr(GetGroupName(ListView, 'Item 5')) + ''' group.');
end;

C++Script, C#Script

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

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

  // Post the captions of list view groups to the log
  if (ListView["wGroupCount"] > 0)
  {
    Log["Message"]("List view groups:");
    for (i=0; i<ListView["wGroupCount"]; i++)
      Log["Message"](ListView["wGroups"](i, true)["Header"]);
  }

  // Obtain groups that contain some items
  Log["Message"]("The list view item 'Item 1' belongs to the '" +
                 GetGroupName(ListView, "Item 1") + "' group.");
  Log["Message"]("The list view item 'Item 5' belongs to the '" +
                 GetGroupName(ListView, "Item 5") + "' group.");
}

function GetGroupName (AListView, AItem)
{
  // Get the group that contains AItem
  var Group = AListView["wGroup"](AItem);
  // Return the group's caption
  if (Group != null)
    return Group["Header"];
  else
    return null;
}

Working With List View Groups in Desktop Windows Applications

See Also