`CImageList` 类

项目
06/16/2023

提供 Windows 公共图像列表控件的功能。

语法

class CImageList : public CObject

成员

公共构造函数

名称	描述
`CImageList::CImageList`	构造 `CImageList` 对象。

公共方法

名称	描述
`CImageList::Add`	向图像列表添加图像。
`CImageList::Attach`	将图像列表附加到 `CImageList` 对象。
`CImageList::BeginDrag`	开始拖动图像。
`CImageList::Copy`	在 `CImageList` 对象中复制图像。
`CImageList::Create`	初始化图像列表并将其附加到 `CImageList` 对象。
`CImageList::DeleteImageList`	删除图像列表。
`CImageList::DeleteTempMap`	由 `CWinApp` 空闲时间处理程序调用，以删除由 `FromHandle` 创建的任何临时 `CImageList` 对象。
`CImageList::Detach`	从 `CImageList` 对象中拆离图像列表对象并返回图像列表的句柄。
`CImageList::DragEnter`	在拖动操作期间锁定更新，并在指定位置显示拖动图像。
`CImageList::DragLeave`	解锁窗口并隐藏拖动图像，以便可以更新窗口。
`CImageList::DragMove`	移动在拖放操作期间拖动的图像。
`CImageList::DragShowNolock`	在拖动操作期间显示或隐藏拖动图像，而不锁定窗口。
`CImageList::Draw`	绘制在拖放操作期间拖动的图像。
`CImageList::DrawEx`	在指定的设备上下文中绘制图像列表项。该函数使用指定的绘图样式，并将图像与指定颜色混合。
`CImageList::DrawIndirect`	绘制图像列表中的图像。
`CImageList::EndDrag`	结束拖动操作。
`CImageList::ExtractIcon`	基于图像列表中的图像和蒙板创建图标。
`CImageList::FromHandle`	在提供了图像列表的句柄时返回指向 `CImageList` 对象的指针。如果 `CImageList` 对象未附加到该句柄，则会创建并附加一个临时 `CImageList` 对象。
`CImageList::FromHandlePermanent`	在提供了图像列表的句柄时返回指向 `CImageList` 对象的指针。如果未将 `CImageList` 对象附加到句柄，则返回 NULL。
`CImageList::GetBkColor`	检索图像列表的当前背景色。
`CImageList::GetDragImage`	获取用于拖动的临时图像列表。
`CImageList::GetImageCount`	检索图像列表中的图像数。
`CImageList::GetImageInfo`	检索有关图像的信息。
`CImageList::GetSafeHandle`	检索 `m_hImageList`。
`CImageList::Read`	从存档中读取图像列表。
`CImageList::Remove`	从图像列表中移除图像。
`CImageList::Replace`	将图像列表中的图像替换为新图像。
`CImageList::SetBkColor`	设置图像列表的背景色。
`CImageList::SetDragCursorImage`	创建新的拖动图像。
`CImageList::SetImageCount`	重置图像列表中的图像计数。
`CImageList::SetOverlayImage`	将图像的从零开始的索引添加到要用作覆盖掩码的图像列表中。
`CImageList::Write`	将图像列表写入存档。

公共运算符

“属性”	描述
`CImageList::operator HIMAGELIST`	返回附加到 `CImageList` 的 `HIMAGELIST`。

公共数据成员

“属性”	描述
`CImageList::m_hImageList`	包含附加到此对象的图像列表的句柄。

备注

“图像列表”是一个由相同大小的图像组成的集合，每一个图像都可以通过其从零开始的索引引用。图像列表用于有效地管理大的图标或位图集。图像列表中的所有图像包含在一个采用屏幕设备格式的宽位图中。图像列表可能包含一个单色位图，该位图包含用于透明地绘制图像的蒙板（图标样式）。 Microsoft Win32 应用程序编程接口 (API) 提供可让你绘制图像、创建和销毁图像列表、添加和移除图像、替换图像、合并图像以及拖动图像的图像列表函数。

此控件（以及 CImageList 类）仅适用于在 Windows 95/98 和 Windows NT 版本 3.51 及更高版本下运行的程序。

有关使用 CImageList 的详细信息，请参阅控件和使用 CImageList。

继承层次结构

CObject

CImageList

要求

标头afxcmn.h：

`CImageList::Add`

调用此函数可向图像列表添加一个或多个图像或图标。

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

int Add(
    CBitmap* pbmImage,
    COLORREF crMask);

int Add(HICON hIcon);

参数

pbmImage
指向包含图像的位图的指针。图像数是从位图的宽度推断出来的。

pbmMask
指向包含蒙板的位图的指针。如果未将蒙板用于图像列表，则忽略此参数。

crMask
用于生成蒙板的颜色。给定位图中此颜色的每个像素都更改为黑色，蒙板中的相应位设置为一个。

hIcon
包含新图像的位图和蒙板的图标句柄。

返回值

如果成功，则为第一个新图像的从零开始的索引；否则为 -1。

备注

你需要负责在处理完图柄句柄后将其释放。

示例

// 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`

调用此函数可将图像列表附加到 CImageList 对象。

BOOL Attach(HIMAGELIST hImageList);

参数

hImageList
图像列表对象的句柄。

返回值

如果附加成功，则不为 0；否则为 0。

示例

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`

调用此函数可开始拖动图像。

BOOL BeginDrag(
    int nImage,
    CPoint ptHotSpot);

参数

nImage
要拖动的图像的从零开始的索引。

ptHotSpot
起始拖动位置（通常是光标位置）的坐标。坐标相对于图像的左上角。

返回值

如果成功，则不为 0；否则为 0。

备注

此函数创建用于拖动的临时图像列表。该图像将指定的图像及其蒙板与当前光标组合在一起。为了响应后续 WM_MOUSEMOVE 消息，可以使用 DragMove 成员函数移动拖动图像。若要结束拖动操作，可以使用 EndDrag 成员函数。

示例

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`

构造 CImageList 对象。

CImageList();

`CImageList::Copy`

此成员函数实现 Win32 函数 ImageList_Copy 的行为，如 Windows SDK 中所述。

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

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

参数

iDst
要用作复制操作目标的图像的从零开始的索引。

iSrc
要用作复制操作源的图像的从零开始的索引。

uFlags
指定要进行的复制操作类型的位标志值。此参数可能是以下值之一：

值	含义
`ILCF_MOVE`	源图像被复制到目标图像的索引中。此操作导致给定图像的多个实例。 `ILCF_MOVE` 是默认值。
`ILCF_SWAP`	源图像和目标图像在图像列表中交换位置。

pSrc
指向作为复制操作目标的 CImageList 对象的指针。

返回值

如果成功，则不为零，否则为零。

示例

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`

初始化图像列表并将其附加到 CImageList 对象。

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);

参数

cx
每个图像的尺寸，以像素为单位。

cy
每个图像的尺寸，以像素为单位。

nFlags
指定要创建的图像列表的类型。此参数可以是以下值的组合，但它只能包含一个 ILC_COLOR 值。

值	含义
`ILC_COLOR`	如果未指定其他 `ILC_COLOR*` 标志，则使用默认行为。通常，默认值为 `ILC_COLOR4`；但对于较旧的显示驱动程序，默认值为 `ILC_COLORDDB`。
`ILC_COLOR4`	使用 4 位（16 色）与设备无关的位图 (DIB) 节作为图像列表的位图。
`ILC_COLOR8`	使用 8 位 DIB 节。用于颜色表的颜色与半色调调色板的颜色相同。
`ILC_COLOR16`	使用 16 位（32/64k 颜色）DIB 节。
`ILC_COLOR24`	使用 24 位 DIB 节。
`ILC_COLOR32`	使用 32 位 DIB 节。
`ILC_COLORDDB`	使用与设备相关的位图。
`ILC_MASK`	使用蒙板。图像列表包含两个位图，其中一个是用作蒙板的单色位图。如果未包含此值，则图像列表仅包含一个位图。有关么蒙板图像的其他信息，请参阅绘制图像列表中的图像。

nInitial
图像列表最初包含的图像数。

nGrow
当系统需要调整列表大小以为新图像腾出空间时，图像列表可以增长的图像数。此参数表示重设大小的图像列表可以包含的新图像数。

nBitmapID
要与图像列表关联的位图的资源 ID。

crMask
用于生成蒙板的颜色。指定位图中此颜色的每个像素都更改为黑色，蒙板中的相应位设置为一个。

lpszBitmapID
包含图像的资源 ID 的字符串。

imagelist1
对 CImageList 对象的引用。

nImage1
第一个现有图像的索引。

imagelist2
对 CImageList 对象的引用。

nImage2
第二个现有图像的索引。

dx
第二个图像相对于第一个图像的 x 轴偏移量（以像素为单位）。

dy
第二个图像相对于第一个图像的 y 轴偏移量（以像素为单位）。

pImageList
一个指向 CImageList 对象的指针。

返回值

如果成功，则不为 0；否则为 0。

备注

分两步构建 CImageList。首先，调用构造函数，然后调用 Create，这将创建图像列表并将其附加到 CImageList 对象。

示例

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

`CImageList::DeleteImageList`

调用此函数可删除图像列表。

BOOL DeleteImageList();

返回值

如果成功，则不为 0；否则为 0。

示例

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

`CImageList::DeleteTempMap`

DeleteTempMap 由 CWinApp 空闲时间处理程序自动调用，可删除由 FromHandle 创建的任何临时 CImageList 对象，但不会销毁与 ImageList 对象临时关联的任何句柄 (hImageList)。

static void PASCAL DeleteTempMap();

示例

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

`CImageList::Detach`

调用此函数可将图像列表对象从 CImageList 对象拆离。

HIMAGELIST Detach();

返回值

图像列表对象的句柄。

注解

此函数返回图像列表对象的句柄。

示例

请参阅 CImageList::Attach 的示例。

`CImageList::DragEnter`

在拖动操作期间，锁定对 pWndLock 指定的窗口的更新，并在 point 位置显示拖动图像。

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

参数

pWndLock
指向拥有拖动图像的窗口的指针。

point
显示拖动图像的位置。坐标相对于窗口的左上角（而不是工作区）。

返回值

如果成功，则不为 0；否则为 0。

备注

坐标相对于窗口的左上角，因此在指定坐标时必须补偿窗口元素的宽度，如边框、标题栏和菜单栏。

如果 pWndLock 为 NULL，则此函数在与桌面窗口关联的显示上下文中绘制图像，并且坐标相对于屏幕左上角。

此函数在拖动操作期间将锁定给定窗口的所有其他更新。如果需要在拖动操作期间执行任何绘制（如突出显示拖放操作的目标），可以使用 CImageList::DragLeave 函数暂时隐藏拖动的图像。

示例

请参阅 CImageList::BeginDrag 的示例。

`CImageList::DragLeave`

解锁 pWndLock 指定的窗口并隐藏拖动图像，从而允许更新窗口。

static BOOL PASCAL DragLeave(CWnd* pWndLock);

参数

pWndLock
指向拥有拖动图像的窗口的指针。

返回值

如果成功，则不为 0；否则为 0。

示例

请参阅 CImageList::EndDrag 的示例。

`CImageList::DragMove`

调用此函数可移动在拖放操作期间拖动的图像。

static BOOL PASCAL DragMove(CPoint pt);

参数

pt
新的拖动位置。

返回值

如果成功，则不为 0；否则为 0。

备注

通常调用此函数以响应 WM_MOUSEMOVE 消息。若要开始拖动操作，请使用 BeginDrag 成员函数。

示例

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

   CDialog::OnMouseMove(nFlags, point);
}

`CImageList::DragShowNolock`

在拖动操作期间显示或隐藏拖动图像，而不锁定窗口。

static BOOL PASCAL DragShowNolock(BOOL bShow);

参数

bShow
指定是否显示拖动图像。

返回值

如果成功，则不为 0；否则为 0。

注解

CImageList::DragEnter 函数在拖动操作期间锁定对窗口的所有更新。但是，此函数不会锁定窗口。

`CImageList::Draw`

调用此函数可绘制在拖放操作期间拖动的图像。

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

参数

pDC
指向目标设备上下文的指针。

nImage
要绘制的图像的从零开始的索引。

pt
在指定设备上下文中绘制的位置。

nStyle
指定绘制样式的标志。可以是以下一个或多个值：

值	含义
`ILD_BLEND25`，`ILD_FOCUS`	绘制图像，与系统突出显示颜色混合 25%。如果图像列表不包含蒙板，则此值不起作用。
`ILD_BLEND50`, `ILD_SELECTED`, `ILD_BLEND`	绘制图像，与系统突出显示颜色混合 50%。如果图像列表不包含蒙板，则此值不起作用。
`ILD_MASK`	绘制蒙板。
`ILD_NORMAL`	使用图像列表的背景色绘制图像。如果背景色为 `CLR_NONE` 值，则使用蒙板以透明方式绘制图像。
`ILD_TRANSPARENT`	使用蒙板以透明方式绘制图像，而不考虑背景色。

返回值

如果成功，则不为 0；否则为 0。

示例

请参阅 CImageList::SetOverlayImage 的示例。

`CImageList::DrawEx`

在指定的设备上下文中绘制图像列表项。

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

参数

pDC
指向目标设备上下文的指针。

nImage
要绘制的图像的从零开始的索引。

pt
在指定设备上下文中绘制的位置。

sz
要绘制的图像部分相对于图像左上角的大小。请参阅 Windows SDK 中 ImageList_DrawEx 中的 dx 和 dy。

clrBk
图像背景色。请参阅 Windows SDK 中 ImageList_DrawEx 中的 rgbBk。

clrFg
图像的前景色。请参阅 Windows SDK 中 ImageList_DrawEx 中的 rgbFg。

nStyle
指定绘制样式的标志。请参阅 Windows SDK 中 ImageList_DrawEx 中的 fStyle。

返回值

如果成功，则不为 0；否则为 0。

备注

该函数使用指定的绘图样式，并将图像与指定颜色混合。

示例

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

`CImageList::DrawIndirect`

调用此成员函数可绘制图像列表中的图像。

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);

参数

pimldp
指向包含绘制操作相关信息的 IMAGELISTDRAWPARAMS 结构的指针。

pDC
指向目标设备上下文的指针。完成后必须删除此 CDC 对象。

nImage
要绘制的图像的从零开始的索引。

pt
一个 POINT 结构，其中包含将绘制图像的 x 坐标和 y 坐标。

sz
一个 SIZE 结构，指示要绘制的图像的大小。

ptOrigin
一个 POINT 结构，其中包含的 x 坐标和 y 坐标指定绘图操作相对于图像本身的左上角。不绘制 x 坐标左侧和 y 坐标上方的图像像素。

fStyle
指定绘制样式的标志，还可以选择覆盖图像。有关覆盖图像的信息，请参阅“注解”部分。 MFC 默认实现 ILD_NORMAL 使用图像列表的背景色绘制图像。如果背景色为 CLR_NONE 值，则使用蒙板以透明方式绘制图像。

IMAGELISTDRAWPARAMS 结构的 fStyle 成员下描述了其他可能的样式。

dwRop
指定光栅操作代码的值。这些代码定义如何将源矩形的颜色数据与目标矩形的颜色数据组合以实现最终颜色。 MFC 的默认实现 SRCCOPY将源矩形直接复制到目标矩形。如果 fStyle 参数不包含 ILD_ROP 标志，则忽略此参数。

IMAGELISTDRAWPARAMS 结构的 dwRop 成员下描述了其他可能的值。

rgbBack
图像背景色，默认为 CLR_DEFAULT。此参数可以是应用程序定义的 RGB 值或以下值之一：

值	含义
`CLR_DEFAULT`	默认背景色。使用图像列表背景色绘制图像。
`CLR_NONE`	无背景色。以透明方式绘制图像。

rgbFore
图像前景色，默认为 CLR_DEFAULT。此参数可以是应用程序定义的 RGB 值或以下值之一：

值	含义
`CLR_DEFAULT`	默认前景色。使用系统突出显示颜色作为前景颜色绘制图像。
`CLR_NONE`	无混合颜色。图像与目标设备上下文的颜色混合。

仅当 fStyle 包含 ILD_BLEND25 或 ILD_BLEND50 标志时才使用此参数。

fState
指定绘制状态的标志。此成员可以包含一个或多个图像列表状态标志。

Frame
影响饱和和 alpha 混合效果的行为。

与 ILS_SATURATE 一起使用时，此成员保存添加到图标中每个像素的 RGB 三元组的每个颜色分量的值。

与 ILS_APLHA 一起使用时，此成员保存 Alpha 通道的值。此值可以为 0-255，0 表示完全透明，255 表示完全不透明。

crEffect
一个 COLORREF 值，用于发光和阴影效果。

返回值

如果成功绘制图像，则为 TRUE；否则为 FALSE。

注解

如果要自行填充 Win32 结构，请使用第一个版本。如果要利用 MFC 的一个或多个默认参数，或者要避免管理结构，请使用第二个版本。

覆盖图像是在主图像之上绘制的图像，在此成员函数中由 nImage 参数指定。通过结合使用 Draw 成员函数和使用 INDEXTOOVERLAYMASK 宏指定的覆盖蒙板的从 1 开始的索引，绘制覆盖蒙板。

示例

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`

调用此函数可结束拖动操作。

static void PASCAL EndDrag();

备注

若要开始拖动操作，请使用 BeginDrag 成员函数。

示例

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`

调用此函数可基于图像及其在图像列表中的相关蒙板创建图标。

HICON ExtractIcon(int nImage);

参数

nImage
图像的从零开始的索引。

返回值

如果成功，则为图标的句柄，否则为 NULL。

注解

此方法依赖于 ImageList_ExtractIcon 宏的行为来创建图标。有关图标创建和清理的详细信息，请参阅 ImageList_ExtractIcon 宏。

示例

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`

在提供了图像列表的句柄时返回指向 CImageList 对象的指针。

static CImageList* PASCAL FromHandle(HIMAGELIST hImageList);

参数

hImageList
指定图像列表。

返回值

如果成功，则为指向 CImageList 对象的指针；否则为 NULL。

备注

如果 CImageList 尚未附加到该句柄，则会创建并附加一个临时 CImageList 对象。此临时 CImageList 对象仅在应用程序下次在其事件循环中有空闲时间之前有效，到时将删除所有临时对象。

示例

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`

在提供了图像列表的句柄时返回指向 CImageList 对象的指针。

static CImageList* PASCAL FromHandlePermanent(HIMAGELIST hImageList);

参数

hImageList
指定图像列表。

返回值

如果成功，则为指向 CImageList 对象的指针；否则为 NULL。

备注

如果未将 CImageList 对象附加到句柄，则返回 NULL。

示例

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`

调用此函数可检索图像列表的当前背景色。

COLORREF GetBkColor() const;

返回值

CImageList 对象背景色的 RGB 颜色值。

示例

请参阅 CImageList::SetBkColor 的示例。

`CImageList::GetDragImage`

获取用于拖动的临时图像列表。

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

参数

lpPoint
接收当前拖动位置的 POINT 结构的地址。

lpPointHotSpot
POINT 结构的地址，该结构接收拖动图像相对于拖动位置的偏移量的。

返回值

如果成功，则为指向用于拖动的临时图像列表的指针；否则为 NULL。

`CImageList::GetImageCount`

调用此函数可检索图像列表中的图像数。

int GetImageCount() const;

返回值

图像数。

示例

请参阅 CImageList::ExtractIcon 的示例。

`CImageList::GetImageInfo`

调用此函数可检索有关图像的信息。

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

参数

nImage
图像的从零开始的索引。

pImageInfo
指向接收有关图像的信息的 IMAGEINFO 结构的指针。此结构中的信息可用于直接操作图像的位图。

返回值

如果成功，则不为 0；否则为 0。

注解

IMAGEINFO 结构包含有关图像列表中的图像的信息。

`CImageList::GetSafeHandle`

调用此函数可检索 m_hImageList 数据成员。

HIMAGELIST GetSafeHandle() const;

返回值

附加图像列表的句柄，否则为 NULL（如果没有附加对象）。

示例

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

`CImageList::m_hImageList`

附加到此对象的图像列表的句柄。

HIMAGELIST m_hImageList;

备注

m_hImageList 数据成员是 HIMAGELIST 类型的公共变量。

示例

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

`CImageList::operator HIMAGELIST`

使用此运算符获取 CImageList 对象的附加句柄。

operator HIMAGELIST() const;

返回值

如果成功，则为由 CImageList 对象表示的图像列表的句柄；否则为 NULL。

备注

此运算符是强制转换运算符，它支持直接使用 HIMAGELIST 对象。

示例

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

`CImageList::Read`

调用此函数可从存档读取图像列表。

BOOL Read(CArchive* pArchive);

参数

pArchive
指向要从中读取图像列表的 CArchive 对象的指针。

返回值

如果成功，则不为 0；否则为 0。

示例

// 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`

调用此函数可从图像列表对象中移除图像。

BOOL Remove(int nImage);

参数

nImage
要移除的图像的从零开始的索引。

返回值

如果成功，则不为 0；否则为 0。

备注

nImage 之后的所有项现在都下移一个位置。例如，如果一个图像列表包含两个项，则删除第一个项后，剩下那个项将补到第一位。 nImage=0 表示第一个位置的项。

示例

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

`CImageList::Replace`

调用此函数可将图像列表中的图像替换为新图像。

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

int Replace(
    int nImage,
    HICON hIcon);

参数

nImage
要替换的图像的从零开始的索引。

pbmImage
指向包含图像的位图的指针。

pbmMask
指向包含蒙板的位图的指针。如果未将蒙板用于图像列表，则忽略此参数。

hIcon
包含新图像的位图和蒙板的图标句柄。

返回值

如果成功，返回 BOOL 的版本返回非零值；否则返回 0。

如果成功，则返回 int 的版本返回图像的从零开始的索引；否则返回 -1。

备注

在调用 SetImageCount 后调用此成员函数，以将新的有效图像分配给占位符图像索引号。

示例

请参阅 CImageList::SetImageCount 的示例。

`CImageList::SetBkColor`

调用此函数可设置图像列表的背景色。

COLORREF SetBkColor(COLORREF cr);

参数

cr
要设置的背景色。它可能是 CLR_NONE。在这种情况下，使用蒙板以透明方式绘制图像。

返回值

如果成功，则为上一个背景色；否则为 CLR_NONE。

示例

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

`CImageList::SetDragCursorImage`

通过组合给定图像（通常是鼠标光标图像）与当前拖动图像来创建新的拖动图像。

BOOL SetDragCursorImage(
    int nDrag,
    CPoint ptHotSpot);

参数

nDrag
要与拖动图像组合的新图像的索引。

ptHotSpot
新图像中热点的位置。

返回值

如果成功，则不为 0；否则为 0。

注解

由于拖动函数将在拖动操作期间使用新图像，因此应使用 Windows ShowCursor 函数在调用 CImageList::SetDragCursorImage 后隐藏实际鼠标光标。否则，系统在拖动操作期间可能看起来具有两个鼠标光标。

`CImageList::SetImageCount`

调用此成员函数以重置 CImageList 对象中的图像数。

BOOL SetImageCount(UINT uNewCount);

参数

uNewCount
指定图像列表中的新图像总数的值。

返回值

如果成功，则不为零，否则为零。

注解

如果调用此成员函数来增加图像列表中的图像数，则为每个附加图像调用 Replace 以将新索引分配给有效图像。如果未能将索引分配给有效图像，则创建新图像的绘制操作将是不可预测的。

如果使用此函数减小图像列表的大小，将释放截断的图像。

示例

// 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`

通过调用此函数，可将图像的从零开始的索引添加到要用作覆盖蒙板的图像列表中。

BOOL SetOverlayImage(
    int nImage,
    int nOverlay);

参数

nImage
要用作覆盖蒙板的图像的从零开始的索引。

nOverlay
覆盖蒙板的从 1 开始的索引。

返回值

如果成功，则不为 0；否则为 0。

备注

最多可将四个索引添加到列表中。

覆盖蒙板是在其他图像上透明绘制的图像。通过结合使用 CImageList::Draw 成员函数和使用 INDEXTOOVERLAYMASK 宏指定的覆盖蒙板的从 1 开始的索引，在图像上绘制覆盖蒙板。

示例

// 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`

调用此函数可将图像列表对象写入存档。

BOOL Write(CArchive* pArchive);

参数

pArchive
指向要在其中存储图像列表的 CArchive 对象的指针。

返回值

如果成功，则不为 0；否则为 0。

示例

// 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);

另请参阅

CObject 类
 层次结构图
 CListCtrl 类
 CTabCtrl 类

Share via

CImageList 类

语法

成员

公共构造函数

公共方法

公共运算符

公共数据成员

备注

继承层次结构

要求

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` 类

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