Working with list views

When using list view fields in your application, there are several common tasks you will perform, such as adding items and resizing columns. This section describes how to perform common list view operations.

Adding items to a list view

Several steps are required to add items to a list view field.

First, use the ListView_ItemAdd() function to add a new item.
If additional information will be included with the item, use the ListView_ItemSetSubitem() function to specify any string subitems.
If some of the subitems contain currency, integer, date or time values, you can use functions such as ListView_ItemSetIntSubitem() or ListView_ItemSetCurrencySubitem() to add an additional integer, currency, date or time component to each subitem. The additional components will be used when items in the list view are sorted.
Finally, if the list view can be displayed in report view mode, use the ListView_ColumnAdd() function to add columns to the list. If you don’t add columns, no items will be shown in report view mode.

If the list view field is shown in report view mode, add all of the items and subitems before adding columns the list. This prevents the list view field from flashing as items are added, because the items are shown only after columns are added.

Clearing a list view

To remove a single item from a list view field, use the ListView_ItemRemove() function, specifying the index of the item to remove. To remove all items from the list, use the constant LV_ALL to indicate that all items should be removed.

Removing all items from a list view field does not affect the columns that have been added. To remove all columns, use the ListView_ColumnRemove() function, and use the constant LV_ALL to indicate all columns should be removed.

If your application will displaying an empty list view field, consider using the ListView_SetEmptyMessage() function to specify a message to be displayed in the empty list view field.

Sorting

The SortMethod property specifies the default sorting order for items in the list view field. You can use the ListView_Sort() function to re-sort the items in the list using another sorting method. When you add items to the list view field, they will always be added to the end of the list, regardless of the current sorting order. Use the ListView_Sort() function to re-sort the list after adding items.

By default, the list view will use the string component of a subitem when sorting a column in the list view. The list view items will be sorted in ASCII order, which may not be appropriate if the list view field contains non-string values, such as currency, integer, date or time values. If this is the case, you can use functions such as ListView_ItemSetIntSubitem() and ListView_ItemSetCurrencySubitem() and to add an additional integer, currency, date or time component to each subitem. If the subitems for a column contain an additional component, its value will be used as the basis for sorting the column.

If all the subitems for a column don’t contain the same type of additional component, the items in that column may not sort consistently. To ensure consistent sorting, be sure all subitems in a column have the same type of additional component.

Sizing columns

When you add a column to a list, it will be wide enough to fully display the column heading. If items in the column are wider than the heading, they will be truncated. You can use the optional width parameter to specify the width of the column when you add it. The ListView_GetStringWidth() function is useful when specifying the width of a column. You pass a string to this function to find out how wide the column must be to contain the string without truncating.

If the column has already been added to the list, you can use the ListView_ColumnSetWidth() function to specify the width of the column. Specifying the LV_AUTO_SIZE as the column width will size the column so the widest column item will be displayed without truncating. If you are setting the width of the last column in the list view, use the LV_AUTO_FIT constant to resize the column to fill the remaining space in the list view.