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 may want to use callbacks if your application already stores some of this information.

A callback item in a list view control is an item for which the application stores the text, 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 LV_ITEM structure to LPSTR_TEXTCALLBACK. If the application stores the icon index for an item, set the iImage member of the item's LV_ITEM 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 get 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 LV_DISPINFO structure that specifies the type of information required and identifies the item or subitem of interest. 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 (that is, a change in the text, icon, or state information being tracked by the application), 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 can 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.