Anchor Sides: what changed

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

Old	New		Line
1	1		There are some new [[Property\|properties]] and [[Method\|methods]] for automatic layout of controls. You can now setup controls to keep a certain distance to other controls, or center relative to other controls. See below for examples.
2	2
3	3		Each of the four sides of a control (Left, Top, Right, Bottom) can now be anchored/bound to a side of another control. For example you can now anchor the left side of [[TEdit]] to the right side of a [[TLabel]]. Everytime the Label is moved or resized the Edit's left side will follow, which normally results in moving the Edit parallel to the Label.
4	4
5	5		## Example 1
6	6
7		-	~~```~~
	7	+	```text
8	8		+--------+ +-------+
9	9		\| Label1 \| \| Edit1 \|
10	10		+--------+ \| \|
11	11		+-------+
12	12		```
13	13
14	14		### In code
15	15
16	16		``` Pascal
17	17		Edit1.AnchorSide[akLeft].Side := asrRight;
18	18		Edit1.AnchorSide[akLeft].Control := Label1;
19	19		Edit1.Anchors := Edit1.Anchors + [akLeft];
20	20		```
21	21
22	22		You can define the distance with the BorderSpacing properties:
23	23
24	24		``` Pascal
25	25		Edit1.BorderSpacing.Left := 10;
26	26		```
27	27
28	28		The same can be done with the method:
29	29
30	30		``` Pascal
31	31		Edit1.AnchorToNeighbour(akLeft, 10, Label1);
32	32		```
33	33
34	34		### Notes
35	35
36	36		The Edit1.Left will follow Label1.Left+Label1.Width, not the other way around. That means, moving Label1 will move Edit1. But moving Edit1 will be undone by the [[LCL]]. If you also anchor the right side of Label1 to the left side of Edit1, you created a circle, and this can result together with some other autosize properties in a loop. This is ignored by the LCL or automagically repaired when the Parent.AutoSize is [[True\|true]].
37	37
38	38		### Via the Anchor Editor
39	39
40	40		The anchor editor is a floating window that is available via the menu View / Anchor Editor or via the button on the Anchors property in the object inspector.
41	41
42	42		![](/wiki-images/2/28/Anchor_Editor_en.png)
43	43
44	44		## Example 2
45	45
46	46		You can anchor the Edit's top side to follow the Label's top side:
47	47
48	48		+--------+ +-------+
49	49		\| Label1 \| \| Edit1 \|
50	50		+--------+ \| \|
51	51		+-------+
52	52
53	53		``` Pascal
54	54		Edit1.AnchorSide[akTop].Side := asrTop;
55	55		Edit1.AnchorSide[akTop].Control := Label1;
56	56		Edit1.Anchors := Edit1.Anchors + [akTop];
57	57		```
58	58
59	59		The same can be done with the method:
60	60
61	61		``` Pascal
62	62		Edit1.AnchorParallel(akTop,0,Label1);
63	63		```
64	64
65	65		## Example 3
66	66
67	67		Centering a Label vertically to an Edit:
68	68
69	69		+-------+
70	70		+--------+ \| \|
71	71		\| Label1 \| \| Edit1 \|
72	72		+--------+ \| \|
73	73		+-------+
74	74
75	75		``` Pascal
76	76		Edit1.AnchorSide[akTop].Side := asrCenter;
77	77		Edit1.AnchorSide[akTop].Control := Label1;
78	78		Edit1.Anchors := Edit1.Anchors + [akTop] - [akBottom];
79	79		```
80	80
81	81		The same can be done with the method:
82	82
83	83		``` Pascal
84	84		Edit1.AnchorVerticalCenterTo(Label1);
85	85		```
86	86
87	87		Obviously anchoring the bottom side of Edit1 does not make sense when centering.
88	88
89	89		## Example 4
90	90
91	91		Using a [[TSplitter]] with the AnchorEditor between two panels: the left panel should behave as if it had `Align=alLeft`, the right panel should behave as if it had `Align=alClient`.
92	92
93	93		- Do not use the `Align` properties of the panels and of the splitter. They must be set to `alNone`. This is important for the splitter for which the default value is `alLeft`.
94	94		- In the anchor editor do the following adjustments:
95	95		- Anchor the top and bottom sides of the panels and the splitter to the corresponding sides of the form.
96	96		- Select the first panel and anchor its left side to the left side of the form and its right side to the left side of the splitter.
97	97		- Select the second panel and anchor its right side to the right side of the form and its left side to the right side of the splitter.
98	98		- The left and right sides of the splitter must not be anchored (as seen from the splitter itself) because this would fix the position of the splitter and make it not movable.
99	99
100	100		The same effect can be achieved by this code:
101	101
102	102		``` pascal
103	103		procedure TForm1.FormCreate(Sender: TObject);
104	104		begin
105	105		with Panel1 do
106	106		begin
107	107		AnchorSideTop.Control := Self;
108	108		AnchorSideBottom.Control := Self;
109	109		AnchorSideBottom.Side := asrBottom;
110	110		AnchorSideLeft.Control := Self;
111	111		AnchorSideRight.Control := Splitter1;
112	112		Anchors := [akLeft, akRight, akTop, akBottom];
113	113		end;
114	114		with Panel2 do
115	115		begin
116	116		AnchorSideTop.Control := Self;
117	117		AnchorSideBottom.Control := Self;
118	118		AnchorSideBottom.Side := asrBottom;
119	119		AnchorSideLeft.Control := Splitter1;
120	120		AnchorSideLeft.Side := asrBottom;
121	121		AnchorSideRight.Control := self;
122	122		AnchorSideRight.Side := asrBottom;
123	123		Anchors := [akLeft, akRight, akTop, akBottom];
124	124		end;
125	125		with Splitter1 do
126	126		begin
127	127		AnchorSideTop.Control := Self;
128	128		Splitter1.AnchorSideBottom.Control := Self;
129	129		AnchorSideBottom.Side := asrBottom;
130	130		Anchors := [akTop, akBottom];
131	131		end;
132	132		end;
133	133		```
134	134
135	135		## New property
136	136
137	137		``` Pascal
138	138		property AnchorSide[Kind: TAnchorKind]: TAnchorSide read GetAnchorSide;
139	139		```
140	140
141	141		This is not published in the [[IDE Window: Object Inspector\|object inspector]]. You can edit it in the designer via the [[IDE Window: Anchor Editor\|anchor editor]] (Menu: View -\> View anchor editor, or click on button of 'Anchors' property).
142	142
143	143		## New methods to easily configure common layouts
144	144
145	145		``` Pascal
146	146		procedure AnchorToNeighbour(Side: TAnchorKind; Space: integer; Sibling: TControl);
147	147		procedure AnchorParallel(Side: TAnchorKind; Space: integer; Sibling: TControl);
148	148		procedure AnchorHorizontalCenterTo(Sibling: TControl);
149	149		procedure AnchorVerticalCenterTo(Sibling: TControl);
150	150		procedure AnchorAsAlign(TheAlign: TAlign; Space: Integer);
151	151		```
152	152
153	153		AnchorVerticalCenterTo works with Parent too. Then it will center on the client area, that means the center of the control is at ClientHeight div 2.
154	154
155	155		Center anchoring is not yet fully supported when computing the size of the parent. For example when you put a label center anchored into a [[TGroupBox\|Groupbox1]] and set Groupbox1.AutoSize to true then Groupbox1 height will shrink leaving no space for the label. The solution is to center to a control that is not centered. For example center a Label1 to a [[TComboBox\|ComboBox]] and use for the ComboBox the default anchors (Anchors=\[akLeft,akTop\]).
156	156
157	157		## Anchoring to invisible controls
158	158
159	159		Anchoring to invisible controls works intuitively. For example: The below controls A, B, C are anchored (C.Left to B.Right and B.Left to A.Right):
160	160
161		-	~~```~~
	161	+	```text
162	162		+---+ +---+ +---+
163	163		\| A \| \| B \| \| C \|
164	164		+---+ +---+ +---+
165	165		```
166	166
167	167		If B is hidden (Visible:=[[False\|false]]) then C.Left will skip B and use the right of A, resulting in
168	168
169		-	~~```~~
	169	+	```text
170	170		+---+ +---+
171	171		\| A \| \| C \|
172	172		+---+ +---+
173	173		```
174	174
175	175		## Circular references
176	176
177	177		You can build circular references by anchoring two sides to each other, which creates an impossible anchoring. The LCL notices that, but will not raise an exception, because it can be a temporary circle. For example: A row of buttons. Button1 is left of Button2, Button2 is left of Button3. Now the order is changed to: Button3, Button1, Button2. If the reanchoring is started with Button3, a circle is created temporarily and is fixed when the reordering is completed. The LCL detects circles and will not move the Button. Circles are not the only anomaly.
178	178
179	179		There is one exception to this rule. If the Parent.AutoSize is true, then the LCL will automatically break circles on autosize and writes a warning via [[DebugLn\|debugln]] (windows: --debug-log.txt, linux, et al: stdout). Which anchor is broken depends on the order of controls and the sides. So, temporary circles are still allowed with AutoSize=true if you enclose the change in
180	180
181	181		``` Pascal
182	182		Parent.DisableAutosizing;
183	183		try
184	184		// change anchors, aligns, bounds...
185	185		finally
186	186		Parent.EnableAutosizing;
187	187		end;
188	188		```
189	189
190	190		The AutoSize algorithm does not only break circles, but fixes Align/AnchorSide inconsistencies too.
191	191
192	192		Eventually it would be good to add some hints in the designer or a tool to list the circles and inconsistencies.
193	193
194	194		## See also
195	195
196	196		- [[Autosize / Layout]]
197	197		- [[Example: Anchors. How to reliably align dynamically created controls under changing visibility]]
198	198
199	199		---
200	200		From the Free Pascal wiki, page "Anchor Sides", as it stood on 2021-10-11 after a change by Kai Burghardt, 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