Autosize / Layout: what changed

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

Old	New		Line
1	1		## Overview
2	2
3	3		The [[LCL]] can automatically alter a control's size and position so it adapts to changes in font, theme and text or other content. If you want to run your program on several platforms, or if your captions are available in several languages, your controls need to adapt correctly to their environment. The [[LCL]] allows you not only to make a quick first design (moving controls around on a form using the mouse) but also later to set several key properties which will make the controls automatically adapt subsequently to changed content etc.
4	4
5	5		- Fixed design: this is the default when placing a control in the Designer. The control's position is fixed relative to its parent. The control's size and position (Left, Top) is fully adjustable by the programmer. You can move the control around with the mouse, and resize it freely.
6	6		- Aligned: aligned controls fill up the remaining parental space at the top, bottom, left, or right, or fill the entire remaining space.
7	7		- Anchored: you can anchor a control's sides (left, top, right, bottom) to its parent or to another control. Anchoring means: the [[LCL]] will try to maintain the same distance from the anchor point.
8	8		- Layout: controls can be automatically aligned in rows and columns (e.g. TRadioGroup)
9	9		- Custom via OnResize: you can align controls yourself in code using the OnResize and OnChangeBounds events.
10	10		- Custom controls: writing your own controls, you can override nearly every [[LCL]] behaviour you want.
11	11
12	12		### Precedence rules
13	13
14	14		1. Constraints
15	15		2. Align
16	16		3. Anchors
17	17		4. ChildSizing.Layout
18	18		5. AutoSize
19	19		6. OnResize, OnChangeBounds - however, if you set bounds that conflict with the rules above you will create an endless loop
20	20
21	21		### Common Properties
22	22
23	23		Several important properties can be changed to configure autosizing:
24	24
25	25		- Left, Top, Width, Height
26	26		- AutoSize: autosize instructs the [[LCL]] to automatically resize the Width and Height of a control
27	27		- Anchors: lets you create dependencies, for example to anchor a ComboBox to the right side of a Label.
28	28		- Align
29	29		- Constraints: lets you set a minimum and maximum for the Width and Height
30	30		- BorderSpacing: lets you set the spacing between anchored controls
31	31		- ChildSizing: lets you set the layout and spacing of child controls
32	32
33	33		The internals of the algorithms are explained here: [[LCL AutoSizing]].
34	34
35	35		## Fixed design
36	36
37	37		Fixed design is the default. The Anchor's property is set to \[akLeft,akTop\], which means the values of Left and Top are not changed by the [[LCL]]. If AutoSize is false, the [[LCL]] does not alter Width or Height. If AutoSize is true, the Width and Height are changed to fit the content. For example, TLabel.AutoSize defaults to true and thus changing its Caption will resize the label to accommodate the changed wording. TButton.AutoSize defaults to false, so changing a button's Caption does not resize the button. When you set Button.AutoSize to true the Button will shrink or enlarge every time the button's Caption or its font (or theme) changes. Note, this change does not always happen immediately. For example during FormCreate all autosizing is suspended. At any time you can change the "Left", "Top", "Width", or the "Height" property.
38	38
39	39		## AutoSize
40	40
41	41		`AutoSize` is a boolean property found in many classes; it permits the size of a control to be adjusted automatically to accommodate differences in the text or graphic contained therein, and allows most efficient use of available space. This is a crucial mechanism to create cross platform forms.
42	42
43	43		Normally AutoSize=true does two things for a visible control:
44	44
45	45		- If possible it resizes the control to the preferred size. For example a TButton's Width and Height is resized to fit the caption, while a TEdit is only resized in Height. A TEdit's Width is not autosized. You can change the Width of a TEdit. (see GetPreferredSize).
46	46		- It moves all fixed positioned child controls by the same amount, so that the leftmost child control is moved to Left=0 (depends on BorderSpacing) and the topmost child control is moved to Top=0.
47	47
48	48		### Lazarus vs Delphi
49	49
50	50		- Delphi's AutoSize happens only when certain properties change, for example when the Font of a TLabel is changed. The [[LCL]] AutoSize is always active. Delphi allows one to change the size of a Label which has AutoSize=true, the Lazarus control does not.
51	51		- Delphi's hidden controls are not autosized.
52	52		- With Delphi, changing the size of a control does not resize/move anchored child controls during loading, but a constructor is normally used to make the desired effect. When using akRight,akBottom anchors, set AnchorSides and BorderSpacing to keep the distance correct.
53	53
54	54		### AutoSize and resizing the control
55	55
56	56		With AutoSize=false buttons are given a default fixed size.
57	57
58	58		![](/wiki-images/1/1f/Autosize1.png)
59	59
60	60		When setting AutoSize=true for each button, the buttons are enlarged (or shrunk) to fit the text and theme frame.
61	61
62	62		![](/wiki-images/7/75/Autosize_on.png)
63	63
64	64		AutoSize does not shrink to the smallest possible size as you can see in the OK Button. It uses the GetPreferredSize method of the control, which calls the CalculatePreferredSize method. The default TWinControl implementation queries the widget set, which might have a preferred width or height. Each control can override the CalculatePreferredSize method. For example TImage overrides it and returns the size of the Picture. If no preferred width (height) is available the returned value is 0 and the [[LCL]] will keep the Width (Height) (unless the ControlStyle flag csAutoSize0x0 is set, which is currently only used by TPanel).
65	65
66	66		A TWinControl computes the size of all its child controls and uses that to compute its preferred size.
67	67
68	68		When a control is anchored to both left and right its width is fixed. For example with Align=alTop the control is anchored to left and right and follows the width of the Parent. If Parent.AutoSize is true, then the Parent will use the preferred width of the control to compute its own preferred width, and thus the control will be resized to its preferred width. See [[Autosize / Layout\|Align and AutoSize]]. If no preferred width is available, then the last set bounds are used (BaseBounds or ReadBounds). If no bounds were set, the GetControlClassDefaultSize method is used. Same for Height and anchoring to top and bottom.
69	69
70	70		Constraints are always applied and have precedence.
71	71
72	72		### AutoSize and moving child controls
73	73
74	74		When AutoSize=false you can place and move controls freely:
75	75
76	76		![](/wiki-images/7/75/Autosize_on.png)
77	77
78	78		When AutoSize=true child controls with fixed positions are moved to fit.
79	79
80	80		![](/wiki-images/d/d9/Autosize_panel_on.png)
81	81
82	82		Both buttons on the panel were moved by the same amount to top and left, so that there is no space left to the left and top. If the buttons would have BorderSpacing\>0 or the Panel.ChildSizing.LeftRightSpacing\>0 the buttons would be moved so that the defined space is used.
83	83
84	84		Only child controls with the following values are moved:
85	85
86	86		- Anchors=\[akLeft,akRight\]
87	87		- AnchorSide\[akLeft\].Control=nil
88	88		- AnchorSide\[akTop\].Control=nil
89	89		- Align=alNone
90	90
91	91		The moving of the child controls depend on the propert [[Autosize / Layout\|ChildSizing.Layout]]. The layout is applied in the method TWinControl.AlignControls which can be overridden completely or in parts. For example TToolBar overrides ControlsAligned to position all controls with Align=alCustom and defines a flow layout where controls that do not fit are put into subsequent lines.
92	92
93	93		Controls can disable the moving of child controls by setting the ControlStyle flag csAutoSizeKeepChildLeft and csAutoSizeKeepChildTop (since 0.9.29).
94	94
95	95		### AutoSize and Forms
96	96
97	97		Forms without Parent are controlled by the window manager and can therefore not be placed or resized freely. Setting the size is only a recommendation and might be ignored by the window manager. For example you might set the Width of a Form to 1000 and the widget set might answer with a resize to 800. If you set the Width in OnResize you might create an endless loop. That's why the [[LCL]] TForm disables AutoSize when the widget set resizes the form.
98	98
99	99		That means AutoSize for forms stops when the user resizes the form or if the window manager does not like the bounds. For example some Linux window managers have features like magnetic sides which resizes windows in relationship to other windows.
100	100
101	101		#### Force the auto sizing of a form
102	102
103	103		You can start/execute a new AutoSize by doing:
104	104
105	105		``` pascal
106	106		Form1.AutoSize := False;
107	107		Form1.AutoSize := True;
108	108		```
109	109
110	110		#### Compute the size of an autosized form in advance
111	111
112	112		When placing an autosized form you might need the size of the form before showing it. Autosizing requires the handle. You can compute the size of a form before showing it with:
113	113
114	114		``` pascal
115	115		Form1.HandleNeeded;
116	116		Form1.GetPreferredSize(PreferredWidth,PreferredHeight);
117	117		```
118	118
119	119		Note: The window manager and form events might change the size. The preferred size does not include the form's window borders. This is a planned feature.
120	120
121	121		## Anchor Sides
122	122
123	123		Controls have four sides: akLeft, akTop, akRight and akBottom. Each side can be anchored to the parent or the side of another sibling (a control with the same parent). Anchoring means keeping the distance. The default is Anchors=\[akLeft,akTop\]. Vertical anchors are independent of horizontal anchors. Some properties like Align and Parent.AutoSize have higher precedence and can change the behaviour.
124	124
125	125		### Anchored to Parent or Nil
126	126
127	127		Anchoring to Nil (the default) has almost the same effect as anchoring to the Parent. Both try to keep the distance to a side of the Parent's client area. Anchoring to Nil uses the distance of the last SetBounds call, while Anchoring to Parent uses the BorderSpacing value.
128	128
129	129		There are four combinations of akLeft,akRight (akTop,akBottom):
130	130
131	131		- akLeft, no akRight: the control's Left is fixed and not changed by the [[LCL]]. The right side is not anchored, so it follows the left side. That means the Width is kept too.
132	132		- akLeft and akRight: the control's Left is fixed and not changed by the [[LCL]]. The right side is anchored to the Parent's right side. That means if the Parent is enlarged by 100pixel then the control's Width is enlarged by 100pixel too.
133	133		- akRight, no akLeft: the control's left side is not anchored, so it will follow its right side. The right side is anchored. That means if the parent is enlarged by 100pixel then the control is moved to the right by 100pixel.
134	134		- no akLeft and no akRight: neither sides are anchored. The position of the center of the control scales with the parent. For example if the control is in the middle of the parent and the parent is enlarged by 100 pixel, then the control is moved 50pixel to the right.
135	135
136	136		#### Changing the size of the parent of an anchored control
137	137
138	138		When changing the size of a parent all anchored child controls are moved and/or resized immediately unless AutoSizing is disabled. For example AutoSizing is disabled during loading of a form and during creation of a form.
139	139
140	140		A GroupBox with a Button: ![](/wiki-images/6/60/Anchors1.png)
141	141
142	142		When the GroupBox is enlarged the distance of the anchored side is kept:
143	143
144	144		With akLeft, no akRight: ![](/wiki-images/0/05/Anchors_akLeft.png)
145	145
146	146		With akLeft and akRight: ![](/wiki-images/6/66/Anchors_akLeft_akRight.png)
147	147
148	148		With akRight, no akLeft: ![](/wiki-images/d/d3/Anchors_akRight_no_akLeft.png)
149	149
150	150		Three buttons in a groupbox: ![](/wiki-images/4/48/Anchors_no_akLeft_no_akRight_small.png)
151	151
152	152		With no akLeft and no akRight their centers are scaled: ![](/wiki-images/7/7b/Anchors_no_akLeft_no_akRight_big.png)
153	153
154	154		Notes:
155	155
156	156		- Loading a form is like one big SetBounds. During loading properties are set using the values of the lfm. Keep in mind that there can be multiple lfm files because of ancestors and frames. After loading the [[LCL]] enables autosizing. Anchored controls use the bounds at the end of loading. Any step in between is ignored.
157	157		- For custom controls it is often better to set AnchorSides instead of only Anchors.
158	158
159	159		#### Changing the size of an anchored control
160	160
161	161		When changing the Width of an anchored control, for example via the Object Inspector or via code Button1.Width:=3, you can see the difference between anchoring to Parent and anchoring to Nil. Anchoring to Parent will resize and move the Button1, while anchoring to Nil will only resize. For example:
162	162
163	163		##### Anchored to nil
164	164
165	165		![](/wiki-images/b/bd/Anchored_right_nil_resize1.png) A Button1 anchored \[akTop,akRight\], AnchorSide\[akRight\].Control=nil
166	166
167	167		![](/wiki-images/a/a0/Anchored_right_nil_resize2.png) Setting the Width to a smaller value will shrink the button, keeping the button's Left, increasing the distance of the right side.
168	168
169	169		![](/wiki-images/1/16/Anchored_right_nil_resize3.png) When the Groupbox is resized the button will keep the new distance.
170	170
171	171		Explanation: setting the Width is equivalent to calling SetBounds(Left,Top,NewWidth,Height). That's why the Left is kept. This is Delphi compatible.
172	172
173	173		##### Anchored to Parent
174	174
175	175		![](/wiki-images/4/45/Anchored_right_parent_resize1.png) A Button1 anchored \[akTop,akRight\], AnchorSide\[akRight\].Control=Button1.Parent
176	176
177	177		![](/wiki-images/0/04/Anchored_right_parent_resize2.png) Setting the Width to a smaller value will shrink the button, keeping the right distance, changing the button's Left.
178	178
179	179		#### Anchored to sibling
180	180
181	181		You can anchor to neighbor controls. The following example shows:
182	182
183	183		- you can anchor a label's left to the left of a button
184	184		- anchor a label's top to the bottom of a button
185	185		- anchor the center of a label to the center of a button
186	186
187	187		![](/wiki-images/e/ee/Anchorsides_example1.png)
188	188
189	189		![](/wiki-images/b/ba/Anchorside_example2.png)
190	190
191	191		For more details and how to setup anchors see: [[Anchor Sides]].
192	192
193	193		![](/wiki-images/6/6d/Anchoreditor.png)
194	194
195	195		### BorderSpacing
196	196
197	197		The BorderSpacing properties controls the minimum amount of space around a control. The properties are:
198	198
199	199		- Around: this amount in pixel is added to Left, Top, Right, Bottom.
200	200		- Left: space in pixel on the left side of the control
201	201		- Top: space in pixel above the control
202	202		- Right: space in pixel on the right side of the control
203	203		- Bottom: space in pixel below the control
204	204		- InnerBorder: this amount in pixel is added twice to the preferred width and height. Some controls override the calculation and ignore this property. An example where it works is TButton. With InnerBorder you can make a button bigger than needed.
205	205		- CellAlignHorizontal: This is used in table layouts like ChildSizing.Layout=cclLeftToRightThenTopToBottom. If the control is smaller than the table cell, this property defines where to align the control: to the left ccaLeftTop, to the right ccaRightBottom or in the middle ccaCenter.
206	206		- CellAlignVertical: same as CellAlignHorizontal but for vertical alignment.
207	207
208	208		#### BorderSpacing rules
209	209
210	210		- Around is added to Left,Top,Right,Bottom borderspacing
211	211		- The space can be even bigger, if the controls have constraints that don't allow to expand.
212	212
213	213		##### Anchoring to the opposite side
214	214
215	215		For example right side of A to left side of B.
216	216
217	217		Both borderspacings of A and B are used.
218	218
219	219		- The horizontal space between two controls (LeftControl, RightControl on Parent) is the maximum of
220	220		- LeftControl.BorderSpacing.Right + LeftControl.BorderSpacing.Around
221	221		- RightControl.BorderSpacing.Left + RightControl.BorderSpacing.Around
222	222		- Parent.ChildSizing.HorizontalSpacing
223	223		- The vertical space works analog: between two controls (TopControl, BottomControl on Parent) is the maximum of
224	224		- TopControl.BorderSpacing.Bottom + TopControl.BorderSpacing.Around
225	225		- BottomControl.BorderSpacing.Top + BottomControl.BorderSpacing.Around
226	226		- Parent.ChildSizing.VerticalSpacing
227	227
228	228		For instance if LeftControl.BorderSpacing.Right = 3 and LeftControl.BorderSpacing.Around = 4, then there is at least 7 pixel space between the two controls. If RightControl.BorderSpacing.Left = 4 and RightControl.BorderSpacing.Around = 4 then the space will be at least 8. If Parent.ChildSizing.HorizontalSpacing = 10 then the space will be at least 10.
229	229
230	230		##### Anchoring to the same side
231	231
232	232		For example right side of A to right side of B.
233	233
234	234		- Only borderspacings of A is used.
235	235		- Parent.ChildSizing.Horizontal/VerticalSpacing are not used.
236	236
237	237		##### Anchoring to center
238	238
239	239		For example center of A to center of B.
240	240
241	241		No borderspacing is used and no Parent.ChildSizing.Horizontal/VerticalSpacing is used.
242	242
243	243		##### Example
244	244
245	245		A common example is anchoring a Label to an Edit.
246	246
247	247		![](/wiki-images/1/1e/BorderSpacing_Anchors.png)
248	248
249	249		The Label center is vertically anchored to the Edit. The Edit's left side is anchored to the right side of the Label. Both have BorderSpacing.Around=6. This results in 6 pixel space between the Label and the Edit and 6 pixel space left of the Label and 6 pixel space right of the Edit. There is 6 pixel space above and below the Edit as well.
250	250
251	251		- The left space between a control and its parent (Label1 on GroupBox1) is the maximum of
252	252		- Label1.BorderSpacing.Left + Label1.BorderSpacing.Around
253	253		- GroupBox1.ChildSizing.LeftTopSpacing
254	254
255	255		- The right space between a control and its parent (Edit1 on GroupBox1) is the maximum of
256	256		- Edit1.BorderSpacing.Right + Edit1.BorderSpacing.Around
257	257		- GroupBox1.ChildSizing.RightBottomSpacing
258	258
259	259		- When a control's center is anchored to another control, for example the above Label is centered vertically to the Edit1, then all spacings are ignored.
260	260
261	261		- When a control's left side is anchored to the left side of another control (i.e. they are aligned with the left side), then the distance between both left's side is the
262	262		- Control1.BorderSpacing.Left + Control1.BorderSpacing.Around
263	263
264	264		Here is a more complex example:
265	265
266	266		![](/wiki-images/9/9c/Borderspacing_anchors2.png)
267	267
268	268		The important parts of the lfm code:
269	269
270		-	~~``` pascal~~
	270	+	``` lfm
271	271		object GroupBox1: TGroupBox
272	272		AutoSize = True
273	273		Caption = 'GroupBox1'
274	274		TabOrder = 0
275	275		object Label1: TLabel
276	276		AnchorSideLeft.Control = GroupBox1
277	277		AnchorSideTop.Control = Edit1
278	278		AnchorSideTop.Side = asrCenter
279	279		BorderSpacing.Around = 6
280	280		Caption = 'Label1'
281	281		end
282	282		object Edit1: TEdit
283	283		AnchorSideLeft.Control = Label1
284	284		AnchorSideLeft.Side = asrBottom
285	285		AnchorSideTop.Control = GroupBox1
286	286		AnchorSideRight.Control = GroupBox1
287	287		AnchorSideRight.Side = asrBottom
288	288		Anchors = [akTop, akLeft, akRight]
289	289		BorderSpacing.Around = 6
290	290		TabOrder = 0
291	291		Text = 'Edit1'
292	292		end
293	293		object Label2: TLabel
294	294		AnchorSideLeft.Control = GroupBox1
295	295		AnchorSideTop.Control = Edit1
296	296		AnchorSideTop.Side = asrBottom
297	297		BorderSpacing.Around = 6
298	298		Caption = 'Label2'
299	299		end
300	300		object ComboBox1: TComboBox
301	301		AnchorSideLeft.Control = Label2
302	302		AnchorSideTop.Control = Label2
303	303		AnchorSideTop.Side = asrBottom
304	304		AnchorSideRight.Control = GroupBox1
305	305		AnchorSideRight.Side = asrBottom
306	306		Anchors = [akTop, akLeft, akRight]
307	307		BorderSpacing.Right = 6
308	308		TabOrder = 1
309	309		Text = 'ComboBox1'
310	310		end
311	311		object CheckBox1: TCheckBox
312	312		AnchorSideLeft.Control = GroupBox1
313	313		AnchorSideTop.Control = ComboBox1
314	314		AnchorSideTop.Side = asrBottom
315	315		BorderSpacing.Around = 6
316	316		Caption = 'CheckBox1'
317	317		TabOrder = 2
318	318		end
319	319		object Label3: TLabel
320	320		AnchorSideLeft.Control = GroupBox1
321	321		AnchorSideTop.Control = Edit2
322	322		AnchorSideTop.Side = asrCenter
323	323		BorderSpacing.Around = 6
324	324		Caption = 'Label3'
325	325		end
326	326		object Edit2: TEdit
327	327		AnchorSideLeft.Control = Label3
328	328		AnchorSideLeft.Side = asrBottom
329	329		AnchorSideTop.Control = CheckBox1
330	330		AnchorSideTop.Side = asrBottom
331	331		BorderSpacing.Around = 6
332	332		TabOrder = 3
333	333		Text = 'Edit2'
334	334		end
335	335		end
336	336		```
337	337
338	338		#### BorderSpacing and Align
339	339
340	340		BorderSpacing works with Align. In the example below there is a Memo1 with Align=alTop and a Memo2 with Align=alCLient.
341	341
342	342		- Normally the two Memos would fill the whole GroupBox.
343	343		- But the Memo1 has BorderSpacing.Around=10, so there 10 pixel space around Memo1.
344	344		- The Memo2 has BorderSpacing.Top=20. The space between Memo1 and Memo2 is the maximum, which is the 20 from Memo2.
345	345		- Memo2 has also BorderSpacing.Right=50 so there is 50 Pixel space right of Memo2.
346	346		- The GroupBox can define default space for all its child controls via ChildSizing.LeftRightSpacing/VerticalSpacing/HorizontalSpacing. In this example it does not (all 0).
347	347
348	348		![](/wiki-images/1/13/Borderspacing_align1.png)
349	349
350	350		## Align
351	351
352	352		The Align property works pretty much like in Delphi and can be used to quickly fill an area. For example to let a TListBox fill the entire area of its Parent, set ListBox1.Align=alClient. The align values alTop, alBottom, alLeft and alRight will place controls without overlapping if possible. That means all controls with Align in alLeft,alTop,alBottom,alRight will not overlap if there is enough space.
353	353
354	354		The algorithm works as follows:
355	355
356	356		- First all controls with alTop are put to the top of the client area. If there are several controls with alTop the last added/moved will be put topmost. The algorithm will try to avoid overlapping and keep the height of the control, while expanding the width to maximum. AnchorSides of the left, top and right sides are ignored. The bottom AnchorSide works normal. Borderspacing and Parent.ChildSizing spaces are considered, so you can define space around each aligned control.
357	357		- Then all controls with alBottom are put to the bottom of the client area. Otherwise it works analog to alTop.
358	358		- Then all controls with alLeft are put to the left of the client area between the alTop and alBottom controls. Otherwise it works analog to alTop.
359	359		- Then all controls with alRight are put to the right of the client area between the alTop and alBottom controls. Otherwise it works analog to alTop.
360	360		- If there is a control with alClient it will fill the remaining client.
361	361		- If there is more than one control with alClient they will be placed at the same position, overlapping each other. Use the Visibility property to define which one is shown.
362	362
363	363		![](/wiki-images/e/e6/Autosize_align.png)
364	364
365	365		### Align and BorderSpacing
366	366
367	367		The space of BorderSpacing and of the parent's ChildSizing is applied to aligned controls. The memo below has Align=alClient.
368	368
369	369		![](/wiki-images/b/b4/Autosize_align_borderspacing.png)
370	370
371	371		### Align and Anchoring
372	372
373	373		The free side of an aligned control (e.g. the right side of a Align=alLeft) follows the anchoring rules. If the anchor is not set, then the control will keep its Width. If the anchor is set, then the Width will change.
374	374
375	375		### Align and AutoSize
376	376
377	377		A control aligned with alLeft or alRight expands vertically, and will use its designed width. If AutoSize is set to true, then the Width will be the preferred width. The button below has Align=alRight and AutoSize=true.
378	378
379	379		![](/wiki-images/3/35/Autosize_align_autosize.png)
380	380
381	381		### Align and parent AutoSize
382	382
383	383		A control aligned with alClient fills the remaining space. A parent control with AutoSize=true will expand or shrink to enclose its children exactly. What happens if you combine these two properties? Say you put a button with Align=alClient into a groupbox with AutoSize=true?
384	384
385	385		![](/wiki-images/b/b1/Autosize_nested1.png)
386	386
387	387		The [[LCL]] uses the preferred size of the buttons and expands or shrinks the groupbox accordingly:
388	388
389	389		![](/wiki-images/2/28/Autosize_nested2.png)
390	390
391	391		### alCustom
392	392
393	393		This Align value exists for custom AutoSize algorithms and is treated by the [[LCL]] almost like alNone. Controls with alCustom are not moved by the [[LCL]] but by your custom control. You have to override CalculatePreferredSize and DoAutoSize.
394	394
395	395		### Order of controls with same Align
396	396
397	397		Controls with same Align are positioned in the following order. On alLeft the control with the lowest Left wins, for alTop the lowest Top, for alRight the biggest Left+Width, for alBottom the biggest Top+Height. If two controls have the same coordinate the one last moved (calls to SetBounds or SetParent) wins. Controls can override CreateControlAlignList to change the order or override DoAlignChildControls to handle the whole Align.
398	398
399	399		Note: Before 0.9.29 controls at the same coordinate were put in Z order. This resulted in reordering in some cases and had to be fixed. There is one incompatibility: If you added several controls with alTop or alLeft without specifying bounds the controls are put at 0,0 and therefore the last added wins, where formerly the first won.
400	400
401	401		Note for Delphians: Contrary to the VCL the LCL can and often does delay recomputing the layout. Delphi does the layout after every property change. Setting Align=alTop calls in the VCL a special AlignControls, where the current control has a special meaning. That's why in the VCL the order of setting properties is important. The LCL layout algorithm is independent of the chronological order of setting the properties.
402	402
403	403		For example all changes in FormCreate are delayed and the layout is computed from the final property values. On the other hand ButtonClick has no delay (aka you have to add the Disable/EnableAutoSize yourself), so inserting alTop controls may have different results.
404	404
405	405		If you want a specific order, use Disable/EnableAutoSize and set the "Top" properties. For example TForm.OnCreate is called with AutoSize disabled, so you can use:
406	406
407	407		``` pascal
408	408		procedure TForm1.FormCreate(Sender: TObject);
409	409		begin
410	410		// making sure Panel2 is above Panel1, even though Panel1 is set first:
411	411		Panel1.Align:=alTop;
412	412		Panel1.Top:=1;
413	413		Panel2.Align:=alTop;
414	414		Panel2.Top:=0;
415	415		end;
416	416		```
417	417
418	418		## Layout
419	419
420	420		### Rows, columns and lines
421	421
422	422		You can align child controls in rows and columns using the ChildSizing properties. For example:
423	423
424	424		- ChildSizing.Layout=cclLeftToRightThenTopToBottom
425	425		- ChildSizing.ControlsPerLine=3
426	426		- AutoSize=false (the groupbox does not resize to fit the child controls)
427	427
428	428		![](/wiki-images/1/10/Autosize_layout_lefttoright.png)
429	429
430	430		The Layout property defaults to cclNone. If you set Layout to another value, every child, that has normal anchors, will be aligned. Normal anchors means:
431	431
432	432		- Anchors=\[akLeft,akTop\]
433	433		- AnchorSide\[akLeft\].Control=nil
434	434		- AnchorSide\[akTop\].Control=nil
435	435		- Align=alNone
436	436
437	437		The value cclLeftToRightThenTopToBottom will put the first child at top, left, the second to the right, and so forth. This is a line. The property ControlsPerLine defines when a new line is started. In the above example each line (row) has 3 controls. There are 12 controls, so there are 4 lines (rows) each with 3 controls (columns). If ControlsPerLine is 0 it means unlimited controls per line - there would be only one row with all childs.
438	438
439	439		You can see that the rows have different sizes, each row has the size of the biggest control and that the controls are resized to column width. There is no space between the rows. The space in the image comes from the used theme, not from the [[LCL]].
440	440
441	441		### Fixed space between rows and columns
442	442
443	443		You can add space between with these properties:
444	444
445	445		- ChildSizing.VerticalSpacing - Space between rows
446	446		- ChildSizing.HorizontalSpacing - Space between columns
447	447		- ChildSizing.LeftRightSpacing - Space on the left and right of all columns
448	448		- ChildSizing.TopBottomSpacing - Space above and below of all columns
449	449
450	450		The above example with ChildSizing.VerticalSpacing=6, ChildSizing.HorizontalSpacing=15, ChildSizing.LeftRightSpacing=30, ChildSizing.TopBottomSpacing=10, AutoSize=true
451	451
452	452		![](/wiki-images/a/a9/Autosize_layout_parentspacing.png)
453	453
454	454		Additionally you can add individual space for each control with its BorderSpacing properties.
455	455
456	456		### Enlarge
457	457
458	458		The above example resized the GroupBox to the needed space. If your GroupBox has a fixed size or if it is not freely resizable, for instance if the GroupBox should fill the whole width of the form, then the childs should enlarge. There are several modes. The default mode ChildSizing.EnlargeHorizontal=crsAnchorAligning is to not enlarge anything. The space on the right side will be unused.
459	459
460	460		- crsAnchorAligning - do not use the extra space
461	461		- crsScaleChilds - multiply the width/height with the same factor
462	462		- crsHomogeneousChildResize - add to each width/height the same amount
463	463		- crsHomogeneousSpaceResize - add to each space between the childs the same amount
464	464
465	465		#### crsScaleChilds
466	466
467	467		ChildSizing.EnlargeHorizontal=crsScaleChilds, ChildSizing.EnlargeVertical=crsScaleChilds, AutoSize=false
468	468
469	469		![](/wiki-images/b/b0/Autosize_layout_scalechilds.png)
470	470
471	471		For example if the ClientWidth is twice as big as needed, then every child will be twice as big.
472	472
473	473		#### crsHomogeneousChildResize
474	474
475	475		ChildSizing.EnlargeHorizontal=crsHomogeneousChildResize, ChildSizing.EnlargeVertical=crsHomogeneousChildResize, AutoSize=false
476	476
477	477		![](/wiki-images/3/39/Autosize_layout_homogeneouschildresize.png)
478	478
479	479		For example if the ClientWidth is 30 pixel bigger than needed, then every child will be 10 pixel broader.
480	480
481	481		#### crsHomogeneousSpaceResize
482	482
483	483		ChildSizing.EnlargeHorizontal=crsHomogeneousSpaceResize, ChildSizing.EnlargeVertical=crsHomogeneousSpaceResize, AutoSize=false
484	484
485	485		![](/wiki-images/9/96/Autosize_layout_homogeneousspaceresize.png)
486	486
487	487		For example if the ClientWidth is 40 pixel bigger than needed, there will be 10 pixel space on the left, right and between each child.
488	488
489	489		### Shrink
490	490
491	491		Shrinking works similarly to enlarging. You can set different modes if there is not enough space for controls. ShrinkHorizontal, ShrinkVertical.
492	492
493	493		### Individual cells
494	494
495	495		In the above examples all controls were resized the same, each filled the whole cell. A cell is the space in a specific row and column. Normally a control fills the whole cell space. This can be changed with the properties BorderSpacing.CellAlignHorizontal and BorderSpacing.CellAlignVertical.
496	496
497	497		For example set the BorderSpacing.CellAlignHorizontal of the fifth button to caCenter you will get this:
498	498
499	499		![](/wiki-images/d/d3/Autosize_layout_cellhorizontal_cacenter.png)
500	500
501	501		There are four possible values for CellAlignHorizontal/CellAlignVertical:
502	502
503	503		- caFill: the child control fills the whole width (height) of the cell
504	504		- caCenter: the child control uses its preferred width (height) and will be centered in the cell
505	505		- caLeftTop: the child control uses its preferred width (height) and will be leftaligned in the cell
506	506		- caRightBottom: the child control uses its preferred width (height) and will be rightaligned in the cell
507	507
508	508		![](/wiki-images/c/c0/Autosize_layout_cellalign.png)
509	509
510	510		## Custom layout with OnResize / OnChangeBounds
511	511
512	512		Sometimes the [[LCL]] layout is not sufficient. The below example shows a GroupBox1 with a ListBox1 and a Memo1. The ListBox1 should fill one third of the space, the Memo1 takes the rest.
513	513
514	514		![](/wiki-images/4/4b/Autosize_onresize.png)
515	515
516	516		Whenever the GroupBox is resized the ListBox1.Width should be one third. To achieve this set the OnResize event of the GroupBox1 to:
517	517
518	518		``` pascal
519	519		procedure TForm1.GroupBox1Resize(Sender: TObject);
520	520		begin
521	521		ListBox1.Width := GroupBox1.ClientWidth div 3;
522	522		end;
523	523		```
524	524
525	525		### Common mistake: Wrong OnResize event
526	526
527	527		Do not put all your resizing code into the Form OnResize event. The Form OnResize event is only called when the Form was resized. The child controls (e.g. a GroupBox1) is resized later, so the GroupBox1.ClientWidth has still the old value during the FormResize event. You must use the GroupBox1.OnResize event to react to changes of GroupBox1.ClientWidth.
528	528
529	529		### Common mistake: Width instead of ClientWidth, AdjustClientRect
530	530
531	531		The Width is the size including the frame. The ClientWidth is the inner Width without the frame. Some controls like the TPanel paints a further frame. Then you have to use AdjustClientRect. The same example, but instead of a GroupBox1 the ListBox1 is in a Panel1:
532	532
533	533		``` pascal
534	534		procedure TForm1.Panel1Resize(Sender: TObject);
535	535		var
536	536		r: TRect;
537	537		begin
538	538		r := Panel1.ClientRect;
539	539		Panel1.AdjustClientRect(r);
540	540		ListBox1.Width := (r.Right - r.Left) div 3;
541	541		end;
542	542		```
543	543
544	544		## Custom Controls
545	545
546	546		When you write your own control, you can override and fine tune many parts of the [[LCL]] autosizing.
547	547
548	548		### SetBounds, ChangeBounds, DoSetBounds
549	549
550	550		SetBounds is called when the properties Left, Top, Width, Height, BoundsRect is set or the user calls it directly. SetBounds updates the BaseBounds and BaseParentClientSize, which are used by anchoring to keep the distance. For example loading a Form with TMemo and the lfm contains TMemo's Left and Width, then SetBounds is called two times for the memo. When the user maximizes a window, SetBounds is called for the form, but not for the Memo, keeping the BaseBounds of the Memo. If the Memo is anchored to the right, the Width of the Memo is changed based on the BaseBounds and BaseParentClientSize. Keep in mind that the given aLeft, aTop, aWidth, aHeight might not be valid and will be changed by the [[LCL]] before applied. Delphi calls SetBounds more often. SetBounds calls ChangeBounds with KeepBase=false.
551	551
552	552		ChangeBounds is called whenever the position or size of the control is set, either via the properties or by the layouter of the [[LCL]]. SetBounds calls internally ChangeBounds with KeepBase=false, while the [[LCL]] layouter calls it with KeepBase=true. Override this for code that might change the preferred size or resizes other controls. Keep in mind that the given aLeft, aTop, aWidth, aHeight might not be valid and will be changed by the [[LCL]] before applied. You can call this function.
553	553
554	554		DoSetBounds is a low level function to set the private variables FLeft, FTop, FWidth, FHeight. Do not call this function, only the [[LCL]] calls it. It also updates FClientWidth and FClientHeight accordingly. Override this to update the content layout of the control, for example scroll bars. As always: do not paint here, but call Invalidate and paint in OnPaint or override Paint.
555	555
556	556		DoAdjustClientRectChange is called by the [[LCL]] and the [[LCL]] interface, when the ClientRect has changed and the Width and Height were kept.
557	557
558	558		WMSize exists for Delphi/VCL compatibility. It is called by the [[LCL]] interface and on every change of bounds.
559	559
560	560		### AdjustClientRect
561	561
562	562		The method AdjustClientRect can be overriden by your custom controls and affects Align, ChildSizing.Layout and AnchorSides. It does not affect the meaning of Left, Top and does not affect normal anchoring (for example setting).
563	563
564	564		When you want to draw your own frame, then the child controls should be aligned within these frames. For example TPanel draws a frame and reduces the client area by overriding the method AdjustClientRect:
565	565
566	566		``` pascal
567	567		TCustomPanel = class(TCustomControl)
568	568		...
569	569		protected
570	570		...
571	571		procedure AdjustClientRect(var aRect: TRect); override;
572	572		...
573	573
574	574		procedure TCustomPanel.AdjustClientRect(var aRect: TRect);
575	575		var
576	576		BevelSize: Integer;
577	577		begin
578	578		inherited AdjustClientRect(aRect);
579	579
580	580		BevelSize := BorderWidth;
581	581		if (BevelOuter <> bvNone) then
582	582		inc(BevelSize, BevelWidth);
583	583		if (BevelInner <> bvNone) then
584	584		inc(BevelSize, BevelWidth);
585	585
586	586		InflateRect(aRect, -BevelSize, -BevelSize);
587	587		end;
588	588		```
589	589
590	590		#### AdjustClientRect and Align
591	591
592	592		AdjustClientRect can be used to reduce the client area used by all autosize operations. For example TPanel uses AdjustClientRect to reduce the client area by the borderwidth:
593	593
594	594		![](/wiki-images/c/ca/Adjustclientrect_align.png)
595	595
596	596		The Button1 in the screenshot was created with Align=alClient. ChildSizing.Layout is affected too.
597	597
598	598		When anchoring to a parent via AnchorSides the AdjustClientRect is used too:
599	599
600	600		``` pascal
601	601		Button1.AnchorParallel(akTop,0,Button1.Parent);
602	602		```
603	603
604	604		The Button1's top side is anchored to the top side of the parent's client area. If the AdjustClientRect adds 3 to the Top the Button1.Top will be 3 (3 plus 0).
605	605
606	606		### Own AutoSize
607	607
608	608		When AutoSize is set to true the control should be resized to the preferred size if possible.
609	609
610	610		#### Preferred Size
611	611
612	612		The new size is fetched by the [[LCL]] via GetPreferredSize which calls CalculatePreferredSize, which can be overridden. For example let's write a TQuadrat, which is a TShape, but its height should equal its width:
613	613
614	614		``` pascal
615	615		TQuadrat = class(TShape)
616	616		protected
617	617		procedure CalculatePreferredSize(var PreferredWidth,
618	618		PreferredHeight: integer; WithThemeSpace: Boolean); override;
619	619		end;
620	620		...
621	621		procedure TQuadrat.CalculatePreferredSize(var PreferredWidth,
622	622		PreferredHeight: integer; WithThemeSpace: Boolean);
623	623		begin
624	624		PreferredHeight:=Width;
625	625		end;
626	626		```
627	627
628	628		The method CalculatePreferredSize gets two var parameters: PreferredWidth and PreferredHeight. They default to 0 which means: there is no preferred size, so the [[LCL]] will not change the size. The above function sets PreferredHeight to the current Width. The boolean parameter WithThemeSpace is deprecated and always false.
629	629
630	630		Important: CalculatePreferredSize must not change the bounds or any other value of the control that can trigger an autosize. Doing so will create a loop.
631	631
632	632		Computing the PreferredWidth/Height can be expensive. Therefore the [[LCL]] caches the result until InvalidatePreferredSize is called for the control. In our example the PreferredHeight depends on the Width, so we must invalidate when the Width changes:
633	633
634	634		``` pascal
635	635		TQuadrat = class(TShape)
636	636		protected
637	637		...
638	638		procedure DoSetBounds(ALeft, ATop, AWidth, AHeight: integer); override;
639	639		end;
640	640		...
641	641		procedure TQuadrat.DoSetBounds(ALeft, ATop, AWidth, AHeight: integer);
642	642		begin
643	643		inherited DoSetBounds(ALeft, ATop, AWidth, AHeight);
644	644		InvalidatePreferredSize;
645	645		// Note: The AdjustSize can be omitted here, because the [[LCL]] does that after calling DoSetBounds.
646	646		end;
647	647		```
648	648
649	649		The [[LCL]] will automatically trigger the autosizing when the bounds have changed, so the example is complete.
650	650
651	651		The default TWinControl implementation of CalculatePreferredSize queries the widget set, which might return a preferred width and/or height. Each control can override the CalculatePreferredSize method. For example TImage overrides it and returns the size of the Picture. If no preferred width (height) is available the returned value is 0 and the [[LCL]] will keep the current Width (Height). If 0 is a valid size for your control, you must set the ControlStyle flag csAutoSize0x0 (ControlStyle:=ControlStyle+\[csAutoSize0x0\];). An example is the [[LCL]] control TPanel.
652	652
653	653		#### AdjustSize
654	654
655	655		When the preferred size depends on a new property, then every time the property changes the auto sizing must be triggered. For example:
656	656
657	657		``` pascal
658	658		procedure TQuadrat.SetSubTitle(const AValue: string);
659	659		begin
660	660		if FSubTitle = AValue then exit;
661	661		FSubTitle := AValue;
662	662		InvalidatePreferredSize;
663	663		AdjustSize;
664	664		end;
665	665		```
666	666
667	667		## Reduce overhead with DisableAutoSizing, EnableAutoSizing
668	668
669	669		Since Lazarus 0.9.29 there is a new autosizing algorithm, that reduces the overhead and allows deep nested dependencies. Up to 0.9.28 DisableAlign/EnableAlign and Disable/EnableAutoSizing worked only for one control and its direct child controls.
670	670
671	671		Each time you change a property the [[LCL]] triggers a recomputation of the layout:
672	672
673	673		``` pascal
674	674		Label1.Caption := 'A'; // first recompute
675	675		Label2.Caption := 'B'; // second recompute
676	676		```
677	677
678	678		The recomputations will trigger events and send messages. To reduce the overhead you can suspend the autosizing:
679	679
680	680		``` pascal
681	681		DisableAutoSizing;
682	682		try
683	683		Label1.Caption := 'A'; // no recompute
684	684		Label2.Caption := 'B'; // no recompute
685	685		finally
686	686		EnableAutoSizing; // one recompute
687	687		end;
688	688		```
689	689
690	690		You must balance calls to Disable/EnableAutoSizing. Autosizing starts only when EnableAutoSizing is called after a corresponding (earlier) DisableAutoSizing.
691	691
692	692		Since 0.9.29 the Disable/EnableAutoSizing works for the entire form. This means every call to DisableAutoSizing suspends autosizing for all controls on that form. If you write your own control you can now use the following:
693	693
694	694		``` pascal
695	695		procedure TMyRadioGroup.DoSomething;
696	696		begin
697	697		DisableAutoSizing; // disables not only TMyRadioGroup, but the whole form's autosizing
698	698		try
699	699		// delete items ...
700	700		// add, reorder items ...
701	701		// change item captions ...
702	702		finally
703	703		EnableAutoSizing; // recompute
704	704		end;
705	705		end;
706	706		```
707	707
708	708		Which basically means: you do not have to care. Just call Disable/EnableAutoSizing.
709	709
710	710		Note: this is wrong:
711	711
712	712		``` pascal
713	713		Button1.DisableAutoSizing;
714	714		Label1.EnableAutoSizing; // wrong: every control has its own autosizing reference counter
715	715		```
716	716
717	717		### DisableAutoSizing and Form bounds
718	718
719	719		DisableAutoSizing has another useful effect under asynchronous Window Managers such as you find in Linux systems. Each time a form is resized or moved the bounds are sent to the widget set (DoSendBoundsToInterface). Even if the form is not shown the Handle is resized. The window manager often treats these bounds only as a proposal. The window manager has its own logic and often only the first bounds sent are used. The second, third or further moves may be ignored. With DisableAutoSizing you can make sure that only the final bounds are sent to the widget set making the form bounds more reliable.
720	720
721	721		## Example: a button panel
722	722
723	723		This example combines several of the [[LCL]] layout mechanisms to create a panel with three buttons: a Help button to the left and Ok and Cancel buttons to the right. We want the panel to be at the bottom of the form filling the entire width. The buttons and the panel are autosized to fit all fonts and themes.
724	724
725	725		Step 1: Create the panel and set its Align property to alBottom. Add three TBitBtns.
726	726
727	727		![](/wiki-images/7/7e/Autosize_example_buttonpanel1.png)
728	728
729	729		Set the Kind properties of the BitBtns to show the glyphs. You might need to set GlyphShowMode to gsmAlways to see them on your platform. Set the BitBtn's AutoSize property to True, which will shrink/enlarge the buttons to fit perfectly around the glyphs and text. Depending on your theme and platform you might notice that the buttons have different heights.
730	730
731	731		![](/wiki-images/4/49/Autosize_example_buttonpanel2.png)
732	732
733	733		Set the Align property of the help button to alLeft and set the other two buttons' Align property to alRight. This will enlarge the buttons vertically and move them to the far left/right. alLeft/alRight has no effect on the width, so the buttons use their preferred width.
734	734
735	735		![](/wiki-images/b/b6/Autosize_example_buttonpanel3.png)
736	736
737	737		The Panel height is still fixed. Now set the panel AutoSize property to True. The panel now shrinks vertically to fit the tallest button.
738	738
739	739		![](/wiki-images/3/36/Autosize_example_buttonpanel4.png)
740	740
741	741		The Ok button has a short caption, so the button is very small. Set the button's Constraints.MinWidth to 75. The button will now enlarge somewhat.
742	742
743	743		![](/wiki-images/3/32/Autosize_example_buttonpanel5.png)
744	744
745	745		Now add some space around the buttons. Set the panel's ChildSizing.LeftTopSpacing/RightBottomSpacing/HorizontalSpacing to 6.
746	746
747	747		![](/wiki-images/4/46/Autosize_example_buttonpanel6.png)
748	748
749	749		Finally clear the Caption of the panel and set its BevelOuter to bvNone.
750	750
751	751		![](/wiki-images/4/4e/Autosize_example_buttonpanel7.png)
752	752
753	753		## Scrolling
754	754
755	755		Some [[LCL]] controls like TScrollBox, TForm, and TFrame show scrollbars if the child controls are too big to fit the scrollbox, form or frame. They inherit this behaviour from their ancestor TScrollingWinControl.
756	756
757	757		A scrolling control's logical client area can be bigger than the visible client area. The visible client area is ClientRect. It always starts at 0,0 and its width and height is the inner area. For example in a TGroupBox it is the size of the area inside the frame. So the following is always true:
758	758
759	759		``` pascal
760	760		ClientWidth <= Width
761	761		ClientHeight <= Height
762	762		```
763	763
764	764		The logical client area is defined by the method GetLogicalClientRect. By default it is the same as ClientRect. When a child control is anchored to the right side, it uses the logical client area. TScrollingWinControl overrides this method and returns the Range of the scrollbars if they are bigger than the ClientRect. The Range can be set manually or automatically with AutoScroll=true. An example for AutoScroll=true:
765	765
766	766		![](/wiki-images/d/db/Autoscroll_all_fit1.png)
767	767
768	768		The upper button has a fixed Width of 200. The lower button is anchored to the right side of the panel. Therefore the child controls have a preferred width of 200. Because the panel is bigger than 200 the logical client area is bigger too and the lower button expands.
769	769
770	770		Now the panel is shrunk, so that the ClientWidth becomes lower than 200:
771	771
772	772		![](/wiki-images/2/27/Autoscroll_not_fit1.png)
773	773
774	774		The preferred width is still 200, so the logical client area is now 200 and bigger than the visible client area. The lower button has now a Width of 200 and the panel shows a horizontal scrollbar.
775	775
776	776		### Scroll Position
777	777
778	778		Changing the Position of a scrollbar does not change the Left or Top of any child control, nor does it change the logical client area, nor does it affect autosizing. The child controls are only virtually moved.
779	779
780	780		### Scrolling and AutoSize
781	781
782	782		When AutoSize=true the [[LCL]] will expand the control to accommodate all its child controls, and no scrollbars are needed. If the control cannot be expanded, then (only) is the secondary action of AutoSize executed: moving the child controls.
783	783
784	784		## Docking
785	785
786	786		Docking uses the described methods and properties of this page, see [[Docking]].
787	787
788	788		## Splitter
789	789
790	790		See [[TSplitter]].
791	791
792	792		## TLabel.WordWrap
793	793
794	794		TLabel.WordWrap changes the behavior of the preferred size of the label. WordWrap=true requires that the Width of the label is fixed, for example by anchoring the left and right size of the label. The preferred height of the label is then computed by breaking the Caption into multiple lines.
795	795
796	796		## DPI auto-adjustment and absolute layout auto-adjustment
797	797
798	798		Historically the [[LCL]] has been utilized mostly to design absolute layouts, despite the huge amount of options which Lazarus offers for flexible layouts, like Align, Anchors, etc, as described on the rest of this article. On top of that, it has also historically ignored the DPI of the target and instead utilized values in pixels to measure the left, top, width and height properties of controls. For desktop platforms and Windows CE this has worked reasonably well, but with the advent of [[LCL]] support for Android this could no longer be ignored. Starting in Lazarus 0.9.31 the [[LCL]] can reinterprete the [[LCL]] absolute layout in pixels as a flexible grid. There are multiple modes to choose from and they will allow to reinterprete the pixel values as either really absolute, or as in being adjusted for the DPI or as in being considered simply a fraction of the form size.
799	799
800	800		It is important to note that these new rules affect only controls which are positioned without Align and with the most standard Anchors only.
801	801
802	802		In the case where the values will be adjusted for DPI, there is a new property: TCustomForm.DesignTimeDPI which should store the DPI value of the system where the form was designed. The positioning values will be expanded when the target DPI is larger than the design time DPI or reduced otherwise. The common value for desktop DPIs is 96 and is the default value given.
803	803
804	804		property DesignTimeDPI: Integer read FDesignTimeDPI write FDesignTimeDPI;
805	805
806	806		The way in which the layout is adjusted can be controlled with the property TApplication.LayoutAdjustmentPolicy
807	807
808	808		``` pascal
809	809		TLayoutAdjustmentPolicy = (
810	810		lapDefault, // widget set dependent
811	811		lapFixedLayout, // A fixed absolute layout in all platforms
812	812		lapAutoAdjustWithoutHorizontalScrolling, // Smartphone platforms use this one,
813	813		// the x axis is stretched to fill the screen and
814	814		// the y is scaled to fit the DPI
815	815		lapAutoAdjustForDPI // For desktops using High DPI, scale x and y to fit the DPI
816	816		);
817	817		```
818	818
819	819		And the following new methods in TControl allow to force a layout-autoadjustment in a particular control and all its children or to control how particular descendants of TControl react to this:
820	820
821	821		``` pascal
822	822		TControl = class
823	823		public
824	824		...
825	825		procedure AutoAdjustLayout(AMode: TLayoutAdjustmentPolicy;
826	826		const AFromDPI, AToDPI, AOldFormWidth, ANewFormWidth: Integer); virtual;
827	827		function ShouldAutoAdjustLeftAndTop: Boolean; virtual;
828	828		function ShouldAutoAdjustWidthAndHeight: Boolean; virtual;
829	829		```
830	830
831	831		LCL-CustomDrawn-Android will call AutoAdjustLayout when the screen rotates, for example.
832	832
833	833		## More details
834	834
835	835		Many controls override TControl.DoAutoSize to perform the actual auto-sizing.
836	836
837	837		IMPORTANT: Many Delphi controls override this method and many call this method directly after setting some properties.
838	838
839	839		During handle creation not all interfaces can create complete Device Contexts which are needed to calculate things like text size.
840	840
841	841		That's why you should always call AdjustSize instead of `DoAutoSize`.
842	842
843	843		`TControl.AdjustSize` calls `DoAutoSize` in a smart fashion.
844	844
845	845		During loading and handle creation the calls are delayed.
846	846
847	847		This method initially does the same as TWinControl.DoAutoSize. But since `DoAutoSize` is commonly overriden by descendant components, it is not useful to perform all tests, which can result in too much overhead. To reduce this the [[LCL]] calls `AdjustSize` instead.
848	848
849	849		When setting AutoSize = true the [[LCL]] autosizes the control in width and height. This is one of the most complex parts of the [[LCL]], because the result depends on nearly a hundred properties. Let's start simple:
850	850
851	851		The [[LCL]] will only autosize the Width (Height) if it is free to resize. In other words - the width is not autosized if:
852	852
853	853		- the left and right side is anchored. You can anchor the sides with the Anchors property or by setting the Align property to alTop, alBottom or alClient.
854	854		- the Width is bound by the Constraints properties. The Contraints can also be overriden by the widget set. For example the winapi does not allow resizing the height of a combobox. And the gtk widget set does not allow resizing the width of a vertical scrollbar.
855	855
856	856		Same for Height.
857	857
858	858		The new size is calculated by the protected method TControl.CalculatePreferredSize. This method asks the widget set for an appropriate Width and Height. For example a TButton has preferred Width and Height. A TComboBox has only a preferred Height. The preferred Width is returned as 0 and so the [[LCL]] does not autosize the Width - it keeps the width unaltered. Finally a TMemo has no preferred Width or Height. Therefore AutoSize has no effect on a TMemo.
859	859
860	860		Some controls override this method. For example the TGraphicControl descendants like TLabel have no window handle and so cannot query the widget set. They must calculate their preferred Width and Height themselves.
861	861
862	862		The widget sets must override the GetPreferredSize method for each widget class that has a preferred size (Width or Height or both).
863	863
864	864		### Parent.AutoSize
865	865
866	866		The above described the simple explanation. The real algorithm provides far more possibilities and is therefore far more complex.
867	867
868	868		### Properties / Methods
869	869
870	870		- Left
871	871		- Top
872	872
873	873		If Parent\<\>nil then Left, Top are the pixel distance to the top, left pixel of the parent's client area (not scrolled). Remember the client area is always without the frame and scrollbars of the parent. For Delphi users: Some VCL controls like TGroupbox define the client area as the whole control including the frame and some not - the [[LCL]] is more consistent, and therefore Delphi incompatible. Left and Top can be negative or bigger than the client area. Some widget sets define a minimum/maximum somewhere around 10.000 or more.
874	874
875	875		When the client area is scrolled the Left and Top are kept unchanged.
876	876
877	877		During resizing/moving Left and Top are not always in sync with the coordinates of the Handle object.
878	878
879	879		If Parent=nil then Left, Top depend on the widget set and the window manager. Till Lazarus 0.9.25 this is typically the screen coordinate of the left,top of the client area of the form. This is Delphi incompatible. It is planned to change this to the Left, Top of the window.
880	880
881	881		Hint: Each time you change Left and Top the [[LCL]] moves instantly and recomputes the whole layout. If you want to change Left and Top use instead:
882	882
883	883		``` pascal
884	884		with Button1 do
885	885		SetBounds(NewLeft, NewTop, Width, Height);
886	886		```
887	887
888	888		- Width
889	889		- Height
890	890
891	891		The Size in pixels must not be negative, and most widget sets do not allow Width=0 and/or Height=0. Some controls on some platforms define a bigger minimum constraint in Constraints.MinInterfaceWidth/Height. Instead of sizing a control to Width=0 and/or Height=0, set Visible=false or Parent=nil. During resizing/moving Width and Height are not always in sync with the size of the Handle object.
892	892
893	893		- BoundsRect
894	894
895	895		Same as Bounds(Left, Top, Width, Height).
896	896
897	897		Common newbie mistake:
898	898
899	899		``` pascal
900	900		BoundsRect.Left := 3; // WRONG: common newbie mistake
901	901		```
902	902
903	903		This has no effect, because reading BoundsRect is a function. It creates a temporary TRect on the stack. The above is the same as
904	904
905	905		``` pascal
906	906		var
907	907		r: TRect;
908	908		begin
909	909		r := BoundsRect; // fetch the bounds
910	910		r.Left := 3; // change a value on the stack
911	911		end; // no change
912	912		```
913	913
914	914		- ClientRect
915	915
916	916		Left and Top are always 0,0. Width and Height are the visible size in pixels of the client area. Remember the client area is without the frame and without scrollbars. In a scrollable client area the logical client area can be bigger than the visible.
917	917
918	918		- ClientOrigin
919	919
920	920		Returns the screen coordinate of the topleft coordinate 0,0 of the client area. Note that this value is the position as stored in the interface and is not always in sync with the [[LCL]]. When a control is moved, the [[LCL]] sets the bounds to the desired position and sends a move message to the interface. It is up to the interface to handle moves instantly or queued.
921	921
922	922		- LCLIntf.GetClientBounds
923	923
924	924		Returns the client bounds of a control. Like ClientRect, but Left and Top are the pixel distances to the control's left, top. For example on a TGroupBox the Left, Top are the width and height of the left and top frame border. Scrolling has no effect on GetClientBounds.
925	925
926	926		- LCLIntf.GetWindowRect
927	927
928	928		After the call, ARect will be the control area in screen coordinates. That means, Left and Top will be the screen coordinate of the TopLeft pixel of the Handle object and Right and Bottom will be the screen coordinate of the BottomRight pixel.
929	929
930	930		- FBaseBoundsLock: integer
931	931
932	932		Increased/Decreased by LockBaseBounds/UnlockBaseBounds. Used to keep FBaseBounds during SetBounds calls.
933	933
934	934		- FBaseParentClientSize: TPoint
935	935
936	936		The Parent.ClientRect size valid for the FBaseBounds. FBaseBounds and FBaseParentClientSize are used to calculate the distance for akRight (akBottom). When the parent is resized, the [[LCL]] knows what distance to keep.
937	937
938	938		- FBoundsRectForNewParent: TRect
939	939
940	940		When changing the Parent of a control the Handle is recreated and many things can happen. Especially for docking forms the process is too unreliable. Therefore the BoundsRect is saved. The VCL uses a similar mechanism.
941	941
942	942		- fLastAlignedBounds: TRect
943	943
944	944		See TControl.SetAlignedBounds for an explanation. In short: It stops some circles between interface and [[LCL]] autosizing.
945	945
946	946		- FLastChangebounds: TRect
947	947
948	948		Used to stop calling ChangeBounds with the same coordinates. This happens very often.
949	949
950	950		- FLastDoChangeBounds: TRect
951	951
952	952		Used to avoid calling OnChangeBounds with the same coordinates. This reduces user defined autosizing.
953	953
954	954		- FLastResizeClientHeight: integer
955	955		- FLastResizeClientWidth: integer
956	956		- FLastResizeHeight: integer
957	957		- FLastResizeWidth: integer
958	958
959	959		Used to avoid calling OnResize with the same coordinates. This reduces user defined autosizing.
960	960
961	961		- FLoadedClientSize: TPoint
962	962
963	963		During loading many things are delayed and many things are set and worse: in the wrong order. That's why SetClientWidth/SetClientHeight calls are stored and set at end of loading again. This way the [[LCL]] can restore the distances (e.g. akRight) used during designing.
964	964
965	965		- FReadBounds: TRect
966	966
967	967		Same as FLoadedClientSize, but for SetLeft, SetTop, SetWidth, SetHeight.
968	968
969	969		- procedure SetBoundsRectForNewParent(const AValue: TRect);
970	970
971	971		Used to set FBoundsRectForNewParent. See above.
972	972
973	973		- procedure SetAlignedBounds(aLeft, aTop, aWidth, aHeight: integer); virtual;
974	974
975	975		As SetBounds but without changing the default sizes.
976	976
977	977		- procedure SetInitialBounds(aLeft, aTop, aWidth, aHeight: integer); virtual;
978	978
979	979		A smart version of SetBounds, reducing overhead during creation and loading.
980	980
981	981		- procedure UpdateBaseBounds(StoreBounds, StoreParentClientSize, UseLoadedValues: boolean); virtual;
982	982
983	983		Commit current bounds to base bounds.
984	984
985	985		- procedure SetClientHeight(Value: Integer);
986	986		- procedure SetClientSize(Value: TPoint);
987	987		- procedure SetClientWidth(Value: Integer);
988	988
989	989		Exists for Delphi compatibility too. Resizes the control, to get the wanted ClientRect size.
990	990
991	991		- procedure ChangeBounds(ALeft, ATop, AWidth, AHeight: integer); virtual;
992	992
993	993		This is the internal SetBounds. Applies constraints, updates base bounds, calls OnChangeBound, OnResize, locks bounds.
994	994
995	995		- procedure DoSetBounds(ALeft, ATop, AWidth, AHeight: integer); virtual;
996	996
997	997		This really sets the FLeft, FTop, FWidth, FHeight private variables.
998	998
999	999		- procedure SetBounds(aLeft, aTop, aWidth, aHeight: integer); virtual;
1000	1000
1001	1001		This is the standard procedure overriden by many Delphi controls. TWinControl overrides it too.
1002	1002
1003	1003		- - ignores calls when bounds are locked
1004	1004		- lock the FBoundsRealized to avoid overhead to the interface during auto sizing.
1005	1005
1006	1006		ChangeBounds is not locked this way.
1007	1007
1008	1008		- Function GetClientOrigin: TPoint; virtual;
1009	1009
1010	1010		Screen coordinate of Left, Top of client area.
1011	1011
1012	1012		- Function GetClientRect: TRect; virtual;
1013	1013
1014	1014		Size of client area. (always Left=0, Top=0)
1015	1015
1016	1016		- Function GetScrolledClientRect: TRect; virtual;
1017	1017
1018	1018		Visible client area in ClientRect.
1019	1019
1020	1020		- function GetChildsRect(Scrolled: boolean): TRect; virtual;
1021	1021
1022	1022		Returns the Client rectangle relative to the control's Left, Top. If Scrolled is true, the rectangle is moved by the current scrolling values (for an example see TScrollingWincontrol).
1023	1023
1024	1024		- function GetClientScrollOffset: TPoint; virtual;
1025	1025
1026	1026		Returns the scrolling offset of the client area.
1027	1027
1028	1028		- function GetControlOrigin: TPoint; virtual;
1029	1029
1030	1030		Returns the screen coordinate of the topleft coordinate 0,0 of the control area. (The topleft pixel of the control on the screen) Note that this value is the position as stored in the interface and is not always in sync with the [[LCL]]. When a control is moved, the [[LCL]] sets the bounds to the wanted position and sends a move message to the interface. It is up to the interface to handle moves instantly or queued.
1031	1031
1032	1032		## FAQ
1033	1033
1034	1034		### Why does AutoSize not work in the designer properly?
1035	1035
1036	1036		In the designer controls can be dragged around and properties can be set in almost any order. To allow this and avoid possible conflicts, the AutoSizing is not updated on every change at design time.
1037	1037
1038	1038		### Why does TForm.AutoSize not work when something changes?
1039	1039
1040	1040		See [[Autosize / Layout\|AutoSize and Forms]]
1041	1041
1042	1042		### Do I need to call Application.ProcessMessages when creating lots of controls?
1043	1043
1044	1044		Application.ProcessMessages is called by the [[LCL]] automatically after every message (e.g. after every event like OnClick). Calling it yourself is only needed if the changes should become visible to the user immediately. For example:
1045	1045
1046	1046		``` pascal
1047	1047		procedure TFrom.Button1Click(Sender: TObject);
1048	1048		begin
1049	1049		// change width of a control
1050	1050		Button1.Width := Button1.Width + 10;
1051	1051		// apply any needed changes and repaint the button
1052	1052		Application.ProcessMessages;
1053	1053		// do a lot of things that takes a long time
1054	1054		...
1055	1055		// after leaving the OnClick the LCL automatically processes messages
1056	1056		end;
1057	1057		```
1058	1058
1059	1059		### When enabling Anchors at runtime the control resizes, does not use the current values. Why?
1060	1060
1061	1061		akBottom means: keep a distance to the bottom side of the parent. The distance to keep is defined by the base bounds. They are set at designtime or by runtime calls of SetBounds or UpdateBaseBounds.
1062	1062
1063	1063		For example: A TListBox (Anchors=\[akLeft,aTop\]) at designtime has a bottom distance of 100 pixel. And a button to enable/disable the akBottom of the TListBox. Now start the application and press the button to enable akBottom. The 100 pixel distance will be activated, because this was the last time the programmer defined the base bounds of the TListBox. All other resizes were done by the [[LCL]] and are irrelevant. The programmers base bounds rules. You can resize the form and the 100 pixel will be kept. In order to use the current bounds as base bounds use:
1064	1064
1065	1065		``` pascal
1066	1066		ListBox1.UpdateBaseBounds(true, true, false);
1067	1067		ListBox1.Anchors := ListBox1.Anchors + [akBottom];
1068	1068		```
1069	1069
1070	1070		Setting Anchors does not automatically call UpdateBaseBounds, because this would destroy the ability to change properties independently.
1071	1071
1072	1072		### Resizing stringgrid columns in form's OnResize event does not work
1073	1073
1074	1074		The Form's OnResize is triggered when the Form's Width, Height, ClientWidth or ClientHeight changes. This is per se independent of TStringGrid. Of course it often happens that both the Form and the TStringGrid are resized. This means using forms OnResize will often work, but not always. A prominent example where it always fails is when the theme is changed and you have a TStringGrid in a TGroupBox in a TForm. When the theme changed the form size is kept, so no Forms OnResize is triggered. But the TGroupBox changed, so the TStringGrid should be resized.
1075	1075
1076	1076		Solution: Use the TStringGrid's OnResize.
1077	1077
1078	1078		### Why is TForm.Width equal to TForm.ClientWidth?
1079	1079
1080	1080		Mattias' notes:
1081	1081
1082	1082		"There are historical and technical reasons.
1083	1083
1084	1084		For forms without parent the Clientwidth equals the Width, because the real Width including the frame was not available on Linux ten years ago (at least not reliable on various window managers). I didn't test, but I heard it is now possible with gtk2. The main problem is the autosizing, because this needs the frame sizes before the form is mapped to the screen. It might be, that this is only available after an event, which means that you have to wait for it, which means trouble for ShowModal. Changing this breaks compatibility with a lot of existing [[LCL]] code, but for this we added the LCLVersion in the lfm files.
1085	1085
1086	1086		There is a new compiler define LCLRealFormBounds In Lazarus trunk 1.7 that enables real size for a form. To use it just compile your application with LCLRealFormBounds ON. For now, only win32 widget set is supported.
1087	1087
1088	1088		For all other controls the rules is ClientWidth\<=Width. The Width is the ClientWidth plus the widget frame. The question is if the scrollbars belong to the frame. I would say yes and it was implemented that way some time ago. Apparently this has changed. See the current cursor problem on synedit."
1089	1089
1090	1090		### I get an infinite loop / How to debug autosizing?
1091	1091
1092	1092		Here are some notes, describing what other users did wrong and how to find out:
1093	1093
1094	1094		#### Differences to Delphi
1095	1095
1096	1096		For Delphi users: Please read: [[Autosize / Layout\|Lazarus_vs_Delphi]]
1097	1097
1098	1098		#### Overriding a [[LCL]] method and triggering a recompute
1099	1099
1100	1100		You override a method and tell the [[LCL]] to compute again, even if nothing changed. Check for AdjustSize, Realign, AlignControls, InvalidatePreferredSize. For example:
1101	1101
1102	1102		``` pascal
1103	1103		procedure TMainForm.SetBounds(ALeft, ATop, AWidth, AHeight: integer);
1104	1104		begin
1105	1105		// This will create an endless loop
1106	1106		InvalidatePreferredSize;
1107	1107
1108	1108		// This will create an endless loop too:
1109	1109		OtherComponent.Left:=10;
1110	1110		OtherComponent.Left:=20;
1111	1111
1112	1112		inherited SetBounds(ALeft, ATop, AWidth, AHeight);
1113	1113		end;
1114	1114		```
1115	1115
1116	1116		Explanation: The SetBounds method is called often, even without changing anything. For example a "Left:=30;" will do so.
1117	1117
1118	1118		Remedy: Check for changes:
1119	1119
1120	1120		``` pascal
1121	1121		procedure TMainForm.SetBounds(ALeft, ATop, AWidth, AHeight: integer);
1122	1122		begin
1123	1123		if (Left <> ALeft) or (Top <> ATop) or (Width <> AWidth) or (Height <> AHeight) then
1124	1124		InvalidatePreferredSize;
1125	1125		inherited SetBounds(ALeft, ATop, AWidth, AHeight);
1126	1126		end;
1127	1127		```
1128	1128
1129	1129		##### TWinControl.AlignControls
1130	1130
1131	1131		``` pascal
1132	1132		procedure AlignControls(aControl: TControl; var aRect: TRect); override;
1133	1133		```
1134	1134
1135	1135		AlignControls moves and sizes all child controls. The [[LCL]] implementation ignores controls with Align=alCustom.
1136	1136
1137	1137		The parameter aControl: TControl is kept for VCL compatibility. The [[LCL]] always passes nil. It gives aControl precedence when applying the Align property. When you have for example two controls A,B with Align=alLeft then the one with the lower Left is put left most. If both have the same Left then creation order wins. Now imagine you want to switch both controls A,B in the designer. You drag B to the left. This results in setting B.Left to 0. Now AlignControls starts and find both A.Left=0 and B.Left=0. Normally A would win. To let B win the VCL calls AlignControls(B,r). So aControl is the last moved. Contrary to the VCL the [[LCL]] allows to combine multiple layout changes without recomputing on every step. The [[LCL]] keeps track of the last moved controls in TWinControl.fAlignControls and applies the order in TWinControl.CreateControlAlignList. The aControl parameter is always nil.
1138	1138
1139	1139		See TWinControl.CreateControlAlignList.
1140	1140
1141	1141		#### OnResize/OnChangeBounds conflict with [[LCL]] properties
1142	1142
1143	1143		You set bounds that bite the [[LCL]] properties. For example a TLabel.AutoSize is true by default. If you set the Label1.Width in an OnResize event, the [[LCL]] will recompute, resize the Label1 and call the OnResize again. Start your application in the debugger and reproduce the bug. When it enters the loop, pause the application and see the call stack. If you see one of your events or your methods start searching there. For example:
1144	1144
1145	1145		``` pascal
1146	1146		procedure TMainForm.FormResize(Sender: TObject);
1147	1147		begin
1148	1148		// if Button1 is anchored or AutoSize=true then the following might create an endless loop:
1149	1149		Button1.Width:=100;
1150	1150		end;
1151	1151		```
1152	1152
1153	1153		#### [[LCL]] interface bug, custom widget
1154	1154
1155	1155		Sometimes the [[LCL]] interface or your custom control has a bug and undoes the [[LCL]] bounds. Compile the [[LCL]] with -dVerboseIntfSizing. This will write the communication between [[LCL]] and the [[LCL]] interface. If a widget does not allow free resizing, it must tell the [[LCL]] via the Constraints. Search for SetInterfaceConstraints in the various [[LCL]] interfaces and TWSControlClass.ConstraintWidth/Height.
1156	1156
1157	1157		#### alCustom
1158	1158
1159	1159		You use alCustom. This was only half implemented in earlier Lazarus versions, but some clever programmers used it to create some special effects. Now it is implemented and your program does not work anymore. Please see here what alCustom does: [[Autosize / Layout\|alCustom]].
1160	1160
1161	1161		## See also
1162	1162
1163	1163		- [[Docking]]
1164	1164		- [[High DPI]]
1165	1165		- [[Anchor Sides]]
1166	1166
1167	1167		---
1168	1168		From the Free Pascal wiki, page "Autosize / Layout", as it stood on 2021-04-13 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