Remember form position and size: what changed

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

Old	New		Line
1	1		# Using TForm.SessionProperties and TXMLPropStorage
2	2
3	3		In some applications, it is nice if the user modified settings for the position and size of the form are saved at program end and reused the next time the program starts. Lazarus has a fairly easy way to do this using [[TXMLPropStorage]] or [[TINIPropStorage]] available.
4	4
5	5		A simple example will illustrate these functions:
6	6
7	7		- create new application (main menu Project -\> New Project -\> Application)
8	8		- pass an TXMLPropStorage component on the form (find it on the Misc tab of the component palette)
9	9
10		-	~~<figure>~~
11		-	~~<img src="KomponentenpaletteTXMLPropStorage.png" title="KomponentenpaletteTXMLPropStorage.png" />~~
12		-	~~<figcaption>KomponentenpaletteTXMLPropStorage.png</figcaption>~~
13		-	~~</figure>~~
	10	+	![](/wiki-images/0/00/KomponentenpaletteTXMLPropStorage.png)
14	11
15	12		- in the Object Inspector: XMLPropStorage1 -\> FileName eg set "session.xml"
16	13		- in the Object Inspector: Form1 -\> Edit sessionProperties (the \[...\] button simply click)
17	14		- now select each of the Form1 properties Left, Top, Width, Height and add it
18	15		- confirm with OK and restart project
19	16		- change and move the form size
20	17		- end the program and restart it and it will return to the size and position it ended with last time.
21	18
22	19		Further information under [[TXMLPropStorage]]
23	20
24	21		# General method
25	22
26	23		## Simple example
27	24
28	25		A basic approach to keep form position and size between application restart is to store these state values to some persistent storage like XML file, INI file or Windows registry. You need at least store TForm properties Left, Top, Width and Height. But if form is maximized state you need also store values of TForm RestoredLeft, RestoredTop, RestoredWidth and RestoredHeight so form will be correctly sized if user click on maximize botton again to switch back to normal state.
29	26
30	27		For simplification TXMLConfig component is used as persistent storage. Place this component on your form and set its filename property to Config.xml.
31	28
32	29		``` pascal
33	30		procedure TForm1.StoreFormState;
34	31		begin
35	32		with XMLConfig1 do begin
36	33		SetValue('NormalLeft', Left);
37	34		SetValue('NormalTop', Top);
38	35		SetValue('NormalWidth', Width);
39	36		SetValue('NormalHeight', Height);
40	37
41	38		SetValue('RestoredLeft', RestoredLeft);
42	39		SetValue('RestoredTop', RestoredTop);
43	40		SetValue('RestoredWidth', RestoredWidth);
44	41		SetValue('RestoredHeight', RestoredHeight);
45	42
46	43		SetValue('WindowState', Integer(WindowState));
47	44		end;
48	45		end;
49	46		```
50	47
51	48		Restoration of stored form properties is a little bit complicated as properties have to be set in right order to prevent form resize animation or values to be overwritten by internal form mechanism. There is a rule that if normal and restored bounds are equal then form was in normal state. If normal and restored bounds are different then form is probably in maximized state and restored bounds are set to original position and size before maximization. As we have stored WindowState then we can use it to decide if form is in maximized state. To restore maximized state we have to first set form to normal state then set TForm.BoundsRect and after that set wsMaximized state. This is because Restored properties are read only and we can set them directly.
52	49
53	50		``` pascal
54	51		procedure TForm1.RestoreFormState;
55	52		var
56	53		LastWindowState: TWindowState;
57	54		begin
58	55		with XMLConfig1 do begin
59	56		LastWindowState := TWindowState(GetValue('WindowState', Integer(WindowState)));
60	57
61	58		if LastWindowState = wsMaximized then begin
62	59		WindowState := wsNormal;
63	60		BoundsRect := Bounds(
64	61		GetValue('RestoredLeft', RestoredLeft),
65	62		GetValue('RestoredTop', RestoredTop),
66	63		GetValue('RestoredWidth', RestoredWidth),
67	64		GetValue('RestoredHeight', RestoredHeight));
68	65		WindowState := wsMaximized;
69	66		end else begin
70	67		WindowState := wsNormal;
71	68		BoundsRect := Bounds(
72	69		GetValue('NormalLeft', Left),
73	70		GetValue('NormalTop', Top),
74	71		GetValue('NormalWidth', Width),
75	72		GetValue('NormalHeight', Height));
76	73		end;
77	74		end;
78	75		end;
79	76		```
80	77
81	78		Functions should be executed from OnShow and OnClose handlers.
82	79
83	80		``` pascal
84	81		procedure TForm1.FormClose(Sender: TObject; var CloseAction: TCloseAction);
85	82		begin
86	83		StoreFormState;
87	84		end;
88	85
89	86		procedure TForm1.FormShow(Sender: TObject);
90	87		begin
91	88		RestoreFormState;
92	89		end;
93	90		```
94	91
95	92		## Support for more forms
96	93
97	94		To support storing state for multiple forms we need to extend our functions to support Form parameter and allow store their values to different XMLConfig paths.
98	95
99	96		``` pascal
100	97		procedure TForm1.StoreFormState(Form: TForm);
101	98		begin
102	99		with XMLConfig1 do begin
103	100		SetValue('Forms/' + Form.Name + '/NormalLeft', Form.Left);
104	101		SetValue('Forms/' + Form.Name + '/NormalTop', Form.Top);
105	102		SetValue('Forms/' + Form.Name + '/NormalWidth', Form.Width);
106	103		SetValue('Forms/' + Form.Name + '/NormalHeight', Form.Height);
107	104
108	105		SetValue('Forms/' + Form.Name + '/RestoredLeft', Form.RestoredLeft);
109	106		SetValue('Forms/' + Form.Name + '/RestoredTop', Form.RestoredTop);
110	107		SetValue('Forms/' + Form.Name + '/RestoredWidth', Form.RestoredWidth);
111	108		SetValue('Forms/' + Form.Name + '/RestoredHeight', Form.RestoredHeight);
112	109
113	110		SetValue('Forms/' + Form.Name + '/WindowState', Integer(Form.WindowState));
114	111		end;
115	112		end;
116	113
117	114		procedure TForm1.RestoreFormState(Form: TForm);
118	115		var
119	116		LastWindowState: TWindowState;
120	117		begin
121	118		with XMLConfig1 do begin
122	119		LastWindowState := TWindowState(GetValue('Forms/' + Form.Name + '/WindowState', Integer(Form.WindowState)));
123	120
124	121		if LastWindowState = wsMaximized then begin
125	122		Form.WindowState := wsNormal;
126	123		Form.BoundsRect := Bounds(
127	124		GetValue('Forms/' + Form.Name + '/RestoredLeft', Form.RestoredLeft),
128	125		GetValue('Forms/' + Form.Name + '/RestoredTop', Form.RestoredTop),
129	126		GetValue('Forms/' + Form.Name + '/RestoredWidth', Form.RestoredWidth),
130	127		GetValue('Forms/' + Form.Name + '/RestoredHeight', Form.RestoredHeight));
131	128		Form.WindowState := wsMaximized;
132	129		end else begin
133	130		Form.WindowState := wsNormal;
134	131		Form.BoundsRect := Bounds(
135	132		GetValue('Forms/' + Form.Name + '/NormalLeft', Form.Left),
136	133		GetValue('Forms/' + Form.Name + '/NormalTop', Form.Top),
137	134		GetValue('Forms/' + Form.Name + '/NormalWidth', Form.Width),
138	135		GetValue('Forms/' + Form.Name + '/NormalHeight', Form.Height));
139	136		end;
140	137		end;
141	138		end;
142	139
143	140		procedure TForm1.FormClose(Sender: TObject; var CloseAction: TCloseAction);
144	141		begin
145	142		StoreFormState(Self);
146	143		end;
147	144
148	145		procedure TForm1.FormShow(Sender: TObject);
149	146		begin
150	147		RestoreFormState(Self);
151	148		end;
152	149		```
153	150
154	151		## Minimized and Fullscreen states
155	152
156	153		TForm.WindowState have two additional states wsMinimized and wsFullscreen. These special states need special care if they should be supported.
157	154
158	155		## Ensure that restored form is visible
159	156
160	157		As size of screen can change in time we need to check restored form position and size to ensure that form is visible to user and so your can manipulate with them.
161	158
162	159		``` pascal
163	160		function TForm1.CheckFormIsEntireVisible(Rect: TRect): TRect;
164	161		var
165	162		Width: Integer;
166	163		Height: Integer;
167	164		begin
168	165		Result := Rect;
169	166		Width := Rect.Right - Rect.Left;
170	167		Height := Rect.Bottom - Rect.Top;
171	168		if Result.Left < (Screen.DesktopLeft) then begin
172	169		Result.Left := Screen.DesktopLeft;
173	170		Result.Right := Screen.DesktopLeft + Width;
174	171		end;
175	172		if Result.Right > (Screen.DesktopLeft + Screen.DesktopWidth) then begin
176	173		Result.Left := Screen.DesktopLeft + Screen.DesktopWidth - Width;
177	174		Result.Right := Screen.DesktopLeft + Screen.DesktopWidth;
178	175		end;
179	176		if Result.Top < Screen.DesktopTop then begin
180	177		Result.Top := Screen.DesktopTop;
181	178		Result.Bottom := Screen.DesktopTop + Height;
182	179		end;
183	180		if Result.Bottom > (Screen.DesktopTop + Screen.DesktopHeight) then begin
184	181		Result.Top := Screen.DesktopTop + Screen.DesktopHeight - Height;
185	182		Result.Bottom := Screen.DesktopTop + Screen.DesktopHeight;
186	183		end;
187	184		end;
188	185		```
189	186
190	187		If requirement for entire form surface to be visible is too strong then we could check that at least part of form is visible. Here Part is size in pixels which should be at least visible for both horizontal and vertical position and size.
191	188
192	189		``` pascal
193	190		function TForm1.CheckFormIsPartialVisible(Rect: TRect; Part: Integer): TRect;
194	191		var
195	192		Width: Integer;
196	193		Height: Integer;
197	194		begin
198	195		Result := Rect;
199	196		Width := Rect.Right - Rect.Left;
200	197		Height := Rect.Bottom - Rect.Top;
201	198		if Result.Right < (Screen.DesktopLeft + Part) then begin
202	199		Result.Left := Screen.DesktopLeft + Part - Width;
203	200		Result.Right := Screen.DesktopLeft + Part;
204	201		end;
205	202		if Result.Left > (Screen.DesktopLeft + Screen.DesktopWidth - Part) then begin
206	203		Result.Left := Screen.DesktopLeft + Screen.DesktopWidth - Part;
207	204		Result.Right := Screen.DesktopLeft + Screen.DesktopWidth - Part + Width;
208	205		end;
209	206		if Result.Bottom < (Screen.DesktopTop + Part) then begin
210	207		Result.Top := Screen.DesktopTop + Part - Height;
211	208		Result.Bottom := Screen.DesktopTop + Part;
212	209		end;
213	210		if Result.Top > (Screen.DesktopTop + Screen.DesktopHeight - Part) then begin
214	211		Result.Top := Screen.DesktopTop + Screen.DesktopHeight - Part;
215	212		Result.Bottom := Screen.DesktopTop + Screen.DesktopHeight - Part + Height;
216	213		end;
217	214		end;
218	215		```
219	216
220	217		# See also
221	218
222	219		- [[Form Tutorial]]
223	220
224	221		---
225	222		From the Free Pascal wiki, page "Remember form position and size", as it stood on 2020-02-25 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).
226	223		Category: Lazarus
227	224		Category: Tutorials

Back to history