List-View Controls

A list-view control is a window that displays a collection of items; each item consists of an icon and a label. List-view controls provide several ways to arrange and display items. For example, additional information about each item can be displayed in columns to the right of the icon and label. The following illustration shows a window with a list-view control in icon view.

• List-View Creation
• List-View Styles and Views
• List-View Working Areas
• List-View Image Lists
• List-View Items and Subitems
• List-View Columns
• List-View Scroll Position
• List-View Label Editing
• List-View Colors
• List-View Features Supported in Windows XP

List-View Creation

To create a list-view control, call the CreateWindow or CreateWindowEx function and specify the WC_LISTVIEW window class. This window class is registered when the common controls dynamic-link library (DLL) loads. To ensure that this DLL loads, use the InitCommonControls or InitCommonControlsEx function. Because list-view controls display both icons and text, as part of the creation process you must load the bitmaps and insert the text items.

Normally you will use the resource editor to create a list view control.

List-View Styles and Views

List-view controls display items in four different views. The control's window style specifies the current view. Additional window styles specify the alignment of items and control-specific features. The following table describes the four views.

You can change the view type after you create a list-view control. To retrieve and change the window style, use the GetWindowLong and SetWindowLong functions. To determine the window styles of the current view, use the LVS_TYPEMASK value.

You can control the way items are arranged in icon or small icon view by specifying either the LVS_ALIGNTOP (default) or LVS_ALIGNLEFT window style.

You can change the alignment after you create a list-view control. To determine the current alignment, use the LVS_ALIGNMASK value.

Additional window styles provide other options, such as whether a user can edit labels or select more than one item at a time. For a complete list, see List-View Window Styles .

Extended List-View Styles

The extended list-view control styles provide options such as check boxes, flat scroll bars, grid lines, and hot-tracking. For a complete list, see Extended List-View Styles . You do not access extended list-view styles in the same manner as standard window styles. You do not use the GetWindowLong and SetWindowLong functions to make extended style changes.

There are two messages that set and retrieve extended style information, LVM_SETEXTENDEDLISTVIEWSTYLE and LVM_GETEXTENDEDLISTVIEWSTYLE . Instead of sending the messages explicitly, you can use the following corresponding macros: ListView_SetExtendedListViewStyle , ListView_SetExtendedListViewStyleEx , and ListView_GetExtendedListViewStyle .

Virtual List-View Style

A virtual list view is a list-view control that has the LVS_OWNERDATA style. This style enables the control to handle millions of items because the owner receives the burden of managing item data. This allows you to use the virtual list-view control with large databases of information, where specific methods of data access are already in place.

A virtual list-view control maintains very little item information itself. Except for the item selection and focus information, the owner of the control must manage all item information. Other processes request item information from the owner by using LVN_GETDISPINFO notification messages.

Because this type of list control is intended for large data sets, it is recommended that you cache requested item data to improve retrieval performance. The list view provides a cache-hinting mechanism to assist in optimizing the cache. The hint is implemented in the form of an LVN_ODCACHEHINT notification message.

Creating a Virtual List-View Control

You create virtual list-view controls using the CreateWindow or CreateWindowEx function, specifying the LVS_OWNERDATA window style as part of the dwStyle function parameter.

You can use the LVS_OWNERDATA style in combination with most other window styles, except the LVS_SORTASCENDING or LVS_SORTDESCENDING style. All virtual list-view controls default to the LVS_AUTOARRANGE style.

Compatibility Issues

All four of the list-view styles—icon, small icon, list, and report view—support the LVS_OWNERDATA style. List-view controls that have the LVS_OWNERDATA style do not store any item-specific information. Therefore, the only valid item state flags that you can apply to an item are LVIS_SELECTED and LVIS_FOCUSED . No other state information is stored. In particular, the list-view control does not maintain state or overlay images for each item. However, you can have the list-view control query your application for these images by sending it an LVM_SETCALLBACKMASK message.

Most list-view control messages and the associated macros are fully supported. However, some messages have limitations or are unsupported when you use the LVS_OWNERDATA style. The following table summarizes the affected messages.

Handling Virtual List-View Control Notification Messages

List-view controls with the LVS_OWNERDATA style send the same notification messages as other list-view controls and two additional ones: LVN_ODCACHEHINT and LVN_ODFINDITEM . The following are the most common notifications that the list-view control with the LVS_OWNERDATA style sends.

Cache Management

A list-view control with the LVS_OWNERDATA style produces a large number of LVN_GETDISPINFO notification messages and, to assist in optimizing the cache, an LVN_ODCACHEHINT message. LVN_ODCACHEHINT messages provide information about the recommended items to include within the cache. These messages are sent as WM_NOTIFY messages, with the lParam value acting as the address of an NMLVCACHEHINT structure.

The NMLVCACHEHINT structure includes two integer members, iFrom and iTo, that represent the inclusive endpoints of a range of items that most likely will be needed. The owner must be prepared to load the cache with the item information for each of the items within the recommended range.

The list control often needs item information for the first item (offset 0). The LVN_ODCACHEHINT notification message might not always include item 0, but it must always be included in the cache.

The last items in the list are accessed often. Therefore, the owner might want to keep a second cache that includes the items at the end of the list. The requested range from LVN_ODCACHEHINT can be checked against the end cache to make it available automatically instead of reloading the same end range each time.

List-View Working Areas

List-view controls support working areas, which are rectangular virtual areas that the list-view control uses to arrange its items. A working area is not a window and cannot have a visible border. By default, the list-view control has no working areas. By creating a working area, you can create an empty border on the left, top, or right of the items or cause a horizontal scroll bar to be displayed when there normally would not be one.

The number of working areas can be retrieved with the LVM_GETNUMBEROFWORKAREAS message. The working areas are changed with the LVM_SETWORKAREAS message and can be retrieved with the LVM_GETWORKAREAS message. Both of these messages take the address of an array of RECT structures as the lParam and the number of RECT structures as the wParam. The left and top members of these structures specify the coordinates of the upper-left corner (the origin) of the working area, and the right and bottom members specify the lower-right corner of the working area. All the coordinates are in client coordinates of the list view. The maximum number of working areas allowed is defined by the LV_MAX_WORKAREAS value.

Changing the working area has no effect on list-view controls that have the LVS_LIST or LVS_REPORT view, but the working areas will be maintained when the view type is changed. With the LVS_ICON and LVS_SMALLICON views, the working area can be modified to change the way the items are displayed. Making the width of the working area (right - left) greater than the client width of the control causes the items to be wrapped at that width and the horizontal scroll bar to be displayed. Making the width of the working area narrower than the width of the control's client area causes the items to be wrapped within the working area and not the client area. Setting the left or top member to a positive value causes the items to be displayed starting at the working area, creating an empty space between the edge of the control and the items. An empty space can also be created between the right edge of the control and the items by making the width of the working area less than the client width of the control.

List-View Image Lists

By default, a list-view control does not display item images. To display item images, you must create image lists and associate them with the control. A list-view control can have three image lists:

• An image list that contains full-sized icons displayed when the control is in icon view.
• An image list that contains small icons displayed when the control is in small icon view, list view, or report view.
• An image list that contains state images, which are displayed to the left of the full-sized or small icon. You can use state images, such as checked and cleared check boxes, to indicate application-defined item states. State images are displayed in icon view, small icon view, list view, and report view.

The full-sized and small icon image lists can also contain overlay images, which are designed to be drawn transparently over the item icons.

To use overlay images in a list-view control:

1. Call the ImageList_SetOverlayImage function to assign an overlay image index to an image in the full-sized and small icon image lists. An overlay image is identified by a one-based index.
2. You can associate an overlay image index with an item when you call the ListView_InsertItem or ListView_SetItem macro. Use the INDEXTOOVERLAYMASK macro to specify an overlay image index in the state member of the item's LVITEM structure. You must also set the LVIS_OVERLAYMASK bits in the stateMask member.

If a state image list is specified, a list-view control reserves space to the left of each item's icon for a state image.

To associate a state image with an item, use the INDEXTOSTATEIMAGEMASK macro to specify a state image index in the state member of the LVITEM structure. The index identifies an image in the control's state image list. Although image list indexes are zero-based, the control uses one-based indexes to identify state images. A state image index of zero indicates that an item has no state image.

By default, when a list-view control is destroyed, it destroys the image lists assigned to it. However, if a list-view control has the LVS_SHAREIMAGELISTS window style, the application is responsible for destroying the image lists when they are no longer in use. You should specify this style if you assign the same image lists to multiple list-view controls; otherwise, more than one control might try to destroy the same image list.

List-View Items and Subitems

Each item in a list-view control has an icon, a label, a current state, and an application-defined value. By using list-view messages, you can add, modify, and delete items as well as retrieve information about items.

Each item can have one or more subitems. A subitem is a string that, in report view, is displayed in a column separate from the item's icon and label. To specify the text of a subitem, use the LVM_SETITEMTEXT or LVM_SETITEM message. All items in a list-view control have the same number of subitems. The number of subitems is determined by the number of columns in the list-view control. When you add a column to a list-view control, you specify its associated subitem index.

The LVITEM structure defines a list-view item or subitem. The iItem member is the zero-based index of the item. The iSubItem member is the one-based index of a subitem or zero if the structure contains information about an item. Additional members specify the item's text, icon, state, and item data. Item data is an application-defined value associated with a list-view item.

To add an item to a list-view control, use the LVM_INSERTITEM message, specifying the address of an LVITEM structure. Before adding multiple items, you can send the control an LVM_SETITEMCOUNT message, specifying the number of items the control will ultimately contain. This message enables the list-view control to reallocate its internal data structures only once rather than every time you add an item. You can determine the number of items in a list-view control by using the LVM_GETITEMCOUNT message. If you are adding a large number of items to a list-view control, you can speed up the process by disabling redrawing before adding the items, then enable redrawing after the items are added. Use the WM_SETREDRAW message to enable and disable redrawing.

To change the attributes of a list-view item, use the LVM_SETITEM message, specifying the address of an LVITEM structure. The mask member of this structure specifies the item attributes you want to change. For example, to change only the text of an item or subitem, use the LVM_SETITEMTEXT message.

To retrieve information about a list-view item, use the LVM_GETITEM message, specifying the address of the LVITEM structure to fill in. The mask member of this structure specifies the item attributes to be retrieved. To retrieve only an item or subitem's text, use the LVM_GETITEMTEXT message.

To delete a list-view item, use the LVM_DELETEITEM message. You can delete all items in a list-view control by using the LVM_DELETEALLITEMS message.

List-View Item States

An item's state is a value that specifies the item's availability, indicates user actions, or otherwise reflects the item's status. A list-view control changes some state bits, such as when the user selects an item. An application might change other state bits to disable or hide the item or to specify an overlay image or state image. For more information about overlay images and state images, see List-View Image Lists.

An item's state is specified by the state member of the LVITEM structure. When you specify or change an item's state, the stateMask member specifies which state bits you need to change. You can change an item's state by using the LVM_SETITEMSTATE message. You can specify an item's state when you create it or when you change its attributes by using the LVM_SETITEM message. To determine an item's current state, use the LVM_GETITEMSTATE or LVM_GETITEM message.

To set an item's overlay image, the stateMask member of the LVITEM structure must include the LVIS_OVERLAYMASK value, and the state member must include the one-based index of the overlay image shifted left 8 bits by using the INDEXTOOVERLAYMASK macro. The index can be zero to specify no overlay image.

To set an item's state image, the stateMask member of the LVITEM structure must include the LVIS_STATEIMAGEMASK value, and the state member must include the one-based index of the state image shifted left 12 bits by using the INDEXTOSTATEIMAGEMASK macro. The index can be zero to specify no state image.

Callback Items and the Callback Mask

For each of its items, a list-view control typically stores the label text, the image list index of the item's icons, and a set of bit flags for the item's state. You can define callback items or change the control's callback mask to indicate that the application, rather than the control, stores some or all of this information. You might want to use callbacks if your application stores some of this information.

A callback item in a list-view control is an item for which the application stores the text or icon index, or both. You can define callback items when you send the LVM_INSERTITEM message to add an item to the list-view control. If the application stores the text for the item or subitem, set the pszText member of the item's LVITEM structure to LPSTR_TEXTCALLBACK. If the application stores the icon index for an item, set the iImage member of the item's LVITEM structure to I_IMAGECALLBACK.

The callback mask of a list-view control is a set of bit flags that specify the item states for which the application, rather than the control, stores the current data. The callback mask applies to all of the control's items, unlike the callback item designation, which applies to a specific item. The callback mask is zero by default, meaning that the list-view control stores all item state information. After creating a list-view control and initializing its items, you can send the LVM_SETCALLBACKMASK message to change the callback mask. To retrieve the current callback mask, send the LVM_GETCALLBACKMASK message.

When a list-view control must display or sort a list-view item for which the application stores callback information, the control sends the LVN_GETDISPINFO notification message to the control's parent window. This message specifies an NMLVDISPINFO structure that contains the type of information required and identifies the item or subitem to retrieve. The parent window must process LVN_GETDISPINFO to provide the requested data.

If the list-view control detects a change in an item's callback information, such as a change in the text, icon, or state information, the control sends an LVN_SETDISPINFO notification message to notify you of the change.

If you change a callback item's attributes or state bits, you use the LVM_UPDATE message to force the control to repaint the item. This message also causes the control to arrange its items if it has the LVS_AUTOARRANGE style. You can use the LVM_REDRAWITEMS message to redraw a range of items by invalidating the corresponding portions of the list-view control's client area.

By effectively using callback items and the callback mask, you can ensure that each item attribute is maintained in only one place. Doing this can simplify your application, but the only space saved is the memory that would otherwise be required to store item labels and subitem text.

List-View Item Position

Every list-view item has a position and size, which you can retrieve and set using messages. You can also determine which item, if any, is at a specified position. The position of list-view items is specified in view coordinates, which are client coordinates offset by the scroll position.

To retrieve and set an item's position, use the LVM_GETITEMPOSITION and LVM_SETITEMPOSITION messages. LVM_GETITEMPOSITION works for all views, but LVM_SETITEMPOSITION works only for icon and small icon views.

You can determine which item, if any, is at a particular location by using the LVM_HITTEST message.

To retrieve the bounding rectangle for a list item or only for its icon or label, use the LVM_GETITEMRECT message.

Arranging, Sorting, and Finding Items

You can use list-view messages to arrange and sort items and to find items based on their attributes or positions. Arranging repositions items to align on a grid, but the indexes of the items do not change. Sorting changes the sequence of items (and their corresponding indexes) and then repositions them accordingly. You can arrange items only in icon and small icon views, but you can sort items in any view. To find items, you send list-view messages that specify an item location or property.

To arrange items, use the LVM_ARRANGE message. You can ensure that items are arranged at all times by specifying the LVS_AUTOARRANGE window style.

To sort items, use the LVM_SORTITEMS message. When you sort using this message, you specify an application-defined callback function that the list-view control calls to compare the relative order of any two items. The control passes to the comparison function the item data associated with each of the two items. The item data is the value that was specified in the lParam member of the item's LVITEM structure when it was inserted into the list. By specifying the appropriate item data and supplying an appropriate comparison function, you can sort items by their label, by any subitem, or by any other property. Note that sorting items does not reorder the corresponding subitems. When items are reordered, their corresponding subitems are carried with them; that is, whole rows are kept together. To order the columns separately from one another, detaching the subitems from their items, you must regenerate the columns after sorting using LVM_SETITEM.

You can ensure that a list-view control is always sorted by specifying the LVS_SORTASCENDING or LVS_SORTDESCENDING window style. Controls with these styles use the label text of the items to sort them in ascending or descending order. You cannot supply a comparison function when using these window styles. If a list-view control has either of these styles, an LVM_INSERTITEM message will fail if you try to insert an item that has LPSTR_TEXTCALLBACK as the pszText member of its LVITEM structure.

You can find a list-view item with specific properties by using the LVM_FINDITEM message. You can find a list-view item that is in a specified state and has a specified relationship to a given item by using the LVM_GETNEXTITEM message. For example, you can retrieve the next selected item to the right of a specified item.

List-View Columns

Columns control the way items and their subitems are displayed in report view. Each column has a title and width and is associated with a specific subitem; subitem zero is the item's icon and label. The attributes of a column are defined by an LVCOLUMN structure.

To add a column to a list-view control, use the LVM_INSERTCOLUMN message. To delete a column, use the LVM_DELETECOLUMN message. Note that you cannot delete column zero of a list-view control. You can retrieve and change the properties of an existing column by using the LVM_GETCOLUMN and LVM_SETCOLUMN messages. To retrieve or change a column's width, use the LVM_GETCOLUMNWIDTH and LVM_SETCOLUMNWIDTH messages.

Unless the LVS_NOCOLUMNHEADER window style is specified, column headers appear in report view. The user can click a column header, causing an LVN_COLUMNCLICK notification message to be sent to the parent window. Typically, the parent window sorts the list-view control by the specified column when this clicking occurs. The user can also drag the column guides between the headers to size the columns.

List-view controls can display images next to column titles. To implement this feature, specify the LVCF_IMAGE value and assign the index of the image to the iImage member in the LVCOLUMN structure.

List-view controls can set the order in which columns are displayed. To implement this feature, specify the LVCF_ORDER value and assign the column order to the iOrder member in the LVCOLUMN structure. The column order is zero-based and is in left-to-right order. For example, zero indicates the leftmost column.

List-View Scroll Position

Unless the LVS_NOSCROLL window style is specified, a list-view control can be scrolled to show more items than can fit in the client area of the control. You can retrieve a list-view control's scroll position and related information, scroll a list-view control by a specified amount, or scroll a list-view control so that a specified list item is visible.

In icon view or small icon view, the current scroll position is defined by the view origin. The view origin is the set of coordinates, relative to the visible area of the list-view control, that correspond to the view coordinates (0, 0). To retrieve the current view origin, use the LVM_GETORIGIN message. This message should be used only in icon or small icon view; it returns an error in list or report view.

In list or report view, the current scroll position is defined by the top index. The top index is the index of the first visible item in the list-view control. To retrieve the current top index, use the LVM_GETTOPINDEX message. This message returns a valid result only in list or report view; it returns zero in icon or small icon view.

You can use the LVM_GETVIEWRECT message to retrieve the bounding rectangle of all items in a list-view control, relative to the visible area of the control.

The LVM_GETCOUNTPERPAGE message returns the number of items that fit in one page of the list-view control. This message returns a valid result only in list and report views; in icon and small icon views, it returns the total number of items.

To scroll a list-view control by a specific amount, use the LVM_SCROLL message. Using the LVM_ENSUREVISIBLE message, you can scroll the list-view control, if necessary, to ensure that a specified item is visible.

List-View Label Editing

A list-view control that has the LVS_EDITLABELS window style enables a user to edit item labels in place. The user begins editing by clicking the label of an item that has the focus. Alternatively, an application can begin editing automatically by using the LVM_EDITLABEL message. The list-view control notifies the parent window when editing begins and when it is canceled or completed. When editing is completed, the parent window is responsible for updating the item's label, if appropriate.

When label editing begins, an edit control is created, positioned, and initialized. Before it is displayed, the list-view control sends its parent window an LVN_BEGINLABELEDIT notification message. If you need to modify the label editing process, you can implement a handler for this notification.

One use for an LVN_BEGINLABELEDIT notification handler is to control which labels the user can edit. To prevent label editing, return a nonzero value. To customize label editing, have the notification handler retrieve a handle to the edit control by sending an LVM_GETEDITCONTROL message to the list-view control. Once you have that handle, you can customize the edit control by sending the usual EM_XXX messages. For instance, to limit the amount of text a user can enter, send the edit control an EM_LIMITTEXT message. You can change the edit control's default text with SetWindowText . You can even subclass the edit control to intercept and discard invalid characters.

When label editing is canceled or completed, a list-view control sends its parent window an LVN_ENDLABELEDIT notification message. The lParam parameter is the address of an NMLVDISPINFO structure. The item member of this structure is an LVITEM structure whose iItem member identifies the item. If editing is canceled, the pszText member of the LVITEM structure is NULL; otherwise, pszText is the address of the edited text. The parent window is responsible for updating the item's label if it wants to keep the new label.

List-View Colors

An application can retrieve and set three colors for a list-view control.

To customize the appearance of a list-view control more significantly, use NM_CUSTOMDRAW (list view) . For applications that run on the Windows XP operating system you can apply visual styles to customize the control's appearance. For information on using visual styles see Visual Styles and Using Windows XP Visual Styles .

List-View Features Supported in Windows XP

The list-view control in the updated version of the common controls delivered with Windows XP contains features that enable you to provide an intuitive interface for your applications and to present visual information more effectively. The features include:

• Grouping. This makes it easier for users to scan large lists for relevant information.
• Insertion marks. This enables users to visually follow the changing location of files during and after drag-and-drop operations.
• Tile view. This provides a compact, yet informative, method for displaying directory, file and other information.

You can also apply visual styles to common controls defined by ComCtl32.dll version 6. Applying visual styles enables you to define the appearance of controls and windows. If you want your application to use visual styles, you must add an application manifest to ensure that ComCtl32.dll version 6 is available. For more information about using manifests and visual styles see Using Windows XP Visual Styles.

Grouping

The grouping features of the list-view control in Windows XP, enable you to visually group logically related sets of items. These groups are separated on the screen by a horizontal group header that contains the title and the number of items in the group. The following image shows some grouped items.

The grouping application programming interface (API) enables group and group element management by providing messages that add items to groups, add groups to views, sort group items, and query groups for item size and other information.

Insertion Marks

Insertion marks show users where dragged items will be placed. Insertion marks currently display when the user drags an item into the Start menu or Quick Launch bar. The insertion mark also works for lists that are set to autoarrange. When a user drags an item to a point between two other items, the insertion mark shows the item's expected new location. The following image shows an insertion mark.

The insertion mark API elements enable placement of insertion marks by providing messages and flags that perform hit detection, that specify the location and appearance of the insertion mark by item, and that query for information about the current size and appearance of the insertion mark.

Tile View

The tile-view features of the list-view control enable you to provide a visual balance between graphical and textual information. The textual information displayed for an item in tile view is the same as the columns information defined for report view. Tile view functions in combination with either the grouping or insertion mark features in the list-view control. The tile view uses a 32 x 32 icon and several lines of text, as shown in the following image.

The tile-view APIs enable you to specify which column fields to display for each item, and to collectively control the size and appearance of all items within a tile-view window. For clarity, the first line of text in a tile is always the item's name.