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