Creating a Tree View Image List

Each item in a tree view control can have four bit images associated with it:

An image such as an open folder, which appears when the item is selected
An image such as a closed folder, displayed when the item is not selected
An overlay image, drawn transparently over the selected or unselected image
A state image, which is an additional image displayed to the left of the selected or unselected image. You can use state images, such as checked and cleared check boxes, to indicate application-defined item states.

By default, a tree view control does not display item images. To display item images, you must create image lists and associate them with the control.

A tree view control can have two image lists: a normal image list and a state image list. A normal image list stores the selected, unselected, and overlay images. A state image list stores state images.

To create an image list, call the ImageList_Create function, and use other image list functions to add bitmaps to the image list. Then, to associate the image list with the tree view control, use the TVM_SETIMAGELIST message. The TVM_GETIMAGELIST message retrieves a handle to one of a tree view control's image lists.

In addition to the selected and unselected images, a tree view control's normal image list can contain up to four overlay images. Overlay images are designed to be drawn transparently over the selected and unselected images. To assign an overlay mask index to an image in the normal image list, call the ImageList_SetOverlayImage function.

By default, all items display the first image in the normal image list for both the selected and unselected states. Also, by default, items do not display overlay images or state images. You can change these default behaviors for an item by sending the TVM_INSERTITEM or TVM_SETITEM messages. These messages use the TVITEM structure to specify image list indexes for an item.

To associate an overlay image with an item, use the INDEXTOOVERLAYMASK macro to specify an overlay mask index in the state member of the item's TVITEM structure. You must also set the TVIS_OVERLAYMASK bits in the stateMask member. Overlay mask indexes are one-based; an index of zero indicates that the application does not specify an overlay 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 item's TVITEM structure. The index identifies an image in the control's state image list.

Note You can speed up the creation of large tree views by disabling the painting of the tree view before adding the items. You do this by sending a WM_SETREDRAW message with the redraw flag set to FALSE. When finished adding items, re-enable painting by sending a WM_SETREDRAW message with the redraw flag set to TRUE.

The following code example shows how to create and set an image list for a tree view control, and then redraw the control using the new images.

BOOL InitTreeViewImageLists (HWND hwndTreeView)
{
  HBITMAP hBmp;          // Handle to the bitmaps to be added

  // Create the image list for the item pictures.
  if ((g_hImgList = ImageList_Create (CX_BITMAP, CY_BITMAP, ILC_MASK, 
                                      NUM_BITMAPS, 0)) == NULL)
    return FALSE;

  // Load the bitmap resource.
  hBmp = LoadBitmap (g_hInst, MAKEINTRESOURCE (IDB_IMAGES));

  // Add the images to the image list, generating a mask from the 
  // bitmap.
  if (ImageList_AddMasked (g_hImgList, hBmp, RGB (0, 255, 0)) == -1)
  {
    return FALSE;
  }

  // Delete the bitmap object and free system resources.
  DeleteObject (hBmp);

  // If not all the images were added, then return.
  if (ImageList_GetImageCount (g_hImgList) < NUM_BITMAPS)
    return FALSE;

  // Set the image list for the tree view control and redraw the
  // control by using the new images.
  TreeView_SetImageList (hwndTreeView, g_hImgList, TVSIL_NORMAL);
  
  return TRUE;
}