`CImageList` 類別

發行項
07/05/2024

提供 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`	傳 `HIMAGELIST` 回附加至的 `CImageList`。

公用資料成員

名稱	描述
`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。

範例

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。

備註

此函式會建立用於拖曳的暫存影像清單。影像會結合指定的影像及其遮罩與目前的游標。為了回應後續 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 ，該對像是複製作業的目標。

傳回值

如果成功則不為零，否則為 0。

範例

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
要與影像清單相關聯之位圖的資源標識符。

crMask
用來產生遮罩的色彩。指定位圖中此色彩的每個像素都會變更為黑色，而遮罩中的對應位會設定為一個。

lpszBitmapID
包含影像資源識別碼的字串。

imagelist1
對 CImageList 物件的參考。

nImage1
第一個現有影像的索引。

imagelist2
對 CImageList 物件的參考。

nImage2
第二個現有影像的索引。

dx
與第一個影像關聯性之第二個影像的 X 軸位移，以像素為單位。

dy
與第一個影像關聯性之第二個影像的 Y 軸位移，以像素為單位。

pImageList
CImageList 物件的指標。

傳回值

如果成功則為非零；否則為 0。

備註

您會在兩個步驟中建構 CImageList 。首先，呼叫建構函式，然後呼叫 Create，這會建立映像清單並將它附加至 CImageList 物件。

範例

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

`CImageList::DeleteImageList`

呼叫此函式以刪除影像清單。

BOOL DeleteImageList();

傳回值

如果成功則為非零；否則為 0。

範例

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

`CImageList::DeleteTempMap`

由CWinApp閑置時間處理程式自動呼叫，DeleteTempMap刪除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。

備註

座標相對於視窗的左上角，因此您必須在指定座標時補償視窗元素的寬度，例如框線、標題列和功能表欄。

如果 pWndLock 為 NULL，則此函式會在與桌面視窗相關聯的顯示內容中繪製影像，而座標則相對於畫面左上角。

此函式會在拖曳作業期間鎖定指定視窗的所有其他更新。如果您需要在拖曳作業期間執行任何繪圖，例如醒目提示拖放作業的目標，您可以使用函式暫時隱藏拖曳的影像 CImageList::DragLeave 。

範例

請參閱 CImageList::BeginDrag 的範例。

`CImageList::DragLeave`

解除鎖定所 pWndLock 指定的視窗，並隱藏拖曳影像，讓視窗得以更新。

static BOOL PASCAL DragLeave(CWnd* pWndLock);

參數

pWndLock
擁有拖曳影像之視窗的指標。

傳回值

如果成功則為非零；否則為 0。

範例

請參閱 CImageList::EndDrag 的範例。

`CImageList::DragMove`

呼叫此函式，以在拖放作業期間移動正在拖曳的影像。

static BOOL PASCAL DragMove(CPoint pt);

參數

pt
新的拖曳位置。

傳回值

如果成功則為非零；否則為 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。

備註

函式會在 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_SELECTEDILD_BLEND`	繪製影像，將 50% 與系統醒目提示色彩混合。如果影像清單不包含遮罩，這個值就不會有任何作用。
`ILD_MASK`	繪製遮罩。
`ILD_NORMAL`	使用影像清單的背景色彩繪製影像。如果背景色彩是 `CLR_NONE` 值，則會使用遮罩以透明方式繪製影像。
`ILD_TRANSPARENT`	使用遮罩以透明方式繪製影像，而不論背景色彩為何。

傳回值

如果成功則為非零；否則為 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 中查看 dx 和 dy ImageList_DrawEx 。

clrBk
影像的背景色彩。 ImageList_DrawEx請參閱 rgbBk Windows SDK 中的。

clrFg
影像的前景色彩。 ImageList_DrawEx請參閱 rgbFg Windows SDK 中的。

nStyle
指定繪圖樣式的旗標。 ImageList_DrawEx請參閱 fStyle Windows SDK 中的。

傳回值

如果成功則為非零；否則為 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會將來源矩形直接複製到目的地矩形。如果參數不包含旗標，fStyleILD_ROP則會忽略此參數。

結構的成員IMAGELISTDRAWPARAMS會dwRop描述其他可能的值。

rgbBack
影像背景色彩，預設 CLR_DEFAULT為。這個參數可以是應用程式定義的 RGB 值或下列其中一個值：

值	意義
`CLR_DEFAULT`	默認背景色彩。影像會使用影像清單背景色彩繪製。
`CLR_NONE`	沒有背景色彩。影像會以透明方式繪製。

rgbFore
影像前景色彩，預設 CLR_DEFAULT為。這個參數可以是應用程式定義的 RGB 值或下列其中一個值：

值	意義
`CLR_DEFAULT`	預設前景色彩。影像會使用系統反白顯示色彩作為前景色彩來繪製。
`CLR_NONE`	無混合色彩。影像會與目的地裝置內容的色彩混合。

只有在包含 ILD_BLEND25 或 ILD_BLEND50 旗標時fStyle，才會使用此參數。

fState
指定繪圖狀態的旗標。這個成員可以包含一或多個映像清單狀態旗標。

Frame
影響飽和和Alpha混合效果的行為。

搭配 ILS_SATURATE使用時，這個成員會保存圖示中每個圖元的 RGB 三元色彩元件中加入的值。

搭配 ILS_APLHA使用時，這個成員會保留Alpha色板的值。這個值可以是 0 到 255,0 是完全透明的，而 255 則完全不透明。

crEffect
COLORREF用於光暈和陰影效果的值。

傳回值

TRUE 如果已成功繪製影像，則為 ;否則 FALSE為。

備註

如果您想要自行填入 Win32 結構，請使用第一個版本。如果您想要利用一或多個 MFC 的預設自變數，或避免管理結構，請使用第二個版本。

重疊影像是繪製在主要影像頂端的影像，由參數指定於這個成員函式中 nImage 。使用 Draw 成員函式搭配使用 INDEXTOOVERLAYMASK 巨集所指定重迭遮罩的一個起始索引，來繪製覆迭遮罩。

範例

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。

備註

結構 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。

範例

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

備註

之後 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。

備註

由於拖曳函式在拖曳作業期間使用新的影像，因此您應該使用 Windows ShowCursor 函式在呼叫 CImageList::SetDragCursorImage之後隱藏實際的滑鼠游標。否則，系統可能會在拖曳作業期間出現兩個滑鼠游標。

`CImageList::SetImageCount`

呼叫這個成員函式來重設物件中的 CImageList 影像數目。

BOOL SetImageCount(UINT uNewCount);

參數

uNewCount
值，指定影像清單中的新影像總數。

傳回值

如果成功則不為零，否則為 0。

備註

如果您呼叫這個成員函式來增加影像清單中的影像數目，請呼叫 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
覆迭遮罩的一個型索引。

傳回值

如果成功則為非零；否則為 0。

備註

最多可以新增四個索引至清單。

重疊遮罩是透過另一個影像以透明方式繪製的影像。使用 CImageList::Draw 成員函式搭配使用 INDEXTOOVERLAYMASK 巨集所指定重疊遮罩的一個基底索引，在影像上繪製覆迭遮罩。

範例

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

範例

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

共用方式為

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`