`CBrush` 类

项目
10/12/2023

封装一个 Windows 图形设备接口 (GDI) 画笔。

语法

class CBrush : public CGdiObject

成员

公共构造函数

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

公共方法

名称	描述
`CBrush::CreateBrushIndirect`	使用 `LOGBRUSH` 结构中指定的样式、颜色和图案初始化画笔。
`CBrush::CreateDIBPatternBrush`	使用独立于设备的位图 (DIB) 指定的模式初始化画笔。
`CBrush::CreateHatchBrush`	使用指定的阴影图案和颜色初始化画笔。
`CBrush::CreatePatternBrush`	使用位图指定的模式初始化画笔。
`CBrush::CreateSolidBrush`	使用指定纯色初始化画笔。
`CBrush::CreateSysColorBrush`	创建默认系统颜色的画笔。
`CBrush::FromHandle`	当给定 Windows `HBRUSH` 对象的句柄时，返回指向 `CBrush` 对象的指针。
`CBrush::GetLogBrush`	获取 `LOGBRUSH` 结构。

公共运算符

“属性”	描述
`CBrush::operator HBRUSH`	返回附加到 `CBrush` 对象的 Windows 句柄。

注解

若要使用 CBrush 对象，请构造 CBrush 对象并将其传递给任何需要画笔的 CDC 成员函数。

画笔可为纯色、阴影或图案。

有关 CBrush 的详细信息，请参阅图形对象。

继承层次结构

CObject

CGdiObject

CBrush

要求

标头：afxwin.h

`CBrush::CBrush`

构造 CBrush 对象。

CBrush();
CBrush(COLORREF crColor);
CBrush(int nIndex, COLORREF crColor);
explicit CBrush(CBitmap* pBitmap);

参数

crColor
将画笔的前景色指定为 RGB 颜色。如果画笔带阴影，此参数指定阴影的颜色。

nIndex
指定画笔的阴影样式。可以是以下任一值：

HS_BDIAGONAL 45 度向下的阴影（从左到右）
HS_CROSS 横向缩放与纵向阴影线
HS_DIAGCROSS 45 度阴影线
HS_FDIAGONAL 45 度向上的阴影（从左到右）
HS_HORIZONTAL 水平阴影
HS_VERTICAL 垂直阴影

pBitmap
指向一个 CBitmap 对象，该对象指定画笔用来绘制的位图。

注解

CBrush 具有四个重载构造函数。没有参数的构造函数构造未初始化的 CBrush 对象，必须先对其进行初始化，然后才能使用。

如果使用不带参数的构造函数，则必须使用 CreateSolidBrush、CreateHatchBrush、CreateBrushIndirect、CreatePatternBrush 或 CreateDIBPatternBrush 初始化生成的 CBrush 对象。如果使用带参数的构造函数之一，则无需进一步初始化。如果遇到错误，具有自变量的构造函数可能会引发异常，而没有自变量的构造函数将始终成功。

具有单个 COLORREF 参数的构造函数构造具有指定颜色的实心画笔。颜色指定一个 RGB 值，并可以使用 WINDOWS.H 中的 RGB 宏进行构造。

具有两个参数的构造函数可构造阴影画笔。 nIndex 参数指定已孵化模式的索引。 crColor 参数指定颜色。

具有 CBitmap 参数的构造函数可构造带图案的画笔。该参数标识位图。假定位图使用 CBitmap::CreateBitmap、CBitmap::CreateBitmapIndirect、CBitmap::LoadBitmap 或 CBitmap::CreateCompatibleBitmap 创建。用于填充图案的位图的最小尺寸为 8 像素 x 8 像素。

示例

// CBrush::CBrush.
CBrush brush1;                           // Must initialize!
brush1.CreateSolidBrush(RGB(0, 0, 255)); // Blue brush.

CRect rc;
GetClientRect(&rc);
ScreenToClient(&rc);

// Save original brush.
CBrush *pOrigBrush = (CBrush *)pDC->SelectObject(&brush1);

// Paint upper left corner with blue brush.
pDC->Rectangle(0, 0, rc.Width() / 2, rc.Height() / 2);

// These constructors throw resource exceptions.
try
{
   // CBrush::CBrush(COLORREF crColor)
   CBrush brush2(RGB(255, 0, 0)); // Solid red brush.

   // CBrush::CBrush(int nIndex, COLORREF crColor)
   // Hatched green brush.
   CBrush brush3(HS_DIAGCROSS, RGB(0, 255, 0));

   // CBrush::CBrush(CBitmap* pBitmap)
   CBitmap bmp;
   // Load a resource bitmap.
   bmp.LoadBitmap(IDB_BRUSH);
   CBrush brush4(&bmp);

   pDC->SelectObject(&brush2);

   // Paint upper right corner with red brush.
   pDC->Rectangle(rc.Width() / 2, 0, rc.Width(),
                  rc.Height() / 2);

   pDC->SelectObject(&brush3);

   // Paint lower left corner with green hatched brush.
   pDC->Rectangle(0, rc.Height() / 2, rc.Width() / 2,
                  rc.Height());

   pDC->SelectObject(&brush4);

   // Paint lower right corner with resource brush.
   pDC->Rectangle(rc.Width() / 2, rc.Height() / 2,
                  rc.Width(), rc.Height());
}
catch (CResourceException *e)
{
   e->ReportError();
   e->Delete();
}

// Reselect original brush into device context.
pDC->SelectObject(pOrigBrush);

`CBrush::CreateBrushIndirect`

使用 LOGBRUSH 结构中指定的样式、颜色和图案初始化画笔。

BOOL CreateBrushIndirect(const LOGBRUSH* lpLogBrush);

参数

lpLogBrush
指向包含画笔信息的 LOGBRUSH 结构。

返回值

如果该函数成功，则为非 0；否则为 0。

备注

随后可以选择画笔作为任何设备上下文的当前画笔。

使用当前文本和背景颜色绘制使用单色（1 个平面，每像素 1 位）位图创建的画笔。由设置为 0 的位表示的像素将使用当前文本颜色进行绘制。由设置为 1 的位表示的像素将使用当前背景颜色绘制。

示例

// Initialize a LOGBRUSH structure.
LOGBRUSH logBrush;
logBrush.lbStyle = BS_HATCHED;
logBrush.lbColor = RGB(0, 192, 192);
logBrush.lbHatch = HS_CROSS;

// Declare an uninitialized CBrush ...
CBrush brush;
// ... and initialize it with the LOGBRUSH.
brush.CreateBrushIndirect(&logBrush);

// Select the brush (and perhaps a pen) into
// the device context.
CBrush *pOldBrush = (CBrush *)pDC->SelectObject(&brush);
CPen *pOldPen = (CPen *)pDC->SelectStockObject(BLACK_PEN);

// Have fun!
pDC->Pie(CRect(100, 100, 300, 300), CPoint(0, 0), CPoint(50, 200));

// Restore the original device context objects.
pDC->SelectObject(pOldBrush);
pDC->SelectObject(pOldPen);

`CBrush::CreateDIBPatternBrush`

使用与设备无关的位图 (DIB) 指定的模式初始化画笔。

BOOL CreateDIBPatternBrush(
    HGLOBAL hPackedDIB,
    UINT nUsage);

BOOL CreateDIBPatternBrush(
    const void* lpPackedDIB,
    UINT nUsage);

参数

hPackedDIB
标识包含打包的设备无关位图 (DIB) 的全局内存对象。

nUsage
指定 BITMAPINFO 数据结构（“打包 DIB”的一部分）的 bmiColors[] 字段是否包含显式 RGB 值或当前所实现逻辑调色板的索引。该参数必须是以下值之一：

DIB_PAL_COLORS 颜色表包含一组 16 位索引。
DIB_RGB_COLORS 颜色表包含文字 RGB 值。

lpPackedDIB
指向由 BITMAPINFO 结构组成的压缩 DIB，其后紧跟定义位图像素的字节数组。

返回值

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

备注

随后可以为任何支持光栅操作的设备上下文选择画笔。

这两个版本在处理 DIB 的方式上有所不同：

在第一种版本中，为了获得 DIB 的句柄，调用 Windows GlobalAlloc 函数来分配一块全局内存，然后用打包的 DIB 填充内存。
在第二种版本中，没有必要调用 GlobalAlloc 来为打包的 DIB 分配内存。

打包的 DIB 由 BITMAPINFO 数据结构组成，紧跟其后的是定义位图像素的字节数组。用作填充图案的位图应为 8 像素 x 8 像素。如果位图较大，Windows 会仅使用与位图左上角的前 8 行和 8 列像素对应的位来创建填充图案。

当应用程序在单色设备上下文中选择双色 DIB 图案画笔时，Windows 会忽略 DIB 中指定的颜色，而改为使用设备上下文当前的文本和背景颜色来显示图案画笔。映射到 DIB 的第一种颜色（在 DIB 颜色表中的 0 偏移量处）的像素使用文本颜色显示。映射到第二种颜色的像素（在颜色表中的 1 偏移量处）使用背景颜色显示。

有关使用以下 Windows 函数的信息，请参阅 Windows SDK：

CreateDIBPatternBrush（提供此函数只是为了与为早于 3.0 的 Windows 版本编写的应用程序兼容；使用 CreateDIBPatternBrushPt 函数。）
CreateDIBPatternBrushPt（此函数应用于基于 Win32 的应用程序。）
GlobalAlloc

示例

// Resource handle to bitmap.
HRSRC hRes;
// Global handles to bitmap resource.
HGLOBAL hData;
void *hLockedData;
CBrush brush;

// Find the resource handle.
hRes = ::FindResource(AfxGetResourceHandle(),
                      MAKEINTRESOURCE(IDB_BRUSH), RT_BITMAP);
if (hRes != NULL)
{
   // Lock and Load (or Load and Lock).
   if (((hData = ::LoadResource(AfxGetResourceHandle(),
                                hRes)) != NULL) &&
       ((hLockedData = ::LockResource(hData)) != NULL))
   {
      // Initialize the brush.
      brush.CreateDIBPatternBrush((const void *)hLockedData,
                                  DIB_RGB_COLORS);

      // Select the brush into the device context.
      CBrush *pOldBrush = pDC->SelectObject(&brush);

      // Draw.
      pDC->Rectangle(50, 50, 200, 200);

      // Restore the original device context.
      pDC->SelectObject(pOldBrush);

      // Free the resource.
      ::FreeResource(hLockedData);
   }
}

`CBrush::CreateHatchBrush`

使用指定的阴影图案和颜色初始化画笔。

BOOL CreateHatchBrush(
    int nIndex,
    COLORREF crColor);

参数

nIndex
指定画笔的阴影样式。可以是以下任一值：

HS_BDIAGONAL 45 度向下的阴影（从左到右）
HS_CROSS 横向缩放与纵向阴影线
HS_DIAGCROSS 45 度阴影线
HS_FDIAGONAL 45 度向上的阴影（从左到右）
HS_HORIZONTAL 水平阴影
HS_VERTICAL 垂直阴影

crColor
将画笔的前景色指定为 RGB 颜色（阴影的颜色）。有关详细信息，请参阅 Windows SDK 中的 COLORREF。

返回值

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

注解

随后可以选择画笔作为任何设备上下文的当前画笔。

示例

CBrush brush;
brush.CreateHatchBrush(HS_BDIAGONAL, RGB(255, 0, 0));

CBrush *pOldBrush;
CPen *pOldPen;

pOldBrush = (CBrush *)pDC->SelectObject(&brush);
pOldPen = (CPen *)pDC->SelectStockObject(NULL_PEN);
pDC->Ellipse(CRect(50, 50, 250, 250));

pDC->SelectObject(pOldBrush);
pDC->SelectObject(pOldPen);

`CBrush::CreatePatternBrush`

使用位图指定的模式初始化画笔。

BOOL CreatePatternBrush(CBitmap* pBitmap);

参数

pBitmap
标识位图。

返回值

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

备注

随后可以为任何支持光栅操作的设备上下文选择画笔。 pBitmap 标识的位图通常使用 CBitmap::CreateBitmap、CBitmap::CreateBitmapIndirect、CBitmap::LoadBitmap 或 CBitmap::CreateCompatibleBitmap 函数进行初始化。

用作填充图案的位图应为 8 像素 x 8 像素。如果位图较大，Windows 将仅使用位图左上角前 8 行和前 8 列像素对应的位。

可以删除模式画笔，而不会影响关联的位图。这意味着位图可用于创建任意数量的图案画笔。

使用当前文本和背景颜色绘制使用单色位图（1 个颜色平面，每像素 1 位）创建的画笔。由设置为 0 的位表示的像素用当前文本颜色绘制。由设置为 1 的位表示的像素使用当前背景颜色绘制。

有关使用 Windows 函数 CreatePatternBrush 的信息，请参阅 Windows SDK。

示例

// Create a hatched bit pattern.
WORD HatchBits[8] = {0x11, 0x22, 0x44, 0x88, 0x11,
                     0x22, 0x44, 0x88};

// Use the bit pattern to create a bitmap.
CBitmap bm;
bm.CreateBitmap(8, 8, 1, 1, HatchBits);

// Create a pattern brush from the bitmap.
CBrush brush;
brush.CreatePatternBrush(&bm);

// Select the brush into a device context, and draw.
CBrush *pOldBrush = (CBrush *)pDC->SelectObject(&brush);
pDC->RoundRect(CRect(50, 50, 200, 200), CPoint(10, 10));

// Restore the original brush.
pDC->SelectObject(pOldBrush);

`CBrush::CreateSolidBrush`

用指定的纯色初始化画笔。

BOOL CreateSolidBrush(COLORREF crColor);

参数

crColor
指定画笔颜色的 COLORREF 结构。颜色指定一个 RGB 值，并可以使用 WINDOWS.H 中的 RGB 宏进行构造。

返回值

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

注解

随后可以选择画笔作为任何设备上下文的当前画笔。

当应用程序使用完 CreateSolidBrush 创建的画笔后，它应从设备上下文中选择画笔。

示例

请参阅 CBrush::CBrush 的示例。

`CBrush::CreateSysColorBrush`

初始化画笔颜色。

BOOL CreateSysColorBrush(int nIndex);

参数

nIndex
指定颜色索引。此值对应于用于绘制 21 个窗口元素之一的颜色。有关值列表，请参阅 Windows SDK 中的 GetSysColor。

返回值

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

注解

随后可以选择画笔作为任何设备上下文的当前画笔。

当应用程序使用完 CreateSysColorBrush 创建的画笔后，它应从设备上下文中选择画笔。

示例

// Declare a CBrush and initialize to a system color.
CBrush brush;
brush.CreateSysColorBrush(COLOR_BTNFACE);

// Select the brush into the device context.
CBrush *pOldBrush = (CBrush *)pDC->SelectObject(&brush);

// Draw.
CRect rect(50, 50, 150, 150);
pDC->Rectangle(rect);

// Reselect the original brush.
pDC->SelectObject(pOldBrush);

`CBrush::FromHandle`

当给定 Windows HBRUSH 对象的句柄时，返回指向 CBrush 对象的指针。

static CBrush* PASCAL FromHandle(HBRUSH hBrush);

参数

hBrush
Windows GDI 画笔的 HANDLE。

返回值

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

注解

如果 CBrush 对象尚未附加到句柄，则会创建并附加一个临时 CBrush 对象。此临时 CBrush 对象仅在应用程序在其事件循环中具有空闲时间之前有效。此时，将删除所有临时图形对象。换言之，临时对象仅在处理一个窗口消息期间有效。

有关使用图形对象的详细信息，请参阅 Windows SDK 中的图形对象。

示例

请参阅 CBrush::CBrush 的示例。

`CBrush::GetLogBrush`

调用此成员函数以检索 LOGBRUSH 结构。

int GetLogBrush(LOGBRUSH* pLogBrush);

参数

pLogBrush
指向包含画笔信息的 LOGBRUSH 结构。

返回值

如果函数成功，并且 pLogBrush 是有效指针，则返回值是存储在缓冲区中的字节数。

如果函数成功，并且 pLogBrush 是 NULL，则返回值是保存函数将存储到缓冲区中的信息所需的字节数。

如果函数失败，返回值为 0。

备注

LOGBRUSH 结构定义画笔的样式、颜色和图案。

例如，调用 GetLogBrush 以匹配位图的特定颜色或图案。

示例

// Example for CBrush::GetLogBrush
LOGBRUSH logbrush;
brushExisting.GetLogBrush(&logbrush);
CBrush brushOther(logbrush.lbColor);

// Another example
// Declare a LOGBRUSH
LOGBRUSH logBrush;

// Using a bitmap for this example.
// The bitmap should be a project resource.
CBitmap bm;
bm.LoadBitmap(IDB_BRUSH);

try
{
   // Create a brush
   CBrush brush1(&bm);

   // Use GetLogBrush to fill the LOGBRUSH structure
   brush1.GetLogBrush(&logBrush);

   // Create a second brush using the LOGBRUSH data
   CBrush brush2;
   brush2.CreateBrushIndirect(&logBrush);

   // Use the first brush
   CBrush *pOldBrush = (CBrush *)pDC->SelectObject(&brush1);
   pDC->Rectangle(CRect(50, 50, 150, 150));

   // The second brush has the specified characteristics
   // of the first brush
   pDC->SelectObject(&brush2);
   pDC->Ellipse(200, 50, 300, 150);

   // Reselect the original brush
   pDC->SelectObject(pOldBrush);
}
catch (CResourceException *e)
{
   e->ReportError();
   e->Delete();
}

`CBrush::operator HBRUSH`

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

operator HBRUSH() const;

返回值

如果成功，则由 CBrush 对象表示的 Windows GDI 对象的句柄；否则 NULL。

备注

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

有关使用图形对象的详细信息，请参阅 Windows SDK 中的图形对象。

示例

RECT rc = {50, 50, 200, 200};

Rectangle(pDC->GetSafeHdc(), rc.left, rc.top, rc.right, rc.bottom);

// The Win32 call to FillRect requires an HBRUSH.
// The HBRUSH operator casts the CBrush object
// to the required type.
CBrush brush;
brush.CreateSysColorBrush(COLOR_BTNFACE);
FillRect(pDC->GetSafeHdc(), &rc, (HBRUSH)brush);

另请参阅

MFC 示例 PROPDLG
CGdiObject 类
 层次结构图
 CBitmap 类
 CDC 类

通过

CBrush 类

语法

成员

公共构造函数

公共方法

公共运算符

注解

继承层次结构

要求

CBrush::CBrush

参数

注解

示例

CBrush::CreateBrushIndirect

参数

返回值

备注

示例

CBrush::CreateDIBPatternBrush

参数

返回值

备注

示例

CBrush::CreateHatchBrush

参数

返回值

注解

示例

CBrush::CreatePatternBrush

参数

返回值

备注

示例

CBrush::CreateSolidBrush

参数

返回值

注解

示例

CBrush::CreateSysColorBrush

参数

返回值

注解

示例

CBrush::FromHandle

参数

返回值

注解

示例

CBrush::GetLogBrush

参数

返回值

备注

示例

CBrush::operator HBRUSH

返回值

备注

示例

另请参阅

反馈

其他资源

`CBrush` 类

`CBrush::CBrush`

`CBrush::CreateBrushIndirect`

`CBrush::CreateDIBPatternBrush`

`CBrush::CreateHatchBrush`

`CBrush::CreatePatternBrush`

`CBrush::CreateSolidBrush`

`CBrush::CreateSysColorBrush`

`CBrush::FromHandle`

`CBrush::GetLogBrush`

`CBrush::operator HBRUSH`