Image List Functions and Member Functions

Because image lists are part of the dynamic-link library for common controls (COMCTL32.DLL), you must include the common control header file in your source code files and also link with the common control export library to use the image list functions, structures, and macros. If you are developing in MFC, you need to include the AFXCMN.H file in your STDAFX.H file to get the definition of the CImageList class. This class provides the functionality of the image list common control and includes a data member, m_hImageList, that is a handle containing the image list attached to the object. The GetSafeHwnd member function will retrieve m_hImageList if you need to get a handle to it in your application.

Table 3-2 on the following page describes all the functions and member functions supported by image list controls. If you would like more details about the functions or their parameters and return values, refer to the Win32 SDK or the MFC 3.1 documentation.

Function Member Function Description
ImageList_Add Add Adds one or more images to an image list. You can add bitmapped images, icons, or cursors.
ImageList_AddIcon Add Adds an icon to an image list. Because the system does not save the hIcon that is passed in, you can destroy hIcon after the function returns.
ImageList_AddMasked Add Adds one or more images to an image list, generating a mask from the given bitmap.
ImageList_BeginDrag BeginDrag Begins dragging an image and creates a temporary image list used for dragging. The drag image combines the specified image and its mask with the current cursor. The drag image can be moved using the ImageList_DragMove function.
ImageList_Create Create Creates a new image list.
ImageList_Destroy DeleteObject Destroys an image list.
ImageList_DragEnter DragEnter Locks the specified area of the screen, preventing it from receiving other updates. This function is called during a drag operation.
ImageList_DragLeave DragLeave Removes any locks on the locked area of the screen through a call to ImageList_DragEnter.
ImageList_DragMove DragMove Moves the image. This function is typically called in response to a WM_MOUSEMOVE message during a drag operation.
ImageList_DragShow- NoLock DragShow- NoLock Shows or hides the image being dragged.
ImageList_Draw Draw Draws an image list item in the specified DC. The drawing styles listed in Table 3-1 (page 69) have no effect on the appearance of a nonmasked image, which is copied to the destination DC using the SRCCOPY raster operation. The colors in the image appear the same regardless of the background color of the DC.

Table 3-2. Image list functions and member functions. (continued)

Function Member Function Description
ImageList_DrawEx Draw Draws an image based on the flags and colors passed into the function.
ImageList_EndDrag EndDrag Ends a drag operation. Although this function returns the handle of the temporary image list that is used for dragging, the temporary image list is destroyed, so the handle returned by this function is invalid.
ImageList_ExtractIcon ExtractIcon Creates an icon based on an image and a mask in an image list.
ImageList_GetBkColor GetBkColor Retrieves the current background color for an image list.
ImageList_GetDragImage GetDragImage Retrieves the temporary image list used for the drag image and the current drag position as well as the offset of the drag image relative to the drag position.
ImageList_GetIcon   Retrieves the specified icon in the image list.
ImageList_GetIconSize   Retrieves the dimensions of each image in an image list.
ImageList_GetImage- Count GetImage- Count Retrieves the number of images in an image list.
ImageList_GetImage- Info GetImage- Info Retrieves information about an image and fills out an IMAGEINFO structure with information about a single image. You can use this information to directly manipulate the bitmaps for the image.
  GetSafeHandle Retrieves the handle to the image list.
ImageList_LoadBitmap Create Creates an image list from the given bitmap resource.
ImageList_LoadImage LoadImage Creates an image list from the specified bitmap, cursor, or icon.
ImageList_Merge Attach Merges two existing images, creating a new image list to store the image. The second image is drawn transparently over the first, and the mask for the new image is the result of performing a logical OR operation between the masks for the two images. You can also detach two image lists by using the Detach member function.
ImageList_Read Read Reads an image list from a stream.
ImageList_Remove Remove Removes an image from an image list.
ImageList_Replace Replace Replaces an image in an image list.
ImageList_ReplaceIcon Replace Replaces an image in an image list, using an icon.
ImageList_SetBkColor SetBkColor Sets the background color for an image list.
ImageList_SetDrag- CursorImage SetDrag- CursorImage Sets the image of the dragged item.
ImageList_SetIconSize SetIconSize Sets the dimensions of the images in an image list and removes all images from the list.
ImageList_SetOverlay- Image SetOverlay- Image Adds to the image list the index of an image that will be used as an overlay mask.
ImageList_Write Write Writes an image list to a stream.