Anchor Docking Step by step example: what changed

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

Old	New		Line
1	1		# Anchor Docking : A step by step example
2	2
3	3		> Warning: THIS EXAMPLE DOES NOT WORK 100% as intended''' see Debugging for more info.
4	4
5	5		We have [[Anchor Docking\|anchor docking]] now... but I know that humans learn by doing, rather than reading... so, lets do it.
6	6
7	7		First, I'll be creating a new application from scratch, and then (hopefully) we can see if we can "convert" an existing application to it (one that worked on the old "Panel" align way).
8	8
9	9		For the first project, I'll be creating an application that should look like this:
10	10
11		-	~~` +-----------------------------+`\~~
12		-	~~` \| Main menu \|`\~~
13		-	~~` +-----------------------------+`\~~
14		-	~~` \| Toolbar (open, save etc.) \|`\~~
15		-	~~` +-----+-----------------------+`\~~
16		-	~~` \| __= \| \|`\~~
17		-	~~` \| \| \|`\~~
18		-	~~` \| T \| Main Application \|`\~~
19		-	~~` \| o \| \| `\~~
20		-	~~` \| o \| \|`\~~
21		-	~~` \| l +-----------------------+`\~~
22		-	~~` \| s \| Output Messages \|`\~~
23		-	~~` +-----+-----------------------+`~~
	11	+	```
	12	+	+-----------------------------+
	13	+	\| Main menu \|
	14	+	+-----------------------------+
	15	+	\| Toolbar (open, save etc.) \|
	16	+	+-----+-----------------------+
	17	+	\| __= \| \|
	18	+	\| \| \|
	19	+	\| T \| Main Application \|
	20	+	\| o \| \|
	21	+	\| o \| \|
	22	+	\| l +-----------------------+
	23	+	\| s \| Output Messages \|
	24	+	+-----+-----------------------+
	25	+	```
24	26
25	27		With the Toolbar, Tools (multiple pages), Output Messages parts all being "dockable". Because "drag" and "drop" isn't implemented yet, I'm not going to try to add functionality to move the parts around. (Compiling the example shows how this is possible)... This project will only be able to say "docked" or "not docked" per each of those parts. (This project would be able to be done with only panels.)
26	28
27	29		# Step 1: Create the main page
28	30
29	31		In essence, we'll just be creating a new form, adding a main menu to the form, and then adding the dockmanager to the form. I also add a stringgrid just to show what it will look like.
30	32
31	33		- Create a new project
32	34		- In Lazarus go to File -\> New ... -\> Select "Application"
33	35		- The first form (unit1.pas) will be the "Main Application" part.
34	36		- Drop a TMainMenu component onto the form
35	37		- Double click on the TMainMenu component, and create:
36	38		- Main - File
37	39		- FileSub - Exit
38	40		- Main - Windows
39	41		- WindowsSub - Dock/Undock Active Window (add a shortcut to F11 - so that we can have )
40	42		- WindowsSub - Save Window Positions
41	43		- Create an "OnCreate" event for the Form
42	44		- Select the form in the form designer
43	45		- In the object inspector, click the "events" tab, and double click the "OnCreate" event
44	46		- Create the docking manager
45	47		- Add this code to the OnCreate event: \`DockingManager:=TLazDockingManager.Create(Self);\`
46	48		- Add the dockmanager variable to the main form's class.
47	49		- Press Ctrl-Shift-Up (this will take you to the OnCreate event's definition in the form's class
48	50		- Add this code to the Form's public class definition : \`DockingManager : TLazDockingManager;\`
49	51		- Add the Docking unit and the XMLPropStorage to the uses section,
50	52		- Scroll up to the uses section
51	53		- Add \`, LDockCtrl, XMLPropStorage\` to the uses section
52	54		- Now we'll just add stuff to make it look like an application
53	55		- Add a StringGrid component
54	56		- Make Align = Client in the object inspector
55	57
56	58		# Step 2: Create our tool bar
57	59
58	60		I'm not going to pretend that I know how to create a proper toolbar... ala excel or even open office's stuff. So I'll just create a form with speed buttons that are all left aligned, and add some icons to it. Also add the dock control to it.
59	61
60	62		- Create a new form (File -\> New Form)
61	63		- Resize it to look "realistic" in size. Mine's height is 61.
62	64		- Add some load/save buttons to it (add some icons too, if you like) and Align = Left them. I added a Load and Save speedbuttons, got some glyphs from Lazarus/images/menu. In my other project I've added a new panel, and put in a combobox there. Do what you want!
63	65		- Add the control docker
64	66		- On the OnCreate event add:
65	67
66	68		``` pascal
67	69		ControlDocker1:=TLazControlDocker.Create(Self);
68	70		ControlDocker1.Name:='ToolbarForm';
69	71		ControlDocker1.Manager:=Form1.DockingManager;
70	72		```
71	73
72	74		- - Add the appropriate units to the uses part. (unit1, LDockCtrl)
73	75		- Add the variable to the Form's public class definition: ControlDocker1 : TLazControlDocker;
74	76
75	77		# Step 3: Our tools pages
76	78
77	79		We'll just create 2 different forms which are identifiably different from each other. And add the dock control to it. Do the following twice:
78	80
79	81		- Create a new form (File -\> New Form)
80	82		- Resize it to look "realistic" in size. (I just made it about 150 wide)
81	83		- Identify it. (I put a label on, saying tool window 1 and 2)
82	84		- Add the control docker
83	85		- On the OnCreate event add:
84	86
85	87		``` pascal
86	88
87	89		ControlDocker1:=TLazControlDocker.Create(Self);
88	90		ControlDocker1.Name:='Toolwindow1Form'; // (or 2 for the second one)
89	91		ControlDocker1.Manager:=Form1.DockingManager;
90	92		```
91	93
92	94		- - Add the appropriate units to the uses part. (unit1, LDockCtrl)
93	95		- Add the variable to the Form's public class definition: ControlDocker1 : TLazControlDocker;
94	96
95	97		# Step 4: Our Message window
96	98
97	99		Just our last form... The output form. Follow the same steps as before...
98	100
99	101		- Create a new form (File -\> New Form)
100	102		- Resize it to look "realistic" in size. (I just made it about 100 high, and quite wide)
101	103		- Add a memo component, and align = client
102	104		- Add the control docker
103	105		- On the OnCreate event add:
104	106
105	107		``` pascal
106	108		ControlDocker1:=TLazControlDocker.Create(Self);
107	109		ControlDocker1.Name:='OutputForm'; // (or 2 for the second one)
108	110		ControlDocker1.Manager:=Form1.DockingManager;
109	111		```
110	112
111	113		- - Add the appropriate units to the uses part. (unit1, LDockCtrl)
112	114		- Add the variable to the Form's public class definition: ControlDocker1 : TLazControlDocker;
113	115
114	116		# Step 5: Putting it all together
115	117
116	118		Now we'll just add everything together on the mainform... and see how it comes out.
117	119
118	120		- Add all the units to the uses section in your main unit. (unit2, unit3, unit4, unit5
119	121		- Next, we'll want to add it to the docking manager... but the problem is that the forms are not created yet at the "OnCreate" event for the main form. So, I'll move the "assigning" of the docking to the "OnActivate" event, and just set a flag that it's been done (so it doesn't do it again)
120	122		- So: Add an Initialized variable to form1's class: Initialized : boolean;
121	123		- At OnCreate we'll set it to "False", and then set it to true during the OnActivate Method.
122	124		- The current "OnActivate" method.
123	125
124	126		``` pascal
125	127		procedure TForm1.FormActivate(Sender: TObject);
126	128		begin
127	129		if initialized then exit;
128	130		Initialized := true;
129	131		// Sets the toolbaar to the top
130	132		DockingManager.Manager.InsertControl(Form2,alTop,Form1);
131	133
132	134		// Set the tool window to the left
133	135		DockingManager.Manager.InsertControl(Form3,alLeft,Form1);
134	136
135	137		// Set the second tool window IN the first
136	138		DockingManager.Manager.InsertControl(Form4,alClient,Form3);
137	139
138	140		// Set the second Message Control to the bottom
139	141		DockingManager.Manager.InsertControl(Form5,alBottom,Form1);
140	142		end;
141	143		```
142	144
143	145		# Debugging
144	146
145	147		This did not work 100% as expected.
146	148
147	149		Stuff that worked as expected:
148	150
149	151		1. The Toolbar looked correct and awesome
150	152		2. The Tool Windows' width was as expected
151	153
152	154		Stuff that didn't work as expected:
153	155
154	156		1. The Second tool window didn't work properly, there was a page control, but the second page wasn't assigned, and the first page had the SECOND tool window assigned
155	157		2. The Main Menu was missing
156	158		3. The Memo was gone... though Form5 was there (maybe not? the "title" didn't read "Form5")
157	159		4. Form5 took over all the space that was meant for the main application. Probably adding constraints to the main window would help.
158	160
159	161		---
160	162		From the Free Pascal wiki, page "Anchor Docking Step by step example", as it stood on 2019-12-30 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).
161	163		Category: Docking
162	164		Category: Lazarus
163	165		Category: Tutorials

Back to history