TBrush: what changed

Revision 0 to 1. Removed lines have a minus sign; added lines have a plus sign.

Title: TBrush

New		Line
1	+	Along with [[TPen]] and [[TFont]], `TBrush` belongs to the most fundamental properties of [[TCanvas]] and defines how a geometric shape is filled.
2	+
3	+	## Properties
4	+
5	+	- `Color`: specifies the basic color (type `TColor`) used to fill the shape
6	+	- `Style`: an enumeration of type `TBrushStyle` which defines the pattern used for filling
7	+	- `bsClear`: no filling at all, `Color` is ignored.
8	+	- `bsSolid`: uniform fill of the shape with the `Color` specified
9	+	- The following styles define hatch patterns which are drawn in the `Color` specified. By default the background between the hatch lines is left empty. In Windows, gtk2 and qt5, it can be filled after calling `SetBkColor(Canvas.Handle, AColor)` if background mode has been set to `OPAQUE`: `SetBkMode(Canvas.Handle, OPAQUE)` which is the default, but can be reverted by calling with the argument `TRANSPARENT` instead of `OPAQUE`. Both functions require the units LCLIntf and LCLType in the uses clause. In other widgetsets the background has to be drawn twice, with `fsSolid` at first. Note that an alpha-channel for transparency seems to be ignored.
10	+	- `bsHorizontal`, `bsVertical`, `bsFDiagonal`, `bsBDiagonal` define a single-line hatch pattern.
11	+	- `bsCross` and `bsDiagCross` define a crossed pattern.
12	+	- `bsImage` and `bsPattern` tile the shape with the image set to the `Bitmap` property of the `Brush`.
13	+	- `Bitmap` defines the image which fills the shape by tiling if `Style` is `bsImage`. Any instance of a class descending from `TCustomBitmap` can be used here (`TBitmap`, `TJpegImage`, `TPortableNetworkgraphic`, etc). But note that `TCanvas.Bitmap` is not created and destroyed by the `Canvas`, it is your responsibility to take care of this. There are also `Image` (type `TFPCustomImage`) and `Pattern` (type `TBrushPattern`) properties which seem to have a similar purpose, but they are inherited from ancestor [[TFPCustomBrush]] and are ignored by `TCanvas`. Using a bitmap for filling the shape does not work on all widgetsets; at the time of this writing it was tested to work on win32/64, qt5 and cocoa.
14	+
15	+	These properties are applied in all subsequent drawing commands.
16	+
17	+	Above description is valid for Windows. Several restrictions may apply for other widgetsets.
18	+
19	+	## Sample code
20	+
21	+	<figure>
22	+	<img src="tbrush_style_bk.png" title="tbrush_style_bk.png" />
23	+	<figcaption>tbrush_style_bk.png</figcaption>
24	+	</figure>
25	+
26	+	The following project draws ten rectangles on the canvas of a `TForm`, fills them with each style and labels them with the appropriate style name. The result is shown in the image above.
27	+
28	+	``` pascal
29	+	type
30	+	TForm1 = class(TForm)
31	+	procedure FormCreate(Sender: TObject);
32	+	procedure FormDestroy(Sender: TObject);
33	+	procedure FormPaint(Sender: TObject);
34	+	private
35	+	FPattern: TCustomBitmap;
36	+	public
37	+	end;
38	+
39	+	uses
40	+	...,
41	+	LCLIntf, LCLType, // for SetBkColor, OPAQUE and TRANSPARENT
42	+	Types, // for OffsetRect
43	+	TypInfo; // for GetEnumName
44	+
45	+	procedure TForm1.FormCreate(Sender: TObject);
46	+	begin
47	+	Width := 550;
48	+	Height := 290;
49	+
50	+	FPattern := TPortableNetworkGraphic.Create;
51	+	FPattern.LoadFromFile('C:\Lazarus\images\debugger\debugger.png'); // path to the image used for filling
52	+	end;
53	+
54	+	procedure TForm1.FormDestroy(Sender: TObject);
55	+	begin
56	+	FPattern.Free;
57	+	end;
58	+
59	+	procedure TForm1.FormPaint(Sender: TObject);
60	+	var
61	+	R: TRect;
62	+	bs: TBrushStyle;
63	+	styleName: String;
64	+	x, y, h: Integer;
65	+	begin
66	+	R := Rect(8, 8, 108, 108);
67	+	h := Canvas.TextHeight('Tg');
68	+
69	+	// Set fill color
70	+	Canvas.Brush.Color := clRed;
71	+
72	+	// Set border color
73	+	Canvas.Pen.Color := clBlack;
74	+
75	+	// Iterate over all available brush styles
76	+	for bs in TBrushStyle do
77	+	begin
78	+	// Set background color
79	+	SetBkMode(Canvas.Handle, OPAQUE);
80	+	SetBkColor(Canvas.Handle, clYellow);
81	+	// Set brush style
82	+	Canvas.Brush.Style := bs;
83	+	if (bs = bsImage) or (bs =bsPattern) then
84	+	Canvas.Brush.Bitmap := FPattern
85	+	else
86	+	Canvas.Brush.Bitmap := nil;
87	+	// Fill a rectangle with the selected brush
88	+	Canvas.Rectangle(R);
89	+	// Get name of brush style and draw it below the rectangle
90	+	styleName := GetEnumName(TypeInfo(TBrushStyle), ord(bs));
91	+	x := (R.Left + R.Right - Canvas.TextWidth(styleName)) div 2;
92	+	y := R.Bottom + 8;
93	+	// No text background
94	+	SetBkMode(Canvas.Handle, TRANSPARENT); // or: Canvas.Brush.Style := bsClear;
95	+	// Draw the brush name
96	+	Canvas.TextOut(x, y, styleName);
97	+	// Position the rectangle for next brush
98	+	if ord(bs) = ord(High(bs)) div 2 then
99	+	OffsetRect(R, -R.Left + 8, R.Height + 20 + h)
100	+	else
101	+	OffsetRect(R, R.Width + 8, 0);
102	+	end;
103	+	end;
104	+	```
105	+
106	+	---
107	+	From the Free Pascal wiki, page "TBrush", as it stood on 2023-11-24 after a change by Wp, out of the wiki's dump of 2024-05-26. Copyright stays with the author who wrote it, according to the old wiki's [[Licensing]] page. If you have concerns about this material, [message the admin](/wiki-contact).

Back to history