ImageList_SetOverlayImage function (commctrl.h)

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.


BOOL ImageList_SetOverlayImage(
  [in] HIMAGELIST himl,
  [in] int        iImage,
  [in] int        iOverlay


[in] himl


A handle to the image list.

[in] iImage

Type: int

The zero-based index of an image in the himl image list. This index identifies the image to use as an overlay mask.

[in] iOverlay

Type: int

The one-based index of the overlay mask.

Return value

Type: BOOL

Returns nonzero if successful, or zero otherwise.


An overlay mask is an image drawn transparently over another image. To draw an overlay mask over an image, call the ImageList_Draw or ImageList_DrawEx function. The fStyle parameter of these functions can use the INDEXTOOVERLAYMASK macro to specify an overlay mask index.

A call to this method fails and returns E_INVALIDARG unless the image list is created using a mask.


Minimum supported client Windows Vista [desktop apps only]
Minimum supported server Windows Server 2003 [desktop apps only]
Target Platform Windows
Header commctrl.h
Library Comctl32.lib
DLL Comctl32.dll
API set ext-ms-win-shell-comctl32-init-l1-1-1 (introduced in Windows 10, version 10.0.14393)