`CImageList` Class

Article
08/03/2021

Provides the functionality of the Windows common image list control.

Syntax

class CImageList : public CObject

Members

Public Constructors

Name	Description
`CImageList::CImageList`	Constructs a `CImageList` object.

Public Methods

Name	Description
`CImageList::Add`	Adds an image or images to an image list.
`CImageList::Attach`	Attaches an image list to a `CImageList` object.
`CImageList::BeginDrag`	Begins dragging an image.
`CImageList::Copy`	Copies an image within a `CImageList` object.
`CImageList::Create`	Initializes an image list and attaches it to a `CImageList` object.
`CImageList::DeleteImageList`	Deletes an image list.
`CImageList::DeleteTempMap`	Called by the `CWinApp` idle-time handler to delete any temporary `CImageList` object created by `FromHandle`.
`CImageList::Detach`	Detaches an image list object from a `CImageList` object and returns a handle to an image list.
`CImageList::DragEnter`	Locks updates during a drag operation and displays the drag image at a specified position.
`CImageList::DragLeave`	Unlocks the window and hides the drag image so that the window can be updated.
`CImageList::DragMove`	Moves the image that is being dragged during a drag-and-drop operation.
`CImageList::DragShowNolock`	Shows or hides the drag image during a drag operation, without locking the window.
`CImageList::Draw`	Draws the image that is being dragged during a drag-and-drop operation.
`CImageList::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.
`CImageList::DrawIndirect`	Draws an image from an image list.
`CImageList::EndDrag`	Ends a drag operation.
`CImageList::ExtractIcon`	Creates an icon based on an image and mask in an image list.
`CImageList::FromHandle`	Returns a pointer to a `CImageList` object when given a handle to an image list. If a `CImageList` object is not attached to the handle, a temporary `CImageList` object is created and attached.
`CImageList::FromHandlePermanent`	Returns a pointer to a `CImageList` object when given a handle to an image list. If a `CImageList` object is not attached to the handle, NULL is returned.
`CImageList::GetBkColor`	Retrieves the current background color for an image list.
`CImageList::GetDragImage`	Gets the temporary image list that is used for dragging.
`CImageList::GetImageCount`	Retrieves the number of images in an image list.
`CImageList::GetImageInfo`	Retrieves information about an image.
`CImageList::GetSafeHandle`	Retrieves `m_hImageList`.
`CImageList::Read`	Reads an image list from an archive.
`CImageList::Remove`	Removes an image from an image list.
`CImageList::Replace`	Replaces an image in an image list with a new image.
`CImageList::SetBkColor`	Sets the background color for an image list.
`CImageList::SetDragCursorImage`	Creates a new drag image.
`CImageList::SetImageCount`	Resets the count of images in an image list.
`CImageList::SetOverlayImage`	Adds the zero-based index of an image to the list of images to be used as overlay masks.
`CImageList::Write`	Writes an image list to an archive.

Public Operators

Name	Description
`CImageList::operator HIMAGELIST`	Returns the `HIMAGELIST` attached to the `CImageList`.

Public Data Members

Name	Description
`CImageList::m_hImageList`	A handle containing the image list attached to this object.

Remarks

An "image list" is a collection of same-sized images, each of which can be referred to by its zero-based index. Image lists are used to efficiently manage large sets of icons or bitmaps. All images in an image list are contained in a single, wide bitmap in screen device format. An image list may also include a monochrome bitmap that contains masks used to draw images transparently (icon style). The Microsoft Win32 application programming interface (API) provides image list functions that enable you to draw images, create and destroy image lists, add and remove images, replace images, merge images, and drag images.

This control (and therefore the CImageList class) is available only to programs running under Windows 95/98 and Windows NT version 3.51 and later.

For more information on using CImageList, see Controls and Using CImageList.

Inheritance Hierarchy

CObject

CImageList

Requirements

Header: afxcmn.h

`CImageList::Add`

Call this function to add one or more images or an icon to an image list.

int Add(
    CBitmap* pbmImage,
    CBitmap* pbmMask);

int Add(
    CBitmap* pbmImage,
    COLORREF crMask);

int Add(HICON hIcon);

Parameters

pbmImage
Pointer to the bitmap containing the image or images. The number of images is inferred from the width of the bitmap.

pbmMask
Pointer to the bitmap containing the mask. If no mask is used with the image list, this parameter is ignored.

crMask
Color used to generate the mask. Each pixel of this color in the given bitmap is changed to black and the corresponding bit in the mask is set to one.

hIcon
Handle of the icon that contains the bitmap and mask for the new image.

Return Value

Zero-based index of the first new image if successful; otherwise - 1.

Remarks

You are responsible for releasing the icon handle when you are done with it.

Example

// Add my icons.
m_myImageList.Add(AfxGetApp()->LoadIcon(IDI_ICON1));
m_myImageList.Add(AfxGetApp()->LoadIcon(IDI_ICON2));

// Add my bitmap, make all black pixels transparent.
CBitmap bm;
bm.LoadBitmap(IDB_BITMAP1);
m_myImageList.Add(&bm, RGB(0, 0, 0));

`CImageList::Attach`

Call this function to attach an image list to a CImageList object.

BOOL Attach(HIMAGELIST hImageList);

Parameters

hImageList
A handle to an image list object.

Return Value

Nonzero if the attachment was successful; otherwise 0.

Example

void AddQuestion(HIMAGELIST hmyImageList)
{
   CImageList imgList;

   // Attach the image list handle to the CImageList object.
   imgList.Attach(hmyImageList);

   // Add a new icon to the image list.
   imgList.Add(AfxGetApp()->LoadStandardIcon(IDI_QUESTION));

   // Detach the handle from the CImageList object.
   imgList.Detach();
}

`CImageList::BeginDrag`

Call this function to begin dragging an image.

BOOL BeginDrag(
    int nImage,
    CPoint ptHotSpot);

Parameters

nImage
Zero-based index of the image to drag.

ptHotSpot
Coordinates of the starting drag position (typically, the cursor position). The coordinates are relative to the upper left corner of the image.

Return Value

Nonzero if successful; otherwise 0.

Remarks

This function creates a temporary image list that is used for dragging. The image combines the specified image and its mask with the current cursor. In response to subsequent WM_MOUSEMOVE messages, you can move the drag image by using the DragMove member function. To end the drag operation, you can use the EndDrag member function.

Example

void CImageListDlg::OnLButtonDown(UINT nFlags, CPoint point)
{
   // Initialize the drag image (usually called from WM_LBUTTONDOWN).
   m_myImageList.BeginDrag(0, CPoint(0, 0));
   m_myImageList.DragEnter(this, point);

   CDialog::OnLButtonDown(nFlags, point);
}

`CImageList::CImageList`

Constructs a CImageList object.

CImageList();

`CImageList::Copy`

This member function implements the behavior of the Win32 function ImageList_Copy, as described in the Windows SDK.

BOOL Copy(
    int iDst,
    int iSrc,
    UINT uFlags = ILCF_MOVE);

BOOL Copy(
    int iDst,
    CImageList* pSrc,
    int iSrc,
    UINT uFlags = ILCF_MOVE);

Parameters

iDst
The zero-based index of the image to be used as the destination of the copy operation.

iSrc
The zero-based index of the image to be used as the source of the copy operation.

uFlags
The bit flag value that specifies the type of copy operation to be made. This parameter can be one of the following values:

Value	Meaning
`ILCF_MOVE`	The source image is copied to the destination image's index. This operation results in multiple instances of a given image. `ILCF_MOVE` is the default.
`ILCF_SWAP`	The source and destination images exchange positions within the image list.

pSrc
A pointer to a CImageList object that is the target of the copy operation.

Return Value

Nonzero if successful; otherwise zero.

Example

CImageList myImageList2;
myImageList2.Create(32, 32, ILC_COLOR8, 0, 4);

// Copy the first image from myImageList2 and make it
// the first image of m_myImageList.
m_myImageList.Copy(0, &myImageList2, 0, ILCF_MOVE);

// Recopy the image to make it also the last image in m_myImageList.
m_myImageList.Copy(m_myImageList.GetImageCount() - 1, (int)0,
                   (UINT)ILCF_MOVE);

`CImageList::Create`

Initializes an image list and attaches it to a CImageList object.

BOOL Create(
    int cx,
    int cy,
    UINT nFlags,
    int nInitial,
    int nGrow);

BOOL Create(
    UINT nBitmapID,
    int cx,
    int nGrow,
    COLORREF crMask);

BOOL Create(
    LPCTSTR lpszBitmapID,
    int cx,
    int nGrow,
    COLORREF crMask);

BOOL Create(
    CImageList& imagelist1,
    int nImage1,
    CImageList& imagelist2,
    int nImage2,
    int dx,
    int dy);

BOOL Create(CImageList* pImageList);

Parameters

cx
Dimensions of each image, in pixels.

cy
Dimensions of each image, in pixels.

nFlags
Specifies the type of image list to create. This parameter can be a combination of the following values, but it can include only one of the ILC_COLOR values.

Value	Meaning
`ILC_COLOR`	Use the default behavior if none of the other `ILC_COLOR*` flags is specified. Typically, the default is `ILC_COLOR4`; but for older display drivers, the default is `ILC_COLORDDB`.
`ILC_COLOR4`	Use a 4-bit (16 color) device-independent bitmap (DIB) section as the bitmap for the image list.
`ILC_COLOR8`	Use an 8-bit DIB section. The colors used for the color table are the same colors as the halftone palette.
`ILC_COLOR16`	Use a 16-bit (32/64k color) DIB section.
`ILC_COLOR24`	Use a 24-bit DIB section.
`ILC_COLOR32`	Use a 32-bit DIB section.
`ILC_COLORDDB`	Use a device-dependent bitmap.
`ILC_MASK`	Uses a mask. The image list contains two bitmaps, one of which is a monochrome bitmap used as a mask. If this value is not included, the image list contains only one bitmap. See Drawing Images from an Image List for additional information on masked images.

nInitial
Number of images that the image list initially contains.

nGrow
Number of images by which the image list can grow when the system needs to resize the list to make room for new images. This parameter represents the number of new images the resized image list can contain.

nBitmapID
Resource IDs of the bitmap to be associated with the image list.

crMask
Color used to generate a mask. Each pixel of this color in the specified bitmap is changed to black, and the corresponding bit in the mask is set to one.

lpszBitmapID
A string containing the resource IDs of the images.

imagelist1
A reference to a CImageList object.

nImage1
Index of the first existing image.

imagelist2
A reference to a CImageList object.

nImage2
Index of the second existing image.

dx
Offset of the x-axis of the second image in relationship to the first image, in pixels.

dy
Offset of the y-axis of the second image in relationship to the first image, in pixels.

pImageList
A pointer to a CImageList object.

Return Value

Nonzero if successful; otherwise 0.

Remarks

You construct a CImageList in two steps. First, call the constructor and then call Create, which creates the image list and attaches it to the CImageList object.

Example

m_myImageList.Create(32, 32, ILC_COLOR8, 0, 4);

`CImageList::DeleteImageList`

Call this function to delete an image list.

BOOL DeleteImageList();

Return Value

Nonzero if successful; otherwise 0.

Example

// Delete the image list and verify.
myImageList2.DeleteImageList();
ASSERT(myImageList2.GetSafeHandle() == NULL);

`CImageList::DeleteTempMap`

Called automatically by the CWinApp idle-time handler, DeleteTempMap deletes any temporary CImageList objects created by FromHandle, but does not destroy any handles ( hImageList) temporarily associated with the ImageList objects.

static void PASCAL DeleteTempMap();

Example

// Note that this is a static member so an instantiated CImageList
// object is unnecessary.
CImageList::DeleteTempMap();

`CImageList::Detach`

Call this function to detach an image list object from a CImageList object.

HIMAGELIST Detach();

Return Value

A handle to an image list object.

Remarks

This function returns a handle to the image list object.

Example

See the example for CImageList::Attach.

`CImageList::DragEnter`

During a drag operation, locks updates to the window specified by pWndLock and displays the drag image at the position specified by point.

static BOOL PASCAL DragEnter(
    CWnd* pWndLock,
    CPoint point);

Parameters

pWndLock
Pointer to the window that owns the drag image.

point
Position at which to display the drag image. Coordinates are relative to the upper left corner of the window (not the client area).

Return Value

Nonzero if successful; otherwise 0.

Remarks

The coordinates are relative to the window's upper left corner, so you must compensate for the widths of window elements, such as the border, title bar, and menu bar, when specifying the coordinates.

If pWndLock is NULL, this function draws the image in the display context associated with the desktop window, and coordinates are relative to the upper left corner of the screen.

This function locks all other updates to the given window during the drag operation. If you need to do any drawing during a drag operation, such as highlighting the target of a drag-and-drop operation, you can temporarily hide the dragged image by using the CImageList::DragLeave function.

Example

See the example for CImageList::BeginDrag.

`CImageList::DragLeave`

Unlocks the window specified by pWndLock and hides the drag image, allowing the window to be updated.

static BOOL PASCAL DragLeave(CWnd* pWndLock);

Parameters

pWndLock
Pointer to the window that owns the drag image.

Return Value

Nonzero if successful; otherwise 0.

Example

See the example for CImageList::EndDrag.

`CImageList::DragMove`

Call this function to move the image that is being dragged during a drag-and-drop operation.

static BOOL PASCAL DragMove(CPoint pt);

Parameters

pt
New drag position.

Return Value

Nonzero if successful; otherwise 0.

Remarks

This function is typically called in response to a WM_MOUSEMOVE message. To begin a drag operation, use the BeginDrag member function.

Example

void CImageListDlg::OnMouseMove(UINT nFlags, CPoint point)
{
   m_myImageList.DragMove(point);

   CDialog::OnMouseMove(nFlags, point);
}

`CImageList::DragShowNolock`

Shows or hides the drag image during a drag operation, without locking the window.

static BOOL PASCAL DragShowNolock(BOOL bShow);

Parameters

bShow
Specifies whether the drag image is to be shown.

Return Value

Nonzero if successful; otherwise 0.

Remarks

The CImageList::DragEnter function locks all updates to the window during a drag operation. This function, however, does not lock the window.

`CImageList::Draw`

Call this function to draw the image that is being dragged during a drag-and-drop operation.

BOOL Draw(
    CDC* pDC,
    int nImage,
    POINT pt,
    UINT nStyle);

Parameters

pDC
Pointer to the destination device context.

nImage
Zero-based index of the image to draw.

pt
Location at which to draw within the specified device context.

nStyle
Flag specifying the drawing style. It can be one or more of these values:

Value	Meaning
`ILD_BLEND25`, `ILD_FOCUS`	Draws the image, blending 25 percent with the system highlight color. This value has no effect if the image list does not contain a mask.
`ILD_BLEND50`, `ILD_SELECTED`, `ILD_BLEND`	Draws the image, blending 50 percent with the system highlight color. This value has no effect if the image list does not contain a mask.
`ILD_MASK`	Draws the mask.
`ILD_NORMAL`	Draws the image using the background color for the image list. If the background color is the `CLR_NONE` value, the image is drawn transparently using the mask.
`ILD_TRANSPARENT`	Draws the image transparently using the mask, regardless of the background color.

Return Value

Nonzero if successful; otherwise 0.

Example

See the example for CImageList::SetOverlayImage.

`CImageList::DrawEx`

Draws an image list item in the specified device context.

BOOL DrawEx(
    CDC* pDC,
    int nImage,
    POINT pt,
    SIZE sz,
    COLORREF clrBk,
    COLORREF clrFg,
    UINT nStyle);

Parameters

pDC
Pointer to the destination device context.

nImage
Zero-based index of the image to draw.

pt
Location at which to draw within the specified device context.

sz
Size of the portion of the image to draw relative to the upper-left corner of the image. See dx and dy in ImageList_DrawEx in the Windows SDK.

clrBk
Background color of the image. See rgbBk in ImageList_DrawEx in the Windows SDK.

clrFg
Foreground color of the image. See rgbFg in ImageList_DrawEx in the Windows SDK.

nStyle
Flag specifying the drawing style. See fStyle in ImageList_DrawEx in the Windows SDK.

Return Value

Nonzero if successful; otherwise 0.

Remarks

The function uses the specified drawing style and blends the image with the specified color.

Example

m_myImageList.DrawEx(&dc, 0, CPoint(0, 0), CSize(16, 16), CLR_DEFAULT,
                     CLR_DEFAULT, ILD_IMAGE);

`CImageList::DrawIndirect`

Call this member function to draw an image from an image list.

BOOL DrawIndirect(IMAGELISTDRAWPARAMS* pimldp);

BOOL DrawIndirect(
    CDC* pDC,
    int nImage,
    POINT pt,
    SIZE sz,
    POINT ptOrigin,
    UINT fStyle = ILD_NORMAL,
    DWORD dwRop = SRCCOPY,
    COLORREF rgbBack = CLR_DEFAULT,
    COLORREF rgbFore = CLR_DEFAULT,
    DWORD fState = ILS_NORMAL,
    DWORD Frame = 0,
    COLORREF crEffect = CLR_DEFAULT);

Parameters

pimldp
A pointer to an IMAGELISTDRAWPARAMS structure that contains information about the draw operation.

pDC
A pointer to the destination device context. You must delete this CDC object when you are done with it.

nImage
The zero-based index of the image to be drawn.

pt
A POINT structure containing the x- and y- coordinates where the image will be drawn.

sz
A SIZE structure indicating the size of the image to be drawn.

ptOrigin
A POINT structure containing the x- and y-coordinates specifying the upper left corner of the drawing operation with respect to the image itself. Pixels of the image that are to the left of the x-coordinate and above the y-coordinate are not drawn.

fStyle
Flag specifying the drawing style and, optionally, the overlay image. See the Remarks section for information on the overlay image. The MFC default implementation, ILD_NORMAL, draws the image using the background color for the image list. If the background color is the CLR_NONE value, the image is drawn transparently using a mask.

Other possible styles are described under the fStyle member of the IMAGELISTDRAWPARAMS structure.

dwRop
Value specifying a raster-operation code. These codes define how the color data for the source rectangle will be combined with the color data for the destination rectangle to achieve the final color. MFC's default implementation, SRCCOPY, copies the source rectangle directly to the destination rectangle. This parameter is ignored if the fStyle parameter does not include the ILD_ROP flag.

Other possible values are described under the dwRop member of the IMAGELISTDRAWPARAMS structure.

rgbBack
The image background color, by default CLR_DEFAULT. This parameter can be an application-defined RGB value or one of the following values:

Value	Meaning
`CLR_DEFAULT`	Default background color. The image is drawn using the image list background color.
`CLR_NONE`	No background color. The image is drawn transparently.

rgbFore
Image foreground color, by default CLR_DEFAULT. This parameter can be an application-defined RGB value or one of the following values:

Value	Meaning
`CLR_DEFAULT`	Default foreground color. The image is drawn using the system highlight color as the foreground color.
`CLR_NONE`	No blend color. The image is blended with the color of the destination device context.

This parameter is used only if fStyle includes the ILD_BLEND25 or ILD_BLEND50 flag.

fState
Flag specifying the drawing state. This member can contain one or more image list state flags.

Frame
Affects the behavior of saturate and alpha-blending effects.

When used with ILS_SATURATE, this member holds the value that is added to each color component of the RGB triplet for each pixel in the icon.

When used with ILS_APLHA, this member holds the value for the alpha channel. This value can be from 0 to 255, with 0 being completely transparent, and 255 being completely opaque.

crEffect
A COLORREF value used for glow and shadow effects.

Return Value

TRUE if the image is successfully drawn; otherwise FALSE.

Remarks

Use the first version if you want to fill the Win32 structure yourself. Use the second version if you want to take advantage of one or more of MFC's default arguments, or avoid managing the structure.

An overlay image is an image that is drawn on top of the primary image, specified in this member function by the nImage parameter. Draw an overlay mask by using the Draw member function with the one-based index of the overlay mask specified by using the INDEXTOOVERLAYMASK macro.

Example

int i, dx, cx, cy, nCount = m_myImageList.GetImageCount();

::ImageList_GetIconSize(m_myImageList, &cx, &cy);

// Draw the images of the image list on the DC.
for (dx = 0, i = 0; i < nCount; i++)
{
   m_myImageList.DrawIndirect(&dc, i, CPoint(dx, 0),
                              CSize(cx, cy), CPoint(0, 0));
   dx += cx;
}

`CImageList::EndDrag`

Call this function to end a drag operation.

static void PASCAL EndDrag();

Remarks

To begin a drag operation, use the BeginDrag member function.

Example

void CImageListDlg::OnLButtonUp(UINT nFlags, CPoint point)
{
   // Terminate the drag image (usually called from WM_LBUTTONUP).
   m_myImageList.DragLeave(this);
   m_myImageList.EndDrag();

   CDialog::OnLButtonUp(nFlags, point);
}

`CImageList::ExtractIcon`

Call this function to create an icon based on an image and its related mask in an image list.

HICON ExtractIcon(int nImage);

Parameters

nImage
Zero-based index of the image.

Return Value

Handle of the icon if successful; otherwise NULL.

Remarks

This method relies on the behavior of the ImageList_ExtractIcon macro to create the icon. Refer to the ImageList_ExtractIcon macro for more information on icon creation and cleanup.

Example

int i, dx, cx, cy, nCount = m_myImageList.GetImageCount();
HICON hIcon;

::ImageList_GetIconSize(m_myImageList, &cx, &cy);

// Draw the images of the image list on the DC.
for (dx = 0, i = 0; i < nCount; i++)
{
   hIcon = m_myImageList.ExtractIcon(i);

   dc.DrawIcon(dx, 0, hIcon);
   dx += cx;
}

`CImageList::FromHandle`

Returns a pointer to a CImageList object when given a handle to an image list.

static CImageList* PASCAL FromHandle(HIMAGELIST hImageList);

Parameters

hImageList
Specifies the image list.

Return Value

A pointer to a CImageList object if successful; otherwise NULL.

Remarks

If a CImageList is not already attached to the handle, a temporary CImageList object is created and attached. This temporary CImageList object is valid only until the next time the application has idle time in its event loop, at which time all temporary objects are deleted.

Example

CImageList *ConvertHandle(HIMAGELIST hmyImageList)
{
   // Convert the HIMAGELIST to a CImageList*.
   ASSERT(hmyImageList != NULL);
   CImageList *pmyImageList = CImageList::FromHandle(hmyImageList);
   ASSERT(pmyImageList != NULL);

   return pmyImageList;
}

`CImageList::FromHandlePermanent`

Returns a pointer to a CImageList object when given a handle to an image list.

static CImageList* PASCAL FromHandlePermanent(HIMAGELIST hImageList);

Parameters

hImageList
Specifies the image list.

Return Value

A pointer to a CImageList object if successful; otherwise NULL.

Remarks

If a CImageList object is not attached to the handle, NULL is returned.

Example

CImageList *ConvertHandlePermanent(HIMAGELIST hmyImageList)
{
   // Convert the HIMAGELIST to a CImageList*.
   ASSERT(hmyImageList != NULL);
   CImageList *pmyImageList = CImageList::FromHandlePermanent(hmyImageList);
   ASSERT(pmyImageList != NULL);

   return pmyImageList;
}

`CImageList::GetBkColor`

Call this function to retrieve the current background color for an image list.

COLORREF GetBkColor() const;

Return Value

The RGB color value of the CImageList object background color.

Example

See the example for CImageList::SetBkColor.

`CImageList::GetDragImage`

Gets the temporary image list that is used for dragging.

static CImageList* PASCAL GetDragImage(
    LPPOINT lpPoint,
    LPPOINT lpPointHotSpot);

Parameters

lpPoint
Address of a POINT structure that receives the current drag position.

lpPointHotSpot
Address of a POINT structure that receives the offset of the drag image relative to the drag position.

Return Value

If successful, a pointer to the temporary image list that is used for dragging; otherwise, NULL.

`CImageList::GetImageCount`

Call this function to retrieve the number of images in an image list.

int GetImageCount() const;

Return Value

The number of images.

Example

See the example for CImageList::ExtractIcon.

`CImageList::GetImageInfo`

Call this function to retrieve information about an image.

BOOL GetImageInfo(
    int nImage,
    IMAGEINFO* pImageInfo) const;

Parameters

nImage
Zero-based index of the image.

pImageInfo
Pointer to an IMAGEINFO structure that receives information about the image. The information in this structure can be used to directly manipulate the bitmaps for the image.

Return Value

Nonzero if successful; otherwise 0.

Remarks

The IMAGEINFO structure contains information about an image in an image list.

`CImageList::GetSafeHandle`

Call this function to retrieve the m_hImageList data member.

HIMAGELIST GetSafeHandle() const;

Return Value

A handle to the attached image list; otherwise NULL if no object is attached.

Example

// Get the safe handle to the image list.
HIMAGELIST hImageList = m_myImageList.GetSafeHandle();

`CImageList::m_hImageList`

A handle of the image list attached to this object.

HIMAGELIST m_hImageList;

Remarks

The m_hImageList data member is a public variable of type HIMAGELIST.

Example

// Get the safe handle to the image list.
HIMAGELIST hImageList = m_myImageList.m_hImageList;

`CImageList::operator HIMAGELIST`

Use this operator to get the attached handle of the CImageList object.

operator HIMAGELIST() const;

Return Value

If successful, a handle to the image list represented by the CImageList object; otherwise NULL.

Remarks

This operator is a casting operator, which supports direct use of an HIMAGELIST object.

Example

// Get the safe handle to the image list.
HIMAGELIST hImageList = m_myImageList;

`CImageList::Read`

Call this function to read an image list from an archive.

BOOL Read(CArchive* pArchive);

Parameters

pArchive
A pointer to a CArchive object from which the image list is to be read.

Return Value

Nonzero if successful; otherwise 0.

Example

// Open the archive to load the image list from.
CFile myFile(_T("myfile.data"), CFile::modeRead);
CArchive ar(&myFile, CArchive::load);
CImageList myImgList;

// Load the image list from the archive.
myImgList.Read(&ar);

`CImageList::Remove`

Call this function to remove an image from an image list object.

BOOL Remove(int nImage);

Parameters

nImage
Zero-based index of the image to remove.

Return Value

Nonzero if successful; otherwise 0.

Remarks

All items following nImage now move down one position. For example, if an image list contains two items, deleting the first item will cause the remaining item to now be in the first position. nImage=0 for the item in the first position.

Example

// Remove every other image from the image list.
for (int i = 0; i < m_myImageList.GetImageCount(); i++)
{
   m_myImageList.Remove(i);
}

`CImageList::Replace`

Call this function to replace an image in an image list with a new image.

BOOL Replace(
    int nImage,
    CBitmap* pbmImage,
    CBitmap* pbmMask);

int Replace(
    int nImage,
    HICON hIcon);

Parameters

nImage
Zero-based index of the image to replace.

pbmImage
A pointer to the bitmap containing the image.

pbmMask
A pointer to the bitmap containing the mask. If no mask is used with the image list, this parameter is ignored.

hIcon
A handle to the icon that contains the bitmap and mask for the new image.

Return Value

The version returning BOOL returns nonzero if successful; otherwise 0.

The version returning int returns the zero-based index of the image if successful; otherwise - 1.

Remarks

Call this member function after calling SetImageCount to assign the new, valid images to the placeholder image index numbers.

Example

See the example for CImageList::SetImageCount.

`CImageList::SetBkColor`

Call this function to set the background color for an image list.

COLORREF SetBkColor(COLORREF cr);

Parameters

cr
Background color to set. It can be CLR_NONE. In that case, images are drawn transparently using the mask.

Return Value

The previous background color if successful; otherwise CLR_NONE.

Example

// Set the background color to white.
m_myImageList.SetBkColor(RGB(255, 255, 255));
ASSERT(m_myImageList.GetBkColor() == RGB(255, 255, 255));

`CImageList::SetDragCursorImage`

Creates a new drag image by combining the given image (typically a mouse cursor image) with the current drag image.

BOOL SetDragCursorImage(
    int nDrag,
    CPoint ptHotSpot);

Parameters

nDrag
Index of the new image to be combined with the drag image.

ptHotSpot
Position of the hot spot within the new image.

Return Value

Nonzero if successful; otherwise 0.

Remarks

Because the dragging functions use the new image during a drag operation, you should use the Windows ShowCursor function to hide the actual mouse cursor after calling CImageList::SetDragCursorImage. Otherwise, the system may appear to have two mouse cursors for the duration of the drag operation.

`CImageList::SetImageCount`

Call this member function to reset the number of images in a CImageList object.

BOOL SetImageCount(UINT uNewCount);

Parameters

uNewCount
The value specifying the new total number of images in the image list.

Return Value

Nonzero if successful; otherwise zero.

Remarks

If you call this member function to increase the number of images in the image list, then call Replace for each additional image to assign the new indexes to valid images. If you fail to assign the indexes to valid images, draw operations that create the new images will be unpredictable.

If you decrease the size of an image list by using this function, the truncated images are freed.

Example

// Set the image count of the image list to be 10 with
// all images being the system question mark icon.
m_myImageList.SetImageCount(10);
HICON hIcon = AfxGetApp()->LoadStandardIcon(IDI_QUESTION);

for (int i = 0; i < 10; i++)
{
   m_myImageList.Replace(i, hIcon);
}

`CImageList::SetOverlayImage`

Call this function to add the zero-based index of an image to the list of images to be used as overlay masks.

BOOL SetOverlayImage(
    int nImage,
    int nOverlay);

Parameters

nImage
Zero-based index of the image to use as an overlay mask.

nOverlay
One-based index of the overlay mask.

Return Value

Nonzero if successful; otherwise 0.

Remarks

Up to four indices can be added to the list.

An overlay mask is an image drawn transparently over another image. Draw an overlay mask over an image by using the CImageList::Draw member function with the one-based index of the overlay mask specified by using the INDEXTOOVERLAYMASK macro.

Example

// Add a new image to the image list.
int nIndex = m_myImageList.Add(AfxGetApp()->LoadStandardIcon(IDI_QUESTION));

if (nIndex != -1)
{
   // Make the new image an overlay image.
   m_myImageList.SetOverlayImage(nIndex, 1);

   // Draw the first image in the image list with an overlay image.
   m_myImageList.Draw(&dc, 0, CPoint(0, 0), INDEXTOOVERLAYMASK(1));
}

`CImageList::Write`

Call this function to write an image list object to an archive.

BOOL Write(CArchive* pArchive);

Parameters

pArchive
A pointer to a CArchive object in which the image list is to be stored.

Return Value

Nonzero if successful; otherwise 0.

Example

// Open the archive to store the image list in.
CFile myFile(_T("myfile.data"), CFile::modeCreate | CFile::modeWrite);
CArchive ar(&myFile, CArchive::store);

// Store the image list in the archive.
m_myImageList.Write(&ar);

CImageList Class

Syntax

Members

Public Constructors

Public Methods

Public Operators

Public Data Members

Remarks

Inheritance Hierarchy

Requirements

CImageList::Add

Parameters

Return Value

Remarks

Example

CImageList::Attach

Parameters

Return Value

Example

CImageList::BeginDrag

Parameters

Return Value

Remarks

Example

CImageList::CImageList

CImageList::Copy

Parameters

Return Value

Example

CImageList::Create

Parameters

Return Value

Remarks

Example

CImageList::DeleteImageList

Return Value

Example

CImageList::DeleteTempMap

Example

CImageList::Detach

Return Value

Remarks

Example

CImageList::DragEnter

Parameters

Return Value

Remarks

Example

CImageList::DragLeave

Parameters

Return Value

Example

CImageList::DragMove

Parameters

Return Value

Remarks

Example

CImageList::DragShowNolock

Parameters

Return Value

Remarks

CImageList::Draw

Parameters

Return Value

Example

CImageList::DrawEx

Parameters

Return Value

Remarks

Example

CImageList::DrawIndirect

Parameters

Return Value

Remarks

Example

CImageList::EndDrag

Remarks

Example

CImageList::ExtractIcon

Parameters

`CImageList` Class

`CImageList::Add`

`CImageList::Attach`

`CImageList::BeginDrag`

`CImageList::CImageList`

`CImageList::Copy`

`CImageList::Create`

`CImageList::DeleteImageList`

`CImageList::DeleteTempMap`

`CImageList::Detach`

`CImageList::DragEnter`

`CImageList::DragLeave`

`CImageList::DragMove`

`CImageList::DragShowNolock`

`CImageList::Draw`

`CImageList::DrawEx`

`CImageList::DrawIndirect`

`CImageList::EndDrag`

`CImageList::ExtractIcon`

`CImageList::FromHandle`

`CImageList::FromHandlePermanent`

`CImageList::GetBkColor`

`CImageList::GetDragImage`

`CImageList::GetImageCount`

`CImageList::GetImageInfo`

`CImageList::GetSafeHandle`

`CImageList::m_hImageList`

`CImageList::operator HIMAGELIST`

`CImageList::Read`

`CImageList::Remove`

`CImageList::Replace`

`CImageList::SetBkColor`

`CImageList::SetDragCursorImage`

`CImageList::SetImageCount`

`CImageList::SetOverlayImage`

`CImageList::Write`