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:

• One that contains full-sized icons displayed when the control is in icon view.
• One that contains small icons displayed when the control is in small icon view, list view, or report view.
• One that contains state images, which are displayed to the left of the full-sized icon or small icon.

You can use state images, such as checked or cleared check boxes, to indicate application-defined item states. State images are displayed in icon view, small icon view, list view, or report view.

To assign an image list to a list view control, use the LVM_SETIMAGELIST message to specify whether the image list contains full-sized icons, small icons, or state images. To retrieve the handle to an image list currently assigned to a list view control, use the LVM_GETIMAGELIST message. You can use the GetSystemMetrics function to determine appropriate dimensions for the full-sized icons and small icons. Use the ImageList_Create function to create an image list, and use other image list functions to add bitmaps to the image list.

You need to create only the image list that the control will use. For example, if the list view control will never be in icon view, you do not need to create and assign a large image list because the large images will never be used. If you create large and small icon image lists, each image list must contain the same images in the same order. This is because a single value is used to identify a list view item's icon in both image lists. You can associate an icon index with an item when you call the ListView_InsertItem or ListView_SetItem macro.

The full-sized icon 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 icon and small icon image lists.

   An overlay image is identified by a one-based index.

2. Call the ListView_InsertItem or ListView_SetItem macro to associate an overlay image index with an item.
3. 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.

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.

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.