Reference: MSEgui: what changed

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

Old	New		Line
1	1		## Widgets
2	2
3	3		### TSimpleWidget
4	4
5	5		see also [[Reference: MSEgui/TSimpleWidget]]
6	6
7	7		### TMainMenuWidget
8	8
9	9		### TSimpleWidget
10	10
11	11		### TMseFormWidget
12	12
13	13		Use it in order to insert a tcustomform descendant into another widget at designtime. Does not try to load resources in "create".
14	14
15	15		tmseform descendants ( MainForm, SimpleForm,.. )
16	16
17	17		Client area of the form & parent of its widgets ( against which the widgets
18	18		are placed and colored ) is presented by the "container" property
19	19		not "container.frame.clientarea"
20	20
21	21		CanClose is called :
22	22
23	23		- on receiving "ek_close" by window
24	24		- for modal window, on focus change
25	25
26	26		- within parent window's "CanClose" where all nested windows are
27	27		checked for OnCloseQuery & OnClose - if any sets "mr_none" then the parent window
28	28		can't close as well
29	29
30	30		- from nested window's "CanParentClose"
31	31		- from own "CanParentClose"
32	32
33	33		- some componnets build oneself in own "Loaded" procedure :
34	34		= widget grids
35	35		= database access components
36	36		= ...
37	37
38	38		The "form.show" has parameter "transientfor".
39	39		The window Z-order is above the "transientfor" window. The exact behaviour
40	40		depends on the window manager.
41	41
42	42		caption
43	43		- run-time caption on the title bar
44	44
45	45		color
46	46		- color behind the client ( contaner ) area
47	47
48	48		container
49	49		- the real parent of form's widgets, <see "tformscrollbox">
50	50
51	51		cursor
52	52		- the mouse over cursor shape
53	53
54	54		enabled - "false" disables all child widgets
55	55
56	56		face
57	57		<see "tfacecomp"> + some more options
58	58
59	59		font
60	60		<see "tfont">
61	61
62	62		frame
63	63		<see "tframecomp"> + some more options
64	64
65	65		icon
66	66		<see "timage">
67	67
68	68		mainmenu
69	69		<see tmainmenu>
70	70
71	71		name
72	72		- name to refer when programming
73	73
74	74		options:
75	75
76	76		fo_main
77	77		- assigns this from as the aplication GUI-face & event receiver
78	78		- causes the icon of this form to be icon of the application
79	79
80	80		fo_terminateonclose
81	81		- causes the application to terminate once the form has closed ( doesn't depend on "fo_main" )
82	82
83	83		fo_freeonclose
84	84		- causes the form (even being modal) to release its memory on closure or OK-return from "CanClose"
85	85
86	86		fo_defaultpos
87	87		- lets the WM to position the form initially
88	88
89	89		fo_screencentered
90	90		- causes the form initially to show in center of the apllication work area
91	91
92	92		fo_closeonesc
93	93		- causes the form to close on "Esc" key pressed ( with MR_ESCAPE & "OnCloseQuery" firing )
94	94
95	95		fo_cancelonesc
96	96		- causes the form to close on "Esc" key pressed ( with MR_CANCEL & "OnCloseQuery" firing )
97	97
98	98		fo_closeonenter
99	99		- causes the form to close on "Enter" key pressed ( with MR_OK & "OnCloseQuery" firing )
100	100
101	101		fo_closeonf10
102	102		- causes the form to close on "F10" key pressed ( with MR_F10 & "OnCloseQuery" firing )
103	103
104	104		fo_globalshortcuts
105	105		- allows on-this-form "ao_globalshortcut" actions to trigger
106	106
107	107		Notes :
108	108		= shortcuts for modal not "fo_localshortcut" forms are processed by app
109	109		= shortcuts for "fo_globalshorcut" forms are processed by the owning window
110	110
111	111		fo_localshortcuts
112	112		- disables triggering shortcuts of on-this-form actions
113	113
114	114		fo_autoreadstat
115	115		- for "cs_ismodule" forms, before "OnLoaded" fires, rereads all statvars from the bound stafile/memorystream
116	116
117	117		fo_autowritestat
118	118		- in "CanClose", after "OnClose" fires [ and before app termination for "fo_terminateonlose" form ],
119	119		rewrites all statvars to the stafile/memorystream
120	120		- for datamodules, does this before "OnDestroy" fires
121	121
122	122		fo_savepos
123	123		- saves/restores Z-order, size & scree coordinates of the form
124	124		as soon as the stat data are ready
125	125
126	126		fo_savestate
127	127		- for top-level form, saves/restores "VSize", "Active" & "Visible"
128	128		as soon as the stat data are ready
129	129
130	130		optionswidget
131	131		<see "any widget">
132	132		optionswindow
133	133		<see "any window">
134	134		popupmenu
135	135		<see "tpopupmenu">
136	136		stafile
137	137		<see "tstafile">
138	138		stavarname
139	139		taborder
140	140		tag
141	141
142	142		visible - for a form, only affects its childs widgets
143	143
144	144		Events:
145	145
146	146		activate = to set focused & redraw the invalidated area
147	147
148	148		oncreate
149	149		- fires before "Loaded" procedure is called
150	150		- fires after creating the widget & its subwidgets but before the final arrangement
151	151		- forms arent' yet visible on return
152	152
153	153		Since "Loaded" procedure hasn't yet worked at this point then
154	154		database contents, values of widget grid's subwidgets
155	155		are invalid in this event ***
156	156
157	157		onloaded
158	158		- fires once "Loaded" procedure of owns & all form's widgets finishes
159	159		- processed after "OnCreate"
160	160		- on finishing, forms aren't yet visible
161	161
162	162		oneventloopstart ( main forms only )
163	163		- only applicable to main forms
164	164		- fires once all application GUI is built and shown
165	165		( and ready to user's interaction )
166	166
167	167		onactivate
168	168		- see {any_widget.OnActivate}
169	169
170	170		onenter
171	171		= see {any_widget.OnEnter}
172	172
173	173		onfocus
174	174		- see {any_widget.OnFocus}
175	175
176	176
177	177		onwindowactivechanged
178	178		- fires on :
179	179		= touching another window even on clicking in a behind-modal window ( or its title bar )
180	180		= 1-st showing the window
181	181		- reactivating the window
182	182
183	183		onbeforepaint
184	184		- fires at the very beginning of "paint", before drawing canvas
185	185
186	186		onpaint
187	187		- fires in "paint" procedure, between drawing canvas and contained widgets
188	188
189	189		onafterpaint (doafterpaint)
190	190		- fires just on return from "paint" procedure
191	191
192	192		onapplicationactivechanged
193	193		- fires :
194	194		= if the application gets/looses input focus
195	195
196	196		onasyncevent (doasyncevent)
197	197		- fires on calling {this_form}.asyncevent(atag) from any place of the application
198	198		once delivered by the app even queue
199	199
200	200		"atag" set by caller(s) helps to branch within "onasyncevent", to identify the caller, etc ***
201	201		generally, doesn't fire instantly because these events are delivered through the app event queue ***
202	202
203	203		onchildmouseevent
204	204		- fires on any mouse activity over its child widget(s) not the (containing) widget oneself
205	205
206	206		for forms, it even fires on enetering "container" therefore it appears as if to be the form itself ***
207	207
208	208		onchildscaled
209	209		- see {any_widget.OnChildScaled}
210	210
211	211		onclientmouseevent
212	212		- fires on any mouse activity over areas expecting user's mouse input (not titlebars/frames/...)
213	213
214	214		onclose
215	215		- fires in "CanClose" if "modalresult <> mr_none"
216	216
217	217		onclosequery
218	218		- fires in "CanClose" before "OnClose"
219	219		- "mr_none" set on return prevents the window (and its parent) from closing
220	220		( "OnClose" is also bypassed )
221	221
222	222		ondeactivate
223	223		- see {any_widget.OnDeactivate}
224	224
225	225		ondefocus
226	226		- see {any_widget.OnDeFocus}
227	227
228	228		ondestroy
229	229		- fires on in-code calling "BeforeDestruction"
230	230
231	231		ondestroyed
232	232		- fires on return from the form's destructor ( when all resources are freed )
233	233
234	234		onterminatequery
235	235		- fires on an attempt to terminate the app
236	236		- by setting "var terminate:= false", allows to cancel termination
237	237
238	238		Termination by debugger/OS facilities can't be blocked this way ( win32 )***
239	239
240	240		onterminated
241	241		- fires for not-yet-destroyed forms, once the app event loop finishes
242	242		- may be caused by any closure of the main app form
243	243		( app termination, WM/OS facilities, )
244	244
245	245		onwindowdestroyed
246	246		- fires once a descendant window is destroyed
247	247		( for a main form, when a modal simple form is closed by any way,.. )
248	248
249	249		onevent
250	250		- fires on receiving an event
251	251		= for simple forms, it's only "ek_loaded"
252	252
253	253		There can be more if the form is connected to object_event sending
254	254		components or if the application uses object events, for example by calling
255	255		tguicomponent.postcomponentevent. ****
256	256
257	257		onexit
258	258		- see {any_widget.OnExit}
259	259
260	260		onfocusedwidgetchanged
261	261		- for a "prev-new" parent-wide focused wigdets pair, fires once installing new focus has finished,
262	262		after "OnFocus"
263	263		- resends for all contained widgets
264	264		- doesn't fire if the "prev-new" pair don't really change
265	265
266	266		onfontheightdelta
267	267		- see {any_widget.OnFontHeightDelta}
268	268
269	269		onhide
270	270		- fires at beginnig of own/parent's
271	271		= hide
272	272		= hidden
273	273		= destroying
274	274		= setting "visible:= false"
275	275		= closing the window ( receiving event "ek_close",.. )
276	276		= calling "window.close"
277	277
278	278		onidle
279	279		- fires everytime when the app GUI event queue gets empty
280	280		- to stop calling for a while, set "again" parameter to "false" (the initial value );
281	281
282	282		DON'T DO ANYTHING AFFECTING THE APP EVENT QUEUE ( MODAL WINDOWS, "ShowMessage", Sleep(N),... ) IN THIS HANDLER.
283	283		MODAL WINDOWS CAUSE RECURSION !
284	284
285	285		A code fragment:
286	286
287	287		again:= i < 5;
288	288		if not again then exit;
289	289
290	290		onkeydown
291	291		- fires on pressing down a keyboard key over the client area when none of child widgets is focused
292	292
293	293		onkeyup
294	294		- fires on releasing a keyboard key over the client area when none of child widgets is focused
295	295
296	296		onmouseevent
297	297		- fires on any mouse activity over the client area
298	298
299	299		onmove
300	300		- see {any_window.OnMove}
301	301
302	302		onpopup
303	303		- see {any_widget.OnPopup}
304	304
305	305		onresize
306	306		- see {any_widget.OnResize}
307	307
308	308		onshortcut
309	309		- fires before built-in shorcut processing
310	310		- "info.eventstate=es_processed" set in "OnShortcut" prevents
311	311		the event from further auto-processing
312	312
313	313		The app
314	314		- recognizes & takes registered shortcuts from app event queue
315	315		- passes the shocrcut event to each of its windows until the event
316	316		is processed otherwise processes it by oneself
317	317
318	318
319	319		onshow
320	320		- fires if the widget is visible:
321	321		= on calling "Show" method
322	322		= on return from "Loaded" procedure
323	323		= on showing the parent widget
324	324		- since called at end, allows to adjust the default behavior
325	325
326	326		onshowhint
327	327		- see {any_widget.OnShowHint}
328	328
329	329		onstatbeforeread
330	330		- fires before loading statvars from the disk file
331	331
332	332		onstatafterread
333	333		- fires once statvars are loaded from the disk file
334	334
335	335		onstatupdate
336	336		- fires at 1-st stage before updating GUI "state/pos" for read statvars
337	337		or
338	338		- fires at pre-last stage before saving GUI "state/pos"
339	339
340	340		onstatread
341	341		- fires at 2-nd stage before updating GUI "state/pos" for read statvars
342	342
343	343		onstatwrite
344	344		- fires at last stage before saving GUI "state/pos"
345	345
346	346		pon stat reading, non-minimized visible windows are shown,
347	347		the active window is activated
348	348
349	349		### TDockFormWidget
350	350
351	351		### TPaintbox
352	352
353	353		How to draw line (or circle) on tpaintbox? In event onpaint:
354	354
355	355		``` pascal
356	356
357	357		procedure tmainfo.paintboxonpaint(const sender: twidget; const canvas: tcanvas);
358	358		begin
359	359		with sender,canvas do begin
360	360		drawline(nullpoint,pointty(size),cl_yellow);
361	361		//diagonal line across widget
362	362		drawellipse(makerect(makepoint(bounds_cx div 2,bounds_cy div 2), size),cl_red);
363	363		//circle (or ellipse) centered in widget
364	364		end;
365	365		end;
366	366		```
367	367
368	368		Makepoint and makerect are in msegraphutils.
369	369
370	370		### TEventWidget
371	371
372	372		A widget which publishes all possible events of a twidget. Normally it is better to implement your own specialized descendant of an existing widget instead to use teventwidget.
373	373
374	374		### TButton
375	375
376	376		- A rectangular clickable area that can show text/bitmap.
377	377
378	378		\- Main properties:
379	379
380		-	~~`Caption: read/write the text that appear on top of it.`\~~
381		-	~~`onexecute: read/write the address of a procedure (event handler) to be executed when clicked.`~~
	380	+	``` pascal
	381	+	Caption: read/write the text that appear on top of it.
	382	+	onexecute: read/write the address of a procedure (event handler) to be executed when clicked.
	383	+	```
382	384
383	385		### TStockGlyphButton
384	386
385	387		### TRichButton
386	388
387	389		### TLabel
388	390
389	391		- Draws a piece of text on the given surface (canvas: screen/printer/bitmap).
390	392
391	393		\- Main properties:
392	394
393		-	~~`Caption: read/write the piece of text.`~~
	395	+	```text
	396	+	Caption: read/write the piece of text.
	397	+	```
394	398
395	399		See also [[Reference: MSEgui/TLabel\|TLabel]]
396	400
397	401		### TGroupBox
398	402
399	403		### TStepBox
400	404
401	405		### TStringDisp
402	406
403	407		- A read only version of TStringEdit, difference from TLabel: has a frame around it.
404	408
405	409		-Main properties:
406	410
407		-	~~`Value: read/write the text that are showed.`\~~
408		-	~~`Caption: A label normally describing the purpose or meaning of the presented text, it can be positioned around the frame.`~~
	411	+	```text
	412	+	Value: read/write the text that are showed.
	413	+	Caption: A label normally describing the purpose or meaning of the presented text, it can be positioned around the frame.
	414	+	```
409	415
410	416		### TByteStringDisp
411	417
412	418		### TIntegerDisp
413	419
414	420		### TRealDisp
415	421
416	422		### TDateTimeDisp
417	423
418	424		### TBooleanDisp
419	425
420	426		### TToolBar
421	427
422	428		### TDrawGrid
423	429
424	430		### TStringGrid
425	431
426	432		### TTabBar
427	433
428	434		### TTabPage
429	435
430	436		### TTabWidget
431	437
432	438		### TDockHandle
433	439
434	440		### TDockPanel
435	441
436	442		### TSpliter
437	443
438	444		A widget very similar to "tspacer" but :
439	445		- designed to rearrange areas occupied by adjacent widgets
440	446		- a linked widget may only enlarge by "eating" the opposite one,
441	447		so the summary area of both widgets don't change
442	448		- has GUI look ( hatched grip, color etc) switched on by default
443	449		- facilitates run-time repositioning oneself and linked widgets
444	450		- linked widgets may even be other splitters, spacers (with their linked widgets ),..
445	451
446	452		Properties:
447	453
448	454		- color
449	455		= see {any_widget.color}
450	456
451	457		- cursor
452	458		= see {any_widget.cursor}
453	459
454	460		- enabled
455	461		= "false" stops user interaction
456	462
457	463		- face
458	464		= see {any_face}
459	465
460	466		- frame
461	467		= see {any_frame}
462	468
463	469		- colorgrip
464	470		= color of grip hatching
465	471
466	472		- grip
467	473		= defines hatching pattern of the grip
468	474
469	475		* stb_dens(N) : the pattern is of rhombuses, the painted rhombs occupy "N" persents of the grip
470	476
471	477		* stb_block(N) : the pattern is of squares, painted & unpainted squares are equally sized and
472	478		both have "N" pixels sides
473	479
474	480		* stb_hatchup(N) : the pattern is of right-tilted lines of 1 pixel width,
475	481		each "N"-th pixel forms these lines
476	482
477	483		* stb_hatchdown(N) : the pattern is of left-tilted lines of 1 pixel width,
478	484		each "N"-th pixel forms these lines
479	485
480	486		* stb_crosshatch(N) : the pattern is of crossing (left & right) tilted lines of 1 pixel width,
481	487		each "N"-th pixel forms these lines
482	488
483	489		- linkbottom/linkleft/linkright/linktop
484	490		= see {tspacer.*}
485	491
486	492		- options
487	493
488	494		= spo_hmove
489	495		* "true" allows the spliter to move horizontally
490	496
491	497		= spo_hprop
492	498		* "true" : keep the left position proportional ( on the ratio of creation time )
493	499		to weigth of the client area of parent
494	500
495	501		= spo_hsizeprop
496	502		* "true" : keep width of the spacer proportional ( on the ratio of creation time )
497	503		to weigth of the client area of parent
498	504		* the width stops shrinking on one set in design time
499	505
500	506		= spo_vmove
501	507		* "true" allows the spliter to move vertically
502	508
503	509		= spo_vprop
504	510		* "true" : keep the top position proportional ( on the ratio of creation time )
505	511		to height of the client area of parent
506	512
507	513		= spo_vsizeprop
508	514		* "true" : keep height of the spacer proportional ( on the ratio of creation time )
509	515		to height of the client area of parent
510	516		* the height stops shrinking on one set in design time
511	517
512	518		= spo_dockleft
513	519		* causes the "linkleft" widget to dock to the left border of splitter
514	520		* make sence only if linkleft "widget.bounds_x" less than "splitter.bounds_x"
515	521
516	522		= spo_docktop
517	523		* causes the "linktop" widget to dock to the top border of splitter
518	524		* make sence only if linktop "widget.bounds_y" less than "splitter.bounds_y"
519	525
520	526		= spo_dockright
521	527		* causes the "linkright" widget to dock to the right border of splitter
522	528		* make sence only if linkright "widget.(bounds_x+bounds_cx)" more than "splitter.(bounds_x+bounds_cx)"
523	529
524	530		= spo_dockbottom
525	531		* causes the "linkbottom" widget to dock to the bottom border of splitter
526	532		* make sence only if linkbottom "widget.(bounds_y+bounds_cy)" more than "splitter.(bounds_y+bounds_cy)"
527	533
528	534		!!! Two special cases :
529	535
530	536		1. (spo_dockleft = spo_dockright = TRUE) && (linkleft = linkright = the_same_widget) :
531	537		causes the "linkleft" widget to adjust to h-positiion & width of the splitter,
532	538		it's even possible that the widget doesn't touch the splitter
533	539
534	540		(spo_docktop = spo_dockbottom = TRUE) && (linktop = linkbottom = the_same_widget) :
535	541		causes the "linktop" widget to adjust to v-position & height of the splitter,
536	542
537	543		It's even possible in these cases that the widget doesn't touch the splitter
538	544
539	545		- optionsscale
540	546		= see {tscalingwidget.optionsscale}
541	547
542	548		- optionswidget
543	549		= see {anywidget.optionswidget}
544	550
545	551		- onactivate, onchildscaled, ondeactivate, ondefocus, onenter, onexit, onfocus,
546	552		onfontheightdelta, onmove, onpopup, onresize, onshowhint
547	553		= see "tspacer"
548	554
549	555		- onupdatelayout
550	556		fires :
551	557
552	558		= on creating the splitter
553	559		= on any reposition of the linked widgets
554	560		( due to moving the splitter, resizing the parent,.. )
555	561
556	562		### TSpacer
557	563
558		-	~~`* a regular widget which creates a kind of positional link between surrounding widgets`\~~
559		-	~~`* designed to maintain distances between widgets`\~~
560		-	~~`* may have GUI look, caption etc switched off by default`\~~
561		-	~~`* resizing a spacer repositions its linked widgets`~~
	564	+	```text
	565	+	* a regular widget which creates a kind of positional link between surrounding widgets
	566	+	* designed to maintain distances between widgets
	567	+	* may have GUI look, caption etc switched off by default
	568	+	* resizing a spacer repositions its linked widgets
	569	+	```
562	570
563	571		Properties:
564	572
565	573		` - anchors`\
566	574		` = see {any_widget.anchors}`
567	575
568	576		` - bounds`\
569	577		` = see {any_widget.bounds}`
570	578
571	579		` - color`\
572	580		` = see {any_widget.color}`
573	581
574	582		` - enabled`\
575	583		` = "false" turns color of the caption to gray`
576	584
577	585		` - visible`\
578	586		` = "true" allows displayable settings (caption text, face, frame etc) to take `\
579	587		` effect in run-time as well`\
580	588		` `\
581	589		` - <face>`\
582	590		` = see {any face}`
583	591
584	592		` - <frame>`\
585	593		` = see {any frame}`
586	594
587	595		` - linkbottom`\
588	596		` = widget linked down to most outer edge (incl. frame[.caption]) of the spacer`\
589	597		` - linkleft`\
590	598		` = widget linked left to most outer edge of the spacer`\
591	599		` - linkright`\
592	600		` = widget linked right to most outer edge of the spacer`\
593	601		` - linktop`\
594	602		` = widget linked up to most outer edge of the spacer`
595	603
596	604		` - dist_bottom, dist_left, dist_right, dist_top :`\
597	605		` = margins between most outer edge the spacer `\
598	606		` and the corresponding linked widget`
599	607
600	608		` - options :`
601	609
602	610		` = spao_glueright`
603	611
604	612		` - if "false" `
605	613
606	614		` h-repositioning or h-resizing the linkleft widget shifts `\
607	615		` the whole linked construction, it becomes the only way to h-shift`
608	616
609	617		` if {an_right IN linkright_widget.anchors} then the spacer `\
610	618		` may be right-resized with auto h-resizing the linkright widget `\
611	619		` so that the right margin of that widget is kept`
612	620
613	621		` if NOT {an_right IN linkright_widget.anchors} then the spacer `\
614	622		` may be right-resized with auto h-shifting the linkright widget `\
615	623		` so that width of that widget is kept`
616	624
617	625		` - if "true" `
618	626
619	627		` h-repositioning or h-resizing the linkright widget shifts `\
620	628		` the whole linked construction, it becomes the only way to h-shift`
621	629
622	630		` if {an_left IN linkleft_widget.anchors} then the spacer `\
623	631		` may be h-resized with auto h-resizing the linkleft widget `\
624	632		` so that the left margin of that widget is kept`
625	633
626	634		` if NOT {an_left IN linkleft_widget.anchors} then the spacer `\
627	635		` may be h-resized with auto h-shifting the linkleft widget `\
628	636		` so that width of that widget is kept`
629	637
630	638		` = spao_gluebottom`
631	639
632	640		` - if "false" `
633	641
634	642		` v-repositioning or v-resizing the linktop widget shifts `\
635	643		` the whole linked construction, it becomes the only way to v-shift`
636	644
637	645		` if {an_bottom IN linkbottom_widget.anchors} then the spacer `\
638	646		` may be v-resized with auto v-resizing the linkbottom widget `\
639	647		` so that the bottom margin of that widget is kept`
640	648
641	649		` if NOT {an_bottom IN linkbottom_widget.anchors} then the spacer `\
642	650		` may be v-resized with auto v-shifting the linkbottom widget `\
643	651		` so that height of that widget is kept`
644	652
645	653		` - if "true" `
646	654
647	655		` v-repositioning or v-resizing the linkbottom widget shifts `\
648	656		` the whole linked construction, it becomes the only way to v-shift`
649	657
650	658		` if {an_top IN linktop_widget.anchors} then the spacer `\
651	659		` may be v-resized with auto v-resizing the linktop widget `\
652	660		` so that the top margin of that widget is kept`
653	661
654	662		` if NOT {an_top IN linktop_widget.anchors} then the spacer `\
655	663		` may be v-resized with auto v-shifting the linktop widget `\
656	664		` so that height of that widget is kept`
657	665
658	666		` - optionsscale`\
659	667		` = see {tscalingwidget.optionsscale}`
660	668
661	669		` - optionswidget`\
662	670		` = see {anywidget.optionswidget}`
663	671
664	672		` - onactivate, onchildscaled, ondeactivate, ondefocus, onenter, onexit, onfocus,`\
665	673		` onfontheightdelta, onpopup, onresize, onshowhint `\
666	674		` = see {any_widget.*}`
667	675
668	676		` - onmove`\
669	677		` = see {any_window.OnMove}`
670	678
671	679		` any "link*" option set disables the spacer to reposition solely, `\
672	680		` repositioning is only controlled by a "glued" widget since then`
673	681
674	682		### TLayouter
675	683
676	684		- a tspacer descendant designed to (auto)resize or/and move its contained widgets acc to some size/positon dependencies
677	685		- may have GUI look, frame caption etc switched off by default
678	686		- layouters may be nested to achieve complex layouts
679	687
680	688		Each layout change/assignment is divided into performing 3 consequent stages :
681	689
682	690		#### Stage 1
683	691
684	692		Widgets auto resized using the following options:
685	693
686	694		- if {lao_placex OR lao_placey} :
687	695
688	696		= if {plo_scalesize in optionslayout} then
689	697		* widgets with "osk_nopropwith" unset in their "optionsskin" are h-scaled
690	698		in the proportion of change of tlayouter's clientwidth
691	699		* widgets with "osk_nopropheight" unset in their "optionsskin" are v-scaled
692	700		in the proportion of change of tlayouter's clientheight
693	701
694	702		For h-resized layouter, the effect looks like :
695	703
696	704		\|--Widget__1---Widget__2--\| => the initial look
697	705
698	706		\|--Widget_1--Widget_2--\| => the layouter gets narrower
699	707
700	708		\|---Widget___1---Widget___2---\| => the layouter gets wider
701	709
702	710		* both widget sizes & margins are affected *
703	711		* Widget_N may generally situate on different y-levels *
704	712
705	713		otherwise :
706	714
707	715		= if lao_scalewidth in optionslayout :
708	716		* widgets with "osk_nopropwith" unset in their "optionsskin" enters in the mode
709	717		( not applied until the layouter resizes! ) when they are h-scaled in the proportion
710	718		as far as clientwidth of the tlayouter changes, then stages 2 & 3 are reapplied
711	719
712	720		For h-resized layouter, the effect looks like :
713	721
714	722		\|--Single____widget????\| => the initial look
715	723
716	724		\|--Single__widget???\| => the layouter gets narrower
717	725
718	726		\|--Single_______widget?????\| => the layouter gets wider
719	727
720	728		* also, if {lao_scaleleft in optionslayout} then left margins of the widgets
721	729		with unset "optionsskin.osk_nopropleft" resize too otherwise retain
722	730
723	731		= if lao_scaleheight in optionslayout :
724	732		* widgets with "osk_nopropheight" unset in their "optionsskin" enters in the mode
725	733		( not applied until the layouter resizes! ) when they are v-scaled in the proportion
726	734		as far as clientheight of the tlayouter changes, then stages 2 & 3 are reapplied
727	735
728	736		* also, if {lao_scaletop in optionslayout} then top margins of the widgets
729	737		with unset "optionsskin.osk_noproptop" resize too otherwise retain
730	738
731	739		* only widget sizes & margins not distances between them are affected *
732	740
733	741		#### Stage 2
734	742
735	743		Widgets may be auto resized in 5 consequent steps using the following options:
736	744
737	745		1. if plo_syncmaxautosize in place_options :
738	746		= all widgets are autosized then their client areas are synchronised to the
739	747		clientareas of the highest and the widest of the widget
740	748		* calls "msegui.syncmaxautosize"
741	749
742	750		2. if plo_syncpaintwidth in place_options :
743	751		= the paintwidths of all widgets are synchronized to the widget with the
744	752		widest outer frame width ( ex. width of "frame.caption" )
745	753		* mainly makes sense if "lao_alignx" set and {align_glue = wam_start or wam_end}
746	754		( see below ) when the widgets will be adjusted in order to fit into the
747	755		inner client width of tlayouter:
748	756
749	757		x-align level
750	758		V
751	759		+----------------------------------+
752	760		\| Widget_1 the_widest_frame_caption\|
753	761		\| Widget_2 frame_caption2 \|
754	762		\| Widget_N wider_frame_captionN \|
755	763		+----------------------------------+
756	764
757	765		here, the effect is shown for "cp_right" frame captions
758	766		// otherwise syncronizes to the outer ( of the frame except its caption ) width
759	767		// of the Z-top widget
760	768		* calls "msegui.syncpaintwidth"
761	769		* paintwidth is the outer width
762	770
763	771		3. if plo_syncpaintheight in place_options :
764	772		= the paintheights of all widgets are synchronized to the widget with the
765	773		highest outer frame width ( ex. width of "frame.caption" ).
766	774		* mainly makes sense if lao_aligny set and {align_glue = wam_start or wam_end}
767	775		( see below ) the widgets will be adjusted in order to fit into the inner
768	776		client height of tlayouter :
769	777
770	778		+------------------------------+
771	779		\| The_ \|
772	780		\| tallest_ taller_ \|
773	781		\| frame_ frame_ frame_ \|
774	782		\| caption caption2 captionN \|
775	783		\| \|
776	784		\| Widget1 Widget_2 Widget_N \|<== y-align level
777	785		+------------------------------+
778	786
779	787		here, the effect is shown for "cp_topleft" frame captions
780	788		// otherwise syncronizes to the outer ( of the frame except its caption )
781	789		// height of the Z-top widget
782	790		* calls "msegui.syncpaintheight"
783	791
784	792		4. plo_synccaptiondistx in place_options :
785	793		= causes all widgets to have the widest common room for their cp_(left/right)* frame captions
786	794		* calls "msegui.synccaptiondistx"
787	795
788	796		5. plo_synccaptiondisty in place_options :
789	797		= causes all widgets to have the highest common room for their cp_(top/bottom)* frame captions
790	798		* calls "msegui.synccaptiondisty"
791	799
792	800		#### Stage 3
793	801
794	802		The widgets may be (re)arranged within the layouter.
795	803
796	804		There're 2 modes of such (re)arrangement which can be partially (orthogonally)
797	805		combined (see later):
798	806
799	807		1) The place(ment) mode ( lao_place* in optionslayout ) :
800	808
801	809		- widgets are placed at some distances between each other, possibly with some
802	810		margins, rooms of invisible widgets ( having visible=false) are also allocated
803	811		unless "plo_noinvisible in place_options"
804	812
805	813		* the widgets are placed in the order of decreasing their "widgetrect.x"
806	814		coordinates before alignment
807	815
808	816		* the inter-widget distances and the side margins ( if apllied ) in both
809	817		dimentions are identical and limited between "place_mindist" and
810	818		"place_maxdist"
811	819
812	820		= if {lao_placex in optionslayout} and {place_mode <> wam_none} then the
813	821		following relevant settings apply:
814	822
815	823		* non-limiting value of "place_maxdist" :
816	824
817	825		# \|Widget_1------Widget_2------Widget_3\|
818	826
819	827		* non-limiting value of "place_maxdist" and {plo_propmargin in place_options} :
820	828
821	829		# \|---Widget_1---Widget_2---Widget_3---\|
822	830
823	831		* limiting value of "place_maxdist" and {place_mode = wam_start} :
824	832
825	833		# \|Widget_1----Widget_2----Widget_3????\|
826	834
827	835		* limiting value of "place_maxdist" and {place_mode = wam_start} and
828	836		{plo_propmargin in place_options} :
829	837
830	838		# \|---Widget_1---Widget_2---Widget_3???\|
831	839
832	840		* limiting value of "place_maxdist" and {place_mode = wam_end} :
833	841
834	842		# \|??????Widget_1---Widget_2---Widget_3\|
835	843
836	844		* limiting value of "place_maxdist" and {place_mode = wam_end} and
837	845		{plo_propmargin in place_options} :
838	846
839	847		# \|???Widget_1---Widget_2---Widget_3---\|
840	848
841	849		* limiting value of "place_maxdist" and {place_mode = wam_center} :
842	850
843	851		# \|???Widget_1---Widget_2---Widget_3???\|
844	852
845	853		* limiting value of "place_maxdist" and {plo_endmargin in place_options} :
846	854
847	855		# \|Widget_1----Widget_2----Widget_____3\|, or
848	856
849	857		# \|Widget_1----Widget_____2----Widget_3\|, or
850	858
851	859		# \|Widget_____1----Widget_2----Widget_3\|, here, the most left amongst
852	860		widgets having both [an_left,an_right] set is expanded otherwise the most
853	861		right widget ( Widget_3 in the example )
854	862
855	863		* limiting value of "place_maxdist" and {place_mode = wam_end} and
856	864		{plo_propmargin in place_options} and {plo_endmargin in place_options} :
857	865
858	866		# \|--Widget_1--Widget_____2--Widget_3--\|,
859	867
860	868		The Legend:
861	869		===========
862	870		limiting value of "place_maxdist" : such value which produce some visual
863	871		effect on the layouter
864	872
865	873		"----" : distance ( = number of minuses, limited by place_maxdis )
866	874		"????" : some remaining space ( = number of questmarks )
867	875		"Widget_1" : widget of the original size
868	876		"Widget__..__1" : (auto)resized widget
869	877
870	878		= if {lao_placey in optionslayout} and {place_mode <> wam_none} then the things
871	879		are handled in the same manner as with "lao_placex" but for the vertical
872	880		"top2bottom" direction of placement instead of the horizontal "left2right" one.
873	881
874	882		2) the align(ment) mode ( optionslayout.lao_align* ) :
875	883
876	884		- widgets are gathered into a visual group to a dedicated "leader" widget of
877	885		the layout ( set by "align_leader" and defaults to the lowest in
878	886		Z-Order = twidget.widgets[0] ) the leader stays in place while the others :
879	887
880	888		= if lao_alignx in optionslayout ( the hor alignment mode ):
881	889		* if align_mode = wam_start :
882	890		snap their left borders to the left border of leader
883	891		* else if align_mode = wam_end :
884	892		snap their right borders to the right border of leader
885	893		* else if align_mode = wam_center :
886	894		snap their v-axes to the v-axis of leader after that,
887	895		= if lao_aligny in optionslayout ( the vert alignment mode ):
888	896		* if align_mode = wam_start :
889	897		snap their top borders to the top border of leader
890	898		* else if align_mode = wam_end :
891	899		snap their bottom borders to the bottom border of leader
892	900		* else if align_mode = wam_center :
893	901		snap their h-axes to the h-axis of leader
894	902
895	903		- after that, the whole widget group can be aligned within the layouter:
896	904
897	905		= if align_glue = wam_start
898	906		* if lao_alignx in optionslayout:
899	907		the left extent of group snaps to the left border of layouter
900	908		* if lao_aligny in optionslayout:
901	909		the top extent of group snaps to the top border of layouter
902	910		= else if align_glue = wam_end
903	911		* if lao_alignx in optionslayout:
904	912		the right extent of group snaps to the right border of layouter
905	913		* if lao_aligny in optionslayout:
906	914		the bottom extent of group snaps to the bottom border of layouter
907	915		= else if align_glue = wam_center
908	916		* if lao_alignx in optionslayout:
909	917		the v-axis of group snaps to the v-axis of layouter
910	918		* if lao_aligny in optionslayout:
911	919		the h-axis of group snaps to the h-axis of layouter
912	920
913	921		Mutually exclusive settings:
914	922		* only one of "align_mode" can be choosen
915	923		* only one of "glue_mode" can be choosen
916	924		* "optionslayout.lao_alignx" & "optionslayout.lao_placex"
917	925		* "optionslayout.lao_aligny" & "optionslayout.lao_placey"
918	926
919	927		V-alignment ( optionslayout.lao_aligny ) may be combined with h-placement
920	928		( optionslayout.lao_placex ), and h-alignment ( optionslayout.lao_alignx ) may
921	929		be combined with v-placement ( optionslayout.lao_placey )
922	930
923	931		NOTE:
924	932		The effects of the above described { resizing / placement / alignment } are
925	933		irreversible. So, the only way to revert is to set "wan_none" then to revert
926	934		manually.
927	935
928	936		### TListView
929	937
930	938		### TImage
931	939
932	940		<any image>
933	941
934	942		* Note that switch to the monochrome mode is irerreversible ! *
935	943
936	944		alignment:
937	945
938	946		By default, images are top-left aligned, with the original size preserved.
939	947
940	948		al_xcentered = centers the image horizontally
941	949		al_ycentered = centers the image vertically
942	950
943	951		al_right = docks the image to the right border of placeholder
944	952		al_bottom = docks the image to the bottom border of placeholder
945	953
946	954		al_grayed = fills non-transparent areas with the selected color
947	955
948	956		al_stretchx = adjusts size so that to fill the placeholder in width
949	957		al_stretchy = adjusts size so that to fill the placeholder in height
950	958		al_fit = adjusts size so that to fill the placeholder in both width & height
951	959
952	960		al_tiled = spawns the image & tile the whole placeholder with the copies
953	961
954	962		Interpolation mode while stretching
955	963
956	964		al_intpol = antialiases as far as the size changes
957	965		(the only working in Linux)
958	966		al_or = interpolation pixel operation is "or" -> 1's are extended
959	967		al_and = interpolation pixel operation is "and" -> 0's are extended
960	968		( al_or and al_and only on win32, mainly useful for stretching of monochrome bitmaps) :
961	969
962	970		colorbackground = color of image transparent ( masked ) areas in monochrome
963	971		non-masked mode
964	972		colorforeground = color of non-transparent areas in monochrome mode
965	973
966	974		options:
967	975
968	976		bmo_monochrome = fills non-transparent areas with "colorforeground",
969	977		also, in non-masked mode, fills transparent areas
970	978		with "colorbackground"
971	979
972	980		bmo_masked = activates built-in image transparency {it "hides" transparent (masked) areas}
973	981		bmo_colormask = applies faded edge transparency on the color masked areas in the image
974	982
975	983		transparency = makes the image transparent as long as enlights areas behind
976	984		the image with the selected color
977	985
978	986		transparentcolor = for a non-masked image, assigns a color indicate transparency areas
979	987		( on matching areas, the image will be seen through )
980	988
981	989		### TDial
982	990
983	991		### TChart
984	992
985	993		There are demos here:
986	994
987	995		<https://github.com/mse-org/mseuniverse/tree/master/attic/msedocumenting/mse/trunk/help/tutorials/widgets/charts>
988	996
989	997		### TChartRecorder
990	998
991	999		### TPolygon
992	1000
993	1001		### TPickWidget
994	1002
995	1003		### TOpenglWidget
996	1004
997	1005		## Edit
998	1006
999	1007		### TStringEdit
1000	1008
1001	1009		### TMemoEdit
1002	1010
1003	1011		### THexStringEdit
1004	1012
1005	1013		### TDropdownListEdit
1006	1014
1007		-	~~`A tstringedit with a dropdownlist to choose text values. Important dropdown.options members:`\~~
1008		-	~~`- deo_autodropdown dropdown on keypress`\~~
1009		-	~~`- deo_selectonly don't allow entering arbitrary text.`\~~
1010		-	~~`- deo_forceselect don't allow entering empty text.`~~
	1015	+	```text
	1016	+	A tstringedit with a dropdownlist to choose text values. Important dropdown.options members:
	1017	+	- deo_autodropdown dropdown on keypress
	1018	+	- deo_selectonly don't allow entering arbitrary text.
	1019	+	- deo_forceselect don't allow entering empty text.
	1020	+	```
1011	1021
1012	1022		### THistoryEdit
1013	1023
1014		-	~~`A tstringedit which shows the previously entered values in a dropdownlist for selection.`~~
	1024	+	```text
	1025	+	A tstringedit which shows the previously entered values in a dropdownlist for selection.
	1026	+	```
1015	1027
1016	1028		### TIntegerEdit
1017	1029
1018	1030		### TKeyStringEdit
1019	1031
1020		-	~~`Maps string to string.`~~
	1032	+	```text
	1033	+	Maps string to string.
	1034	+	```
1021	1035
1022	1036		### TEnumEdit
1023	1037
1024		-	~~`Maps integer to string, zero based and sequencial (first item 0, next 1, ...).`~~
	1038	+	```text
	1039	+	Maps integer to string, zero based and sequencial (first item 0, next 1, ...).
	1040	+	```
1025	1041
1026	1042		### TEnumTypeEdit
1027	1043
1028	1044		A TEnumEdit which maps Pascal enums to their names. Use OnInit event to store the typeinfo pointer of the enum type into sender.typeinfopo.
1029	1045
1030	1046		``` pascal
1031	1047
1032	1048		procedure tmainfo.enumtypeeditinit(const sender: tenumtypeedit);
1033	1049		begin
1034	1050		sender.typeinfopo := PTypeInfo(TypeInfo(TMyEnumeratedType));
1035	1051		end;
1036	1052		```
1037	1053
1038	1054		### TSelector
1039	1055
1040	1056		TSelector is the most specialized widget of the dropdown editwidget group, it is based on tenumedit (tenumedit maps an integer to a string) and uses for the dropdownlist a second map which must be created on the fly in ongetdropdowninfo. An example is tcommselector where the enumedit maps commnrty to commname and the dropdownlist shows the available RS232 ports only.
1041	1057
1042	1058		### TRealEdit
1043	1059
1044	1060		### TRealSpinEdit
1045	1061
1046	1062		### TDateTimeEdit
1047	1063
1048	1064		### TCalendarDateTimeEdit
1049	1065
1050	1066		### TEdit
1051	1067
1052	1068		MSEgui counterpart of Delphi TEdit. You will never use it.
1053	1069
1054	1070		### TWidgetGrid
1055	1071
1056	1072		### TItemEdit
1057	1073
1058	1074		### TDropDownItemEdit
1059	1075
1060		-	~~`A tstringedit with a dropdownlist to choose text values. Important dropdown.options members:`\~~
1061		-	~~`- deo_autodropdown dropdown on keypress`\~~
1062		-	~~`- deo_selectonly don't allow entering arbitrary text.`\~~
1063		-	~~`- deo_forceselect don't allow entering empty text.`~~
	1076	+	```text
	1077	+	A tstringedit with a dropdownlist to choose text values. Important dropdown.options members:
	1078	+	- deo_autodropdown dropdown on keypress
	1079	+	- deo_selectonly don't allow entering arbitrary text.
	1080	+	- deo_forceselect don't allow entering empty text.
	1081	+	```
1064	1082
1065	1083		### TMBDropDownItemEdit
1066	1084
1067	1085		### TTreeItemEdit
1068	1086
1069	1087		### TRecordFieldEdit
1070	1088
1071		-	~~`Used in twidgetgrid in order to edit fields of a ttreeitemedit. Example is MSEide projecttreeform.pas.`~~
	1089	+	```text
	1090	+	Used in twidgetgrid in order to edit fields of a ttreeitemedit. Example is MSEide projecttreeform.pas.
	1091	+	```
1072	1092
1073	1093		### TDialogStringEdit
1074	1094
1075	1095		A tstringedit with an ellipse button. Use "onexecute" to show the dialog.
1076	1096
1077	1097		### TPointerEdit
1078	1098
1079	1099		### TSlider
1080	1100
1081	1101		### TProgressBar
1082	1102
1083	1103		### TBooleanEdit
1084	1104
1085	1105		### TBooleanEditRadio
1086	1106
1087	1107		### TDataButton
1088	1108
1089	1109		A button with an integer value. Clicking increments the value until "max", then it restarts with "min". Can be inserted into a twidgetgrid. The current value selects the showed image and face by the items of "imagenums" and "valuefaces".
1090	1110
1091	1111		### TStockGlyphDataButton
1092	1112
1093	1113		### TDataIcon
1094	1114
1095	1115		Shows an imagelist item by lookup from "value" to "imagenums". Clicking increments value until "max" then it restarts with "min". Can be inserted into a twidgetgrid.
1096	1116
1097	1117		### TTextEdit
1098	1118
1099	1119		Only useful if inserted into a twidgetgrid, builds a text editor, used in MSEide source editor.
1100	1120
1101	1121		### TDataImage
1102	1122
1103	1123		A pixmap display widget which can be inserted into twidgetgrid.
1104	1124
1105	1125		### TTerminal
1106	1126
1107	1127		Only useful if inserted into a twidgetgrid, builds a very simple terminal emulator. Used in MSEide target console.
1108	1128
1109	1129		## NoGui
1110	1130
1111	1131		### TAction
1112	1132
1113	1133		Shortcut processing order :
1114	1134
1115	1135		- the smallest piece of processing is "doshortcut" procedure which
1116	1136		is called until processed:
1117	1137		= starting from the sender up to the toplevel widget
1118	1138		= then by all child widgets with non-set "ow_noparentshortcut"
1119	1139		= then, if "ow_nochildshortcut" isn't set, by the parent widget
1120	1140		= then by the widget oneself
1121	1141
1122	1142		- "doshortcut" is checked in the following order:
1123	1143		= starting from form's main menu
1124	1144		= then from the owning window ( the widget oneself )
1125	1145		= then from the application
1126	1146
1127	1147		*** A shortcut is bound to a widget by :
1128	1148		- placing an action component on the widget ***
1129	1149		- direct assigning the shortcut to the widget (menus,..)
1130	1150		---------------------------
1131	1151
1132	1152		caption, color, colorglyph, helpcontext, hint, imagecheckedoffset,
1133	1153		imagelist <see "timagelist">, imagenr, imagenrdisabled
1134	1154
1135	1155		- sets look of "clients" (buttons, menu/toolbar items,..), unless
1136	1156		these clients have "state.as_local*" set :
1137	1157
1138	1158		* For meaning of these options, see help on the "client" widgets *
1139	1159
1140	1160		group
1141	1161		- default value for one-named property of the bound widgets
1142	1162		( menu items,... )
1143	1163
1144	1164		options :
1145	1165		ao_updateonidle
1146	1166		- runs this action in cycle, waiting for no gui events everytime
1147	1167
1148	1168		ao_globalshortcut
1149	1169		- allows the action to trigger on a non-main form
1150	1170		(the shortcut is triggered whatever form of the applicatin it was pressed on,
1151	1171		otherwise only when the form where the aption is placed on is focused )
1152	1172
1153	1173		ao_nocandefocus
1154	1174		- causes the action not to call "CanDefocus" for focused edit widget of active form
1155	1175		before executing own code
1156	1176		( it helps to avoid the effect of cancelling changes in these widgets
1157	1177		on activating the bound shortcut )
1158	1178
1159	1179		shortcut
1160	1180		- keyboard combination triggering the action
1161	1181
1162	1182		shortcut
1163	1183		- alternative "shortcut" and handled identically
1164	1184
1165	1185		state :
1166	1186
1167	1187		as_disabled
1168	1188		- prevents the action from triggering, also puts the bound widgets to "disabled" look
1169	1189
1170	1190		as_invisible
1171	1191		- in run-time, hides the bound widget, still reacting on the shortcut or direct call
1172	1192
1173	1193		as_checked
1174	1194		- selects the bound menu item if it has "mao_checkbox" option set
1175	1195
1176	1196		as_default
1177	1197		as_local*
1178	1198
1179	1199		statfile
1180	1200		<see "tstatfile">
1181	1201
1182	1202		stavarname
1183	1203
1184	1204
1185	1205		tagaction
1186	1206		onasyncevent
1187	1207		onchange
1188	1208		onexecute
1189	1209		onupdate
1190	1210
1191	1211		### TActivator
1192	1212
1193	1213		### TCustomLookupbuffer
1194	1214
1195	1215		- provides a group of parallel arrays of float(=datetime), integer and widestring types,
1196	1216		and facilities to :
1197	1217		= search in any array
1198	1218		= on found position, quickly obtain corresponding value in another array
1199	1219		- for each type, several arrays may be kept
1200	1220		- each array is integer-indexed, even string ones ( case[in]sensitive )
1201	1221		- uses two way of accessing arrays data, through :
1202	1222		= physic : array storage index ( row number ) directly
1203	1223		= logical : the integer index ( see above ):
1204	1224		first, physic row number is known for the logical index then the data
1205	1225		are accessed with the found number
1206	1226
1207	1227		*** logical index values are built automatically based on array values,
1208	1228		on updating its data ***
1209	1229		- dont' have interface to load data ( see its descendants for that )
1210	1230
1211	1231		fieldcountfloat - number of float arrays
1212	1232		fieldcountinteger - number of integer arrays
1213	1233		fieldcounttext - number of widestring arrays
1214	1234
1215	1235		Event handlers:
1216	1236		- onchange
1217	1237
1218	1238		Public interface:
1219	1239
1220	1240		procedure beginupdate; - marks beginning of "update"
1221	1241		procedure endupdate; - if all "update" finished, fires "onchange" event
1222	1242		procedure clearbuffer; - clears all arrays then fires "onchange"
1223	1243
1224	1244		procedure checkbuffer;
1225	1245		- [re]loads the arrays with most actual data
1226	1246		- just a stub here since doesn't have a data source
1227	1247
1228	1248		function find(const fieldno: integer; const avalue: integer/realty/msestring;
1229	1249		out aindex: integer; const filter: lbfiltereventty = nil): boolean;
1230	1250		- applies external filtering ("filter" procedure) then incrementally searches integer/realty(datetime) array "fieldno"
1231	1251		for value "avalue" starting from logical index "aindex", returns "true" and the updated logical index
1232	1252		if found else next bigger;
1233	1253
1234	1254		function find(const fieldno: integer; const avalue: msestring;
1235	1255		out aindex: integer;
1236	1256		const caseinsensitive: boolean;
1237	1257		const filter: lbfiltereventty = nil): boolean; overload;
1238	1258		- applies external filtering ("filter" procedure) then incrementally searches widestring array "fieldno" for value "avalue",
1239	1259		in "caseinsensitive" manner, starting from logical index "aindex", returns "true" and the updated logical index
1240	1260		if found else next bigger;
1241	1261
1242	1262		function findphys(const fieldno: integer; const avalue: integer;
1243	1263		out aindex: integer; const filter: lbfiltereventty = nil): boolean; overload;
1244	1264		- applies external filtering ("filter" procedure) then incrementally searches integer/realty(datetime) array "fieldno"
1245	1265		for value "avalue" starting from row number "aindex", returns "true" and the updated row number
1246	1266		if found else next bigger;
1247	1267
1248	1268		function findphys(const fieldno: integer; const avalue: msestring; out aindex: integer; const caseinsensitive: boolean;
1249	1269		const filter: lbfiltereventty = nil): boolean; overload;
1250	1270		- applies external filtering ("filter" procedure) then incrementally searches widestring array "fieldno" for value "avalue",
1251	1271		in "caseinsensitive" manner, starting from row number "aindex", returns "true" and the updated row number
1252	1272		if found else next bigger;
1253	1273
1254	1274		The external filtering ("filter") procedure takes the arguments of the caller
1255	1275		togehther with physical row number found in the caller which allows
1256	1276		to check several values at once for that number, within the filter
1257	1277
1258	1278		function integervaluephys(const fieldno,aindex: integer): integer;
1259	1279		- returns value of integer array "fieldno" at row number "aindex"
1260	1280
1261	1281		function integervaluelog(const fieldno,aindex: integer): integer;
1262	1282		- returns value of integer array "fieldno" where the array index equals to "aindex"
1263	1283
1264	1284		function integerindex(const fieldno,aindex: integer): integer;
1265	1285		- returns row number of integer array "fieldno" where the array index equals to "aindex"
1266	1286
1267	1287		function integerindexar(const fieldno: integer): integerarty;
1268	1288		- returns all bunch of indexes of integer array "fiedlno"
1269	1289
1270	1290		function integerar(const fieldno: integer): integerarty;
1271	1291		- returns all bunch of data of integer array "fiedlno"
1272	1292
1273	1293		function floatvaluephys(const fieldno,aindex: integer): realty;
1274	1294		- returns value of real/datetime array "fieldno" at row number "aindex"
1275	1295
1276	1296		function floatvaluelog(const fieldno,aindex: integer): realty;
1277	1297		- returns value of real/datetime array "fieldno" where the array index equals to "aindex"
1278	1298
1279	1299		function floatindex(const fieldno,aindex: integer): integer;
1280	1300		- returns row number of real/datetime array "fieldno" where the array index equals to "aindex"
1281	1301
1282	1302		function floatindexar(const fieldno: integer): integerarty;
1283	1303		- returns all bunch of indexes of real/datetime array "fiedlno"
1284	1304
1285	1305		function floatar(const fieldno: integer): realarty;
1286	1306		- returns all bunch of data of real/datetime array "fiedlno"
1287	1307
1288	1308		function textvaluephys(const fieldno,aindex: integer): msestring;
1289	1309		- returns value of widestring array "fieldno" at row number "aindex"
1290	1310
1291	1311		function textvaluelog(const fieldno,aindex: integer;
1292	1312		const caseinsensitive: boolean): msestring;
1293	1313		- returns value of widestring array "fieldno" where the array index equals to "aindex"
1294	1314
1295	1315		function textindex(const fieldno,aindex: integer;
1296	1316		const caseinsensitive: boolean): integer;
1297	1317		- returns row number of widestring array "fieldno" where the array index equals to "aindex"
1298	1318
1299	1319		function textindexar(const fieldno: integer;
1300	1320		const caseinsensitive: boolean): integerarty;
1301	1321		- returns all bunch of indexes of widestring array "fiedlno"
1302	1322
1303	1323		function textar(const fieldno: integer): msestringarty;
1304	1324		- returns all bunch of data of widestring array "fiedlno"
1305	1325
1306	1326
1307	1327		function lookupinteger(const integerkeyfieldno,integerfieldno,
1308	1328		keyvalue: integer): integer; overload;
1309	1329		- returns value of integer array "integerfieldno" at position where
1310	1330		value of parallel integer array "integerkeyfieldno" equals to "keyvalue"
1311	1331		( 0 if not found )
1312	1332
1313	1333		function lookupinteger(const stringkeyfieldno,integerfieldno: integer;
1314	1334		const keyvalue: msestring): integer; overload;
1315	1335		- returns value of integer array "integerfieldno" at position where
1316	1336		value of parallel widestring array "stringkeyfieldno" equals to "keyvalue"
1317	1337		( 0 if not found )
1318	1338
1319	1339		function lookuptext(const integerkeyfieldno,textfieldno,
1320	1340		keyvalue: integer): msestring; overload;
1321	1341		- returns value of integer array "textfieldno" at position where
1322	1342		value of parallel integer array "integerkeyfieldno" equals to "keyvalue"
1323	1343		( '' if not found )
1324	1344
1325	1345		function lookuptext(const stringkeyfieldno,textfieldno: integer;
1326	1346		const keyvalue: msestring): msestring; overload;
1327	1347		- returns value of integer array "textfieldno" at position where
1328	1348		value of parallel integer array "integerkeyfieldno" equals to "keyvalue"
1329	1349		( '' if not found )
1330	1350
1331	1351		function lookupfloat(const integerkeyfieldno,floatfieldno,
1332	1352		keyvalue: integer): realty; overload;
1333	1353		- returns value of real/datetime array "floatfieldno" at position where
1334	1354		value of parallel integer array "integerkeyfieldno" equals to "keyvalue"
1335	1355		( emptyreal if not found )
1336	1356
1337	1357		function lookupfloat(const stringkeyfieldno,floatfieldno: integer;
1338	1358		keyvalue: msestring): realty; overload;
1339	1359
1340	1360		- returns value of real/datetime array "floatfieldno" at position where
1341	1361		value of parallel widestring array "stringkeyfieldno" equals to "keyvalue"
1342	1362		( emptyreal if not found )
1343	1363
1344	1364		function count: integer; - returns number of data rows
1345	1365
1346	1366		property fieldcounttext: integer; - returns/sets number of widestring arrays
1347	1367		property fieldcountfloat: integer; - returns/sets number of real/datetime arrays
1348	1368		property fieldcountinteger: integer; - returns/sets number of integer arrays
1349	1369
1350	1370		the above "fieldcount*" props clear the buffer on setting a value
1351	1371
1352	1372		property integervalue[const fieldno,aindex: integer]: integer; - a shortcut to "integervaluephys"
1353	1373		property floatvalue[const fieldno,aindex: integer]: realty; - a shortcut to "floatvaluephys"
1354	1374		property textvalue[const fieldno,aindex: integer]: msestring; - a shortcut to "textvaluephys"
1355	1375
1356	1376		property onchange: notifyeventty;
1357	1377		- called in "changed" wich in turn is called in :
1358	1378		= clearbuffer
1359	1379		= endupdate
1360	1380		= doasyncevent
1361	1381		= loaded
1362	1382		= tlookupbuffer.addrow
1363	1383
1364	1384		### TLookupBuffer
1365	1385
1366	1386		tlookupbuffer = class(tcustomlookupbuffer)
1367	1387
1368	1388		- extends "tcustomlookupbuffer" with methods of run-time data filling
1369	1389
1370	1390		- see <tcustomlookupbuffer>
1371	1391
1372	1392		+= Extentions to the public interface:
1373	1393
1374	1394		procedure addrow(const integervalues: array of integer;
1375	1395		const textvalues: array of msestring;
1376	1396		const floatvalues: array of realty);
1377	1397
1378	1398		- adds one row to each of widestring arrays, integer arrays and real/datetime arrays,
1379	1399		array size of "{type}values" equals to number of {type} arrays
1380	1400
1381	1401		procedure addrows(const integervalues: array of integerarty;
1382	1402		const textvalues: array of msestringarty;
1383	1403		const floatvalues: array of realarty);
1384	1404
1385	1405		- adds many data rows to each of widestring arrays, integer arrays and real/datetime arrays,
1386	1406		only min length of the input data arrays are inserted, longer data are truncated
1387	1407		array size of "{type}values" equals to number of {type} arrays and the size of "{type}values[i]"
1388	1408		describes number od data elements in the array
1389	1409
1390	1410
1391	1411		### TDBLookupBuffer
1392	1412
1393	1413		tdblookupbuffer = class(tcustomdblookupbuffer -> tcustomlookupbuffer)
1394	1414
1395	1415		- extends "tcustomlookupbuffer" with interface to fill arrays with DB-data
1396	1416		- see <tcustomlookupbuffer> & <tcustomdblookupbuffer>
1397	1417
1398	1418		Extentions to the public interface:
1399	1419
1400	1420		procedure checkbuffer; - if data obsolete ("invalid") then reloads them from "datasource"
1401	1421
1402	1422		property datasource: tdatasource; - sets/returns DB data source where to load data from
1403	1423		property textfields: tdbfieldnamearrayprop; - allows to assign a {datasource:datafield} to each of widestring arrays
1404	1424		property integerfields: tdbfieldnamearrayprop; - allows to assign a {datasource:datafield} to each of integer arrays
1405	1425		property floatfields: tdbfieldnamearrayprop; - allows to assign a {datasource:datafield} to each of real/datetime arrays
1406	1426
1407	1427		property optionsdb: lbdboptionsty; - tunes some DB behaviour apects
1408	1428		- olbdb_closedataset :
1409	1429		= once data obsolete, opens (if needed) the supplier dataset (disabling its bound controls)
1410	1430		then [re]loads data from it then closes it
1411	1431
1412	1432		- olbdb_invalidateifmodified :
1413	1433		= gets marked "invalid" once contents of the bound dataset change,
1414	1434		it signals to reload the buffer with the new data just before next accessing
1415	1435		( for any purpose - searching, lookuping, getting value/(array of values),..)
1416	1436
1417	1437		### TDBmemoLookupbuffer
1418	1438
1419	1439		- allows to use for lookup-ing any text-convertable DB-fields
1420	1440		- an analog of tdblookupbuffer, but :
1421	1441		- "integerfields" may be names of any integer-convertable DB-fields
1422	1442		- "floatfields" may be names of any (real/datetime)-convertable DB-fields
1423	1443		- "textfields" may be names of any text-presentable DB-fields
1424	1444
1425	1445		- each DB-field value ( presenting a memo generally of many lines ) may supply many data rows at once
1426	1446		to the bound array of the buffer, since this value will be internally splitted & turned into native array values,
1427	1447		and the resulting "count" (arrays row count) of the whole buffer will be the minimal rows count amongst arrays
1428	1448		of the buffer, the rest data are truncated
1429	1449
1430	1450		- when loading widestring arrays, also checks for & performs "utf8-to-widestring" conversion of values of
1431	1451		the bound DB-fields so that these arrays always store widestrings
1432	1452
1433	1453		### TThreadComp
1434	1454
1435	1455		### TStatFile
1436	1456
1437	1457		- so that to be in effect, it should also be assigned to the form where the widget using the stafile is placed on
1438	1458		- in design, if "onstatwrite" is set and "filedir" is not yet created, deactivate exception "ECreateError" in project settings ( "Debugger" tab )
1439	1459		- "filedir" may contain "~/" indicating the user's home directory
1440	1460		- options "oe_savestate" & "oe_savevalue" of "client" widgets define what to store to the file
1441	1461		- position etc changes or/and value changes
1442	1462		- in case when a main form shares its stafile with non-main forms, on creating non-main ones, just edited not saved data of the main form ( bound to vars of the statfile) are reset to values read from the statfile upon creating the form; for "sfo_memory", this effect absents unless widgets on the concurring forms share same variable[s]; to avoid this behaviour, disable "fo_autoreadstat" & "fo_autowritestat" of the non-main forms
1443	1463		- each "tstafile" owns:
1444	1464		= tstatwriter:
1445	1465		* provides methods of writing sections & statvars to a memory/file stream
1446	1466		- tstatreader:
1447	1467		* holds list of sections with statvars each
1448	1468		* provides search & check & reading interface to the statvars
1449	1469		* provides reading statvars from a memory/file stream
1450	1470
1451	1471		Positioning to a section speeds up accessing its statvars
1452	1472
1453	1473		- there also is "tstatfiler" ( exposed by some "tstatfile" events ) which:
1454	1474		= may present or "tstatwriter" or "tstatreader" ( there's a check method )
1455	1475		= provides directionless "update" methods with internal switch to needed direction of processing
1456	1476		- "reading" or "writing" statvars on per-section basis
1457	1477
1458	1478		activator :
1459	1479		<see tactivator> : NOT YET DONE
1460	1480
1461	1481		encoding = "en_utf8" selected here, allows to store non-Latin text in the file
1462	1482		filedir = directory where to keep the file ( by default - the current working directory )
1463	1483		filename = name of the file
1464	1484
1465	1485		options:
1466	1486		sfo_memory = reads & writes not from a disk file but from a named memory stream
1467	1487		( there's an exclusion - see below "sfo_savedata" ),
1468	1488		mostly useful for presenting last used values on recalling
1469	1489		non-main forms etc ( data even survive recreating forms),
1470	1490		or even for data "exchange" between non-main modal( non-concurring ) forms
1471	1491		in case of the target widgets share same statvarnames
1472	1492
1473	1493		sfo_createpath = creates "filedir" if necessary
1474	1494		sfo_savedata = used only with "sfo_memory", commands to save
1475	1495		the memory data to the master statfile (see below)
1476	1496
1477	1497		sfo_activatorread = activator activate triggers reading ???
1478	1498		sfo_activatorwrite = activator deactivate triggers writing ???
1479	1499
1480	1500		statfile = a master statfile
1481	1501		statvarname = name of section of this file in the upper statfile
1482	1502		Tag = an integer property for misc purposes
1483	1503
1484	1504		Event handlers:
1485	1505		onstatafterread - fires on return from "readstat"
1486	1506		onstatafterwrite - fires on return from "writestat"
1487	1507		onstatbeforeread - fires on beginning of "readstat"
1488	1508		onstatbeforewrite - fires on beginning of "writestat"
1489	1509		onstatread = fires after reading state data
1490	1510		onstatwrite = fires after writing state data
1491	1511		onstatupdate = fires after reading/writing state data just before
1492	1512		"onstatread" & "onstatwrite"
1493	1513
1494	1514		Public methods:
1495	1515
1496	1516		procedure initnewcomponent(const ascale: real); override;
1497	1517		- does nothing but fixes the default file name as the statfile default
1498	1518
1499	1519		procedure readstat(stream: ttextstream = nil); overload;
1500	1520		- rereads all statvars of the stafile/memorystream
1501	1521
1502	1522		procedure readstat(const aname: msestring; const statreader: tstatreader); overload;
1503	1523		- rereads "aname" statvar of the statfile
1504	1524
1505	1525		procedure writestat(const stream: ttextstream = nil); overload;
1506	1526		- rewrites all statvars to the stafile/memorystream
1507	1527		(if neccessary, prepares to writting - creates "filedir", stafile,...)
1508	1528
1509	1529		procedure writestat(const aname: msestring; const statwriter: tstatwriter); overload;
1510	1530		- overwrites "aname" statvar of the statfile
1511	1531
1512	1532		procedure updatestat(const aname: msestring; const statfiler: tstatfiler);
1513	1533		- depending on kind of "statfiler" ( writer/reader ), writes/reads
1514	1534		the most up-to-date stat data
1515	1535
1516	1536		### TTimer
1517	1537
1518	1538		### TNoGuiAction
1519	1539
1520	1540		### TPipeReadercomp
1521	1541
1522	1542		### TSysEnvManager
1523	1543
1524	1544		### TProcessMonitor
1525	1545
1526	1546		### TFilechangeNotifier
1527	1547
1528	1548		### TShortCutController
1529	1549
1530	1550		### TPostscriptPrinter
1531	1551
1532	1552		### TGdiPrinter
1533	1553
1534	1554		### TWmfPrinter
1535	1555
1536	1556		### TSkinController
1537	1557
1538	1558		### TGuiThreadComp
1539	1559
1540	1560		## Font
1541	1561
1542	1562		See also : [[Reference: MSEgui/TFont]]
1543	1563
1544	1564		### Any Font
1545	1565
1546	1566		charset { ANSI/ DEFAULT/ SYMBOL /SHIFTJIS /HANGEUL /GB2312 /CHINESEBIG5 /OEM
1547	1567		/JOHAB / HEBREW/ ARABIC/ GREEK/ TURKISH/ VIETNAMESE/ THAI/ EASTEUROPE/
1548	1568		RUSSIAN/ MAC/ BALTIC }
1549	1569		- changes the font to the nearest containing the selected encoding(charset)
1550	1570		- no font change made if the supplied encoding doesn't match any font
1551	1571		color
1552	1572		- color of the glyphs contours
1553	1573		colorbackground
1554	1574		- fill color of the glyph cells ( not including extraspace )
1555	1575		colorshadow
1556	1576		- color of SE glyph "edges" ( if not "cl_none", deactivates "colorbackground" )
1557	1577		extraspace
1558	1578		- v-space between glyph cells of adjacent text rows (negative values cause the cells to overlap )
1559	1579		height
1560	1580		- v-size of glyph cells, in pixels
1561	1581		name
1562	1582		- initially, font is choosen by { "family" = this name }
1563	1583		options:
1564	1584		foo_fixed
1565	1585		- changes the font to the nearest "mono" spaced (usually = Courier)
1566	1586		foo_proportional
1567	1587		- changes the font to the nearest "proportionally" spaced (usually = Helvetica)
1568	1588		foo_helvetica
1569	1589		- changes the font to the nearest in "sans" category (usually = Helvetica)
1570	1590		foo_roman
1571	1591		- changes the font to the nearest in "serif" category (usually = Times[ New Roman])
1572	1592		foo_script
1573	1593		- Win32 only, changes the font to the nearest in "script" category
1574	1594		foo_decorative
1575	1595		- Win32 only, changes the font to the nearest in "decorative" category
1576	1596		foo_antialiased
1577	1597		- Linux-only, enables antialiasing (if disabled by Xft globally)
1578	1598		foo_nonantialiased
1579	1599		- Linux-only, disables antialiasing (if enabled by Xft globally)
1580	1600		usually making glyph extents (not cells !) a bit wider
1581	1601		style:
1582	1602		fs_bold
1583	1603		- gives the font a "bold" look
1584	1604		fs_italic
1585	1605		- gives the font an "italic" look
1586	1606		fs_underline
1587	1607		- gives the font an "underlined" look
1588	1608		fs_strikeout
1589	1609		- gives the font a "striked out" look
1590	1610		fs_selected
1591	1611		- "TRUE" here combined with {tf_noselect:=FALSE}, causes the text described by this font
1592	1612		to be initially selected ( with the clipboard operations available ),
1593	1613		currently applicable only to richstrings
1594	1614
1595	1615		width
1596	1616		- 10*{ glyph cell width, average in pixels }, 0 = {font default}
1597	1617
1598	1618		xscale
1599	1619		- width ratio of each glyph {cell & contour}, the effect is similar to "width"
1600	1620
1601	1621		*** "foo_*" font selection overrides one made with "name"
1602	1622
1603	1623		*** if change with "foo_*" is unsuccessful then the nearest "sans" font is usually chosen
1604	1624
1605	1625		*** The categories :
1606	1626
1607	1627		sans => have no serifs and have strokes of even thickness
1608	1628		serif => have serifs at glyph contours and made up of strokes of varying thickness
1609	1629		script => resemble handwriting
1610	1630		decorative => flashy styles to be used sparingly in headlines or posters
1611	1631
1612	1632		## GUI
1613	1633
1614	1634		### TWindow
1615	1635
1616	1636		twindow = class(teventobject,icanvas)
1617	1637		public
1618	1638
1619	1639		// releases mouse, unlinks from the canvas, processes all pending events of the window
1620	1640		// if called from within main thread then destroys the window directly
1621	1641		// otherwise posts a window destroy event for oneself and waits for it to be processed
1622	1642		procedure destroywindow;
1623	1643
1624	1644		// registers the instance of onself in the "owner" widget, allocates the canvas,
1625	1645		// adds a reference to oneself,
1626	1646		// then prepares the "owner" hierarchy to be invalidated ( "owner.rootchanged" )
1627	1647		// since now, the window is allocated and belongs to the "aowner" widget
1628	1648		constructor create(aowner: twidget);
1629	1649
1630	1650		destructor destroy; override;
1631	1651
1632	1652		// adds "method" to the internal list of scroll dependants
1633	1653		procedure registeronscroll(const method: notifyeventty);
1634	1654
1635	1655		// removes "method" from the internal list of scroll dependants
1636	1656		procedure unregisteronscroll(const method: notifyeventty);
1637	1657
1638	1658		// releases mouse if captured, resets the cursor, then enters an event loop for the window,
1639	1659		// TRUE on return if the window is destroyed
1640	1660		function beginmodal: boolean;
1641	1661
1642	1662		* checks if the "sender" window is already modal to avoid circularity,
1643	1663		if not then starts an event loop for the "sender" where the "sender" is a receiver of GUI events,
1644	1664		once the loop is terminated reactivates the previously active window if it was,
1645	1665		TRUE if modalwindow destroyed
1646	1666
1647	1667		function tinternalapplication.beginmodal(const sender: twindow): boolean;
1648	1668
1649	1669		// removes the internal stuff which indicates the modal state
1650	1670		procedure endmodal;
1651	1671
1652	1672		// if the window is visible,
1653	1673		// deactivates the previously active window, shows the window (see below),
1654	1674		// if no active window in the app or the window or its Z-predecessor is modal and
1655	1675		// the app has no focused widget then prepares the bound widget to be focused,
1656	1676		// then addresses the WM to put the window to foreground
1657	1677		procedure activate;
1658	1678
1659	1679		// if the bound widget has visible=true then:
1660	1680		// - if NOT windowevent then :
1661	1681		// = address the WM to set size of the window acc to window opts
1662	1682		// wp_maximized, wp_fullscreen or normal size otherwise
1663	1683		// = if the window is normally sized, moves it to its default position is specified ( screen centered etc )
1664	1684		// - unhides/unminimizes the window if needed
1665	1685		// - shows other windows of the applications acc to state of the window group
1666	1686		// ( in normal size or minimized )
1667	1687
1668	1688		private
1669	1689		procedure twindow.show(windowevent: boolean);
1670	1690
1671	1691		// TRUE if this window currently grabs user input
1672	1692		( a widget drawn within the window(=form) is in focus,.. )
1673	1693		function active: boolean;
1674	1694
1675	1695		// if the window was active then deactivates the window & remembers it as the previous active ( to restore leater if requested ),
1676	1696		// returns TRUE if that storage occurred
1677	1697		function deactivateintermediate: boolean;
1678	1698
1679	1699		// makes the window active & clears the above app reference to it ( "active before deactivating" )
1680	1700		procedure reactivate; //clears app.finactivewindow
1681	1701
1682	1702		// scans the app event queue for "ek_expose" event[s] addressed to the window,
1683	1703		// if found then redraws that part of the window which the event describes
1684	1704		// ( processed events are then deleted )
1685	1705		procedure update;
1686	1706
1687	1707		// TRUE if the window :
1688	1708		// 1) doesn't have an inner widget grabbing input focus
1689	1709		// or
1690	1710		// 2) has such widget, and this widget ( and all its descendants )
1691	1711		// pass "CanClose" check
1692	1712		//
1693	1713		// * see also "twidget.CanClose" *
1694	1714		//
1695	1715		function candefocus: boolean;
1696	1716
1697	1717		// tries to defocus the currently focused widget if it belongs to the window,
1698	1718		// if succeeds then executes code of virtual "DoDefocus" of the widget descessor
1699	1719		// ( this code defines behaviour & look of the widget on defocusing );
1700	1720		//
1701	1721		// no defocusing is done if the focused widget ( or its descendants )
1702	1722		// doesn't pass "CanClose" check
1703	1723		//
1704	1724		procedure nofocus;
1705	1725
1706	1726		// setfocusedwidget(widget)
1707	1727
1708	1728		property focuscount: cardinal read ffocuscount;
1709	1729		function close: boolean; //true if ok
1710	1730		procedure beginmoving; //lock window rect modification
1711	1731		procedure endmoving;
1712	1732		procedure bringtofront;
1713	1733		procedure sendtoback;
1714	1734		procedure stackunder(const predecessor: twindow);
1715	1735		//stacking is performed in mainloop idle, nil means top
1716	1736		procedure stackover(const predecessor: twindow);
1717	1737		//stacking is performed in mainloop idle, nil means bottom
1718	1738		function stackedunder: twindow; //nil if top
1719	1739		function stackedover: twindow; //nil if bottom
1720	1740		function hastransientfor: boolean;
1721	1741
1722	1742		procedure capturemouse;
1723	1743		procedure releasemouse;
1724	1744		procedure postkeyevent(const akey: keyty;
1725	1745		const ashiftstate: shiftstatesty = []; const release: boolean = false;
1726	1746		const achars: msestring = '');
1727	1747
1728	1748		function winid: winidty;
1729	1749		function haswinid: boolean;
1730	1750		function state: windowstatesty;
1731	1751		function visible: boolean;
1732	1752		function activating: boolean; //in internalactivate proc
1733	1753		function normalwindowrect: rectty;
1734	1754		property updateregion: regionty read fupdateregion;
1735	1755		function updaterect: rectty;
1736	1756
1737	1757		procedure registermovenotification(sender: iobjectlink);
1738	1758		procedure unregistermovenotification(sender: iobjectlink);
1739	1759
1740	1760		property options: windowoptionsty read foptions;
1741	1761
1742	1762		// widget
1743	1763		property owner: twidget read fowner;
1744	1764
1745	1765		property focusedwidget: twidget read ffocusedwidget;
1746	1766		property transientfor: twindow read ftransientfor;
1747	1767		property modalresult: modalresultty read fmodalresult write setmodalresult;
1748	1768		property buttonendmodal: boolean read getbuttonendmodal write setbuttonendmodal;
1749	1769		property globalshortcuts: boolean read getglobalshortcuts write setglobalshortcuts;
1750	1770		property localshortcuts: boolean read getlocalshortcuts write setlocalshortcuts;
1751	1771		property windowpos: windowposty read getwindowpos write setwindowpos;
1752	1772		property caption: msestring read fcaption write setcaption;
1753	1773
1754	1774		windowoptionty = (wo_popup,wo_message,wo_buttonendmodal,wo_groupleader,
1755	1775		wo_windowcentermessage); //showmessage centered in window
1756	1776
1757	1777		optionswindow:
1758	1778		wo_popup
1759	1779		- in run-time, hides all OS windows-manager ( WM ) decorations (title bar, buttons "Close/Resize,Min/Max" etc),
1760	1780		letting only its client area to appear
1761	1781		so :
1762	1782		= the window should have own facilities to replace the deactivated WM functionality if needed
1763	1783		= can't be resized/maximize/minimized/moved
1764	1784		wo_message
1765	1785		- similar to "wo_popup" but allows WM to close ( with "Close" button ) & move the window
1766	1786
1767	1787		wo_groupleader
1768	1788		- keeps on the WM taskbar a shortcut to the window
1769	1789		( if the parent window is a groupleader too then displays a step upper in its group )
1770	1790
1771	1791		Event handlers:
1772	1792
1773	1793		- onmove
1774	1794		= fires once the (window/widget) is created/moved ( with check if really moved by a distance)
1775	1795
1776	1796		### TFormScrollbox
1777	1797
1778	1798		- presents client area of form & parent of its widgets,
1779	1799		initially stretched to fit the form & bound with anchoring
1780	1800		but may be adjusted with "bounds" & "anchors"
1781	1801
1782	1802		Properties:
1783	1803
1784	1804		anchors
1785	1805		bounds
1786	1806
1787	1807		color
1788	1808		- color of the whole container area ( except its frame ) & form widgets
1789	1809		if their color is "cl_parent"
1790	1810
1791	1811		name = container
1792	1812
1793	1813		cursor, enabled, face, frame, helpcontext, hint, optionswidget, popupmenu,
1794	1814		taborder, tag, visible, onactivate, onafterpaint, onbeforepaint,
1795	1815		onchildmouseevent, onclientmouseevent, ondeativate, ondefocus, onenter,
1796	1816		onexit, onfocus, onfontheightdelta, onmouseevent, onpaint, onpopup
1797	1817		onresize, onshowhint
1798	1818		- the same meaning as for the served form
1799	1819
1800	1820		oncalcminscrollsize
1801	1821		onscroll
1802	1822		onchildscaled
1803	1823
1804	1824		### TFaceList
1805	1825
1806	1826		### TFrameComp
1807	1827
1808	1828		See also here: [[Reference: MSEgui/TFrame]].
1809	1829
1810	1830		Terminology :
1811	1831
1812	1832		{client area = area of the widget which interacts with a user}
1813	1833
1814	1834		{bevelling = additional facets rising/sinking frame & client area,
1815	1835		constists of two parts -
1816	1836		- external: between frame and widget
1817	1837		- internal: between frame and client area
1818	1838		}
1819	1839
1820	1840		{frame= flat space between external & internal facets,
1821	1841		floats at the inner level of the external facet
1822	1842		}
1823	1843
1824	1844		* Both frame & bevelling affect the client area *
1825	1845
1826	1846		--------------------------
1827	1847		template:
1828	1848
1829	1849		colorclient = color of the client area
1830	1850
1831	1851		colorframe = color of the frame
1832	1852		colorframeactive = used instead of colorframe if the widget is
1833	1853		active; "cl_default" means same as colorframe.
1834	1854
1835	1855		works if (leveli/levelo <> 0 that's the facets exist :
1836	1856
1837	1857		colorshadow = color of facets screened from the NW light source
1838	1858		colordkshadow = color of shadows dropped by the NW light source
1839	1859		colordkwidth = width of the shadows in pixel, -1=default
1840	1860
1841	1861		colorlight = color of facets exposed to the NW light source
1842	1862		colorhighlight = color of brighter edges of the facets
1843	1863		colorhlwidth = width of the brighter edges in pixel, -1=default
1844	1864
1845	1865		extraspace = if applied to menu items, adds more space between these items
1846	1866
1847	1867		framei_:
1848	1868		(for extendable widgets like menus, these settings widen the widget,
1849	1869		for non-extendable like buttons - they squeeze the text area )
1850	1870
1851	1871		bottom= lower margin of text to the client area
1852	1872		left = left margin of text to the client area
1853	1873		right = margin of text to the client area
1854	1874		top = upper margin of text to the client area
1855	1875
1856	1876		framewidth= width of the frame
1857	1877		leveli = {width=height} of the internal facet, positive -> raised, negative -> sunken
1858	1878		levelo = {width=height} of the external facet, positive -> raised, negative -> sunken
1859	1879
1860	1880		<any frame>
1861	1881
1862	1882		* extends & customizes "tframecomp" *
1863	1883
1864	1884		template
1865	1885		- "tframecomp" supplying the initial settings
1866	1886
1867	1887		colorclient,colordkshadow,colordkwidth,colorframe,colorframeactive,
1868	1888		colorhighlight,colorhlwidth,colorlight,colorshadow,framewidth,
1869	1889		leveli, levelo, framei_*,
1870	1890
1871	1891		<see "tframecomp">
1872	1892
1873	1893		font
1874	1894		<see "tfont">
1875	1895
1876	1896		caption
1877	1897		- some descriptive text( function name, user prompt,...) placed
1878	1898		in a N/W/S/E-combination to the widget's client area
1879	1899
1880	1900		***
1881	1901		non-empty caption if (captionpos <> cp_center) & (captiondistouter=false & captiondist>0) enlarges the framed widget
1882	1902		by the corresponding size of caption
1883	1903
1884	1904		***
1885	1905
1886	1906		captiondist - margin between the caption & the client area
1887	1907
1888	1908		captiondistouter :
1889	1909
1890	1910		- if "false"(by default), the distance is measured between
1891	1911		the inner (facing the client area) extent of the caption
1892	1912		and the client area outward the area,
1893	1913		the caption is placed outside of the client area
1894	1914
1895	1915		- if "true", the caption is mirrored against the edge of client area as
1896	1916		to the position when "false"
1897	1917
1898	1918		* nagative values of "captiondist" visually inverse "out of" and within *
1899	1919
1900	1920		captionnoclip - do not clip frame and client area for caption background
1901	1921		( the client area preserves own background under the caption text)
1902	1922
1903	1923		captionnooffset - shift orthogonal to "captiondist"
1904	1924
1905	1925		captionpos - "corner" where to place the caption
1906	1926
1907	1927		localprops :
1908	1928
1909	1929		frl_levelo - "levelo" overrides "template.levelo"
1910	1930		frl_leveli - "leveli" overrides "template.leveli"
1911	1931		frl_framewidth - "framewidth" overrides "template.framewidth"
1912	1932		frl_colorclient - "colorclient" overrides "template.colorclient"
1913	1933		frl_colorframe - "colorframe" overrides "template.colorframe"
1914	1934		frl_colorframeactive - "colorframeactive" overrides "template.colorframeactive"
1915	1935		frl_colordkshadow - "colordkshadow" overrides "template.colordkshadow"
1916	1936		frl_colorshadow - "colorshadow" overrides "template.colorshadow"
1917	1937		frl_colorlight - "colorlight" overrides "template.colorlight"
1918	1938		frl_colorhighlight - "colorhighlight" overrides "template.colorhighlight"
1919	1939		frl_colordkwidth - "colordkwidth" overrides "template.colordkwidth"
1920	1940		frl_colorhlwidth - "colorhlwidth" overrides "template.colorhlwidth"
1921	1941		frl_fileft - "framei_left" overrides "template.framei_left"
1922	1942		frl_firight - "framei_right" overrides "template.framei_right"
1923	1943		frl_fitop - "framei_top" overrides "template.framei_top"
1924	1944		frl_fibottom - "framei_bottom" overrides "template.framei_bottom"
1925	1945
1926	1946		frl_nodisable
1927	1947
1928	1948		### TFaceComp
1929	1949
1930	1950		See also here: <https://wiki.freepascal.org/Reference:_MSEgui/TFace>
1931	1951
1932	1952		- doesn't affect the widget frame but client area of the frame
1933	1953
1934	1954		template:
1935	1955		fade:
1936	1956		color[i]: = colors forming the fade
1937	1957		direction: = direction where the fade grows to
1938	1958		gd_(right/up/left/down)
1939	1959
1940	1960		pos[i]: = relational position of color[i] on the direction (0.0..1.0) extent
1941	1961
1942	1962		transparency = makes the face half-transparent and enlighten the underlying widget
1943	1963		with a light source of the selected color
1944	1964		( in this case, colors of the face & the widget & the light source
1945	1965		simply summarize to higher brightness )
1946	1966
1947	1967		image:
1948	1968		see <any image>
1949	1969
1950	1970		options:
1951	1971
1952	1972		*** The fade colors are used not as colors but RGB alpha values ($00 -> opaque, $ff -> transparent)
1953	1973		if fao_alpha* are set *** :
1954	1974
1955	1975		fao_alphafadeall = applies blending to the widget & all its children
1956	1976		fao_alphafadenochildren = preserves child widgets from blending
1957	1977		fao_alphafadeimage = applies blending to "face.image"
1958	1978
1959	1979		<any face>
1960	1980
1961	1981		* extends & customizes "tfacecomp" *
1962	1982
1963	1983		fade, image, option
1964	1984		- see "tfacecomp"
1965	1985
1966	1986		template
1967	1987		- "tfacecomp" supplying the initial settings
1968	1988
1969	1989		localprops :
1970	1990		fal_options - "options" overrides "template.options"
1971	1991		fal_fadirection - "fade.direction" overrides "template.fade.direction"
1972	1992		fal_image - "image" overrides "template.image"
1973	1993		fal_fapos - "fade.pos[i]" overrides "template.fade.pos[i]"
1974	1994		fal_facolor - "fade.color[i]" overrides "template.fade.color[i]"
1975	1995		fal_fatransparency - "fade.transparency" overrides "template.fade.transparency"
1976	1996
1977	1997		### TBitmapComp
1978	1998
1979	1999		### TScalingwidget
1980	2000
1981	2001		optionsscale :
1982	2002		autosizing to provide room for :
1983	2003		= {"frame.caption" + "offset_*"}
1984	2004		= "offset_" if "frame.caption" is unset and "osc_shrink" is set
1985	2005
1986	2006		= osc_expandx
1987	2007		- makes the widget wider to fit the caption if needed
1988	2008
1989	2009		= osc_shrinkx
1990	2010		- makes the widget narrower to have no space left & right to the "frame.caption"
1991	2011
1992	2012		= osc_expandy
1993	2013		- makes the widget taller to fit the caption if needed
1994	2014
1995	2015		= osc_shrinky
1996	2016		- makes the widget lower to have no space up & down to the "frame.caption"
1997	2017
1998	2018		= osc_invisishrinkx
1999	2019		- fully h-collapses if "visible=false" ( run-time only )
2000	2020
2001	2021		= osc_invisishrinky
2002	2022		- fully v-collapses if "visible=false" ( run-time only )
2003	2023
2004	2024		### TImageList
2005	2025
2006	2026		### TPopupMenu
2007	2027
2008	2028		### TMainMenu
2009	2029
2010	2030		## Dialog
2011	2031
2012	2032		### TFileListview
2013	2033
2014	2034		### TFileDialog
2015	2035
2016	2036		### TFaceComp
2017	2037
2018	2038		### TFileNameEdit
2019	2039
2020	2040		### TDirDropdownEdit
2021	2041
2022	2042		### TColorEdit
2023	2043
2024	2044		### TMemoDialogEdit
2025	2045
2026	2046		### TPageSizeSelector
2027	2047
2028	2048		### TPageOrientationSelector
2029	2049
2030	2050		## Application
2031	2051
2032	2052		### TGuiApplication
2033	2053
2034	2054		tguiapplication = class(tcustomapplication)
2035	2055		public
2036	2056
2037	2057		// [re]starts the system timer with the new period and
2038	2058		// subscribes the application to be a receiver of the modified "ek_timer" event
2039	2059		// ( can check for it in the event queue )
2040	2060		procedure settimer(const us: integer);
2041	2061
2042	2062		// finds a window by its winID
2043	2063		function findwindow(id: winidty; out window: twindow): boolean;
2044	2064
2045	2065		// finds a window by its ID & adjusts "rect" so that it
2046	2066		// fits "bounds_minc" & "bounds_maxc" of the found window
2047	2067		procedure checkwindowrect(winid: winidty; var rect: rectty);
2048	2068
2049	2069		// initialises the timer and "megraphics"
2050	2070		procedure initialize;
2051	2071
2052	2072		// frees the allocated system resources (GDI, event subscription, the timer)
2053	2073		procedure deinitialize;
2054	2074
2055	2075		// creates a form instance, it will be shown in "application.run"
2056	2076		procedure createform(instanceclass: widgetclassty; var reference);
2057	2077
2058	2078		// invalidates all registered forms ( all their widgets will be redrawn )
2059	2079		procedure invalidate;
2060	2080
2061	2081		// calls a nested main event loop, forces processing any pending messages,
2062	2082		procedure processmessages; override; //handle with care!
2063	2083
2064	2084		// TRUE if no pending events to process for the application
2065	2085		function idle: boolean; override;
2066	2086
2067	2087		// requests to indicate waiting ( to show the "watches" cursors )
2068	2088		procedure beginwait; override;
2069	2089
2070	2090		// removes the "watches" if no unclosed requests for displaying them,
2071	2091		// otherwise closes the currently active request
2072	2092		procedure endwait; override;
2073	2093
2074	2094		// TRUE if there are unclosed requests for displaying "watches"
2075	2095		function waiting: boolean;
2076	2096
2077	2097		// TRUE if ESC has just been pressed
2078	2098		// - if all requests for displaying "watches" are closed then refreshes
2079	2099		// the internal list of events ( the GUI-queue -> the app event list)
2080	2100		function waitescaped: boolean; //true if escape pressed while waiting
2081	2101
2082	2102		// sets state of the current wait dialogue ( but doesn't close one ) to undefined
2083	2103		procedure resetwaitdialog;
2084	2104
2085	2105		// runs "aexecuteaction" in the main thread in OnIdle mode,
2086	2106		// then shows a cancellable message,
2087	2107		// if the one is cancelled then runs "acancelaction" then
2088	2108		// either fully clears (if exceptions occur )
2089	2109		// or terminates the execution otherwise,
2090	2110		// true if not cancelled;
2091	2111		// "application.processmessages" must be called regularly if "aexecuteaction" is used here,
2092	2112		// alternatively "aidleaction" can be used, call sleep ( some time ) in order to minimize
2093	2113		// processor load.
2094	2114		// If athread <> nil the function starts and terminates the thread
2095	2115		function waitdialog(const athread: tthreadcomp = nil; const atext: msestring = '';
2096	2116		const caption: msestring = '';
2097	2117		const acancelaction: notifyeventty = nil;
2098	2118		const aexecuteaction: notifyeventty = nil): boolean; override;
2099	2119
2100	2120		// closes the currently modal waitdialogue with "cancelled" state
2101	2121		procedure cancelwait;
2102	2122
2103	2123		// closes the currently modal waitdialogue with "ok" state
2104	2124		procedure terminatewait;
2105	2125
2106	2126		function waitstarted: boolean; // the last waitdialogue is currently showing for some requests
2107	2127		function waitcanceled: boolean; // the last waitdialogue has been cancelled for some request (but can be shown fot others ?)
2108	2128		function waitterminated: boolean; // the last waitdialogue has been terminated for some request (but can be shown fot others ?)
2109	2129
2110	2130		// if called from the main app thread then shows as a modal message describing the exception
2111	2131		// otherwise posts an async event for which the message will be called
2112	2132		procedure showexception(e: exception; const leadingtext: string = ''); override;
2113	2133
2114	2134		// posts an async event for which the message describing the exception will be called
2115	2135		procedure showasyncexception(e: exception; const leadingtext: string = '');
2116	2136
2117	2137		// "application.errormessage" shows standard error message ( with "ERROR" title )
2118	2138		procedure errormessage(const amessage: msestring); override;
2119	2139
2120	2140		// [re]calculates timings & position of hint for "ahintedwidget"
2121	2141		// if "ow_timedhint" in "ahintedwidget.foptionswidget" then iys showtime will be
2122	2142		// "defaulthintshowtime" ( an app wide setting, 3sec by default)
2123	2143		procedure inithintinfo(var info: hintinfoty; const ahintedwidget: twidget);
2124	2144
2125	2145		// shows the supplied hint text within "aposrect" with alignment "aplacement" during "ashowtime",
2126	2146		// the avail ( but not used currenly ) flags are : hfl_show,hfl_custom,hfl_noautohidemove,hfl_noautohidemove
2127	2147		procedure showhint(const sender: twidget; const hint: msestring;
2128	2148		const aposrect: rectty; const aplacement: captionposty = cp_bottomleft;
2129	2149		const ashowtime: integer = defaulthintshowtime; //0 -> inifinite,
2130	2150		// -1 defaultshowtime if ow_timedhint in sender.optionswidget
2131	2151		const aflags: hintflagsty = defaulthintflags
2132	2152		); overload;
2133	2153
2134	2154		// shows the supplied hint text at left-top position"apos" during "ashowtime",
2135	2155		// the avail ( but not used currenly ) flags are : hfl_show,hfl_custom,hfl_noautohidemove,hfl_noautohidemove
2136	2156		procedure showhint(const sender: twidget; const hint: msestring;
2137	2157		const apos: pointty;
2138	2158		const ashowtime: integer = defaulthintshowtime; //0 -> inifinite,
2139	2159		// -1 defaultshowtime if ow_timedhint in sender.optionswidget
2140	2160		const aflags: hintflagsty = defaulthintflags
2141	2161		); overload;
2142	2162
2143	2163		// shows the hint fully defined in "info" for the widget "sender"
2144	2164		procedure showhint(const sender: twidget; const info: hintinfoty); overload;
2145	2165
2146	2166		// removes the current hint widget & frees its resources & stops its stop timer
2147	2167		procedure hidehint;
2148	2168
2149	2169		// restarts the current hint and its stop timer
2150	2170		procedure restarthint(const sender: twidget);
2151	2171
2152	2172		function hintedwidget: twidget; //last hinted widget
2153	2173		function activehintedwidget: twidget; //nil if no hint active
2154	2174
2155	2175		// returns helpcontext of active widget, '' if none;
2156	2176		function activehelpcontext: msestring;
2157	2177
2158	2178		// returns helpcontext of the widget under mouse, '' if none;
2159	2179		function mousehelpcontext: msestring;
2160	2180
2161	2181		// TRUE if one of the app's window/console is in input focus
2162	2182		function active: boolean;
2163	2183
2164	2184		// returns the desktop resolution ( or the virtual one if used )
2165	2185		function screensize: sizety;
2166	2186
2167	2187		// returns the (virtual) desktop resolution except the tray area,
2168	2188		// nil -> current active window
2169	2189		function workarea(const awindow: twindow = nil): rectty;
2170	2190
2171	2191		// returns which application window ( a form not an eventwidget, an openglwidget or a windowwidget !)
2172	2192		// is active ( provides the input focus ),
2173	2193		// it's same for all widgets of the form served by this window
2174	2194		function activewindow: twindow;
2175	2195
2176	2196		/ * A transient window is a descendant of ( "transientfor" ) another window in the stacking order hierarchy */
2177	2197
2178	2198		// returns a first non-transient ( on top of the app stacking order ) window upward
2179	2199		// from the currently active window of the application.
2180	2200		// or that active window if no such
2181	2201		function regularactivewindow: twindow;
2182	2202
2183	2203		// same as "activewindow" but the window must not be released (?)
2184	2204		function unreleasedactivewindow: twindow;
2185	2205
2186	2206		// returns the focused widget of the currently active window if one exists
2187	2207		function activewidget: twidget;
2188	2208
2189	2209		// returns the widget presenteing the currently active window
2190	2210		function activerootwidget: twidget;
2191	2211
2192	2212		// returns the window ( not hidden or disabled !) under the screen point "pos"
2193	2213		function windowatpos(const pos: pointty): twindow;
2194	2214
2195	2215		// puts to "awidget" the container of widget pointed by "namepath"
2196	2216		// ( finalizing "." is discarded if found ) ,
2197	2217		// FALSE if not found, and NIL and TRUE if "namepath" = ''
2198	2218		function findwidget(const namepath: string; out awidget: twidget): boolean;
2199	2219
2200	2220		// rebuilds the application's window list accorrding to the current on-screen Z-order of its windows;
2201	2221		// window list is ordered by "z" - bottom first & top last;
2202	2222		// invisibles first
2203	2223		procedure sortzorder;
2204	2224
2205	2225		// returns a copy of the internal window list of application
2206	2226		function windowar: windowarty;
2207	2227
2208	2228		// returns the list of application window winIDs
2209	2229		function winidar: winidarty;
2210	2230
2211	2231		// returns the count of the application windows
2212	2232		function windowcount: integer;
2213	2233
2214	2234		// returns the window by its number ( "index" >= 0) in the application window list
2215	2235		property windows[const index: integer]: twindow read getwindows;
2216	2236
2217	2237		// returns the lowest visible window in stackorder,
2218	2238		// calls "sortzorder" within
2219	2239		function bottomwindow: twindow;
2220	2240
2221	2241		// returns the highest visible window in stackorder,
2222	2242		// calls "sortzorder" within
2223	2243		function topwindow: twindow;
2224	2244
2225	2245		// TRUE if all owned windows pass "CanClose" check or
2226	2246		// don't have focused widgets
2227	2247		function candefocus: boolean;
2228	2248
2229	2249		// subscribes the handler "method" to receive keyboard events
2230	2250		procedure registeronkeypress(const method: keyeventty);
2231	2251
2232	2252		// unsubscribes the handler "method" from receiving keyboard events
2233	2253		procedure unregisteronkeypress(const method: keyeventty);
2234	2254
2235	2255		// subscribes the handler "method" to receive shortcut events
2236	2256		procedure registeronshortcut(const method: keyeventty);
2237	2257
2238	2258		// unsubscribes the handler "method" from receiving shortcut events
2239	2259		procedure unregisteronshortcut(const method: keyeventty);
2240	2260
2241	2261		// subscribes the handler "method" to receive "OnWindowActiveChanged" event ( form-wide )
2242	2262		procedure registeronactivechanged(const method: activechangeeventty);
2243	2263
2244	2264		// unsubscribes the handler "method" from receiving "OnWindowActiveChanged" event ( form-wide )
2245	2265		procedure unregisteronactivechanged(const method: activechangeeventty);
2246	2266
2247	2267		// subscribes the handler "method" to receive "OnDestroyed" events ( form-wide )
2248	2268		procedure registeronwindowdestroyed(const method: windoweventty);
2249	2269
2250	2270		// unsubscribes the handler "method" from receiving "OnDestroyed" events ( form-wide )
2251	2271		procedure unregisteronwindowdestroyed(const method: windoweventty);
2252	2272
2253	2273		// subscribes the handler "method" to receive "OnWindowDestroyed" events ( form-wide )
2254	2274		procedure registeronwiniddestroyed(const method: winideventty);
2255	2275
2256	2276		// unsubscribes the handler "method" form receiving "OnWindowDestroyed" events ( form-wide )
2257	2277		procedure unregisteronwiniddestroyed(const method: winideventty);
2258	2278
2259	2279		// subscribes the handler "method" to receive "ApplicationActiveChanged" events ( form-wide )
2260	2280		procedure registeronapplicationactivechanged(const method: booleaneventty);
2261	2281
2262	2282		// unsubscribes the handler "method" from receiving "ApplicationActiveChanged" events ( form-wide )
2263	2283		procedure unregisteronapplicationactivechanged(const method: booleaneventty);
2264	2284
2265	2285		// tcustomapplication
2266	2286
2267	2287		// subscribes the handler "method" to receive "OnTerminated" event ( form-wide )
2268	2288		procedure registeronterminated(const method: notifyeventty);
2269	2289
2270	2290		// unsubscribes the handler "method" from receiving "OnTerminated" events ( form-wide )
2271	2291		procedure unregisteronterminated(const method: notifyeventty);
2272	2292
2273	2293		// subscribes the handler "method" to receive "OnTerminateQuery" event ( form-wide )
2274	2294		procedure registeronterminate(const method: terminatequeryeventty);
2275	2295
2276	2296		// unsubscribes the handler "method" from receiving "OnTerminateQuery" event ( form-wide )
2277	2297		procedure unregisteronterminate(const method: terminatequeryeventty);
2278	2298
2279	2299		// subscribes the handler "method" to receive "OnIdle" event ( form-wide )
2280	2300		procedure registeronidle(const method: idleeventty);
2281	2301
2282	2302		// unsubscribes the handler "method" from receiving "OnIdle" events ( form-wide )
2283	2303		procedure unregisteronidle(const method: idleeventty);
2284	2304
2285	2305		// calls "canclose" of all application windows except the "sender" window
2286	2306		// if all "canclose"are TRUE then checks "OnTerminateQuery"
2287	2307		// for all its subscribers ( usually forms of the application )
2288	2308		procedure terminate(const sender: twindow = nil);
2289	2309
2290	2310		// TRUE as long as a "terminate" call is in progress
2291	2311		function terminating: boolean;
2292	2312
2293	2313		// TRUE as long as a "deinitialize" call is in progress
2294	2314		function deinitializing: boolean;
2295	2315
2296	2316		// returns the current caret object ( the text input focus indicator ) of the application
2297	2317		/ ( this object provides facilities to control position & appearance & visibility & timings of the caret )
2298	2318		property caret: tcaret read fcaret;
2299	2319
2300	2320		// returns the current mouse object of the application
2301	2321		/ ( this object provides facitities to control position & appearance of the mouse )
2302	2322		property mouse: tmouse read fmouse;
2303	2323
2304	2324		// simulates mouseparkevent
2305	2325		// ( an adjusting mouse movement without user intervention - grid snapping, docking etc ?)
2306	2326		procedure mouseparkevent;
2307	2327
2308	2328		// sets mouse position correction for further mouse events,
2309	2329		// the real position is less the visual one by the supplied shift
2310	2330		procedure delayedmouseshift(const ashift: pointty);
2311	2331
2312	2332		// returns/sets a cursor shape used for widgets having their cursor shape set to "cr_default";
2313	2333		// setting it to "cr_default" restores the individual widget cursor(s)
2314	2334		property widgetcursorshape: cursorshapety read fwidgetcursorshape write
2315	2335		fwidgetcursorshape;
2316	2336
2317	2337		// returns/sets the current application-wide cursor shape ( not "watches" if a waiting dialog is currently displayed ! )
2318	2338		// or request to set a new cursor shape ( app-wide );
2319	2339		// doesn't change when changing mouse widgets
2320	2340		//
2321	2341		// if called from a non-main app thread & no waiting dialogue displayed then redraws
2322	2342		// the cursor immediately;
2323	2343		// set it to "cr_default" to restore the shape to one set by "widgetcursorshape"
2324	2344		//
2325	2345		property cursorshape: cursorshapety; // cr_arrow, cr_*
2326	2346
2327	2347		// assures the displayed mouse cursor shape to be the shape assigned to the currently under-mouse widget,
2328	2348		// otherwise "cr_default"
2329	2349		procedure updatecursorshape; //restores cursorshape of mousewidget
2330	2350
2331	2351		// returns a widget of the application where the mouse is currently positioned over
2332	2352		property mousewidget: twidget read fmousewidget;
2333	2353
2334	2354		// returns a widget of the application currently "owning" the mouse ( grabbing all mouse input )
2335	2355		property mousecapturewidget: twidget read fmousecapturewidget;
2336	2356
2337	2357		// returns/sets a window to become the main window of the application
2338	2358		// then resets all other application windows to the window group it belongs to ( Linux only );
2339	2359		//
2340	2360		// the main window minimizes all windows if minimized;
2341	2361		property mainwindow: twindow read fmainwindow write setmainwindow;
2342	2362
2343	2363		// returns which system thread was allocated to the application on its start
2344	2364		// ( the main thread )
2345	2365		property thread: threadty read fthread;
2346	2366
2347	2367		// returns teh widget where a mouse button click occured last time
2348	2368		// ( to compare with when determinibg whether another widget is clicked )
2349	2369		property buttonpresswidgetbefore: twidget read fbuttonpresswidgetbefore;
2350	2370
2351	2371		// returns teh widget where a mouse button release occured last time
2352	2372		// ( to compare with when determinibg whether another widget is clicked )
2353	2373		property buttonreleasewidgetbefore: twidget read fbuttonreleasewidgetbefore;
2354	2374
2355	2375		// returns/sets the interval of mouse double click recognition ( in microsecs ),
2356	2376		// defaults to 0.4 sec
2357	2377		property dblclicktime: integer read fdblclicktime write fdblclicktime default
2358	2378		defaultdblclicktime; //us
2359	2379
2360	2380		// tcustomapplication
2361	2381
2362	2382		// creates a datamodule instance ( its startup code including "OnLoaded" is executed )
2363	2383		procedure createdatamodule(instanceclass: msecomponentclassty; var reference);
2364	2384
2365	2385		// enters the application event loop;
2366	2386		//
2367	2387		// once the loop finishes, performs "OnTerminated" for all its subscribers,
2368	2388		// destroys all application forms ( components & windows )
2369	2389		procedure run;
2370	2390
2371	2391		// TRUE if the eventloop is entered
2372	2392		function running: boolean;
2373	2393
2374	2394		// returns/sets the application name
2375	2395		// ( defaults to the full path to application executable in the native OS format );
2376	2396		// currently, only for informatiion query purposes
2377	2397		property applicationname: msestring read fapplicationname write fapplicationname;
2378	2398
2379	2399
2380	2400		// if exclusive "rights" are satisfied for the main thread ( a mutex lock is OK ) & the event loop is in progress
2381	2401		// then posts the "event" to the main application thread for asyc processing,
2382	2402		// otherwise adds the event to the internal list for further handling as soon as the above conditions meet
2383	2403		procedure postevent(event: tevent);
2384	2404
2385	2405		// TRUE if never idle since last call,
2386	2406		// unlocks the application and calls sleep if not mainthread and asleepus >= 0
2387	2407		function checkoverload(const asleepus: integer = 100000): boolean;
2388	2408
2389	2409		// returns/sets the application exception handler
2390	2410		property onexception: exceptioneventty read fonexception write fonexception;
2391	2411
2392	2412		// if not "eabort" & no unhandled exceptions,
2393	2413		// executes the above "OnException" code if assigned
2394	2414		// or shows an exception message otherwise;
2395	2415		procedure handleexception(sender: tobject = nil;
2396	2416		const leadingtext: string = '');
2397	2417
2398	2418		// synchronizes the calling thread with the main event loop ( via a mutex),
2399	2419		// TRUE if the calling thread allready holds the mutex,
2400	2420		// the mutex is recursive
2401	2421		function lock: boolean;
2402	2422
2403	2423		// tries to synchronize the calling thread with the main event loop ( via a mutex)
2404	2424		function trylock: boolean;
2405	2425
2406	2426		// releases the mutex if the calling thread holds the mutex,
2407	2427		// TRUE if no unlock done
2408	2428		function unlock: boolean;
2409	2429
2410	2430		// releases the mutex recursively if the calling thread holds the mutex,
2411	2431		// returns "count" for the below "relockall"
2412	2432		function unlockall: integer;
2413	2433
2414	2434		// regains the mutex to serve "count" locks
2415	2435		procedure relockall(count: integer);
2416	2436
2417	2437		// creates a syncronize event ( which will fire asyncronously then waits for another thread will allow it to finish ), assigns "proc" to it as the event handler,
2418	2438		// then frees all locks temporarily then posts the event to the app event queue & waits fot it to be processed the resores the locks;
2419	2439		//
2420	2440		// TRUE if not aborted, quiet -> shows no exceptions if occurs
2421	2441		//
2422	2442		// the "syncronize event" is an event owning a semaphore which can be touched by another thread
2423	2443		// thus causing "event.waitfo" to return & to exec the event handler code
2424	2444		//
2425	2445		function synchronize(const proc: objectprocty;
2426	2446		const quite: boolean = false): boolean;
2427	2447
2428	2448		// TRUE if the calling ( this function ) thread is the application main thread
2429	2449		function ismainthread: boolean;
2430	2450
2431	2451		// TRUE if the currently locked thread is the application main thread
2432	2452		function islockthread: boolean;
2433	2453
2434	2454		// waith for "athread" to terminate,
2435	2455		// does "unlock-relock" around waiting
2436	2456		procedure waitforthread(athread: tmsethread);
2437	2457
2438	2458		// post a "nothing-to-do" event for asynchronous processing in the main thread
2439	2459		procedure wakeupmainthread;
2440	2460
2441	2461		// invalidates all registered forms of the application so that their widgets redraw land-specific captions
2442	2462		// ( changed by "mseconsts.setlangconsts" ),
2443	2463		// called internally in "setlangconsts" before return
2444	2464		procedure langchanged; virtual;
2445	2465
2446	2466		// returns/sets "aps_terminated" state flag ( no actions ? )
2447	2467		// this flag is also set internally by "terminate" if not cancelled
2448	2468		property terminated: boolean read getterminated write setterminated;
2449	2469
2450	2470		// returns the number of "handleexception" calls having an effect ( a message or the handler code )
2451	2471		property exceptioncount: longword read fexceptioncount;
2452	2472
2453	2473		private
2454	2474		// function tinternalapplication.beginmodal(const sender: twindow): boolean;
2455	2475
2456	2476		## DB
2457	2477
2458	2478		### DBedit
2459	2479
2460	2480		### DBfields
2461	2481
2462	2482		### TDBwidgetgrid
2463	2483
2464	2484		Properties:
2465	2485
2466	2486		anchors - ...
2467	2487		bounds - ...
2468	2488
2469	2489		color
2470	2490		- color of the grid's client area
2471	2491		cursor
2472	2492		- cursor shape when the mouse is over the client area
2473	2493
2474	2494		datacols
2475	2495		colorselect
2476	2496		linecolor
2477	2497		linecolorfix
2478	2498		linewidth
2479	2499		newrowcol
2480	2500
2481	2501		options
2482	2502		co_readonly
2483	2503		co_nofocus
2484	2504		co_invisible
2485	2505		co_disabled
2486	2506		co_drawfocus
2487	2507		co_mousemovefocus
2488	2508		co_lefbuttonfocusonly
2489	2509		co_focusselect
2490	2510		co_mouseselect
2491	2511		co_keyselect
2492	2512		co_multiselect
2493	2513		co_resetselectionexit
2494	2514		co_rowselect
2495	2515		co_fixwidth
2496	2516		co_fixpos
2497	2517		co_fill
2498	2518		co_proportional
2499	2519		co_nohscroll
2500	2520		co_savevalue
2501	2521		co_savestate
2502	2522		co_rowfont
2503	2523		co_rowcolor
2504	2524		co_zebracolor
2505	2525		co_nosort
2506	2526		co_sortdescent
2507	2527		co_norearrange
2508	2528		co_cancopy
2509	2529		co_canpaste
2510	2530		co_mousescrollrow
2511	2531		co_rowdatachange
2512	2532
2513	2533		sortcol
2514	2534		width
2515	2535
2516	2536		items[N]
2517	2537		color
2518	2538		colorselect
2519	2539		datalist - ???
2520	2540		face - see <any face>
2521	2541		fontselect - see <any font>
2522	2542		frame - see <any frame>
2523	2543		linecolor
2524	2544		linecolorfix
2525	2545		linewidth
2526	2546		name
2527	2547
2528	2548		options
2529	2549
2530	2550
2531	2551		### Report
2532	2552
2533	2553		#### TRepSpacer
2534	2554
2535	2555		#### TRecordBand
2536	2556
2537	2557		#### TrepValueDisp
2538	2558
2539	2559		#### TRepPageNumdisp
2540	2560
2541	2561		#### TRepPrintDateDisp
2542	2562
2543	2563		#### TBandGroup
2544	2564
2545	2565		#### TTileArea
2546	2566
2547	2567		## Design
2548	2568
2549	2569		### TGdbMi
2550	2570
2551	2571		### TSyntaxEdit
2552	2572
2553	2573		### TSyntaxPainter
2554	2574
2555	2575		## Comm
2556	2576
2557	2577		### TCommPort
2558	2578
2559	2579		### TAsciiCommPort
2560	2580
2561	2581		### TAsciiProtPort
2562	2582
2563	2583		### TCommSelector
2564	2584
2565	2585		## General stuff
2566	2586
2567	2587		### Properties for all widgets
2568	2588
2569	2589		name
2570	2590
2571	2591		anchors
2572	2592
2573	2593		-----------
2574	2594
2575	2595		- they control of design/runtime sticking widgets to their parents
2576	2596
2577	2597		- dimention pair ( top/bottom or left/right ) both set to "false" cause
2578	2598		the widget to fit the parent's client area in that dimention;
2579	2599		this effect may be partial in case of "bounds_c*max" settings limit the extents
2580	2600
2581	2601		*** Return to the look "before dimention fit" is only possible by manual resizing or setting "bounds_*"
2582	2602		-----------
2583	2603		an_left
2584	2604		- on run-time, resizes/shifts left the widget to keep the design-set distance
2585	2605		between the widget's left border and the left side of parent's client area
2586	2606		as the parent resizes, until scrolling begins
2587	2607
2588	2608		an_top
2589	2609		- on run-time, resizes/shifts up the widget to keep the design-set distance
2590	2610		between the widget's top border and the upper side of parent's client area
2591	2611		as the parent resizes, until scrolling begins
2592	2612
2593	2613		an_right
2594	2614		- on run-time, resizes/shifts right the widget to keep the design-set distance
2595	2615		between the widget's right border and the right side of parent's client area
2596	2616		as the parent resizes, until scrolling begins
2597	2617
2598	2618		an_bottom
2599	2619		- on run-time, resizes/shifts down the widget to keep the design-set distance
2600	2620		between the widget's bottom border and the lower side of parent's client area
2601	2621		as the parent resizes, until scrolling begins
2602	2622
2603	2623		bounds
2604	2624
2605	2625		cx - width of the widget
2606	2626		cxmax, cxmin - design/runtime width of the widget is enforced between "cxmax" and "cxmin"
2607	2627		cy - height of the widget
2608	2628		cymax, cymin - design/runtime height of the widget is enforced between "cymax" and "cymin"
2609	2629		x - distance between the widget's left border and the left side of parent's client area
2610	2630		y - distance between the widget's top border and the upper side of parent's client area
2611	2631
2612	2632		autosize
2613	2633
2614	2634		-----------
2615	2635		- only applicable to widgets with "ow_autosize" set
2616	2636		- the effect may be partial in case when "bounds_c*max" settings limit the extents
2617	2637		-----------
2618	2638
2619	2639		cx - addition to width of the widget (with h-centering post applied)
2620	2640		cy - addition to height of the widget (with v-centering post applied)
2621	2641
2622	2642		- color
2623	2643		= the default color of client area & caption text background
2624	2644		= may be overwritten:
2625	2645		* the client area - with "frame.colorclient"
2626	2646		* the caption BG - with "frame.font.colorbackground"
2627	2647
2628	2648		- font
2629	2649		= see {any font}
2630	2650
2631	2651		- frame
2632	2652		= see {any frame}
2633	2653
2634	2654		- face
2635	2655		= see {any face}
2636	2656
2637	2657		- hint
2638	2658		= descriptive text appearing when mouse pointer enters the widget
2639	2659
2640	2660		- cursor
2641	2661		= shape of the mouse pointer over the client area of widget (run-time only)
2642	2662
2643	2663		- visible
2644	2664		= "true" allow the widget to appear ( run-time only )
2645	2665
2646	2666		- enabled
2647	2667		= "true" allows the widget to participate in GUI interaction
2648	2668		= "false" disallows the widget & its children :
2649	2669		* processing all events & shortcuts & menu calls
2650	2670		* auto "CanClose" check
2651	2671
2652	2672		Also "false" usually paints the widget in color marking
2653	2673		the "disabled" state ( usually light gray font color )
2654	2674
2655	2675		- popupmenu
2656	2676		= reference to a preset tpopupmenu widget serving the right-click menu
2657	2677
2658	2678		- taborder
2659	2679		- {0..N} order number when TAB-key cycling through widgets in the container
2660	2680
2661	2681		- tag
2662	2682		- an integer value bound to this widget instance
2663	2683
2664	2684		- helpcontext
2665	2685		= a string returned by "(active/mouse)helpcontext" methods of the owning form
2666	2686		when this widget is focused or under mouse in the active window
2667	2687
2668	2688		- zorder
2669	2689		= reading: finds the current Z-order of the widget's window
2670	2690		= setting: if the value = 0 then lowers the widget's window in the stacking hierarchy, otherwise rises
2671	2691
2672	2692		optionswidget:
2673	2693
2674	2694		ow_background
2675	2695		- keeps the window/widget on bottom of the Z-order stack.
2676	2696
2677	2697		ow_top
2678	2698		- keeps the window/widget in foreground
2679	2699
2680	2700		ow_noautosizing
2681	2701		- when docking, not to resize for the docking area
2682	2702
2683	2703		ow_mousefocus
2684	2704		- "false" here disables focusing the widget with mouse
2685	2705		( and "OnFocus" doesn't fire on mouse clicks )
2686	2706
2687	2707		ow_tabfocus
2688	2708		- "false" here disables focusing the widget with "TAB" key
2689	2709		( and "OnFocus" doesn't fire on TAB pressed )
2690	2710
2691	2711		ow_parenttabfocus
2692	2712		- enters the childs on TAB-focusing then returns to the widget after
2693	2713		sequential TAB-ing through its child widgets,
2694	2714		otherwise TAB-ing cycles on the children if entered
2695	2715
2696	2716		ow_arrowfocus
2697	2717		- allows the widget ( and its children in turn ) to be focused with
2698	2718		the arrow keys
2699	2719
2700	2720		ow_subfocus, ow_arrowfocusin, ow_arrowfocusout
2701	2721		- in case of arrow keys focusing enabled for child-containing widget,
2702	2722		determine behaviour on entering & leaving the widget, see the below table:
2703	2723
2704	2724		ow_subfocus \| ow_arrowfocusin \| ow_arrowfocusout \| effect
2705	2725
2706	2726		FALSE FALSE FALSE entering-/leaving-
2707	2727		FALSE FALSE TRUE entering-/leaving+
2708	2728		FALSE TRUE FALSE entering(nearest)+/leaving-
2709	2729		FALSE TRUE TRUE entering(nearest)+/leaving+
2710	2730		TRUE FALSE FALSE entering(last focused)+/leaving-
2711	2731		TRUE FALSE TRUE entering(last focused)+/leaving+
2712	2732		TRUE TRUE FALSE entering(nearest)+/leaving-
2713	2733		TRUE TRUE TRUE entering(nearest)+/leaving+
2714	2734
2715	2735		- "entering" is focusing on a child within the widget
2716	2736		- "leaving" is return from last child onto the widget's level
2717	2737		- "nearest" is the child closest on the arrow direction
2718	2738		- "last focused" is the child focused on last leaving the widget
2719	2739
2720	2740		*** The Up/Down arrow keys can leave from the children circle,
2721	2741		but Left/Right can only toggle between the children ***
2722	2742
2723	2743		*** mouse entering/leaving isn't controllable by these options
2724	2744
2725	2745		ow_focusbackonesc
2726	2746		- on pressing "Esc", returns input focus to the previously focused widget
2727	2747
2728	2748		ow_noparentshortcut
2729	2749
2730	2750		* disables processing of delegated ( from the parent ) shortcuts *
2731	2751
2732	2752		- "true" here disables processing shortcuts if they're delegated
2733	2753		from the parent widget ( obviously, not processed by the parent )
2734	2754
2735	2755		ow_nochildshortcut
2736	2756
2737	2757		* disables delegating shortcuts to the parent for taking decision *
2738	2758
2739	2759		- if "true" then the widget tries to process it by oneself
2740	2760		otherwise it's passed to the parent widget for further chaining
2741	2761
2742	2762		* A shortcut can only be processed once ( by one widget ) *
2743	2763
2744	2764		ow_canclosenil
2745	2765		- "true" here allows to continue even if there's contained widget(s)
2746	2766		not passing "CanClose" check
2747	2767
2748	2768		ow_mousetransparent
2749	2769		- "true" here causes the widget oneself ( not its contained ones )
2750	2770		not to react to mouse events ( just allow them through to the children )
2751	2771
2752	2772		ow_mousewheel
2753	2773		- enables/disables {scrolling/navigating} with wheel of ImPS/2 etc mouse
2754	2774
2755	2775		ow_noscroll
2756	2776		- don't use screen image scrolling for twidget.scrollrect,
2757	2777		redraw the whole scrolled widget rectangle instead;
2758	2778		sometimes needed with background fades.
2759	2779
2760	2780		ow_nochildpaintclip
2761	2781		-
2762	2782
2763	2783		ow_destroywidgets
2764	2784		- "true" here causes calling "free" for all containing widgets as well
2765	2785
2766	2786		ow_hinton
2767	2787		- to show the hint even in case of hinting is disabled on the parent
2768	2788		( "parent.ow_hintoff= true & parent.ow_hinton= false" )
2769	2789
2770	2790		ow_hintoff
2771	2791		- "true" here combined with "ow_hinton=false" fully disables displaying the hint
2772	2792
2773	2793		ow_multiplehint
2774	2794		- "true" here causes the widget to redisplay its hint on each {>3px} move within the widget oneself
2775	2795
2776	2796		ow_timedhint
2777	2797		- "true" here causes hint of the widget to disappear after a timed inteval (about 2 secs by default)
2778	2798
2779	2799		ow_fontlineheight (design-time only)
2780	2800		- causes "extraspace" of the last text line to be drawn,
2781	2801		in turn it causes adjustment of widget height if "ow_autoscale" is set
2782	2802
2783	2803		* makes sence only if "ow_autoscale=true" & ow_autosize=false & "extraspace <> 0" *
2784	2804
2785	2805		ow_fontglyphheight (design-time only)
2786	2806		- causes only interline "extraspace"-s to be drawn, opposite to "ow_fontlineheight"
2787	2807
2788	2808		ow_autoscale (design-time only)
2789	2809		- causes that if the contents change (design OR run-time) so that its' height changes
2790	2810		then the widget will be v-scaled as well
2791	2811
2792	2812		ow_autosize (design-time only)
2793	2813		- causes that widget's height & width & client area adjust so that to provide space for contents of the client area
2794	2814		- no design-time change of height/width are possible as long as this option is in effect
2795	2815
2796	2816		ow_autosizeanright
2797	2817		- when autosizing & {an_right isn't set}, the design-set right margin against the parent is preserved
2798	2818
2799	2819		ow_autosizeanbottom
2800	2820		- when autosizing & {an_bottom isn't set}, the design-set bottom margin against the parent is preserved
2801	2821
2802	2822		optionsskin:
2803	2823
2804	2824		- osc_noskin
2805	2825		- osc_framebuttononly
2806	2826		- osc_container
2807	2827
2808	2828		Methods:
2809	2829
2810	2830		// tmsecomponent
2811	2831
2812	2832		// (re)draws the widget according to the related skin if apllicable;
2813	2833		//
2814	2834		// also called internally by "loaded" procedure ( before "OnLoaded" code ),
2815	2835		// by ShowMessage ( for the internal widgets of the message dialogue ),
2816	2836		// when creating tab & form & menu widgets
2817	2837		procedure updateskin(const recursive: boolean = false);
2818	2838
2819	2839		// TRUE if the instance is created but not yet ready
2820	2840		// for interaction & accessing data & appearance change & receiving events etc
2821	2841		// ( the stage between firing "OnCreate" & "OnLoaded" )
2822	2842		function loading: boolean;
2823	2843
2824	2844		{$ifdef FPC}
2825	2845		procedure setinline(value: boolean); // ?
2826	2846		procedure setancestor(value: boolean); // ?
2827	2847		{$endif}
2828	2848
2829	2849		// TRUE if all conditios are OK for executing the code of "event" ( a handler must be assigned to the event )
2830	2850		function canevent(const event: tmethod): boolean;
2831	2851
2832	2852		// Shortly, replaces the persistent storage of the widget
2833	2853		//
2834	2854		// if {value <> nil} then
2835	2855		// - if "instance" is nil then calls "createproc" to create the instance,
2836	2856		// then assigns the instance's value:= "value"
2837	2857		// otherwise frees "instance"
2838	2858		procedure setoptionalobject(const value: tpersistent; var instance;
2839	2859		createproc: createprocty);
2840	2860
2841	2861		// creates the persistent storage of the widget via calling "createproc"
2842	2862		procedure getoptionalobject(const instance: tobject; createproc: createprocty);
2843	2863
2844	2864		// obtains & puts to "obj" a CORBA interface entry for "aintf" (GUID,...)
2845	2865		function getcorbainterface(const aintf: ptypeinfo; out obj) : boolean;
2846	2866
2847	2867		// TRUE if the widget is owned, or "self" otherwise
2848	2868		function checkowned(component: tcomponent): boolean;
2849	2869
2850	2870		// TRUE if the widget is owner, or "self" otherwise
2851	2871		function checkowner(component: tcomponent): boolean;
2852	2872
2853	2873		// return the top-most widget in owner chain starting from this widget
2854	2874		function rootowner: tcomponent;
2855	2875
2856	2876		// return the array of owning widgets starting from this widget
2857	2877		// componentarty[0] is the widget oneself
2858	2878		function getrootcomponentpath: componentarty;
2859	2879
2860	2880		// returns items of objeclinker ( which notify this widget )
2861	2881		// and free notify list ( which are notified by this widget ),
2862	2882		// duplicates are removed.
2863	2883		//
2864	2884		// Notifies mainly relate to insertion/removal operation on widgets
2865	2885		// The notify list is maintained by FreeNotification & RemoveFreeNotification
2866	2886		function linkedobjects: objectarty;
2867	2887
2868	2888		// sends "event" recursively to child widgets until no more children or
2869	2889		// the event is processed ( cea_processed ) by one of the children,
2870	2890		// "event" will be destroyed if destroyevent= true and not async
2871	2891		procedure sendcomponentevent(const event: tcomponentevent;
2872	2892		const destroyevent: boolean = true);
2873	2893
2874	2894		// sends "event" to each of owning widgets downward from the root owner,
2875	2895		// "event" will be destroyed if destroyevent= true and not async
2876	2896		procedure sendrootcomponentevent(const event: tcomponentevent;
2877	2897		const destroyevent: boolean = true);
2878	2898
2879	2899		// posts an async "atag"-ged event to be handled by oneself
2880	2900		procedure asyncevent(atag: integer = 0);
2881	2901
2882	2902		// posts a "tcomponentevent" instance from sender=self,
2883	2903		// "kind" is defined when creating the event,
2884	2904		// and "tag" may be adjusted after creation
2885	2905		procedure postcomponentevent(const event: tcomponentevent);
2886	2906
2887	2907		// returns the classname of the widget if the widget is toplevel,
2888	2908		// and "tmsecomponent" otherwise )
2889	2909		property moduleclassname: string read getmoduleclassname;
2890	2910
2891	2911		// returns the classname of the widget as the entry of its constructor
2892	2912		// ( button => tbutton, datamodule => tdm1mo, form => ttstfo, dbstringedit => tdbstringedit,.. )
2893	2913		property actualclassname: string read getactualclassname;
2894	2914
2895	2915		// returns "fmsecomponentstate"
2896	2916		// ( a set of cs_ismodule,cs_endreadproc,cs_loadedproc,cs_noload, cs_hasskin,cs_noskin )
2897	2917		property msecomponentstate: msecomponentstatesty read fmsecomponentstate;
2898	2918
2899	2919		// returns/sets a pointer associated with the widget
2900	2920		// ( contrary to the integer "tag", allows to use an arbitary data type
2901	2921		// for associating data )
2902	2922		property tagpo: pointer read ftagpo write ftagpo;
2903	2923
2904	2924		// returns/sets a string identifying the widget in the help system
2905	2925		property helpcontext: msestring read gethelpcontext write fhelpcontext;
2906	2926
2907	2927		// twidget
2908	2928
2909	2929		// creates an instance of the widget, owned by "aowner" if not NIL
2910	2930		constructor create(aowner: tcomponent); override;
2911	2931
2912	2932		destructor destroy; override;
2913	2933
2914	2934		// ??
2915	2935		procedure afterconstruction; override;
2916	2936
2917	2937		// rescales the widget frame ( if assigned ) then owned widgets ( if exist, recursively ) then bounds_* then the font ( if assigned )
2918	2938		// called before inserting in parentwidget,
2919	2939		// calls "scale(ascale)",
2920	2940		// no visual repainting
2921	2941		procedure initnewcomponent(const ascale: real); virtual;
2922	2942
2923	2943		// restores the "fontheight" to "font.glyphheight" if "ow_fontglyphheight" or
2924	2944		// to "font.lineheight" if "ow_fontlineheight" otherwise,
2925	2945		// ascale is ignored ?
2926	2946		// calls "synctofontheight->setfontheight",
2927	2947		// called after inserting in parentwidget,
2928	2948		// no visual repainting
2929	2949		procedure initnewwidget(const ascale: real); virtual;
2930	2950
2931	2951		// creates the widget frame if not yet created
2932	2952		procedure createframe;
2933	2953
2934	2954		// creates the widget face if not yet created
2935	2955		procedure createface;
2936	2956
2937	2957		// creates the widget font if not yet created
2938	2958		procedure createfont;
2939	2959
2940	2960		// checks ws_loadlock and csdestroing too
2941	2961		function isloading: boolean;
2942	2962
2943	2963		// returns "widgetstatety" - a set of (
2944	2964		// ws_visible,ws_enabled,ws_active,ws_entered,ws_entering,ws_exiting,
2945	2965		// ws_focused,ws_mouseinclient,ws_wantmousebutton,ws_wantmousemove,
2946	2966		// ws_wantmousefocus,ws_iswidget,ws_opaque,ws_nopaint,
2947	2967		// ws_clicked,ws_mousecaptured,ws_clientmousecaptured,
2948	2968		// ws_loadlock,ws_loadedproc,ws_showproc,ws_minclientsizevalid,
2949	2969		// ws_showed,ws_hidden, //used in tcustomeventwidget
2950	2970		// ws_destroying,ws_staticframe,ws_staticface,ws_isvisible
2951	2971		//
2952	2972		// iframe
2953	2973		function widgetstate: widgetstatesty;
2954	2974
2955	2975		// returns "widgetstate1ty" - a set of (
2956	2976		// (ws1_childscaled,ws1_fontheightlock,
2957	2977		// ws1_widgetregionvalid,ws1_rootvalid,
2958	2978		// ws1_anchorsizing,ws1_isstreamed,
2959	2979		// ws1_scaled, //used in tcustomscalingwidget
2960	2980		// ws1_noclipchildren,
2961	2981		// ws1_nodesignvisible,ws1_nodesignframe,ws1_nodesignhandles,
2962	2982		// ws1_nodesigndelete,ws1_designactive,
2963	2983		// ws1_fakevisible,ws1_nominsize //used for report size calculations
2964	2984		// )
2965	2985		property widgetstate1: widgetstates1ty read fwidgetstate1;
2966	2986
2967	2987		* this set of states is needed because the max FPC set size is 32
2968	2988		thus "widgetstate1ty" can't fit all states
2969	2989
2970	2990		// TRUE if the widget is contained within another widget
2971	2991		// ( tcomponent stuff )
2972	2992		function hasparent: boolean; override;
2973	2993
2974	2994		// returns the parent component if it's a widget or the grandparent otherwise
2975	2995		function getparentcomponent: tcomponent; override; // tcomponent
2976	2996
2977	2997		// TRUE if "awidget" is an ascendant or the widget or they are the same widget
2978	2998		function checkdescendent(awidget: twidget): boolean;
2979	2999
2980	3000		// TRUE if app is running and the widget owns the caret or the caret widget
2981	3001		function hascaret: boolean;
2982	3002
2983	3003		// TRUE if "winid" allocated and not loading and not destroying,
2984	3004		// all widgets on a form have "winid" of this form ( a real window allocated by the OS )
2985	3005		// thus have this function TRUE
2986	3006		function windowallocated: boolean;
2987	3007
2988	3008		// TRUE if presents a valid toplevelwindow with assigned "winid"
2989	3009		function ownswindow: boolean;
2990	3010
2991	3011		// invalidated area of the widget, the origin is "clientpos" against the roor widget
2992	3012		function updaterect: rectty;
2993	3013
2994	3014		// calls recursively "canclose" for all contained widgets ( the widget oneself excluded! ),
2995	3015		// TRUE if none of the widgets return FALSE
2996	3016		//
2997	3017		// more specialized widgets may have "canclose" overridden
2998	3018		// to perform more work than just this call recursion
2999	3019		// ( not null or range check,.. )
3000	3020		//
3001	3021		// "onclosequery" must also pass the check if assigned, for the function to succeed
3002	3022		function canclose(const newfocus: twidget = nil): boolean; virtual;
3003	3023
3004	3024		// checks "canclose" first for focused widget of the window ( form,.. )
3005	3025		// if it is a descendant of the widget or the widget oneself,
3006	3026		// then continues with subwidgets of the widget;
3007	3027		// also - finishes editing ( snapshots "value" ) in the focused widget before checking
3008	3028		function canparentclose(const newfocus: twidget): boolean; overload;
3009	3029
3010	3030		// the above function but with the preserved focus
3011	3031		function canparentclose: boolean; overload;
3012	3032		//newfocus = window.focusedwidget
3013	3033
3014	3034		function canfocus: boolean; virtual;
3015	3035		function setfocus(aactivate: boolean = true): boolean; virtual;//true if ok
3016	3036		procedure nextfocus; //sets inputfocus to then next appropriate widget
3017	3037
3018	3038		function findtabfocus(const ataborder: integer): twidget;
3019	3039		//nil if cannot focus
3020	3040
3021	3041		function firsttabfocus: twidget;
3022	3042		function lasttabfocus: twidget;
3023	3043		function nexttaborder(const down: boolean = false): twidget;
3024	3044
3025	3045		function focusback(const aactivate: boolean = true): boolean;
3026	3046		//false if focus not changed
3027	3047
3028	3048		function parentcolor: colorty;
3029	3049		function actualcolor: colorty; virtual;
3030	3050		function actualopaquecolor: colorty;
3031	3051		function backgroundcolor: colorty;
3032	3052		function translatecolor(const acolor: colorty): colorty;
3033	3053
3034	3054		procedure widgetevent(const event: twidgetevent); virtual;
3035	3055
3036	3056		procedure sendwidgetevent(const event: twidgetevent);
3037	3057		//event will be destroyed
3038	3058
3039	3059		procedure release; override;
3040	3060
3041	3061		function show(const modal: boolean = false; const transientfor: twindow = nil): modalresultty; virtual;
3042	3062
3043	3063		procedure hide;
3044	3064		procedure activate(const abringtofront: boolean = true); virtual;
3045	3065		//show and setfocus
3046	3066
3047	3067		procedure bringtofront;
3048	3068		procedure sendtoback;
3049	3069		procedure stackunder(const predecessor: twidget);
3050	3070
3051	3071		procedure paint(const canvas: tcanvas); virtual;
3052	3072		procedure update; virtual;
3053	3073		procedure scrollwidgets(const dist: pointty);
3054	3074
3055	3075		procedure scrollrect(const dist: pointty; const rect: rectty; scrollcaret: boolean);
3056	3076		//origin = paintrect.pos
3057	3077
3058	3078		procedure scroll(const dist: pointty);
3059	3079		//scrolls paintrect and widgets
3060	3080
3061	3081		procedure getcaret;
3062	3082		procedure scrollcaret(const dist: pointty);
3063	3083		function mousecaptured: boolean;
3064	3084		procedure capturemouse(grab: boolean = true);
3065	3085		procedure releasemouse;
3066	3086		procedure capturekeyboard;
3067	3087		procedure releasekeyboard;
3068	3088		procedure synctofontheight; virtual;
3069	3089
3070	3090		procedure dragevent(var info: draginfoty); virtual;
3071	3091		procedure dochildscaled(const sender: twidget); virtual;
3072	3092
3073	3093		procedure invalidatewidget; //invalidates whole widget
3074	3094		procedure invalidate; //invalidates clientrect
3075	3095		procedure invalidaterect(const rect: rectty; org: originty = org_client);
3076	3096		procedure invalidateframestate;
3077	3097
3078	3098		procedure invalidateframestaterect(const rect: rectty;
3079	3099		const org: originty = org_client);
3080	3100		function hasoverlappingsiblings(arect: rectty): boolean; //origin = pos
3081	3101
3082	3102		function window: twindow;
3083	3103		function rootwidget: twidget;
3084	3104
3085	3105		function parentofcontainer: twidget;
3086	3106		//parentwidget.parentwidget if parentwidget has not ws_iswidget,
3087	3107		//parentwidget otherwise
3088	3108
3089	3109		property parentwidget: twidget read fparentwidget write setparentwidget;
3090	3110		function getrootwidgetpath: widgetarty; //root widget is last
3091	3111
3092	3112		// number of contained widgets ( the widget oneself excluded ! )
3093	3113		function widgetcount: integer;
3094	3114
3095	3115		function parentwidgetindex: integer; //index in parentwidget.widgets, -1 if none
3096	3116		property widgets[const index: integer]: twidget read getwidgets;
3097	3117		function widgetatpos(var info: widgetatposinfoty): twidget; overload;
3098	3118		function widgetatpos(const pos: pointty): twidget; overload;
3099	3119
3100	3120		function widgetatpos(const pos: pointty;
3101	3121		const state: widgetstatesty): twidget; overload;
3102	3122
3103	3123		property taborderedwidgets: widgetarty read gettaborderedwidgets;
3104	3124
3105	3125		function findtagwidget(const atag: integer; const aclass: widgetclassty): twidget;
3106	3126		//returns first matching descendent
3107	3127
3108	3128		property container: twidget read getcontainer;
3109	3129		function containeroffset: pointty;
3110	3130		function childrencount: integer; virtual;
3111	3131		property children[const index: integer]: twidget read getchildwidgets; default;
3112	3132
3113	3133		function childatpos(const pos: pointty;
3114	3134		const clientorigin: boolean = true): twidget; virtual;
3115	3135
3116	3136		function getsortxchildren: widgetarty;
3117	3137		function getsortychildren: widgetarty;
3118	3138		property focusedchild: twidget read ffocusedchild;
3119	3139		property focusedchildbefore: twidget read ffocusedchildbefore;
3120	3140
3121	3141		function mouseeventwidget(const info: mouseeventinfoty): twidget;
3122	3142
3123	3143		function checkdescendent(widget: twidget): boolean;
3124	3144		//true if widget is descendent or self
3125	3145
3126	3146		function checkancestor(widget: twidget): boolean;
3127	3147		//true if widget is ancestor or self
3128	3148
3129	3149		function containswidget(awidget: twidget): boolean;
3130	3150
3131	3151		procedure insertwidget(const awidget: twidget); overload;
3132	3152
3133	3153		procedure insertwidget(const awidget: twidget; const apos: pointty); overload; virtual;
3134	3154		//widget can be child
3135	3155
3136	3156		function iswidgetclick(const info: mouseeventinfoty; const caption: boolean = false): boolean;
3137	3157		//true if eventtype = et_butonrelease, button is mb_left, clicked and pos in clientrect
3138	3158		//or in frame.caption if caption = true, origin = pos
3139	3159
3140	3160		function isclick(const info: mouseeventinfoty): boolean;
3141	3161		//true if eventtype = et_butonrelease, button is mb_left, clicked and pos in clientrect
3142	3162
3143	3163		function isdblclick(const info: mouseeventinfoty): boolean;
3144	3164		//true if eventtype = et_butonpress, button is mb_left, pos in clientrect
3145	3165		// and timedlay to last buttonpress is short
3146	3166
3147	3167		function isdblclicked(const info: mouseeventinfoty): boolean;
3148	3168		//true if eventtype in [et_buttonpress,et_butonrelease], button is mb_left,
3149	3169		// and timedlay to last same buttonevent is short
3150	3170
3151	3171		function isleftbuttondown(const info: mouseeventinfoty): boolean;
3152	3172		//true if eventtype = et_butonpress, button is mb_left, pos in clientrect
3153	3173		//origin = paintrect.pos
3154	3174
3155	3175		widgetrect: the widget on-screen area including its frame & frame caption
3156	3176
3157	3177		paintrect: the widget on-screen area except its frame & frame caption
3158	3178
3159	3179		clientrect: virtual area which
3160	3180		- for non-scrolling widgets, equals to "paintrect", with its "pos:= (0,0)"
3161	3181		- for scrolling widgets, may be bigger than "paintrect",
3162	3182		also may shift ( change its "pos" ) when scrolling
3163	3183
3164	3184		// the coord of outer top-left corner against the toplevel form = the window owner,
3165	3185		// including the frame & frame caption
3166	3186		function rootpos: pointty;
3167	3187
3168	3188		// the coord of the outer top-left corner against the screen ( the WM decorations aren't counted in )
3169	3189		// includes the frame & frame caption
3170	3190		property screenpos: pointty;
3171	3191
3172	3192		// the coord of the outer top-left corner against the parent widget,
3173	3193		// including the frame & frame caption
3174	3194		property widgetrect: rectty;
3175	3195		property pos: pointty; // =widgetrect.pos
3176	3196		property size: sizety; // =widgetrect.size
3177	3197		property left: integer; // =bounds_x
3178	3198		property right: integer; //widgetrect.x + widgetrect.cx, sets cx;
3179	3199		property top: integer; // =bounds_y
3180	3200		property bottom: integer; //widgetrect.y + widgetrect.cy, sets cy;
3181	3201		property width: integer; // =bounds_cx
3182	3202		property height: integer; // =bounds_cy
3183	3203		function widgetsizerect: rectty; //pos = nullpoint
3184	3204
3185	3205		// the coord of the paint area ( paintrect ) against own outer top-left corner ( against "widgetrect=pos" )
3186	3206		// except the frame & frame caption
3187	3207		function paintrect: rectty;
3188	3208		function paintpos: pointty;
3189	3209		function paintsize: sizety;
3190	3210		function innerpaintrect: rectty; // mainly equals to paintrect
3191	3211		function clientwidgetrect: rectty; // mainly equals to paintrect
3192	3212		function clientwidgetpos: pointty;
3193	3213		function clippedpaintrect: rectty; // mainly equals to but clipped by all parentpaintrects
3194	3214		function innerwidgetrect: rectty; // mainly equals to paintrect
3195	3215		function innerclientwidgetpos: pointty;
3196	3216
3197	3217		// the coord of the paint area ( paintrect ) against own outer top-left corner ( against "widgetrect=pos" )
3198	3218		// except the frame caption
3199	3219		function framerect: rectty; // =paintrect except the frame caption area
3200	3220		function framepos: pointty;
3201	3221		function framesize: sizety;
3202	3222
3203	3223		// the coord of the client area ( clientrect ) against the paint area ( paintrect )
3204	3224		// usually these areas match
3205	3225		function clientrect: rectty;
3206	3226		property clientsize: sizety;
3207	3227		property clientwidth: integer;
3208	3228		property clientheight: integer;
3209	3229		property clientpos: pointty;
3210	3230
3211	3231		// the coord of the paint area of the parent against the paint area of this widget
3212	3232		function paintrectparent: rectty; //nullrect if parent = nil,
3213	3233
3214	3234		// the coord of the client area of the parent against the paint area of this widget
3215	3235		function clientrectparent: rectty; //nullrect if parent = nil,
3216	3236
3217	3237		// the coord of the inner area against the client area ( clientrect )
3218	3238		function innerclientrect: rectty; // mainly equals to clientrect
3219	3239		function innerclientsize: sizety;
3220	3240		function innerclientpos: pointty;
3221	3241
3222	3242		function framewidth: sizety; //widgetrect.size - paintrect.size
3223	3243		function clientframewidth: sizety; //widgetrect.size - clientrect.size
3224	3244		function innerclientframewidth: sizety; //widgetrect.size - innerclientrect.size
3225	3245		function innerframewidth: sizety; //clientrect.size - innerclientrect.size
3226	3246
3227	3247		// the coord of the paint area against the widgetrect(pos) of the parent
3228	3248		function paintparentpos: pointty; //origin = parentwidget.pos
3229	3249
3230	3250		// the coord of the client area against the widgetrect(pos) of the parent
3231	3251		function clientparentpos: pointty; //origin = parentwidget.pos
3232	3252
3233	3253		// the coord of the widgetrect(pos) against the client area of parent
3234	3254		property parentclientpos: pointty;
3235	3255
3236	3256		function clientpostowidgetpos(const apos: pointty): pointty;
3237	3257		function widgetpostoclientpos(const apos: pointty): pointty;
3238	3258		function widgetpostopaintpos(const apos: pointty): pointty;
3239	3259		function paintpostowidgetpos(const apos: pointty): pointty;
3240	3260		procedure scale(const ascale: real); virtual;
3241	3261
3242	3262		property minsize: sizety read fminsize write setminsize;
3243	3263		property maxsize: sizety read fmaxsize write setmaxsize;
3244	3264		function maxclientsize: sizety; virtual;
3245	3265
3246	3266		property anchors: anchorsty read fanchors write setanchors default defaultanchors;
3247	3267		property defaultfocuschild: twidget read getdefaultfocuschild write setdefaultfocuschild;
3248	3268
3249	3269		procedure changeclientsize(const delta: sizety); //asynchronous
3250	3270
3251	3271		function getcanvas(aorigin: originty = org_client): tcanvas;
3252	3272
3253	3273		function showing: boolean;
3254	3274		//true if self and all ancestors visible and window allocated
3255	3275
3256	3276		function isenabled: boolean;
3257	3277		//true if self and all ancestors enabled
3258	3278
3259	3279		function active: boolean;
3260	3280		function entered: boolean;
3261	3281
3262	3282		function activeentered: boolean;
3263	3283		//true if entered and window is regularactivewindow or inactivated
3264	3284
3265	3285		function focused: boolean;
3266	3286		function clicked: boolean;
3267	3287
3268	3288		function indexofwidget(const awidget: twidget): integer;
3269	3289
3270	3290		procedure changedirection(const avalue: graphicdirectionty;
3271	3291		var dest: graphicdirectionty); virtual;
3272	3292
3273	3293		// (re)arranges "awidgets" horizontally within the parent's client area
3274	3294		// so that awidget[i] were placed next each other
3275	3295		// at h-space dist[i], starting from "startx" with the right margin "endmargin";
3276	3296		//
3277	3297		// if the number of "dist" is fewer than the number of "awidgets" then the remaining h-spaces are taken
3278	3298		// as the last "dist[i]" or "0" if none;
3279	3299		// if the number of "dist" is more than the number of "awidgets" then the extra dist[i] are discarded
3280	3300		//
3281	3301		// non-zero "endmargin" causes one of awdidget[i] to h-resize to provide the margin :
3282	3302		// - if one or more of awidgets[i] have [an_left,an_right] set then the first of such is resized
3283	3303		// otherwise the last awidgets[i] is h-resized
3284	3304		//
3285	3305		procedure placexorder(
3286	3306		const startx: integer;
3287	3307		const dist: array of integer;
3288	3308		const awidgets: array of twidget;
3289	3309		const endmargin: integer = minint);
3290	3310
3291	3311		// (re)arranges "awidgets" vertically within the parent's client area
3292	3312		// so that awidget[i] were placed upper/lower each other
3293	3313		// at v-space dist[i], starting from "starty" with the bottom margin "endmargin";
3294	3314		//
3295	3315		// if the number of "dist" is fewer than the number of "awidgets" then the remaining v-spaces are taken
3296	3316		// as the last "dist[i]" or "0" if none;
3297	3317		// if the number of "dist" is more than the number of "awidgets" then the extra dist[i] are discarded
3298	3318		//
3299	3319		// non-zero "endmargin" causes one of awdidget[i] to v-resize to provide the margin :
3300	3320		// - if one or more of awidgets[i] have [an_top,an_bottom] set then the first of such is resized
3301	3321		// otherwise the last awidgets[i] is v-resized
3302	3322		//
3303	3323		procedure placeyorder(
3304	3324		const starty: integer;
3305	3325		const dist: array of integer;
3306	3326		const awidgets: array of twidget;
3307	3327		const endmargin: integer = minint);
3308	3328		//origin = clientpos, endmargin by size adjust of widgets
3309	3329		//with [an_top,an_bottom], minint -> no change
3310	3330
3311	3331		// if {mode <> wam_none} then (re)arranges "awidgets" horizontally within the parent's client area so that
3312	3332		// awidgets[0] stays on its place but awidgets[1..N] :
3313	3333		// - if {mode = wam_end} then awidgets[i>=1] move or resize ( if "anchors.al_left" set ) so that they right borders match the right border of awidgets[0]
3314	3334		// - if {mode = wam_start} then awidgets[i>=1] move or resize ( if "anchors.al_right" set ) so that they left borders match the left border of awidgets[0]
3315	3335		// - if {mode = wam_center} then awidgets[i>=1] move so that they Y-axes match the Y-axe of awidgets[0]
3316	3336		//
3317	3337		// mainly applicable for v-stacked widgets since h-stacked may overlap after such alignment
3318	3338		//
3319	3339		// returns the reference point ( the coord of awidgets[0] )
3320	3340		function alignx(const mode: widgetalignmodety;
3321	3341		const awidgets: array of twidget): integer;
3322	3342
3323	3343		// if {mode <> wam_none} then (re)arranges "awidgets" vertically within the parent's client area so that
3324	3344		// awidgets[0] stays on its place but awidgets[1..N] :
3325	3345		// - if {mode = wam_end} then awidgets[i>=1] move or resize ( if "anchors.al_top" set ) so that they bottom borders match the bottom border of awidgets[0]
3326	3346		// - if {mode = wam_start} then awidgets[i>=1] move or resize ( if "anchors.al_bottom" set ) so that they top borders match the top border of awidgets[0]
3327	3347		// - if {mode = wam_center} then awidgets[i>=1] move so that they X-axes match the X-axe of awidgets[0]
3328	3348		//
3329	3349		// mainly applicable for h-stacked widgets since v-stacked may overlap after such alignment
3330	3350		//
3331	3351		// returns the reference point ( the coord of awidgets[0] )
3332	3352		function aligny(const mode: widgetalignmodety;
3333	3353		const awidgets: array of twidget): integer;
3334	3354
3335	3355		function actualcursor: cursorshapety; virtual;
3336	3356
3337	3357		Event handlers:
3338	3358
3339	3359		- onactivate
3340	3360
3341	3361		fires :
3342	3362
3343	3363		= on receiving input focus, just before "OnFocus"
3344	3364
3345	3365		= forms specific :
3346	3366		* on 1-st display of the form after "OnLoaded" ( from "Loaded" procedure)
3347	3367		* on switch back from another apllication/WM ( "oe_activate" event )
3348	3368		* after closure of a descendant form
3349	3369		* on minimizing/maximizing the form
3350	3370
3351	3371		- onchildscaled
3352	3372
3353	3373		fires :
3354	3374
3355	3375		= on child/children resizing due to font height change
3356	3376
3357	3377		= form widget: once "form.container" {scrolling widget} is loaded
3358	3378
3359	3379		- ondeactivate
3360	3380		fires
3361	3381		= form widget: when the form looses input focus
3362	3382		= non-form widget: when the widget looses input focus
3363	3383
3364	3384		- ondefocus
3365	3385
3366	3386		fires
3367	3387		= on disabling the widget
3368	3388
3369	3389		= form widget: if another form is focused
3370	3390		= non-form widget: if another widget is focused
3371	3391
3372	3392		- onenter
3373	3393		= fires on any way of taking parent-wide focus as soon as
3374	3394		the parent stores the new child's order, before "OnActivate" & "OnFocus"
3375	3395
3376	3396		- onexit
3377	3397		= fires last on parent-wide lossing focus, after "OnDefocus" & "OnDeactivate"
3378	3398		= for top-level ( not in a container ) forms, doesn't fire
3379	3399
3380	3400		- onfocus
3381	3401		fires
3382	3402		= once the existing widget takes the focus
3383	3403		= on showing the widget's form if the widget has the lowest "TabOrder"
3384	3404
3385	3405		- onfontheightdelta
3386	3406		fires
3387	3407		= if [ow_fontglyphheight OR ow_fontlineheight ] AND {the
3388	3408		new font height differs from the previos one}
3389	3409		= before the parent redraws this widget
3390	3410
3391	3411		- onpopup
3392	3412		fires :
3393	3413		= on calling a popup-menu ( with "RightClick" ), once the menu items of the current level are loaded
3394	3414		( before building the submenus )
3395	3415
3396	3416		- onresize
3397	3417
3398	3418		= fires on creating/(changing size)/(min-max restoring) of widget,
3399	3419		before actual redrawing
3400	3420
3401	3421		= rechecks if there's real work to do
3402	3422
3403	3423		- onshowhint
3404	3424		= fires when a installed hint is activated or on "aplication.showint" called
3405	3425		= since called last, allows to adjust the default behavior
3406	3426
3407	3427		- onbeforeupdateskin
3408	3428		= fires in "updateskin" ( the widget is loaded etc ) before applying the skin
3409	3429
3410	3430		- onafterupdateskin
3411	3431		= fires in "updateskin" ( the widget is loaded etc ) once the skin is applied
3412	3432
3413	3433		### TWidget stuff
3414	3434
3415	3435		Properties:
3416	3436		- name
3417	3437		- anchors
3418	3438		- bounds
3419	3439		- color
3420	3440		- enabled
3421	3441		- visible
3422	3442		- <face> : see {any face}
3423	3443		- <frame> : see {any frame}
3424	3444		- hint
3425	3445		- helpcontext
3426	3446		- tag
3427	3447		- taborder
3428	3448		- cursor
3429	3449		- optionswidget
3430	3450		- optionsskin
3431	3451		- popupmenu
3432	3452
3433	3453		twidget's event handlers:
3434	3454
3435	3455		- on(de)activate
3436	3456		- onbeforeupdateskin
3437	3457		- onafterupdateskin
3438	3458		- onchildscaled
3439	3459		- onfontheightdelta
3440	3460		- on(de)focus
3441	3461		- onenter
3442	3462		- onmove
3443	3463		- onpopup
3444	3464		- onresize
3445	3465		- onshowhint
3446	3466
3447	3467		align_glue :
3448	3468		( outer anchoring mode for widget group, in the align mode )
3449	3469		- wam_none
3450	3470		- wam_start
3451	3471		- wan_center
3452	3472		- wm_end
3453	3473
3454	3474		align_leader :
3455	3475		the widget ( incl another spacer, splitter or layouter ) against which the alignment applies ( the reference widget )
3456	3476
3457	3477		align_mode :
3458	3478		( inner anchoring mode within widget group, in the align mode )
3459	3479		- wam_none
3460	3480		- wam_start
3461	3481		- wan_center
3462	3482		- wm_end
3463	3483
3464	3484		// Place mode:
3465	3485
3466	3486
3467	3487		place_mindist, place_maxdist:
3468	3488		- in the place(ment) mode, limits distance between widgets
3469	3489		( these distance once calculated also define side margins if applicable )
3470	3490
3471	3491		place_mode:
3472	3492		( outer anchoring mode for widget group, in the place mode )
3473	3493		- wam_none
3474	3494		- wam_start
3475	3495		- wan_center
3476	3496		- wm_end
3477	3497
3478	3498		place_options:
3479	3499		- plo_endmargin
3480	3500		= to resize a widget so that it "eats" extra space if it occurs
3481	3501
3482	3502		* only applicable in the place mode, with a limiting value of "place_maxdist" and:
3483	3503
3484	3504		1) {place_mode <> wam_none}
3485	3505		or
3486	3506		2) {place_mode = wam_end} and {plo_propmargin in place_options}
3487	3507
3488	3508		For the exact look, see above
3489	3509
3490	3510		- plo_propmargin
3491	3511		= виджеты расставляются теснее так, чтобы образовались отступы перед и после,
3492	3512		причем расстояние между центрами виджетов было бы таким же,
3493	3513		как и растояние между серединами крайних виджетов и соотв. границами зоны расстановки
3494	3514
3495	3515		- plo_syncmaxautosize
3496	3516		= see above
3497	3517
3498	3518		- plo_synccaptiondistx
3499	3519		= see above
3500	3520
3501	3521		* affects widgets with opposite cp_left/right set as well
3502	3522		* the minimal before-adjustment "captiondist" among all widgets limits "captiondist" for each of the widget
3503	3523		* don't set cfo_captiondistouter here !
3504	3524
3505	3525		- plo_synccaptiondisty
3506	3526		= see above
3507	3527
3508	3528		* affects also widgets with opposite cp_top/bottom set
3509	3529		* the minimal before-adjustment "captiondist" amongst all widgets limits "captiondist" for each of the widget
3510	3530
3511	3531		! here, don't set "cfo_captiondistouter" for affected widgets !
3512	3532
3513	3533		- plo_syncpaintwidth
3514	3534		= see above
3515	3535
3516	3536		- plo_syncpaintheight
3517	3537		= see above
3518	3538
3519	3539		- plo_scalesize
3520	3540		= see above
3521	3541
3522	3542		dist_left, dist_right, dist_top, dist_bottom :
3523	3543		= margins between most outer edge the layouter and
3524	3544		the corresponding linked widget
3525	3545
3526	3546		* see "tspacer" for detail
3527	3547
3528	3548		linkleft,linkright,linktop,linkbottom : see "tspacer"
3529	3549
3530	3550		options:
3531	3551		- spao_glueright, spao_gluebottom:
3532	3552		= set the adjustment dependencies between the layouter and its link_* widgets
3533	3553
3534	3554		* see "tspacer" for more details
3535	3555
3536	3556		// which mode of widget placement to apply - see above
3537	3557		optionslayout:
3538	3558		- lao_alignx
3539	3559		- lao_aligny
3540	3560		- lao_placex
3541	3561		- lao_placey
3542	3562		- lao_scalewidth
3543	3563		- lao_scaleheight
3544	3564		- lao_scaleleft
3545	3565		- lao_scaletop
3546	3566
3547	3567		* lao_place* & lao_align* can't be combined for one direction
3548	3568
3549	3569		optionsscale:
3550	3570
3551	3571		* cause the layouter to provide full space for the widgets as long as they expand/shrink/move
3552	3572
3553	3573		- osc_expandx
3554	3574		= allocates more h-space if needed
3555	3575
3556	3576		- osc_shrinkx
3557	3577		= removes extra h-space if occurred
3558	3578
3559	3579		- osc_expandy
3560	3580		= allocates more v-space if needed
3561	3581
3562	3582		- osc_shrinky
3563	3583		= removes extra v-space if occurred
3564	3584
3565	3585		- osc_invisishrinkx
3566	3586		= fully h-collapses the layouter if "visible=false" ( run-time only )
3567	3587
3568	3588		- osc_invisishrinky
3569	3589		= fully v-collapses the layoter if "visible=false" ( run-time only )
3570	3590
3571	3591		optionsskin:
3572	3592		= see <any widget>
3573	3593
3574	3594		Methods:
3575	3595
3576	3596		constructor create(aowner: tcomponent); override;
3577	3597
3578	3598		### Public stuff
3579	3599
3580	3600		(f)window:
3581	3601		the OS-allocated ( root = toplevel ) window common for all widgets of this window
3582	3602
3583	3603		* "widget.fwindow.fowner = widget.self" in case of the widget present the root "fwindow"
3584	3604		( owns the window )
3585	3605
3586	3606		(f)rootpos:
3587	3607		position of the widget in the coord of toplevel window not the nearest parent widget alone,
3588	3608		calculated as sum of such positions ( fwidgetrect.pos ) starting from the toplevel through the
3589	3609		chain of all parents up to the current widget;
3590	3610		"nullpoint" (0,0) for toplevel widgets ( window-owning forms,..)
3591	3611
3592	3612		screenpos:
3593	3613		- coord aginst the top-left corner of screen
3594	3614		- WM decoration & title aren't parts of the widget !
3595	3615
3596	3616		widgetrect:
3597	3617		the widget on-screen area including its frame & frame caption
3598	3618
3599	3619		paintrect:
3600	3620		the widget on-screen area except its frame & frame caption
3601	3621
3602	3622		clientrect:
3603	3623		virtual area which
3604	3624		- for non-scrolling widgets, equals to "paintrect", with its "pos:= (0,0)"
3605	3625		- for scrolling widgets, may be bigger than "paintrect",
3606	3626		also may shift ( change its "pos" ) when scrolling
3607	3627
3608	3628		* "t*grid" aren't such scrollable widgets since their virtual height would be limited by
3609	3629		the X11 "+-32000" limitation,
3610	3630		so example of such widgets are tscrollbox, "tform.container" etc
3611	3631
3612	3632		framerect:
3613	3633		the widget on-screen area except its frame caption but including inner & outer frame
3614	3634
3615	3635		****************
3616	3636
3617	3637		// releases all thread locks then post the event to the app event queue and
3618	3638		// waits for the event handler finishes ( signalled by "sye_ok on a semaphore )
3619	3639		// finally restores the locks
3620	3640		// true if the handler is not aborted
3621	3641		function synchronizeevent(const aevent: tsynchronizeevent): boolean;
3622	3642
3623	3643		// translates "point" coord against "source" widgetrect to "dest" widgetrect
3624	3644		//
3625	3645		// * nil "source" = from screen coord
3626	3646		// * nil "dest" = to screen coord
3627	3647		procedure translatewidgetpoint1(var point: pointty; const source,dest: twidget);
3628	3648
3629	3649		// the function-framed version of "translatewidgetpoint1"
3630	3650		function translatewidgetpoint(const point: pointty; const source,dest: twidget): pointty;
3631	3651
3632	3652		// rect isntead of point,
3633	3653		// if dest = nil then to screen
3634	3654		// if source = nil then against screen
3635	3655		function translatewidgetrect(const rect: rectty; const source,dest: twidget): rectty;
3636	3656		//-----------------
3637	3657		// translates "point" coord against "source" paintrect to "dest" paintrect
3638	3658		// * nil "source" = from screen coord
3639	3659		// * nil "dest" = to screen coord
3640	3660		procedure translatepaintpoint1(var point: pointty; const source,dest: twidget);
3641	3661
3642	3662		// the function-framed version of "translatepaintpoint1"
3643	3663		function translatepaintpoint(const point: pointty; const source,dest: twidget): pointty;
3644	3664
3645	3665		// rect isntead of point,
3646	3666		// if dest = nil then to screen
3647	3667		// if source = nil then against screen
3648	3668		function translatepaintrect(const rect: rectty;const source,dest: twidget): rectty;
3649	3669		//-----------------
3650	3670		// translates "point" coord against "source" clientrect to "dest" clienttrect
3651	3671		// * nil "source" = from screen coord
3652	3672		// * nil "dest" = to screen coord
3653	3673		procedure translateclientpoint1(var point: pointty;
3654	3674		const source,dest: twidget);
3655	3675
3656	3676		// the function-framed version of "translateclientpoint1"
3657	3677		function translateclientpoint(const point: pointty; const source,dest: twidget): pointty;
3658	3678
3659	3679		// rect isntead of point,
3660	3680		// if dest = nil then to screen
3661	3681		// if source = nil then against screen
3662	3682		function translateclientrect(const rect: rectty; const source,dest: twidget): rectty;
3663	3683		//-----------------
3664	3684
3665	3685		// (re)sorts "awidgets" in order of increasing their "widgetrect.x" coords
3666	3686		// - if parent = nil then the coords are against individual parent of each of "awidgets"
3667	3687		// - if parent is supplied then the coords are against this parent
3668	3688		procedure sortwidgetsxorder(var awidgets: widgetarty; const parent: twidget = nil);
3669	3689
3670	3690		// (re)sorts "awidgets" in order of increasing their "widgetrect.y" coords
3671	3691		// - if parent = nil then the coords are against individual parent of each of "awidgets"
3672	3692		// - if parent is supplied then the coords are against this parent
3673	3693		procedure sortwidgetsyorder(var awidgets: widgetarty; const parent: twidget = nil);
3674	3694
3675	3695		// for each of "widgets", calculates its autosized client area ( min size rect to fit the caption, etc )
3676	3696		// - both hor & ver sizes of client area of each of "widgets" are adjusted to the max of the above calculated areas,
3677	3697		// as the result - client areas of all widgets become identically v+h sized
3678	3698		//
3679	3699		// * right & bottom anchored margins of each widget are preserved
3680	3700		procedure syncmaxautosize(const widgets: array of twidget);
3681	3701
3682	3702		// for each of "widgets", width of client area of each of "widgets" is adjusted so that
3683	3703		// external ( by the outer border of frame ) widths of all widgets become identical
3684	3704		// to the external widht of the widest widget
3685	3705		//
3686	3706		// * if "awidth" >= 0 then no determining the widest widget is taken and
3687	3707		// "awidth" is adjusted to instead, for all widgets
3688	3708		// * right anchored margins of each widget are lost
3689	3709		procedure syncminframewidth(const awidgets: array of twidget;
3690	3710		const awidth: integer = -1);
3691	3711
3692	3712		// for each of "widgets", height of client area of each of "widgets" is adjusted so that
3693	3713		// external ( by the outer border of frame ) heights of all widgets become identical
3694	3714		// to the external height of the highest widget
3695	3715		//
3696	3716		// * if "aheight" >= 0 then no determining the highest widget is taken and
3697	3717		// "aheight" is adjusted to instead, for all widgets
3698	3718		// * bottom anchored margins of each widget are lost
3699	3719		procedure syncminframeheight(const awidgets: array of twidget; const aheight: integer = -1);
3700	3720
3701	3721		## Projects using MSEgui
3702	3722
3703	3723		- [[Projects using MSEgui]]
3704	3724
3705	3725		---
3706	3726		From the Free Pascal wiki, page "Reference: MSEgui", as it stood on 2021-04-09 after a change by Roland57, 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