Creating Image Lists (Windows CE 5.0)

Send Feedback

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-size icons that are displayed when the control is in icon view
  • One that contains small icons that are displayed when the control is in small-icon view, list view, or report view
  • One that contains state images that are displayed to the left of the full-size 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-size icons, small icons, or state images. To retrieve the handle to an image list that currently is 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 functions that are related to image lists 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 never will be in icon view, do not create and assign an image list that contains large images, because the large images never will be used. If you create images lists that contain full-size icons and small icons, each image list must contain the same images in the same order. You must use the same order because a single value is used to identify the icon of a list view item in both image lists. You can associate an icon index with an item when you call the ListView_InsertItem macro or the ListView_SetItem macro.

Both the image list that contains full-size icons and the image list that contains small icons also can 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 index for an overlay image to an image in the images lists that contain full-size icons and small icons.

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

  2. Call the ListView_InsertItem macro or the ListView_SetItem macro to associate an index for an overlay image with an item.

  3. Use the INDEXTOOVERLAYMASK macro to specify an index for an overlay image in the state member of the LVITEM structure of the item.

    You also must set the LVIS_OVERLAYMASK bits in the stateMask member.

To associate a state image with an item, use the INDEXTOSTATEIMAGEMASK macro to specify an index for the state image in the state member of the LVITEM structure.

By default, when a list view control is destroyed, it destroys the image lists that are assigned to it. However, if a list view control has the LVS_SHAREIMAGELISTS window style, you are responsible for destroying the image lists that are no longer in use. Specify this control 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 an 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 list of  small images 
  HIMAGELIST himlLarge;       // The handle to the list of large images 
  INITCOMMONCONTROLSEX iccex; // The INITCOMMONCONTROLSEX structure

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

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

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

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

  // Create the 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
                  hInstance,          // 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, because the list 
  // view control was created with a size of zero. 
  // ...

  // Create the image lists for the large images and small images.
  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 (hInstance, MAKEINTRESOURCE (IDI_DISK), IMAGE_ICON, 
                       16, 16, LR_DEFAULTCOLOR);

    // Add the icon to the image list.
if (hIcon)
{
  if (-1 == ImageList_AddIcon (himlSmall, hIcon))
  {
    DestroyIcon(hIcon);
  }
}

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

    // Add the icon to the image list.
if (hIcon)
{
  if (-1 == ImageList_AddIcon (himlLarge, hIcon))
  {
    DestroyIcon(hIcon);
  }
}
    // Assign the image lists for the large images and small images to 
    // the list view control.
    ListView_SetImageList (hwndListView, himlSmall, LVSIL_SMALL);
    ListView_SetImageList (hwndListView, himlLarge, LVSIL_NORMAL);
  }
 else
{
    if (himlSmall)
    {
      ImageList_Destroy (himlSmall);
    }
    if (himlLarge)
    {
      ImageList_Destroy (himlLarge);
    }
  }
  return hwndListView;
}

See Also

Creating a List View Control | Working with Common Controls

Send Feedback on this topic to the authors

Feedback FAQs

© 2006 Microsoft Corporation. All rights reserved.