Creating 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:

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-size 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-size 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.

Create only the image list that the control will use. For example, if the list view control will never be in icon view, do not 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-size icon and small icon image lists can also contain overlay images, 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-size 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, you are responsible for destroying the image lists no longer in use. 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.

The following code example shows how to create a list view control and accompanying image list. It also shows how to assign the image list to the control.

HWND CreateListView (HINSTANCE hInstance, HWND hwndParent)
{
  DWORD dwStyle;              // The window style of the list view control
  HWND hwndListView;          // The handle to the list view control
  HIMAGELIST himlSmall;       // The handle to the small image list
  HIMAGELIST himlLarge;       // The handle to the large image list
  INITCOMMONCONTROLSEX iccex; // INITCOMMONCONTROLSEX structure

  // Initialize the INITCOMMONCONTROLSEX structure.
  iccex.dwSize = sizeof (INITCOMMONCONTROLSEX);

  // Load list view and header control classes.
  iccex.dwICC = ICC_LISTVIEW_CLASSES;  

  // Register tree view control classes from the common control 
  // DLL.
  InitCommonControlsEx (&iccex);

  // Assign the list view window style.
  dwStyle = WS_TABSTOP | WS_CHILD | WS_BORDER | WS_VISIBLE | 
            LVS_AUTOARRANGE | LVS_REPORT | LVS_OWNERDATA;

  // Create list view control.
  hwndListView = CreateWindowEx (
                  WS_EX_CLIENTEDGE,   // Extended window style
                  WC_LISTVIEW,        // Class name
                  TEXT(""),           // Window name
                  dwStyle,            // Window style
                  0,                  // Horizontal position of window
                  0,                  // Vertical position of window
                  0,                  // Window width
                  0,                  // Window height
                  hwndParent,         // Handle to parent window
                  (HMENU)ID_LISTVIEW, // Handle to menu identifier
                  g_hInst,            // Handle to application instance
                  NULL);              // Window-creation data

  // If it fails in creating the window, return.
  if (!hwndListView)
    return NULL;

  // Insert code to resize the list view window here since the list view
  // control was created zero in size. 
  // ...

  // Create the large and small image lists.
  himlSmall = ImageList_Create (16, 16, ILC_COLORDDB | ILC_MASK, 1, 0);
  himlLarge = ImageList_Create (32, 32, ILC_COLORDDB | ILC_MASK, 1, 0);

  if (himlSmall && himlLarge)
  {
    HICON hIcon;

    // Load the small icon from the instance.
    hIcon = LoadImage (g_hInst, MAKEINTRESOURCE (IDI_DISK), IMAGE_ICON, 
                       16, 16, LR_DEFAULTCOLOR);

    // Add the icon to the image list.
    ImageList_AddIcon (himlSmall, hIcon);

    // Load the small icon from the instance.
    hIcon = LoadIcon (g_hInst, MAKEINTRESOURCE (IDI_DISK));

    // Add the icon to the image list.
    ImageList_AddIcon (himlLarge, hIcon);

    // Assign the large and small image lists to the list view control.
    ListView_SetImageList (hwndListView, himlSmall, LVSIL_SMALL);
    ListView_SetImageList (hwndListView, himlLarge, LVSIL_NORMAL);
  }

  return hwndListView;
}