LCL Internals - Resizing, Moving: what changed

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

Old	New		Line
1	1		## Overview
2	2
3	3		The LCL has a lot of resizing properties (Left, Width, Anchors, Align, AnchorSide, AutoSize, Constraints, ChildSizing, ...) and hooks where applications can alter the behavior (OnResize, OnChangeBounds, ...). All these things can not be calculated in one step, so controls can move quite a lot before the final coordinates come out. To reduce flickering the LCL does not send every move/resize to the LCL interface. For example during Begin/EndAlign and csLoading no move/resize is sent to the interface. The widgetset will try to follow the advices of the LCL, but there are some cases, where it does not follow. For example forms (top level windows) are limited by the window manager policies. And TPage completely depends on the size and theme of the TNotebook.
4	4
5	5		## How the LCL tells the interface to resize/move a handle
6	6
7	7		In TWinControl.DoSendBoundsToInterface the widget function SetBounds is called
8	8
9	9		``` pascal
10	10		TWSWinControlClass(WidgetSetClass).SetBounds(Self, Left, Top, Width, Height);
11	11		```
12	12
13	13		## How the Interface tells the LCL to resize/move a handle
14	14
15	15		### When the client area of a Handle was resized
16	16
17	17		Note: If the theme changes the frame of a TGroupBox can change. This leaves the Size and Position of the TGroupBox unchanged, but the client area can change. The interface calls
18	18
19		-	~~` LCLControl.InvalidateClientRectCache(false);`~~
	19	+	```text
	20	+	LCLControl.InvalidateClientRectCache(false);
	21	+	```
20	22
21	23		and sends a LM_SIZE message as below.
22	24
23	25		### When a Handle of a TWinControl was resized/moved
24	26
25	27		#### First the LCL interface send a LM_WINDOWPOSCHANGED message
26	28
27	29		- x := Left (relative to 0,0 of client area of parent)
28	30		- y := Top
29	31		- cx := Width
30	32		- cy := Height
31	33
32	34		#### Then a LM_SIZE message is sent
33	35
34	36		- Width
35	37		- Height
36	38		- SizeType is a bit flag containing Size_SourceIsInterface plus one of the values SIZENORMAL, SIZEICONIC, SIZEFULLSCREEN.
37	39
38	40		#### Then a LM_MOVE message is sent
39	41
40	42		- MoveType := Move_SourceIsInterface;
41	43		- XPos := Left (relative to 0,0 of client area of parent)
42	44		- YPos := Top
43	45
44	46		### When a form is maximized, minimized or restored the interface sends a LM_SIZE message
45	47
46	48		- Width
47	49		- Height
48	50		- SizeType is a bit flag containing Size_SourceIsInterface plus one of the values SIZENORMAL, SIZEICONIC, SIZEFULLSCREEN.
49	51
50	52		## How the LCL gets the current size / position of a LCL interface handle
51	53
52	54		### LCLIntf.GetWindowSize(Handle, InterfaceWidth, InterfaceHeight)
53	55
54	56		Returns the current width and height of a Handle.
55	57
56	58		### LCLIntf.GetClientRect(Handle, Result)
57	59
58	60		Returns the current width and height (left and top are always 0) of the client area of a Handle (= inner area inside the border/frame of a control).
59	61
60	62		### TWSWinControlClass(WidgetSetClass).GetDefaultClientRect(Self, Left, Top, Width, Height, Result)
61	63
62	64		This function is called first by the LCL to get the ClientRect. If it returns false, the LCL will use GetClientRect if it has already created a handle, otherwise the values loaded from the .lfm. If all this fails, the default is Rect(0,0,Width,Height). GetDefaultClientRect can be used by the LCL interface to reduce flickering by providing good values before the handle is created.
63	65
64	66		### GetWindowRelativePosition(Handle,NewLeft,NewTop)
65	67
66	68		Returns the current Left, Top of a Handle relative to the client area (0,0) of its parent.
67	69
68	70		## Constraints
69	71
70	72		The LCL asks the interface for constraints (min, max for width and height) with the function
71	73
72	74		``` pascal
73	75		GetControlConstraints
74	76		```
75	77
76	78		For example: Under gtk a horizontal scrollbar has a fixed height.
77	79
78	80		## Preferred Size
79	81
80	82		To autosize a control (e.g. a TButton or a TLabel) the LCL asks the interface about the minimum size to render a control nicely:
81	83
82	84		``` pascal
83	85		TWSWinControlClass(WidgetSetClass).GetPreferredSize(Self, PreferredWidth, PreferredHeight, WithThemeSpace);
84	86		```
85	87
86	88		## Scrolling
87	89
88	90		The LCL scrolls child controls only virtually. That means, their Left,Top properties do not change. To scroll it uses the LCL interface function
89	91
90	92		``` pascal
91	93		TWSScrollingWinControlClass(WidgetSetClass).ScrollBy(Self, DeltaX, DeltaY);
92	94		```
93	95
94	96		## Rectangles
95	97
96	98		- BoundsRect - the rectangle containing coordinates of the control within parents coordinates
97	99
98	100
99	101		for TForm (not embedded into another control) coordinates are given in Screen position. The form non-client area (aka header, aka title) section is also NOT PART of the BoundsRect.
100	102
101	103		- ClientsRect - the rectangle containing coordinates of the client area.
102	104
103	105		## Miscellaneous
104	106
105	107		### LCLIntf.GetClientBounds(Handle,Result);
106	108
107	109		Returns the unscrolled client rectangle relative to the top, left of the Handle. In other words it is equivalent to:
108	110
109	111		``` pascal
110	112		CurClientBounds := GetClientRect(Handle)
111	113		OffsetRect(CurClientBounds,FrameBorderLeft,FrameBorderTop);
112	114		```
113	115
114	116		---
115	117		From the Free Pascal wiki, page "LCL Internals - Resizing, Moving", as it stood on 2020-02-19 after a change by Trev, 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