`CBitmap` 類別

發行項
07/05/2024

封裝 Windows 繪圖裝置介面 (GDI) 點陣圖，並提供操作點陣圖的成員函式。

語法

class CBitmap : public CGdiObject

成員

公用建構函式

名稱	描述
`CBitmap::CBitmap`	建構 `CBitmap` 物件。

公用方法

名稱	描述
`CBitmap::CreateBitmap`	使用具有指定寬度、高度和位模式的裝置相依記憶體位圖，初始化物件。
`CBitmap::CreateBitmapIndirect`	使用在結構中 `BITMAP` 指定寬度、高度和點陣圖樣的點陣圖，初始化物件。
`CBitmap::CreateCompatibleBitmap`	使用點陣圖初始化物件，使其與指定的裝置相容。
`CBitmap::CreateDiscardableBitmap`	使用與指定裝置相容的可捨棄位圖，初始化物件。
`CBitmap::FromHandle`	當指定 Windows `HBITMAP` 位圖的句柄時，傳回物件的指標`CBitmap`。
`CBitmap::GetBitmap`	以 `BITMAP` 點圖的相關信息填入結構。
`CBitmap::GetBitmapBits`	將指定位圖的位複製到指定的緩衝區。
`CBitmap::GetBitmapDimension`	傳回點圖的寬度和高度。成員函式先前 `SetBitmapDimension` 已設定高度和寬度。
`CBitmap::LoadBitmap`	從應用程式的可執行檔載入具名點陣圖資源，並將點陣圖附加至物件，以初始化物件。
`CBitmap::LoadMappedBitmap`	載入點陣圖，並將色彩對應至目前的系統色彩。
`CBitmap::LoadOEMBitmap`	載入預先定義的 Windows 位圖並將點陣圖附加至物件，以初始化物件。
`CBitmap::SetBitmapBits`	將點陣圖的位元設定為指定的位值。
`CBitmap::SetBitmapDimension`	將寬度和高度指派給0.1公厘單位的點陣圖。

公用運算子

名稱	描述
`CBitmap::operator HBITMAP`	傳回附加至 `CBitmap` 物件的 Windows 句柄。

備註

若要使用 CBitmap 物件，請建構物件，使用其中一個初始化成員函式將點陣圖句柄附加至該物件，然後呼叫對象的成員函式。

如需使用圖形對象的詳細資訊，請參閱CBitmap圖形物件。

繼承階層架構

CObject

CGdiObject

CBitmap

需求

標頭： afxwin.h

`CBitmap::CBitmap`

建構 CBitmap 物件。

CBitmap();

備註

產生的對象必須使用其中一個初始化成員函式初始化。

`CBitmap::CreateBitmap`

初始化具有指定寬度、高度和位元模式之因裝置而異的記憶體點陣圖。

BOOL CreateBitmap(
    int nWidth,
    int nHeight,
    UINT nPlanes,
    UINT nBitcount,
    const void* lpBits);

參數

nWidth
指定點陣圖的寬度 (以像素為單位)。

nHeight
指定點陣圖的高度 (以像素為單位)。

nPlanes
指定點陣圖中色彩平面的數目。

nBitcount
指定每個顯示像素的色彩位元數目。

lpBits
指向位元組陣列，其中包含初始點陣圖位元值。 NULL如果是，則新位圖會保持未初始化。

傳回值

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

備註

若是彩色點陣圖， nPlanes 或 nBitcount 參數應設為 1。如果這兩個參數都設為 1， CreateBitmap 會建立單色點陣圖。

雖然無法直接選取顯示裝置的點陣圖，但是可以使用， CDC::SelectObject 並使用函式選取為「記憶體裝置內容」的目前點陣圖，並複製到任何相容的裝置內容 CDC::BitBlt 。

當您完成使用 CBitmap 函式所建立的 CreateBitmap 物件時，請先選取點陣圖並移出裝置內容，再刪除 CBitmap 物件。

如需詳細資訊，請參閱結構中BITMAP欄位的描述bmBits。結構 BITMAP 會在成員函式下 CBitmap::CreateBitmapIndirect 描述。

`CBitmap::CreateBitmapIndirect`

初始化點陣圖，其寬度、高度和點陣圖樣（如果已指定的話），在所 lpBitmap指向的結構中指定。

BOOL CreateBitmapIndirect(LPBITMAP lpBitmap);

參數

lpBitmap
指向 BITMAP 包含位圖相關信息的結構。

傳回值

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

備註

雖然無法直接選取顯示裝置的點陣圖，但可以使用或函式，將它選取為記憶體裝置內容CDC::SelectObject目前的點陣圖，並使用或 CDC::StretchBlt 函式複製到任何相容的裝置內容CDC::BitBlt。（函 CDC::PatBlt 式可以將目前筆刷的點圖直接複製到顯示裝置內容。

BITMAP如果使用函式填入 GetObject 參數所lpBitmap指向的結構，則不會指定位圖的位，而且點圖未初始化。若要初始化位圖，應用程式可以使用或 CDC::BitBlt SetDIBits 之類的函式，將的第一個參數 CGdiObject::GetObject 所識別的位複製到所 CreateBitmapIndirect建立之位圖。

當您完成 CBitmap 以 CreateBitmapIndirect 函式建立的物件時，請先從裝置內容中選取位圖，然後刪除 CBitmap 物件。

`CBitmap::CreateCompatibleBitmap`

初始化與所 pDC指定裝置相容的點陣圖。

BOOL CreateCompatibleBitmap(
    CDC* pDC,
    int nWidth,
    int nHeight);

參數

pDC
指定裝置內容。

nWidth
指定點陣圖的寬度 (以像素為單位)。

nHeight
指定點陣圖的高度 (以像素為單位)。

傳回值

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

備註

點陣圖的色彩平面數目相同，或與指定裝置內容相同的每圖元元格式。它可以選取為與所 pDC指定記憶體裝置相容的目前點陣圖。

如果 pDC 是記憶體裝置內容，傳回的點陣圖格式與該裝置內容中目前選取的點陣圖格式相同。「記憶體裝置內容」是代表顯示介面的記憶體區塊。它可以用來準備記憶體中的影像，再將它們複製到相容裝置的實際顯示介面。

建立記憶體裝置內容時，GDI 會自動為其選取單色股票點陣圖。

由於色彩記憶體裝置內容可以選取色彩或單色位圖，因此函式所 CreateCompatibleBitmap 傳回的點陣圖格式不一定相同;不過，非記憶體裝置內容的相容點圖格式一律為裝置格式。

當您完成 CBitmap 使用 CreateCompatibleBitmap 函式建立的物件時，請先從裝置內容中選取位圖，然後刪除 CBitmap 物件。

`CBitmap::CreateDiscardableBitmap`

初始化與所 pDC識別之裝置內容相容的可捨棄位圖。

BOOL CreateDiscardableBitmap(
    CDC* pDC,
    int nWidth,
    int nHeight);

參數

pDC
指定裝置內容。

nWidth
指定位圖的寬度（以位為單位）。

nHeight
指定點圖的高度（以位為單位）。

傳回值

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

備註

點陣圖的色彩平面數目相同，或與指定裝置內容相同的每圖元元格式。應用程式可以將此位圖選取為與所 pDC指定記憶體裝置相容的目前點陣圖。

只有在應用程式尚未將它選取至顯示內容時，Windows 才能捨棄此函式所建立的點陣圖。如果 Windows 在未選取位圖時捨棄位圖，而應用程式稍後會嘗試選取它，則函 CDC::SelectObject 式會傳回 NULL。

當您完成 CBitmap 使用 CreateDiscardableBitmap 函式建立的物件時，請先從裝置內容中選取位圖，然後刪除 CBitmap 物件。

`CBitmap::FromHandle`

當指定 Windows GDI 位圖的句柄時，傳回物件的指標 CBitmap 。

static CBitmap* PASCAL FromHandle(HBITMAP hBitmap);

參數

hBitmap
指定 Windows GDI 位圖。

傳回值

如果成功， CBitmap 則為物件的指標，否則 NULL為。

備註

CBitmap如果物件尚未附加至句柄，則會建立並附加暫存CBitmap物件。這個暫存 CBitmap 物件只有在下次應用程式在其事件迴圈中有閑置時間為止才有效，此時會刪除所有暫存圖形物件。另一種方法是，暫存物件只有在處理一個視窗訊息時才有效。

`CBitmap::GetBitmap`

擷取附加位圖的影像屬性。

int GetBitmap(BITMAP* pBitMap);

參數

pBitMap
BITMAP將接收影像屬性之結構的指標。此參數不得為 NULL。

傳回值

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

備註

`CBitmap::GetBitmapBits`

將附加位圖的點陣圖模式複製到指定的緩衝區。

DWORD GetBitmapBits(
    DWORD dwCount,
    LPVOID lpBits) const;

參數

dwCount
要複製到緩衝區的位元組數目。

lpBits
將接收位圖之緩衝區的指標。

傳回值

如果方法成功，則複製到緩衝區的位元元組數目;否則為 0。

備註

使用 CBitmap::GetBitmap 來判斷所需的緩衝區大小。

`CBitmap::GetBitmapDimension`

傳回點圖的寬度和高度。

CSize GetBitmapDimension() const;

傳回值

位圖的寬度和高度，以0.1公厘為單位。高度位於 cy 對象的成員 CSize 中，而寬度則位於成員中 cx 。如果點圖寬度和高度尚未使用 SetBitmapDimension來設定，則傳回值為 0。

備註

高度和寬度假設先前已使用 SetBitmapDimension 成員函式來設定。

`CBitmap::LoadBitmap`

從應用程式的可執行檔載入名為 lpszResourceName 的點陣圖資源，或由中的 nIDResource 標識碼識別。

BOOL LoadBitmap(LPCTSTR lpszResourceName);
BOOL LoadBitmap(UINT nIDResource);

參數

lpszResourceName
指向包含位圖資源名稱的 Null 終止字串。

nIDResource
指定點陣圖資源的資源識別碼。

傳回值

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

備註

載入的點陣圖會附加至 CBitmap 物件。

如果所 lpszResourceName 識別的位圖不存在，或記憶體不足而無法載入位圖，則函式會傳回 0。

您可以使用函 CGdiObject::DeleteObject 式來刪除函式所載入的 LoadBitmap 點陣圖，或者 CBitmap 解構函式會為您刪除物件。

警告

刪除物件之前，請確定它未選取到裝置內容中。

下列點陣圖已新增至 Windows 3.1 版和更新版本：

OBM_UPARRROWIOBM_DNARROWIOBM_RGARROWIOBM_LFARROWI

這些點陣圖在 Windows 3.0 版和更早版本的設備驅動器中找不到。如需點陣圖的完整清單及其外觀的顯示，請參閱 Windows SDK。

`CBitmap::LoadMappedBitmap`

呼叫此成員函式以載入點陣圖，並將色彩對應至目前的系統色彩。

BOOL LoadMappedBitmap(
    UINT nIDBitmap,
    UINT nFlags = 0,
    LPCOLORMAP lpColorMap = NULL,
    int nMapSize = 0);

參數

nIDBitmap
位圖資源的標識碼。

nFlags
點陣圖的旗標。可以是零或 CMB_MASKED。

lpColorMap
結構的指標 COLORMAP ，其中包含對應位圖所需的色彩資訊。如果此參數為 NULL，則函式會使用預設的色彩對應。

nMapSize
所 lpColorMap指向的色彩對應數目。

傳回值

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

備註

根據預設， LoadMappedBitmap 將會對應常用在按鈕圖像中的色彩。

如需建立對應位圖的相關信息，請參閱 Windows SDK 中的 Windows 函式 CreateMappedBitmap 和 COLORMAP 結構。

`CBitmap::LoadOEMBitmap`

載入 Windows 所使用的預先定義點陣圖。

BOOL LoadOEMBitmap(UINT nIDBitmap);

參數

nIDBitmap
預先定義的 Windows 位圖標識碼。下列可能的值如下 WINDOWS.H：

OBM_BTNCORNERS
OBM_BTSIZE
OBM_CHECK
OBM_CHECKBOXES
OBM_CLOSE
OBM_COMBO
OBM_DNARROW
OBM_DNARROWD
OBM_DNARROWI
OBM_LFARROW
OBM_LFARROWD
OBM_LFARROWI

OBM_MNARROW
OBM_OLD_CLOSE
OBM_OLD_DNARROW
OBM_OLD_LFARROW
OBM_OLD_REDUCE
OBM_OLD_RESTORE
OBM_OLD_RGARROW
OBM_OLD_UPARROW
OBM_OLD_ZOOM
OBM_REDUCE
OBM_REDUCED

OBM_RESTORE
OBM_RESTORED
OBM_RGARROW
OBM_RGARROWD
OBM_RGARROWI
OBM_SIZE
OBM_UPARROW
OBM_UPARROW
OBM_UPARROWD
OBM_ZOOM
OBM_ZOOMD

傳回值

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

備註

開頭為 OBM_OLD 的點陣圖名稱代表3.0之前的 Windows 版本所使用的點陣圖。

請注意，必須先定義常數 OEMRESOURCE ，才能包含 WINDOWS.H ，才能使用任何 OBM_ 常數。

`CBitmap::operator HBITMAP`

使用此運算子取得物件的附加 Windows GDI 句柄 CBitmap 。

operator HBITMAP() const;

傳回值

如果成功，則為物件所 CBitmap 代表之 Windows GDI 物件的句柄，否則 NULL為。

備註

這個運算子是一個轉型運算元，可支援直接使用 HBITMAP 物件。

如需使用圖形對象的詳細資訊，請參閱 Windows SDK 中的圖形物件。

`CBitmap::SetBitmapBits`

將點陣圖的位元設定為所 lpBits指定的位值。

DWORD SetBitmapBits(
    DWORD dwCount,
    const void* lpBits);

參數

dwCount
指定所 lpBits指向的位元組數目。

lpBits
BYTE指向陣列，其中包含要複製到 CBitmap 物件的圖元值。為了讓點圖能夠正確轉譯其影像，應該將值格式化為符合建立實例時 CBitmap 所指定的高度、寬度和色彩深度值。如需詳細資訊，請參閱CBitmap::CreateBitmap。

傳回值

用於設定位陣陣元的位元組數目;如果函式失敗，則為 0。

`CBitmap::SetBitmapDimension`

將寬度和高度指派給0.1公厘單位的點陣圖。

CSize SetBitmapDimension(
    int nWidth,
    int nHeight);

參數

nWidth
指定位圖的寬度（以0.1公厘為單位）。

nHeight
指定位圖的高度（以0.1公厘為單位）。

傳回值

先前的點陣圖維度。 Height 位於 cy 對象的成員變數 CSize 中，而寬度則位於成員變數中 cx 。

備註

除了當應用程式呼叫 GetBitmapDimension 成員函式時，GDI 不會使用這些值來傳回這些值。

另請參閱

MFC 範例 MDI
CGdiObject 類
 階層架構圖表

共用方式為

CBitmap 類別

語法

成員

公用建構函式

公用方法

公用運算子

備註

繼承階層架構

需求

CBitmap::CBitmap

備註

CBitmap::CreateBitmap

參數

傳回值

備註

CBitmap::CreateBitmapIndirect

參數

傳回值

備註

CBitmap::CreateCompatibleBitmap

參數

傳回值

備註

CBitmap::CreateDiscardableBitmap

參數

傳回值

備註

CBitmap::FromHandle

參數

傳回值

備註

CBitmap::GetBitmap

參數

傳回值

備註

CBitmap::GetBitmapBits

參數

傳回值

備註

CBitmap::GetBitmapDimension

傳回值

備註

CBitmap::LoadBitmap

參數

傳回值

備註

CBitmap::LoadMappedBitmap

參數

傳回值

備註

CBitmap::LoadOEMBitmap

參數

傳回值

備註

CBitmap::operator HBITMAP

傳回值

備註

CBitmap::SetBitmapBits

參數

傳回值

CBitmap::SetBitmapDimension

參數

傳回值

備註

另請參閱

意見反應

其他資源

`CBitmap` 類別

`CBitmap::CBitmap`

`CBitmap::CreateBitmap`

`CBitmap::CreateBitmapIndirect`

`CBitmap::CreateCompatibleBitmap`

`CBitmap::CreateDiscardableBitmap`

`CBitmap::FromHandle`

`CBitmap::GetBitmap`

`CBitmap::GetBitmapBits`

`CBitmap::GetBitmapDimension`

`CBitmap::LoadBitmap`

`CBitmap::LoadMappedBitmap`

`CBitmap::LoadOEMBitmap`

`CBitmap::operator HBITMAP`

`CBitmap::SetBitmapBits`

`CBitmap::SetBitmapDimension`