Anchor Docking Step by step example: what changed

Revision 2 to 3. 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		-	~~```~~
	11	+	```text
12	12		+-----------------------------+
13	13		\| Main menu \|
14	14		+-----------------------------+
15	15		\| Toolbar (open, save etc.) \|
16	16		+-----+-----------------------+
17	17		\| __= \| \|
18	18		\| \| \|
19	19		\| T \| Main Application \|
20	20		\| o \| \|
21	21		\| o \| \|
22	22		\| l +-----------------------+
23	23		\| s \| Output Messages \|
24	24		+-----+-----------------------+
25	25		```
26	26
27	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.)
28	28
29	29		# Step 1: Create the main page
30	30
31	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.
32	32
33	33		- Create a new project
34	34		- In Lazarus go to File -\> New ... -\> Select "Application"
35	35		- The first form (unit1.pas) will be the "Main Application" part.
36	36		- Drop a TMainMenu component onto the form
37	37		- Double click on the TMainMenu component, and create:
38	38		- Main - File
39	39		- FileSub - Exit
40	40		- Main - Windows
41	41		- WindowsSub - Dock/Undock Active Window (add a shortcut to F11 - so that we can have )
42	42		- WindowsSub - Save Window Positions
43	43		- Create an "OnCreate" event for the Form
44	44		- Select the form in the form designer
45	45		- In the object inspector, click the "events" tab, and double click the "OnCreate" event
46	46		- Create the docking manager
47	47		- Add this code to the OnCreate event: \`DockingManager:=TLazDockingManager.Create(Self);\`
48	48		- Add the dockmanager variable to the main form's class.
49	49		- Press Ctrl-Shift-Up (this will take you to the OnCreate event's definition in the form's class
50	50		- Add this code to the Form's public class definition : \`DockingManager : TLazDockingManager;\`
51	51		- Add the Docking unit and the XMLPropStorage to the uses section,
52	52		- Scroll up to the uses section
53	53		- Add \`, LDockCtrl, XMLPropStorage\` to the uses section
54	54		- Now we'll just add stuff to make it look like an application
55	55		- Add a StringGrid component
56	56		- Make Align = Client in the object inspector
57	57
58	58		# Step 2: Create our tool bar
59	59
60	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.
61	61
62	62		- Create a new form (File -\> New Form)
63	63		- Resize it to look "realistic" in size. Mine's height is 61.
64	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!
65	65		- Add the control docker
66	66		- On the OnCreate event add:
67	67
68	68		``` pascal
69	69		ControlDocker1:=TLazControlDocker.Create(Self);
70	70		ControlDocker1.Name:='ToolbarForm';
71	71		ControlDocker1.Manager:=Form1.DockingManager;
72	72		```
73	73
74	74		- - Add the appropriate units to the uses part. (unit1, LDockCtrl)
75	75		- Add the variable to the Form's public class definition: ControlDocker1 : TLazControlDocker;
76	76
77	77		# Step 3: Our tools pages
78	78
79	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:
80	80
81	81		- Create a new form (File -\> New Form)
82	82		- Resize it to look "realistic" in size. (I just made it about 150 wide)
83	83		- Identify it. (I put a label on, saying tool window 1 and 2)
84	84		- Add the control docker
85	85		- On the OnCreate event add:
86	86
87	87		``` pascal
88	88
89	89		ControlDocker1:=TLazControlDocker.Create(Self);
90	90		ControlDocker1.Name:='Toolwindow1Form'; // (or 2 for the second one)
91	91		ControlDocker1.Manager:=Form1.DockingManager;
92	92		```
93	93
94	94		- - Add the appropriate units to the uses part. (unit1, LDockCtrl)
95	95		- Add the variable to the Form's public class definition: ControlDocker1 : TLazControlDocker;
96	96
97	97		# Step 4: Our Message window
98	98
99	99		Just our last form... The output form. Follow the same steps as before...
100	100
101	101		- Create a new form (File -\> New Form)
102	102		- Resize it to look "realistic" in size. (I just made it about 100 high, and quite wide)
103	103		- Add a memo component, and align = client
104	104		- Add the control docker
105	105		- On the OnCreate event add:
106	106
107	107		``` pascal
108	108		ControlDocker1:=TLazControlDocker.Create(Self);
109	109		ControlDocker1.Name:='OutputForm'; // (or 2 for the second one)
110	110		ControlDocker1.Manager:=Form1.DockingManager;
111	111		```
112	112
113	113		- - Add the appropriate units to the uses part. (unit1, LDockCtrl)
114	114		- Add the variable to the Form's public class definition: ControlDocker1 : TLazControlDocker;
115	115
116	116		# Step 5: Putting it all together
117	117
118	118		Now we'll just add everything together on the mainform... and see how it comes out.
119	119
120	120		- Add all the units to the uses section in your main unit. (unit2, unit3, unit4, unit5
121	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)
122	122		- So: Add an Initialized variable to form1's class: Initialized : boolean;
123	123		- At OnCreate we'll set it to "False", and then set it to true during the OnActivate Method.
124	124		- The current "OnActivate" method.
125	125
126	126		``` pascal
127	127		procedure TForm1.FormActivate(Sender: TObject);
128	128		begin
129	129		if initialized then exit;
130	130		Initialized := true;
131	131		// Sets the toolbaar to the top
132	132		DockingManager.Manager.InsertControl(Form2,alTop,Form1);
133	133
134	134		// Set the tool window to the left
135	135		DockingManager.Manager.InsertControl(Form3,alLeft,Form1);
136	136
137	137		// Set the second tool window IN the first
138	138		DockingManager.Manager.InsertControl(Form4,alClient,Form3);
139	139
140	140		// Set the second Message Control to the bottom
141	141		DockingManager.Manager.InsertControl(Form5,alBottom,Form1);
142	142		end;
143	143		```
144	144
145	145		# Debugging
146	146
147	147		This did not work 100% as expected.
148	148
149	149		Stuff that worked as expected:
150	150
151	151		1. The Toolbar looked correct and awesome
152	152		2. The Tool Windows' width was as expected
153	153
154	154		Stuff that didn't work as expected:
155	155
156	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
157	157		2. The Main Menu was missing
158	158		3. The Memo was gone... though Form5 was there (maybe not? the "title" didn't read "Form5")
159	159		4. Form5 took over all the space that was meant for the main application. Probably adding constraints to the main window would help.
160	160
161	161		---
162	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).
163	163		Category: Docking
164	164		Category: Lazarus
165	165		Category: Tutorials

Back to history