Anchor Docking: what changed

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

Old	New		Line
1	1		About docking in general see [[Docking]].
2	2
3	3		## Overview
4	4
5	5		Docking allows you to combine forms, or to treat controls as forms. You use the mouse to drag and dock forms together or undock (split) them. The basic dragging, docking and undocking functionality is provided by the LCL. But you need a docking manager to add splitters and grab zones, and to save and restore layouts.
6	6
7	7		Anchor docking has been implemented since version 0.9.29 in the package anchordocking.lpk for use in your own Lazarus applications, and AnchorDockingDsgn.lpk if you wish to make the Lazarus IDE windows dockable. It is easy to use, and provides many features and options not available in earlier docking packages.
8	8
9	9		You will find a code example at: components/anchordocking/miniide/miniide1.lpi
10	10
11	11		This means that the earlier TLazDockingManager and unit LDockCtrl are obsolete and now deprecated.
12	12
13	13		### Features
14	14
15	15		- Drag and dock: Headers are added that can be dragged to dock controls with the mouse. Preview rectangles will show where and how a control is docked.
16	16		- Any layout: By using the LCL's anchors almost any layout is possible. You can dock to left, right, top, bottom, inside or outside or as page like in a TPageControl. You can enlarge docked controls via the popup menu. No need to undock your whole layout.
17	17		- What you see is how it is structured: There are no hidden panels to align controls in rows and columns. Anchor docking makes sure forms do not overlap.
18	18		- Splitters are automatically inserted between docked forms to allow resizing.
19	19		- Page docking. Forms can be docked not only left/right/above/below, but in pages too. A TPageControl is automatically created for native look and feel. A page can contain arbitrary docked forms too, including paged docked forms, allowing nested pages and layouts. When a page is undocked the pagecontrol is automatically removed. You can drag and drop the tabs or use the popup menu to move pages.
20	20		- Easy use: With one line of code you can make a form or control dockable. Just give them unique names.
21	21		- Not only forms, but any TWinControl can be made dockable.
22	22		- Can save/load layouts. The layout information is stored for each dockable control and old layout files will still work even when the application gets more dockable controls or some are removed. The information is stored in the abstract class LCL TConfigStorage. So you can use for example TXMLConfigStorage to store layouts in xml files or you can write your own storage to store it wherever you want.
23	23		- Each docked form is put into a docksite providing an optional header. The header shows the caption of the docked form and contains a close button. You can drag the header to drag the form and undock it or to dock it at another position. The header can be at any of the four sides and moves by default automatically to the smaller side to save space. You can customize this. The header shows a customizable hint allowing to read long captions.
24	24		- When a docksite is resized the child sites are automatically scaled. You can turn this off.
25	25		- Preserve size of forms. For instance when docking a form to a left side of a site the width of the docked form is kept. The same for the other sides and the same for undocking.
26	26		- Flickerless: The restore tries to reuse existing sites and splitters to reduce creation and flickering of forms and to preserve the Z order of forms. This allows to quickly switch between layouts.
27	27		- Header popup menu:
28	28		- lock/unlock (disable dragging)
29	29		- header position (auto, left, top, right, bottom), this is saved/restored with the layout
30	30		- merge (for example after moving a dock page into a layout)
31	31		- undock (needed if no place to undock on screen)
32	32		- enlarge side to left, top, right, bottom
33	33		- close
34	34		- options
35	35		- Page popup menu:
36	36		- lock/unlock (disable dragging)
37	37		- undock (needed if no place to undock on screen)
38	38		- tab position for pagecontrol (top,bottom, left, right), this is saved/restored with the layout
39	39		- move page to the left, right, leftmost, rightmost
40	40		- close
41	41		- options
42	42		- Forms can be made dock sites. Then they can dock at one side. But they can not be docked itself.
43	43		- close button automatically saves a layout
44	44		- Powerful functions to alter the layout. You can use D&D to move a form and you can undock and dock in one move. There are functions to enlarge forms and shrinking others. These functions are available via the header popup menu as well. See below.
45	45		- There is an IDE package which makes the Lazarus IDE dockable. It is called anchordockingdsgn.lpk. Make sure you only install one docking package. Do not install the easydockmgr at the same time!
46	46
47	47		### ToDos
48	48
49	49		- Design time package: Add all layout files to menu
50	50		- simple way to make forms dockable at designtime (that means without writing any code)
51	51		- minimize button and Hide
52	52		- on show again: restore a default layout
53	53		- close button for pages
54	54		- Implement automatic menu merging in the LCL (when two forms with main menus are docked).
55	55
56	56		## Usage I. (Add docking support to the Lazarus IDE)
57	57
58	58		If you don't like the default "separate windows" look of the Lazarus IDE and prefer a single window (e.g., like RAD Studio™), you can install a package called [[AnchorDockingDsgn]] (lazarus/components/anchordocking/design/anchordockingdsgn.lpk). This package makes the IDE windows dockable.
59	59
60	60		### Important to macOS users
61	61
62	62		Before Lazarus 3.0, there are many bugs related to docking.
63	63
64	64		If "anchordockingdsgn" has been installed before Lazarus 3.0, the wrong configuration may be saved and needs to be reset first.
65	65
66	66		The configuration is saved in environmentoptions.xml, which usually located in ~/.lazarus
67	67
68	68		Close the IDE, locate environmentoptions.xml, delete the content between \<AnchorDocking\> and \</AnchorDocking\>, and the initial setting of anchordockingdsgn will be automatically set when the IDE is started again.
69	69
70	70		### Installation
71	71
72	72		Uninstall any other docking managers (e.g., easydockmgrdsgn). From the Lazarus menu bar pick "Package" - "Install/Uninstall Packages" and install the "anchordockingdsgn" package.
73	73
74	74		After you have successfully installed the package and restarted the IDE, the IDE starts with a default docked layout like shown below. Note that AnchorDocking headers and splitters have been added to all dockable windows of the IDE. In case the headers don't get visible, see the section "Options" below on how to enable/disable them.
75	75
76		-	~~<figure>~~
77	76		<img src="2021-12-02_10_21_07-Debian_10.8_Buster_-_VMware_Workstation.png" title="2021-12-02_10_21_07-Debian_10.8_Buster_-_VMware_Workstation.png" width="1333" />
78		-	~~<figcaption>2021-12-02_10_21_07-Debian_10.8_Buster_-_VMware_Workstation.png</figcaption>~~
79		-	~~</figure>~~
80	77
81	78		You can change the layout by grabbing a dockable window by the Anchordocking header and drag and dock it anywhere else, or resize docked windows via splitters added to the window borders. You can right-click on the headers too for other options, for example, to change the look of the headers, as shown farther down below.
82	79
83	80		You can save the layout via the menu item Tools / Save window layout as default. This saves to ~/.lazarus/anchordocklayout.xml and restores it when the IDE starts up.
84	81
85	82		You can also save the layout to a file and load them later.
86	83
87	84		Since Lazarus 1.1 you can pass a command line parameter
88	85
89	86		`./lazarus --anchordocklayout=<filename>`
90	87
91	88		The look (like the headers) can be further tweaked by right-clicking on them.
92	89
93		-	~~<figure>~~
94		-	~~<img src="docking_headers.gif" title="docking_headers.gif" />~~
95		-	~~<figcaption>docking_headers.gif</figcaption>~~
96		-	~~</figure>~~
	90	+	![](/wiki-images/8/8a/Docking_headers.gif)
97	91
98	92		### Options
99	93
100	94		After the successful installation of the AnchorDockingDsgn package, an additional configuration menu is added to the Lazarus options dialog ("Tools" - "Options" - "Environment")
101	95
102		-	~~<figure>~~
103		-	~~<img src="anchordocking_options.png" title="anchordocking_options.png" />~~
104		-	~~<figcaption>anchordocking_options.png</figcaption>~~
105		-	~~</figure>~~
	96	+	![](/wiki-images/3/3a/Anchordocking_options.png)
106	97
107	98		#### Scale on resize
108	99
109	100		When resizing a window, all docked forms inside are scaled by the same percentage.
110	101
111	102		#### Show headers
112	103
113	104		To dock/undock a window, you need to enable this option.
114	105
115	106		#### Flatten headers
116	107
117	108		No 3d frame in headers.
118	109
119	110		#### Header align top/left
120	111
121	112		Headers are automatically put at top or left depending on these two values:
122	113
123	114		- Move header to top, when (width/height)*100\<=HeaderAlignTop, default 80
124	115		- Move header to left, when (width/height)*100\>=HeaderAlignLeft, default 120
125	116		- Otherwise keep the header at the current position.
126	117
127	118		Which means the header is by default put at the smaller side of a docked control. When the control is resized, the header switches to the smaller side.
128	119
129	120		#### Allow dock sites to be minimized
130	121
131	122		A extra minimize button is added, so a site can be minimized. Then sites next to it get more space. If needed, the minimized site then can easy be opened.
132	123
133	124		#### Multine Tabs
134	125
135	126		Feature added in Lazarus 2.2. If a OS support multiline tabs (like Windows), if there are no many tabs, they are shown in multiple lines.
136	127
137	128		#### Floating windows on top
138	129
139	130		Feature added in Lazarus 2.2. If there are undocked windows shown, show these on top of main window. In a own application, there can be set DockMaster.MainDockForm, then all floating windows are shown on top of it. If MainDockForm is not set, Application.MainForm is used.
140	131
141	132		## Usage II. (Add docking support to your own applications)
142	133
143	134		### Quick start
144	135
145	136		Add the package AnchorDocking to the required packages in the project inspector.
146	137
147	138		Then add the unit AnchorDocking to the uses section of your main unit (the unit with your main form).
148	139
149	140		Add to the FormCreate of your main form:
150	141
151	142		``` pascal
152	143		DockMaster.MakeDockSite(Self,[akBottom],admrpChild);
153	144		```
154	145
155	146		For the other dockable forms replace all calls of Show and ShowOnTop with
156	147
157	148		``` pascal
158	149		DockMaster.MakeDockable(Form1,true,true);
159	150		```
160	151
161	152		For the other dockable forms replace all calls of Visible:=true with
162	153
163	154		``` pascal
164	155		DockMaster.MakeDockable(Form1,true);
165	156		```
166	157
167	158		Remove or comment all Hide, Visible:=false, WindowState:= calls.
168	159
169	160		### Prerequisites
170	161
171	162		- Your project must use the package AnchorDocking.
172	163		- All dockable forms must be shown with MakeDockable or MakeDockSite. Do not use Show, BringToFront, ShowOnTop, Visible:=true. Of course you can have some non dockable forms, like hints or splashscreens.
173	164		- All dockable forms must be free resizable, that means no constraints, no BorderStyle bsDialog.
174	165		- No other docking system. AnchorDocking is incompatible with EasyDockMgr.
175	166
176	167		### Making forms dockable
177	168
178	169		There are two ways to make a form dockable. You can use DockMaster.MakeDockable to wrap a form into a dock site. Then your form can dock and be docked completely free. You will use that for the biggest part of your forms, except for the MainForm, because this is only supported for the MainForm on gtk2 and qt. The second way is to use DockMaster.MakeDockSite. The form can dock other sites, but can not be docked itself. You might want to use MakeDockSite for the MainForm. For most other forms you probably want to use this:
179	170
180	171		``` pascal
181	172		// shows YourForm
182	173		// if not already done, wrap the form into a dock site
183	174		DockMaster.MakeDockable(YourForm);
184	175		```
185	176
186	177		Here are some examples how a form looks like that was made dockable with DockMaster.MakeDockable:
187	178
188	179		![](/wiki-images/b/bc/Docksite1.png) ![](/wiki-images/c/c6/Docksite2.png)
189	180
190	181		The header position is normally done automatically and the user can with a right click put it to any of the four sides.
191	182
192	183		### Example: miniide1
193	184
194	185		The example can be found in lazarus/components/anchordocking/miniide/miniide1.lpi. It has a mainform in unit unit1.pas with a main menu which works as a docksite and several forms that are dockable.
195	186
196		-	~~<figure>~~
197		-	~~<img src="Anchordocking_miniide1.png" title="Anchordocking_miniide1.png" />~~
198		-	~~<figcaption>Anchordocking_miniide1.png</figcaption>~~
199		-	~~</figure>~~
	187	+	![](/wiki-images/a/a5/Anchordocking_miniide1.png)
200	188
201	189		### Making the main form a dock site
202	190
203	191		In the TMainIDE.FormCreate the main form MainIDE is turned into a docksite:
204	192
205	193		``` pascal
206	194		DockMaster.MakeDockSite(Self,[akBottom],admrpChild);
207	195		```
208	196
209	197		The parameter \[akBottom\] allows to dock other sites at the bottom of MainIDE. The parameter admrpChild tells the DockMaster that when the MainIDE is enlarged the extra space is distributed to the docked sites.
210	198
211	199		When the user docks a site to the bottom of MainIDE the site is put onto MainIDE (Site.Parent:=MainIDE) with Site.Align=alBottom. The other controls on MainIDE must be compatible to this. MainIDE for example has a BtnPanel with Align=alLeft and a TNoteBook with Align=alClient. See [[Autosize / Layout\|here]] how Align works.
212	200
213	201		The DockMaster adds automatically a splitter:
214	202
215		-	~~<figure>~~
216		-	~~<img src="Anchordocking_miniide_dockedse1.png" title="Anchordocking_miniide_dockedse1.png" />~~
217		-	~~<figcaption>Anchordocking_miniide_dockedse1.png</figcaption>~~
218		-	~~</figure>~~
	203	+	![](/wiki-images/c/ca/Anchordocking_miniide_dockedse1.png)
219	204
220	205		As soon as a dockable form is docked its caption is shown in the dock header.
221	206
222	207		#### Requirements for a custom dock site
223	208
224	209		As long as nothing is docked into a custom dock site, your form can do everything as a normal form. But when a site is docked to it, some properties and methods need special care:
225	210
226	211		- AutoSize=true may result in an endless loop. Disable it or override DoAutoSize/CalculatePreferredSize and take special care.
227	212		- Constraints: The DockMaster clears the maximum Constraints and will restore them on undock.
228	213		- Child controls anchored to the aligned site may overlap. See [[Autosize / Layout\|here]] how Align works.
229	214		- ChildSizing: The spacing properties like LeftRightSpacing, TopBottomSpacing may interfere with the docking layout.
230	215
231	216		### Procedure to create all other forms by name
232	217
233	218		The MainIDE sets the DockMaster.OnCreateControl event, to enable the DockMaster to create forms by name. This is needed to restore layouts.
234	219
235	220		``` pascal
236	221		DockMaster.OnCreateControl:=@DockMasterCreateControl;
237	222		```
238	223
239	224		``` pascal
240	225		procedure TMainIDE.DockMasterCreateControl(Sender: TObject; aName: string; var
241	226		AControl: TControl; DoDisableAutoSizing: boolean);
242	227
243	228		procedure CreateForm(Caption: string; NewBounds: TRect);
244	229		begin
245	230		AControl:=CreateSimpleForm(aName,Caption,NewBounds,DoDisableAutoSizing);
246	231		end;
247	232
248	233		begin
249	234		// first check if the form already exists
250	235		// the LCL Screen has a list of all existing forms.
251	236		// Note: Remember that the LCL allows as form names only standard
252	237		// pascal identifiers and compares them case insensitive
253	238		AControl:=Screen.FindForm(aName);
254	239		if AControl<>nil then begin
255	240		// if it already exists, just disable autosizing if requested
256	241		if DoDisableAutoSizing then
257	242		AControl.DisableAutoSizing;
258	243		exit;
259	244		end;
260	245		// if the form does not yet exist, create it
261	246		if aName='CodeExplorer' then
262	247		CreateForm('Code Explorer',Bounds(700,230,100,250))
263	248		...
264	249		else if aName='DebugOutput' then
265	250		CreateForm('Debug Output',Bounds(400,400,350,150));
266	251		end;
267	252		```
268	253
269	254		Creating a form can be as simple as this:
270	255
271	256		``` pascal
272	257		MyForm:=TMyForm.Create(Self);
273	258		if DoDisableAutoSizing then
274	259		MyForm.DisableAutoSizing;
275	260		```
276	261
277	262		But of course you can put there all kind of initialization code.
278	263
279	264		The DisableAutoSizing reduces flickering. Make sure your forms Visible property is set to false.
280	265
281	266		Remember to call DisableAutoSizing for the form if the parameter DoDisableAutoSizing is set to true, because Disable- and EnableAutosizing calls must be balanced. If you miss the DisableAutosizing, the LCL will raise an exception later:
282	267
283	268		`TControl.EnableAutoSizing SourceEditor1:TSimpleForm: missing DisableAutoSizing`
284	269
285		-	~~<figure>~~
286		-	~~<img src="MissingDisableAutoSizing.png" title="MissingDisableAutoSizing.png" />~~
287		-	~~<figcaption>MissingDisableAutoSizing.png</figcaption>~~
288		-	~~</figure>~~
	270	+	![](/wiki-images/8/8e/MissingDisableAutoSizing.png)
289	271
290	272		If you call DisableAutoSizing too much, your forms will not appear and/or not resize properly as the LCL is waiting for the EnableAutoSizing call that never comes.
291	273
292	274		### Showing forms
293	275
294	276		When a form should be shown, you have probably used something like 'MyForm.Show. Instead you should now use
295	277
296	278		``` pascal
297	279		DockMaster.MakeDockable(MyForm);
298	280		```
299	281
300	282		This will wrap MyForm in a dock site and show it. It is clever enough to figure out if the form is already wrapped in a dock site.
301	283
302	284		If you set the DockMaster.OnCreateControl event you can use this:
303	285
304	286		``` pascal
305	287		DockMaster.ShowControl('MyForm',true);
306	288		```
307	289
308	290		### Docking manually, via code
309	291
310	292		Use the procedure DockMaster.ManualDock to dock a site to or into another.
311	293
312	294		``` pascal
313	295		procedure ManualDock(SrcSite, TargetSite: TAnchorDockHostSite; Align: TAlign; TargetControl: TControl = nil);
314	296		```
315	297
316	298		- SrcSite is the site to be docked. If SrcSite was docked it will be undocked first.
317	299		- TargetSite is the site where SrcSite will be docked into or docked as neighbor.
318	300		- TargetControl specifies if docking as neighbor (=nil), as inside neighbor (=TargetSide) or in front of a page (=a TAnchorDockPage).
319	301
320	302		### Undocking manually, via code
321	303
322	304		Use the procedure DockMaster.ManualFloat to undock a site from its neighbors and create a flotaing top level form. The embedded control stays embedded into a TAnchorDockHostSite.
323	305
324	306		``` pascal
325	307		procedure ManualFloat(AControl: TControl);
326	308		```
327	309
328	310		You can give as parameter a TAnchorDockHostSite or a control embedded into a TAnchorDockHostSite (for example a form made dockable with MakeDockable). The site will be put at the same screen location.
329	311
330	312		### Save layout
331	313
332	314		The DockMaster allows to save the current layout to a TConfigStorage. The miniide example uses the xml version:
333	315
334	316		``` pascal
335	317		procedure TMainIDE.SaveLayout(Filename: string);
336	318		var
337	319		XMLConfig: TXMLConfigStorage;
338	320		begin
339	321		try
340	322		// create a new xml config file
341	323		XMLConfig:=TXMLConfigStorage.Create(Filename,false);
342	324		try
343	325		// save the current layout of all forms
344	326		DockMaster.SaveLayoutToConfig(XMLConfig);
345	327		XMLConfig.WriteToDisk;
346	328		finally
347	329		XMLConfig.Free;
348	330		end;
349	331		except
350	332		on E: Exception do begin
351	333		MessageDlg('Error',
352	334		'Error saving layout to file '+Filename+':'#13+E.Message,mtError,
353	335		[mbCancel],0);
354	336		end;
355	337		end;
356	338		end;
357	339		```
358	340
359	341		### Load layout
360	342
361	343		``` pascal
362	344		procedure TMainIDE.LoadLayout(Filename: string);
363	345		var
364	346		XMLConfig: TXMLConfigStorage;
365	347		begin
366	348		try
367	349		// load the xml config file
368	350		XMLConfig:=TXMLConfigStorage.Create(Filename,True);
369	351		try
370	352		// restore the layout
371	353		// this will close unneeded forms and call OnCreateControl for all needed
372	354		DockMaster.LoadLayoutFromConfig(XMLConfig);
373	355		finally
374	356		XMLConfig.Free;
375	357		end;
376	358		except
377	359		on E: Exception do begin
378	360		MessageDlg('Error',
379	361		'Error loading layout from file '+Filename+':'#13+E.Message,mtError,
380	362		[mbCancel],0);
381	363		end;
382	364		end;
383	365		end;
384	366		```
385	367
386	368		### Enlarge/Shrink
387	369
388	370		The anchor docking manager can enlarge/shrink docked neighbors. This is done via the popup menu of the dock header or in code with the function DockMaster.ManualEnlarge:
389	371
390	372		``` pascal
391	373		function ManualEnlarge(Site: TAnchorDockHostSite; Side: TAnchorKind; OnlyCheckIfPossible: boolean): boolean;
392	374		```
393	375
394	376		Site is a child site, Side the side of Site to expand. If you only want to test if enlarge is possible set OnlyCheckIfPossible to true.
395	377
396	378		### Enlarge one, shrink another
397	379
398	380		Shrink neighbor Object Inspector, enlarge Messages: Right click on the header of Messages and click on Enlarge right side. Two splitters are resized.
399	381
400	382		![](/wiki-images/1/15/Anchordocking_before_enlarge1.png) enlarging Messages to the right side: ![](/wiki-images/f/f8/Anchordocking_after_enlarge1.png)
401	383
402	384		### Enlarge one, shrink many
403	385
404	386		Shrink splitter at one side, enlarge both neighbor splitters, rotate the splitter behind, enlarge Control, shrink controls at rotate splitter. Right click on header of Source Editor 1 then click on Enlarge bottom side.
405	387
406	388		![](/wiki-images/c/cb/Anchordocking_before_enlarge2.png) becomes ![](/wiki-images/4/42/Anchordocking_after_enlarge2.png)
407	389
408	390		### General docking options
409	391
410	392		The AnchorDocking package provides a dialog to setup some of the properties of the DockMaster. The dialog is in the unit AnchorDockOptionsDlg and you can use it simply:
411	393
412	394		``` pascal
413	395		uses ... AnchorDockOptionsDlg;
414	396		...
415	397		procedure TMainIDE.FormCreate(Sender: TObject);
416	398		...
417	399		begin
418	400		...
419	401		DockMaster.OnShowOptions:=@ShowAnchorDockOptions;
420	402		...
421	403		end;
422	404		```
423	405
424	406		This will add a new menu item to the popup menus of the dock headers and pages called Docking options.
425	407
426	408		## Why use Anchors instead of Align?
427	409
428	410		Anchors allow to create any possible rectangular layout. Align is limited. Align with Panels can theoretically create a lot of layouts, but still not all. And some operations like enlarge/shrink are more complicated using Align/Panels than using Anchors. Align works good for a few forms, but the more forms are docked, the more the disadvantages of Align become visible.
429	411
430	412		### Layouts that can be created with Align
431	413
432	414		Align can only create the following layouts:
433	415
434		-	~~<figure>~~
435		-	~~<img src="Anchordocking_align_layout1.png" title="Anchordocking_align_layout1.png" />~~
436		-	~~<figcaption>Anchordocking_align_layout1.png</figcaption>~~
437		-	~~</figure>~~
	416	+	![](/wiki-images/1/13/Anchordocking_align_layout1.png)
438	417
439	418		The alTop controls are always at the top, filling the whole horizontal width. That's because the LCL first aligns all controls with alTop, then all alBottom, then alLeft, then alRight and finally alClient.
440	419
441	420		### Layouts that can be created with Align and Panels
442	421
443	422		It is possible to nest Align layouts by using hidden panels. Then any layout that can be recursively splitted in halves can be created. Then you can create for example:
444	423
445		-	~~<figure>~~
446		-	~~<img src="Anchordocking_align_panels_layout1.png" title="Anchordocking_align_panels_layout1.png" />~~
447		-	~~<figcaption>Anchordocking_align_panels_layout1.png</figcaption>~~
448		-	~~</figure>~~
	424	+	![](/wiki-images/0/0e/Anchordocking_align_panels_layout1.png)
449	425
450	426		This requires only one hidden panel.
451	427
452	428		### Changing Layouts
453	429
454	430		Now the user wants to enlarge the FPDocEditor horizontally (and shrink CodeExplorer). With the AnchorDocking you can simply right click on the FPDocEditor header and click Enlarge right side.
455	431
456		-	~~<figure>~~
457		-	~~<img src="Anchordocking_align_panels_layout2.png" title="Anchordocking_align_panels_layout2.png" />~~
458		-	~~<figcaption>Anchordocking_align_panels_layout2.png</figcaption>~~
459		-	~~</figure>~~
	432	+	![](/wiki-images/8/88/Anchordocking_align_panels_layout2.png)
460	433
461	434		Other docking engines need at least 2 panels. One for SrcEditor,Messages,FPDocEdit,CodeExpl and one for SrcEdit and Messages. Most docking layouters do not even provide a simple way to change the layout in this way. An algorithm to allow this layout change, must analyze the whole structure as if there were no panels and must reparent a lot of things. Basically the algorithm must do the same as the anchor docking algorithm, but with the extra work of translating the layout into Align plus hidden panels.
462	435
463	436		### Layouts that are impossible with Align and Panels
464	437
465	438		Now the user wants to enlarge SourceEditor1 horizontally (and shrink ObjectInspector):
466	439
467		-	~~<figure>~~
468		-	~~<img src="Anchordocking_impossible_with_align_panels1.png" title="Anchordocking_impossible_with_align_panels1.png" />~~
469		-	~~<figcaption>Anchordocking_impossible_with_align_panels1.png</figcaption>~~
470		-	~~</figure>~~
	440	+	![](/wiki-images/e/e9/Anchordocking_impossible_with_align_panels1.png)
471	441
472	442		This layout is impossible with Align and panels, because you can not cut it in two halves. The same with
473	443
474		-	~~<figure>~~
475		-	~~<img src="Anchordocking_impossible_with_align_panels2.png" title="Anchordocking_impossible_with_align_panels2.png" />~~
476		-	~~<figcaption>Anchordocking_impossible_with_align_panels2.png</figcaption>~~
477		-	~~</figure>~~
	444	+	![](/wiki-images/1/1e/Anchordocking_impossible_with_align_panels2.png)
478	445
479	446		### Conclusion
480	447
481	448		Align with hidden panels allows you to easily create a simple docking manager that works well for a few forms, but it will always limit the user. Align is useful for row and column layouts, not for tables. Anchor docking works even for complex forms.
482	449
483	450		## Old/deprecated anchor docking
484	451
485	452		### Create a TLazDockingManager
486	453
487	454		``` pascal
488	455		DockingManager:=TLazDockingManager.Create(Self);
489	456		```
490	457
491	458		The Self as parameter is only used as Owner. That means, when the mainform is freed, the DockingManager is freed too. You can use nil and free the DockingManager yourself.
492	459
493	460		### Optional: Loading a configuration
494	461
495	462		You can load the user configuration from disk.
496	463
497	464		``` pascal
498	465		Config:=TXMLConfigStorage.Create('config.xml',true);
499	466		DockingManager.LoadFromConfig(Config);
500	467		Config.Free;
501	468		```
502	469
503	470		This loads the file config.xml. The config can be created by the SaveToConfig function. See below.
504	471
505	472		### Make a form/control dockable
506	473
507	474		Create a TLazControlDocker for each form/control that should be dockable
508	475
509	476		``` pascal
510	477		ControlDocker1:=TLazControlDocker.Create(Self);
511	478		ControlDocker1.Name:='DockerForm1';
512	479		ControlDocker1.Manager:=DockingManager;
513	480		```
514	481
515	482		### Optional: Saving the user configuration to disk
516	483
517	484		When the program is closed you can save the user configuration to disk
518	485
519	486		``` pascal
520	487		Config:=TXMLConfigStorage.Create('config.xml',true);
521	488		DockingManager.SaveToConfig(Config);
522	489		Config.WriteToDisk;
523	490		Config.Free;
524	491		```
525	492
526	493		## See also
527	494
528	495		- [[AnchorDockingDsgn]] AnchorDocking in the Lazarus IDE
529	496		- [[Anchor Docking Step by step example\|Anchor Docking: A Step by step example]]
530	497		- [[Docking]] in general
531	498		- [[EasyDockingManager]] - an alternative docking implementation with a simpler layout engine and fewer options.
532	499
533	500		---
534	501		From the Free Pascal wiki, page "Anchor Docking", as it stood on 2024-01-27 after a change by Rich2014, 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).
535	502		Category: Docking
536	503		Category: Lazarus IDE plugins

Back to history