Unable to Set Overlay Image for CListCtrl

Question

I'm trying to display images with overlays in a 'CListCtrl' within an MFC dialog box. The list control is in report/details mode.

I cannot find good documentation for showing overlays on some of my item images.

The code that is failing is shown below. I have a 64x32 bitmap with a folder icon in the first 32x32 pixels, and an overlay image in the second 32x32 pixels (IDB_FOLDERS32_OVERLAY). The bitmap has transparencies that seem to work fine.

CBitmap bm;
bm.LoadBitmap(IDB_FOLDERS32_OVERLAY);
m_ImageList.Create(32, 32, ILC_COLOR32, 2, 1);
int index = m_ImageList.Add(&bm, RGB(0, 0, 0));
ASSERT(index >= 0);
m_ImageList.SetOverlayImage(index, 2);

The last line returns 0, which indicates an error. GetLastError() returns 6 (ERROR_INVALID_HANDLE).

I can't for the life of me find reasonable documentation for how to do this anywhere on the web. Can anyone see what I'm missing?

"A call to this method fails and returns E_INVALIDARG unless the image list is created using a mask." maybe? ILC_COLOR32 might not be enough, it might need ILC_MASK as well. — Jonathan Potter
The MFC documentation is generally low quality. Luckily, for just about anything in MFC there is a respective Windows API service, with better documentation. @Jonathan's quote is taken from ImageList_SetOverlayImage. Additional information is available at About Image Lists. Another option available with MFC is single-stepping through the source code. This often helps in identifying the root cause for a failure. — IInspectable
@JonathanPotter: Yes, setting the ILC_MASK flag results in the method returning 1 instead of 0. But the documentation is still horrible even for the Windows API services. Guess I'll spend another day trying to figure out how to correctly create my mask. Then again, I think it might make much more sense to simply have two images, one with the overlay already applied. Don't know why I would want to spend days trying to figure how overlays work. — Jonathan Wood
A mask bitmap is just a 1-bit bitmap with a 1 wherever a pixel is not completely transparent. I actually think it won't even be used if you have a 32 bit image with alpha - it could probably be considered a bug that ILC_MASK is required in this instance. — Jonathan Potter
PS Complaining that Microsoft documentation is horrible is like complaining that the sky is blue. Accept it and move on. :) — Jonathan Potter

Jonathan Wood Jonathan Wood · Accepted Answer · 2015-07-01T19:27:59

Jonathan Potter was correct that I needed to include the ILC_MASK flag in order for SetOverlayImage() to returns a value that indicates success.

However, of all the documentation I could find online, nothing provided a complete description of how to do this. I didn't find a single source, for example, that showed what my bitmap should look like.

To make it more complicated, I am using ILC_COLOR32 to signify a 32-bit color bitmap with alpha (transparency) channel. So I don't have a mask and a mask does not appear compatible with alpha channels.

So in the end, I just created a bitmap with two images: The first is a folder, and the second is a folder with my overlay image on top of it. Problem solved.

At this point, it seems pointless to try and figure out if, or how, masks can be created with 32-bit alpha channel bitmaps.

Unable to Set Overlay Image for CListCtrl

1 Answers