`CBrush` Class

Article
02/01/2022

Encapsulates a Windows graphics device interface (GDI) brush.

Syntax

class CBrush : public CGdiObject

Members

Public Constructors

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

Public Methods

Name	Description
`CBrush::CreateBrushIndirect`	Initializes a brush with the style, color, and pattern specified in a `LOGBRUSH` structure.
`CBrush::CreateDIBPatternBrush`	Initializes a brush with a pattern specified by a device-independent bitmap (DIB).
`CBrush::CreateHatchBrush`	Initializes a brush with the specified hatched pattern and color.
`CBrush::CreatePatternBrush`	Initializes a brush with a pattern specified by a bitmap.
`CBrush::CreateSolidBrush`	Initializes a brush with the specified solid color.
`CBrush::CreateSysColorBrush`	Creates a brush that is the default system color.
`CBrush::FromHandle`	Returns a pointer to a `CBrush` object when given a handle to a Windows `HBRUSH` object.
`CBrush::GetLogBrush`	Gets a `LOGBRUSH` structure.

Public Operators

Name	Description
`CBrush::operator HBRUSH`	Returns the Windows handle attached to the `CBrush` object.

Remarks

To use a CBrush object, construct a CBrush object and pass it to any CDC member function that requires a brush.

Brushes can be solid, hatched, or patterned.

For more information on CBrush, see Graphic Objects.

Inheritance Hierarchy

CObject

CGdiObject

CBrush

Requirements

Header: afxwin.h

`CBrush::CBrush`

Constructs a CBrush object.

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

Parameters

crColor
Specifies the foreground color of the brush as an RGB color. If the brush is hatched, this parameter specifies the color of the hatching.

nIndex
Specifies the hatch style of the brush. It can be any one of the following values:

HS_BDIAGONAL Downward hatch (left to right) at 45 degrees
HS_CROSS Horizontal and vertical crosshatch
HS_DIAGCROSS Crosshatch at 45 degrees
HS_FDIAGONAL Upward hatch (left to right) at 45 degrees
HS_HORIZONTAL Horizontal hatch
HS_VERTICAL Vertical hatch

pBitmap
Points to a CBitmap object that specifies a bitmap with which the brush paints.

Remarks

CBrush has four overloaded constructors. The constructor with no arguments constructs an uninitialized CBrush object that must be initialized before it can be used.

If you use the constructor with no arguments, you must initialize the resulting CBrush object with CreateSolidBrush, CreateHatchBrush, CreateBrushIndirect, CreatePatternBrush, or CreateDIBPatternBrush. If you use one of the constructors that takes arguments, then no further initialization is necessary. The constructors with arguments can throw an exception if errors are encountered, while the constructor with no arguments will always succeed.

The constructor with a single COLORREF parameter constructs a solid brush with the specified color. The color specifies an RGB value and can be constructed with the RGB macro in WINDOWS.H.

The constructor with two parameters constructs a hatch brush. The nIndex parameter specifies the index of a hatched pattern. The crColor parameter specifies the color.

The constructor with a CBitmap parameter constructs a patterned brush. The parameter identifies a bitmap. The bitmap is assumed to have been created by using CBitmap::CreateBitmap, CBitmap::CreateBitmapIndirect, CBitmap::LoadBitmap, or CBitmap::CreateCompatibleBitmap. The minimum size for a bitmap to be used in a fill pattern is 8 pixels by 8 pixels.

Example

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

Initializes a brush with a style, color, and pattern specified in a LOGBRUSH structure.

BOOL CreateBrushIndirect(const LOGBRUSH* lpLogBrush);

Parameters

lpLogBrush
Points to a LOGBRUSH structure that contains information about the brush.

Return Value

Nonzero if the function is successful; otherwise 0.

Remarks

The brush can subsequently be selected as the current brush for any device context.

A brush created using a monochrome (1 plane, 1 bit per pixel) bitmap is drawn using the current text and background colors. Pixels represented by a bit set to 0 will be drawn with the current text color. Pixels represented by a bit set to 1 will be drawn with the current background color.

Example

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

Initializes a brush with the pattern specified by a device-independent bitmap (DIB).

BOOL CreateDIBPatternBrush(
    HGLOBAL hPackedDIB,
    UINT nUsage);

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

Parameters

hPackedDIB
Identifies a global-memory object containing a packed device-independent bitmap (DIB).

nUsage
Specifies whether the bmiColors[] fields of the BITMAPINFO data structure (a part of the "packed DIB") contain explicit RGB values or indices into the currently realized logical palette. The parameter must be one of the following values:

DIB_PAL_COLORS The color table consists of an array of 16-bit indexes.
DIB_RGB_COLORS The color table contains literal RGB values.

lpPackedDIB
Points to a packed DIB consisting of a BITMAPINFO structure immediately followed by an array of bytes defining the pixels of the bitmap.

Return Value

Nonzero if successful; otherwise 0.

Remarks

The brush can subsequently be selected for any device context that supports raster operations.

The two versions differ in the way you handle the DIB:

In the first version, to obtain a handle to the DIB you call the Windows GlobalAlloc function to allocate a block of global memory and then fill the memory with the packed DIB.
In the second version, it is not necessary to call GlobalAlloc to allocate memory for the packed DIB.

A packed DIB consists of a BITMAPINFO data structure immediately followed by the array of bytes that defines the pixels of the bitmap. Bitmaps used as fill patterns should be 8 pixels by 8 pixels. If the bitmap is larger, Windows creates a fill pattern using only the bits corresponding to the first 8 rows and 8 columns of pixels in the upper-left corner of the bitmap.

When an application selects a two-color DIB pattern brush into a monochrome device context, Windows ignores the colors specified in the DIB and instead displays the pattern brush using the current text and background colors of the device context. Pixels mapped to the first color (at offset 0 in the DIB color table) of the DIB are displayed using the text color. Pixels mapped to the second color (at offset 1 in the color table) are displayed using the background color.

For information about using the following Windows functions, see the Windows SDK:

CreateDIBPatternBrush (This function is provided only for compatibility with applications written for versions of Windows earlier than 3.0; use the CreateDIBPatternBrushPt function.)
CreateDIBPatternBrushPt (This function should be used for Win32-based applications.)
GlobalAlloc

Example

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

Initializes a brush with the specified hatched pattern and color.

BOOL CreateHatchBrush(
    int nIndex,
    COLORREF crColor);

Parameters

nIndex
Specifies the hatch style of the brush. It can be any one of the following values:

HS_BDIAGONAL Downward hatch (left to right) at 45 degrees
HS_CROSS Horizontal and vertical crosshatch
HS_DIAGCROSS Crosshatch at 45 degrees
HS_FDIAGONAL Upward hatch (left to right) at 45 degrees
HS_HORIZONTAL Horizontal hatch
HS_VERTICAL Vertical hatch

crColor
Specifies the foreground color of the brush as an RGB color (the color of the hatches). See COLORREF in the Windows SDK for more information.

Return Value

Nonzero if successful; otherwise 0.

Remarks

The brush can subsequently be selected as the current brush for any device context.

Example

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`

Initializes a brush with a pattern specified by a bitmap.

BOOL CreatePatternBrush(CBitmap* pBitmap);

Parameters

pBitmap
Identifies a bitmap.

Return Value

Nonzero if successful; otherwise 0.

Remarks

The brush can subsequently be selected for any device context that supports raster operations. The bitmap identified by pBitmap is typically initialized by using the CBitmap::CreateBitmap, CBitmap::CreateBitmapIndirect, CBitmap::LoadBitmap, or CBitmap::CreateCompatibleBitmap function.

Bitmaps used as fill patterns should be 8 pixels by 8 pixels. If the bitmap is larger, Windows will only use the bits corresponding to the first 8 rows and columns of pixels in the upper-left corner of the bitmap.

A pattern brush can be deleted without affecting the associated bitmap. This means the bitmap can be used to create any number of pattern brushes.

A brush created using a monochrome bitmap (1 color plane, 1 bit per pixel) is drawn using the current text and background colors. Pixels represented by a bit set to 0 are drawn with the current text color. Pixels represented by a bit set to 1 are drawn with the current background color.

For information about using CreatePatternBrush, a Windows function, see the Windows SDK.

Example

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

Initializes a brush with a specified solid color.

BOOL CreateSolidBrush(COLORREF crColor);

Parameters

crColor
A COLORREF structure that specifies the color of the brush. The color specifies an RGB value and can be constructed with the RGB macro in WINDOWS.H.

Return Value

Nonzero if successful; otherwise 0.

Remarks

The brush can subsequently be selected as the current brush for any device context.

When an application has finished using the brush created by CreateSolidBrush, it should select the brush out of the device context.

Example

See the example for CBrush::CBrush.

`CBrush::CreateSysColorBrush`

Initializes a brush color.

BOOL CreateSysColorBrush(int nIndex);

Parameters

nIndex
Specifies a color index. This value corresponds to the color used to paint one of the 21 window elements. See GetSysColor in the Windows SDK for a list of values.

Return Value

Nonzero if successful; otherwise 0.

Remarks

The brush can subsequently be selected as the current brush for any device context.

When an application has finished using the brush created by CreateSysColorBrush, it should select the brush out of the device context.

Example

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

Returns a pointer to a CBrush object when given a handle to a Windows HBRUSH object.

static CBrush* PASCAL FromHandle(HBRUSH hBrush);

Parameters

hBrush
HANDLE to a Windows GDI brush.

Return Value

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

Remarks

If a CBrush object is not already attached to the handle, a temporary CBrush object is created and attached. This temporary CBrush object is valid only until the next time the application has idle time in its event loop. At this time, all temporary graphic objects are deleted. In other words, the temporary object is valid only during the processing of one window message.

For more information about using graphic objects, see Graphic Objects in the Windows SDK.

Example

See the example for CBrush::CBrush.

`CBrush::GetLogBrush`

Call this member function to retrieve the LOGBRUSH structure.

int GetLogBrush(LOGBRUSH* pLogBrush);

Parameters

pLogBrush
Points to a LOGBRUSH structure that contains information about the brush.

Return Value

If the function succeeds, and pLogBrush is a valid pointer, the return value is the number of bytes stored into the buffer.

If the function succeeds, and pLogBrush is NULL, the return value is the number of bytes required to hold the information the function would store into the buffer.

If the function fails, the return value is 0.

Remarks

The LOGBRUSH structure defines the style, color, and pattern of a brush.

For example, call GetLogBrush to match the particular color or pattern of a bitmap.

Example

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

Use this operator to get the attached Windows GDI handle of the CBrush object.

operator HBRUSH() const;

Return Value

If successful, a handle to the Windows GDI object represented by the CBrush object; otherwise NULL.

Remarks

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

For more information about using graphic objects, see Graphic Objects in the Windows SDK.

Example

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

Share via

CBrush Class

Syntax

Members

Public Constructors

Public Methods

Public Operators

Remarks

Inheritance Hierarchy

Requirements

CBrush::CBrush

Parameters

Remarks

Example

CBrush::CreateBrushIndirect

Parameters

Return Value

Remarks

Example

CBrush::CreateDIBPatternBrush

Parameters

Return Value

Remarks

Example

CBrush::CreateHatchBrush

Parameters

Return Value

Remarks

Example

CBrush::CreatePatternBrush

Parameters

Return Value

Remarks

Example

CBrush::CreateSolidBrush

Parameters

Return Value

Remarks

Example

CBrush::CreateSysColorBrush

Parameters

Return Value

Remarks

Example

CBrush::FromHandle

Parameters

Return Value

Remarks

Example

CBrush::GetLogBrush

Parameters

Return Value

Remarks

Example

CBrush::operator HBRUSH

Return Value

Remarks

Example

See also

Feedback

Additional resources

`CBrush` Class

`CBrush::CBrush`

`CBrush::CreateBrushIndirect`

`CBrush::CreateDIBPatternBrush`

`CBrush::CreateHatchBrush`

`CBrush::CreatePatternBrush`

`CBrush::CreateSolidBrush`

`CBrush::CreateSysColorBrush`

`CBrush::FromHandle`

`CBrush::GetLogBrush`

`CBrush::operator HBRUSH`