Image Lists

This section contains information about the programming elements used with image lists.

Overviews

Topic	Contents
Image Lists	An image list is a collection of images of the same size, each of which can be referred to by its index.

Functions

Topic	Contents
HIMAGELIST_QueryInterface	Retrieves a pointer to an IImageList or IImageList2 object that corresponds to the image list's HIMAGELIST handle.
ImageList_Add	Adds an image or images to an image list.
ImageList_AddMasked	Adds an image or images to an image list, generating a mask from the specified bitmap.
ImageList_BeginDrag	Begins dragging an image.
ImageList_CoCreateInstance	Creates a single instance of an imagelist and returns an interface pointer to it.
ImageList_Copy	Copies images within a given image list.
ImageList_Create	Creates a new image list.
ImageList_Destroy	Destroys an image list.
ImageList_DragEnter	Displays the drag image at the specified position within the window.
ImageList_DragLeave	Unlocks the specified window and hides the drag image, allowing the window to be updated.
ImageList_DragMove	Moves the image that is being dragged during a drag-and-drop operation. This function is typically called in response to a WM_MOUSEMOVE message.
ImageList_DragShowNolock	Shows or hides the image being dragged.
ImageList_Draw	Draws an image list item in the specified device context.
ImageList_DrawEx	Draws an image list item in the specified device context. The function uses the specified drawing style and blends the image with the specified color.
ImageList_DrawIndirect	Draws an image list image based on an IMAGELISTDRAWPARAMS structure.
ImageList_Duplicate	Creates a duplicate of an existing image list.
ImageList_EndDrag	Ends a drag operation.
ImageList_GetBkColor	Retrieves the current background color for an image list.
ImageList_GetDragImage	Retrieves the temporary image list that is used for the drag image. The function also retrieves the current drag position and the offset of the drag image relative to the drag position.
ImageList_GetIcon	Creates an icon from an image and mask in an image list.
ImageList_GetIconSize	Retrieves the dimensions of images in an image list. All images in an image list have the same dimensions.
ImageList_GetImageCount	Retrieves the number of images in an image list.
ImageList_GetImageInfo	Retrieves information about an image.
ImageList_LoadImage	Creates an image list from the specified bitmap.
ImageList_Merge	Creates a new image by combining two existing images. The function also creates a new image list in which to store the image.
ImageList_Read	Reads an image list from a stream.
ImageList_ReadEx	Reads an image list from a stream, and returns an interface to the image list.
ImageList_Remove	Removes an image from an image list.
ImageList_Replace	Replaces an image in an image list with a new image.
ImageList_ReplaceIcon	Replaces an image with an icon or cursor.
ImageList_SetBkColor	Sets the background color for an image list. This function only works if you add an icon or use ImageList_AddMasked with a black and white bitmap. Without a mask, the entire image is drawn; hence the background color is not visible.
ImageList_SetColorTable	Sets the color table for an image list.
ImageList_SetDragCursorImage	Creates a new drag image by combining the specified image (typically a mouse cursor image) with the current drag image.
ImageList_SetIconSize	Sets the dimensions of images in an image list and removes all images from the list.
ImageList_SetImageCount	Resizes an existing image list.
ImageList_SetOverlayImage	Adds a specified image to the list of images to be used as overlay masks. An image list can have up to four overlay masks in version 4.70 and earlier and up to 15 in version 4.71. The function assigns an overlay mask index to the specified image.
ImageList_Write	Writes an image list to a stream.
ImageList_WriteEx	Writes an image list to a stream.

Macros

Topic	Contents
ImageList_AddIcon	Adds an icon or cursor to an image list. ImageList_AddIcon calls the ImageList_ReplaceIcon function.
ImageList_ExtractIcon	Calls the ImageList_GetIcon function to create an icon or cursor based on an image and mask in an image list.
ImageList_LoadBitmap	Calls the ImageList_LoadImage function to create an image list from the specified bitmap resource.
ImageList_RemoveAll	Calls the ImageList_Remove function to remove all of the images from an image list.
INDEXTOOVERLAYMASK	Prepares the index of an overlay mask so that the ImageList_Draw function can use it.

Interfaces

Topic	Contents
IImageList	Exposes methods that manipulate and interact with image lists. To use IImageList, specify Comctl32.dll version 6 in the manifest. If you do not do this, Comctl32.dll version 5 will be used by default, with which IImageList could display unpredictable behavior. For more information on manifests, see Enabling Visual Styles.

Methods

Topic	Contents
Add	Adds an image or images to an image list.
AddMasked	Adds an image or images to an image list, generating a mask from the specified bitmap.
BeginDrag	Begins dragging an image.
Clone	Clones an existing image list.
Copy	Copies images from a given image list.
DragEnter	Locks updates to the specified window during a drag operation and displays the drag image at the specified position within the window.
DragLeave	Unlocks the specified window and hides the drag image, which enables the window to update.
DragMove	Moves the image that is being dragged during a drag-and-drop operation. This function is typically called in response to a WM_MOUSEMOVE message.
DragShowNolock	Shows or hides the image being dragged.
Draw	Draws an image list item in the specified device context.
EndDrag	Ends a drag operation.
GetBkColor	Gets the current background color for an image list.
GetDragImage	Gets the temporary image list that is used for the drag image. The function also retrieves the current drag position and the offset of the drag image relative to the drag position.
GetIcon	Creates an icon from an image and a mask in an image list.
GetIconSize	Gets the dimensions of images in an image list. All images in an image list have the same dimensions.
GetImageCount	Gets the number of images in an image list.
GetImageInfo	Gets information about an image.
GetImageRect	Gets an image's bounding rectangle.
GetItemFlags	Gets the flags of an image.
GetOverlayImage	Retrieves a specified image from the list of images used as overlay masks.
Merge	Creates a new image by combining two existing images. This method also creates a new image list in which to store the image.
Remove	Removes an image from an image list.
Replace	Replaces an image in an image list with a new image.
ReplaceIcon	Replaces an image with an icon or cursor.
SetBkColor	Sets the background color for an image list. This method only functions if you add an icon to the image list or use the IImageList::AddMasked method to add a black and white bitmap. Without a mask, the entire image draws, and the background color is not visible.
SetDragCursorImage	Creates a new drag image by combining the specified image, which is typically a mouse cursor image, with the current drag image.
SetIconSize	Sets the dimensions of images in an image list and removes all images from the list.
SetImageCount	Resizes an existing image list.
SetOverlayImage	Adds a specified image to the list of images used as overlay masks. An image list can have up to four overlay masks in Common Controls version 4.70 and earlier, and up to 15 in version 4.71 or later. The method assigns an overlay mask index to the specified image.

Structures

Topic	Contents
IMAGEINFO	Contains information about an image in an image list. This structure is used with the IImageList::GetImageInfo function.
IMAGELISTDRAWPARAMS	Contains information about an image list draw operation and is used with the IImageList::Draw function.