Addressing List View Items and Subitems in Desktop Windows Applications

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.

When using the Win32ListView properties and methods to perform specific operations over a list view, you should specify the item and/or subitem you want to work with. This topic explains the principles of addressing list view items and subitems.

Addressing Items by Captions

In the Win32ListView properties and methods, you can specify the desired list view item or subitem by its caption or index. Usually, it is more convenient to address items and subitems by caption, because it makes the script easier to understand:

It is possible to use wildcard characters (* and ?) or regular expressions when specifying the caption. The asterisk (*) corresponds to a string of any length (including an empty string), the question mark corresponds to any single character (including none). Wildcards and regular expressions are useful if the list group’ captions can be different in different contexts.

To illustrate the wildcards usage, suppose that you want to select the disk C in Windows Explorer. Besides the disk name, Explorer displays its label, which can be different on different computers -- it can be, for instance, System, Windows 10, and so on. If the disk has no label, Explorer displays it with the Local Disk label. So, to create a script that will work on different computers you can use wildcards to address the disk C item, you can use the * wildcard instead of the disk label:

Note, if the item’s caption includes the asterisk (*), you should double it, otherwise it will be treated as a wildcard:

To illustrate the regular expressions usage, suppose that you are testing a multilingual application which changes item labels depending on the chosen user interface language. To create a script that will work on different locales, you can use regular expressions and list the item's caption in multiple languages:

TestComplete can treat string parameters, including list view items’ captions, as case-sensitive or case-insensitive. This feature is controlled by the project’s Use case-sensitive parameters option. If this option is turned off (it is off by default), you can specify the captions of list view items and subitems in any case -- all upper case, all lower case, mixed case, and so on:

If the Use case-sensitive parameters is checked, you can specify list view items and subitems only by their actual captions in the correct case:

Addressing Items by Indexes

If a list view item does not have a caption (like in owner-drawn list views), you can address it by its index. Indexes are zero-based: the first item has the index 0, the second - 1, and so on. The total number of items in a list view are specified by the wItemCount property. So, the last item’s index is wItemCount-1:

Unlike items, subitems are indexed from 1: the first subitem has the index 1, the second - 2, and so on. The last subitem’s index is wColumnCount-1, which also equals to the total number of subitems. The index 0 corresponds to the item itself, that is, an item is considered as not having a subitem. The following statements illustrate addressing subitems:

As already mentioned, indexes are useful for addressing items in owner-drawn list view controls, since they may hold no text. For more information on testing such list views, see Working With Owner-Drawn List View Controls in Desktop Windows Applications.

See Also

Working With List View Controls in Desktop Windows Applications
Working With Owner-Drawn List View Controls in Desktop Windows Applications