TBrush

Source: source/classes/brush.prg

Standalone class (no inheritance)

TBrush manages Windows GDI brush objects used to fill areas with solid colors, hatch patterns, or bitmap images. A brush is required whenever you need to paint a background (window pane, control face, custom-drawn shapes). TBrush supports solid-color brushes, predefined hatch styles, gradient patterns (via an internal bitmap), image-based brushes from files or resources, and NULL brushes that suppress filling. Every TBrush must be released with End() to avoid GDI resource leaks.

Key DATA Members

DATA	Type	Description
`hBrush`	Numeric (Handle)	Windows GDI brush handle. Created by `New()`.
`hBitmap`	Numeric (Handle)	Handle to the bitmap backing image-based and gradient brushes. `nil` for solid and hatch brushes.
`cStyle`	Character	Hatch style name: `"HORIZONTAL"`, `"VERTICAL"`, `"CROSS"`, `"DIAGCROSS"`, `"BORLAND"`, `"BRICKS"`, `"TILED"`, `"TABS"`, or `"NULL"`.
`nRGBColor`	Numeric	RGB color value for solid and hatch brushes.
`aGrad`	Array	Gradient definition array for gradient brushes: `{ { nPercent, nRGB1, nRGB2 }, ... }`.
`cBmpFile`	Character	File path to the bitmap used for image-based brushes.
`cBmpRes`	Character	Resource name of the bitmap used for resource-based brushes.
`nBmpHandle`	Numeric	Direct bitmap handle used for image-based brushes (alternative to file/resource).
`cResizeMode`	Character	Resize mode for bitmap brushes: `"T"` = tile, `"S"` = stretch.
`lVertical`	Logical	If `.T.`, gradient is vertical; if `.F.`, horizontal.
`Cargo`	Any	General-purpose user data slot.

Brush Styles

Style	Description
`"HORIZONTAL"`	Horizontal hatch lines
`"VERTICAL"`	Vertical hatch lines
`"CROSS"`	Cross-hatch (horizontal + vertical)
`"DIAGCROSS"`	Diagonal cross-hatch
`"BORLAND"`	Borland-style diagonal pattern
`"BRICKS"`	Brick-wall pattern
`"TILED"`	Bitmap tiled across the fill area
`"TABS"`	Tab-like pattern
`"NULL"`	NULL brush (no fill). Used to prevent GDI from filling a region.

Methods

Method	Description
`New( cStyle, nRGB, cBmpFile, cBmpRes, nBmpHandle, cResizeMode )`	Create a brush. With no arguments, creates a solid `COLOR_BTNFACE` brush. `cStyle` selects hatch or NULL style. When `cBmpFile` or `cBmpRes` is provided, creates an image-based brush.
`End()`	Delete the GDI brush (and backing bitmap if present) via `DeleteObject()`. Must be called when the brush is no longer needed.
`Resized( x, y, nMode )`	Create a resized version of a bitmap brush. `x` and `y` are the new dimensions; `nMode` is the stretch mode (default: `COLORONCOLOR`).
`Cropped( oWnd, oRect )`	Crop the brush bitmap to a specified rectangle. Useful for creating region-specific brushes.
`Resize( oWnd )`	Resize the brush bitmap to match a window dimensions. The brush is recreated with the scaled bitmap.
`Copy()`	Create an independent copy of the brush with a new GDI handle.
`GdiBrush()`	Return the GDI brush handle (`hBrush`). Used internally when selecting brushes into DCs.
`SameAs( oB )`	Compare two brushes by their attributes (style, color, bitmap). Returns `.T.` if they are equivalent.
`SetColor( nRGB )`	Change the brush color. Recreates the GDI brush handle with the new color.
`SetStyle( cStyle )`	Change the brush style. Recreates the GDI brush handle with the new style.

Commands: DEFINE BRUSH

DEFINE BRUSH oBrush ;
   [ COLOR nRGBColor ] ;
   [ STYLE cStyle ] ;
   [ FILE cBmpFile ] ;
   [ RESOURCE cBmpRes ] ;
   [ RESIZE nWidth, nHeight ]

Example: Solid, Hatch, Gradient, and Bitmap Brushes

#include "FiveWin.ch"

function Main()

   local oWnd, oBrush1, oBrush2, oBrush3

   DEFINE WINDOW oWnd TITLE "TBrush Demo" SIZE 600, 400

   // Solid blue brush
   DEFINE BRUSH oBrush1 COLOR CLR_BLUE

   // Cross-hatch red brush
   DEFINE BRUSH oBrush2 COLOR CLR_RED STYLE "CROSS"

   // Gradient brush (vertical)
   oBrush3 := TBrush():New( , , , , , , .T. )
   oBrush3:aGrad := { { 1.0, nRGB( 40, 80, 140 ), nRGB( 20, 40, 70 ) } }

   oWnd:oBrush := oBrush1

   ACTIVATE WINDOW oWnd CENTERED

   oBrush1:End()
   oBrush2:End()
   oBrush3:End()

return nil

Notes

TBrush is a standalone class — it does not inherit from TWindow or TControl.
Every TBrush must be paired with an End() call. GDI brushes are a limited resource; leaking them degrades system performance.
To assign a brush to a window's background, use oWnd:SetBrush( oBrush ) or oWnd:oBrush := oBrush. The window takes ownership: set oWnd:lTransparent := .F. for the brush to take effect.
Gradient brushes generate a temporary bitmap internally. The aGrad array specifies segments: each entry is { nPercent, nColorTopLeft, nColorBottomRight }.
Bitmap brushes can be tiled (default) or stretched by setting cResizeMode to "S".
The "NULL" style creates a hollow brush that does not fill. Use it when you need the outline of a shape without filling the interior.