Reference: MSEgui: what changed

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

Title: Reference: MSEgui

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