Difference between revisions of "Reference: MSEgui"

From Lazarus wiki
Jump to navigationJump to search
(Added tformscrollbox)
 
(40 intermediate revisions by 3 users not shown)
Line 10: Line 10:
 
=== TMseFormWidget ===
 
=== TMseFormWidget ===
 
Use it in order to insert a tcustomform descendant into another widget at designtime. Does not try to load resources in "create".
 
Use it in order to insert a tcustomform descendant into another widget at designtime. Does not try to load resources in "create".
 +
<pre>
 +
        tmseform descendants ( MainForm, SimpleForm,.. )
  
=== TDockFormWidget ===
+
Client area of the form & parent of its widgets ( against which the widgets
=== TPaintbox ===
+
are placed and colored ) is presented by the "container" property
 +
not "container.frame.clientarea"
 +
 
 +
CanClose is called :
 +
 
 +
- on receiving "ek_close" by window
 +
- for modal window, on focus change
  
How to draw line (or circle) on tpaintbox? In event onpaint:
+
- within parent window's "CanClose" where all nested windows are 
 +
checked for OnCloseQuery & OnClose - if any sets "mr_none" then the parent window
 +
can't close as well
 +
 +
- from nested window's "CanParentClose"
 +
- from own "CanParentClose"
  
<syntaxhighlight lang=pascal>
+
- some componnets build oneself in own "Loaded" procedure :
procedure tmainfo.paintboxonpaint(const sender: twidget; const canvas: tcanvas);
+
= widget grids
begin
+
= database access components
  with sender,canvas do begin
+
= ...
  drawline(nullpoint,pointty(size),cl_yellow); 
 
  //diagonal line across widget  
 
  drawellipse(makerect(makepoint(bounds_cx div 2,bounds_cy div 2), size),cl_red);
 
  //circle (or ellipse) centered in widget                           
 
  end;
 
end;
 
</syntaxhighlight>
 
 
Makepoint and makerect are in msegraphutils.
 
  
=== TEventWidget ===
+
The "form.show" has parameter "transientfor".
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.
+
The window Z-order is above the "transientfor" window. The exact behaviour
 +
depends on the window manager.
 +
       
 +
        caption
 +
- run-time caption on the title bar
  
=== TButton ===
+
color
* A rectangular clickable area that can show text/bitmap.
+
- color behind the client ( contaner ) area
- Main properties:
 
Caption: read/write the text that appear on top of it.
 
onexecute: read/write the address of a procedure (event handler) to be executed when clicked.
 
  
=== TStockGlyphButton ===
+
container
=== TRichButton ===
+
- the real parent of form's widgets, <see "tformscrollbox">
=== TLabel ===
 
* Draws a piece of text on the given surface (canvas: screen/printer/bitmap).
 
- Main properties:
 
Caption: read/write the piece of text.
 
  
See also [[Reference:_MSEgui/TLabel|TLabel]]
+
cursor
 +
- the mouse over cursor shape
  
=== TGroupBox ===
+
enabled - "false" disables all child widgets
=== TStepBox ===
 
=== TStringDisp ===
 
*A read only version of TStringEdit, difference from TLabel: has a frame around it.
 
-Main properties:
 
Value: read/write the text that are showed.
 
Caption: A label normally describing the purpose or meaning of the presented text, it can be positioned around the frame.
 
  
=== TByteStringDisp ===
+
face
=== TIntegerDisp ===
+
<see "tfacecomp"> + some more options
=== TRealDisp ===
 
=== TDateTimeDisp ===
 
=== TBooleanDisp ===
 
=== TToolBar ===
 
=== TDrawGrid ===
 
=== TStringGrid ===
 
=== TTabBar ===
 
=== TTabPage ===
 
=== TTabWidget ===
 
=== TDockHandle ===
 
=== TDockPanel ===
 
=== TSpliter ===
 
<pre>
 
      A widget very similar to "tspacer" but :
 
- designed to rearrange areas occupied by adjacent widgets
 
- a linked widget may only enlarge by "eating" the opposite one,
 
so the summary area of both widgets don't change
 
- has GUI look ( hatched grip, color etc) switched on by default
 
- facilitates run-time repositioning oneself and linked widgets
 
- linked widgets may even be other splitters, spacers (with their linked widgets ),..
 
 
        Properties:
 
  
- color
+
font
= see {any_widget.color}
+
<see "tfont">
  
- cursor
+
frame
= see {any_widget.cursor}
+
<see "tframecomp"> + some more options
 +
 +
icon
 +
<see "timage">
 +
 
 +
mainmenu
 +
<see tmainmenu>
  
- enabled
+
name
= "false" stops user interaction
+
- name to refer when programming
  
- face
+
options:
= see {any_face}
 
  
- frame
+
fo_main
= see {any_frame}
+
- assigns this from as the aplication GUI-face & event receiver
 +
- causes the icon of this form to be icon of the application
  
- colorgrip
+
fo_terminateonclose
= color of grip hatching
+
- causes the application to terminate once the form has closed ( doesn't depend on "fo_main" )
  
- grip
 
= defines hatching pattern of the grip
 
  
* stb_dens(N) : the pattern is of rhombuses, the painted rhombs occupy "N" persents of the grip
+
fo_freeonclose
 +
- causes the form (even being modal) to release its memory on closure or OK-return from "CanClose"
  
* stb_block(N) : the pattern is of squares, painted & unpainted squares are equally sized and
+
fo_defaultpos
both have "N" pixels sides
+
- lets the WM to position the form initially
 
* stb_hatchup(N) : the pattern is of right-tilted lines of 1 pixel width,
 
each "N"-th pixel forms these lines
 
  
* stb_hatchdown(N) : the pattern is of left-tilted lines of 1 pixel width,
+
fo_screencentered
each "N"-th pixel forms these lines
+
- causes the form initially to show in center of the apllication work area
  
* stb_crosshatch(N) : the pattern is of crossing (left & right) tilted lines of 1 pixel width,
+
fo_closeonesc
each "N"-th pixel forms these lines
+
- causes the form to close on "Esc" key pressed ( with MR_ESCAPE & "OnCloseQuery" firing )
  
 +
fo_cancelonesc
 +
- causes the form to close on "Esc" key pressed ( with MR_CANCEL & "OnCloseQuery" firing )
  
- linkbottom/linkleft/linkright/linktop
+
fo_closeonenter
= see {tspacer.*}
+
- causes the form to close on "Enter" key pressed ( with MR_OK & "OnCloseQuery" firing )
  
- options
+
fo_closeonf10
 +
- causes the form to close on "F10" key pressed ( with MR_F10 & "OnCloseQuery" firing )
  
= spo_hmove
+
fo_globalshortcuts
* "true" allows the spliter to move horizontally
+
- allows on-this-form "ao_globalshortcut" actions to trigger
  
= spo_hprop
+
  Notes :
* "true" : keep the left position proportional ( on the ratio of creation time )
+
= shortcuts for modal not "fo_localshortcut" forms are processed by app
to weigth of the client area of parent
+
= shortcuts for "fo_globalshorcut" forms are processed by the owning window
  
= spo_hsizeprop
+
fo_localshortcuts
* "true" : keep width of the spacer proportional ( on the ratio of creation time )
+
- disables triggering shortcuts of on-this-form actions
to weigth of the client area of parent
 
* the width stops shrinking on one set in design time
 
  
= spo_vmove
+
fo_autoreadstat
* "true" allows the spliter to move vertically
+
- for "cs_ismodule" forms, before "OnLoaded" fires, rereads all statvars from the bound stafile/memorystream
  
= spo_vprop
+
fo_autowritestat
* "true" : keep the top position proportional ( on the ratio of creation time )
+
- in "CanClose", after "OnClose" fires [ and before app termination for "fo_terminateonlose" form ],
to height of the client area of parent
+
rewrites all statvars to the stafile/memorystream
 +
- for datamodules, does this before "OnDestroy" fires
  
= spo_vsizeprop
+
fo_savepos
* "true" : keep height of the spacer proportional ( on the ratio of creation time )
+
- saves/restores Z-order, size & scree coordinates of the form
to height of the client area of parent
+
as soon as the stat data are ready
* the height stops shrinking on one set in design time
 
  
= spo_dockleft
+
fo_savestate
* causes the "linkleft" widget to dock to the left border of splitter
+
- for top-level form, saves/restores "VSize", "Active" & "Visible"  
* make sence only if linkleft "widget.bounds_x" less than "splitter.bounds_x"
+
as soon as the stat data are ready
  
= spo_docktop
+
optionswidget
* causes the "linktop" widget to dock to the top border of splitter
+
<see "any widget">
* make sence only if linktop "widget.bounds_y" less than "splitter.bounds_y"
+
optionswindow
 +
<see "any window">
 +
popupmenu
 +
<see "tpopupmenu">
 +
stafile
 +
<see "tstafile">
 +
stavarname
 +
taborder
 +
tag
  
= spo_dockright
+
visible - for a form, only affects its childs widgets
* causes the "linkright" widget to dock to the right border of splitter
 
* make sence only if linkright "widget.(bounds_x+bounds_cx)" more than "splitter.(bounds_x+bounds_cx)"
 
  
= spo_dockbottom
+
Events:
* causes the "linkbottom" widget to dock to the bottom border of splitter
 
* make sence only if linkbottom "widget.(bounds_y+bounds_cy)" more than "splitter.(bounds_y+bounds_cy)"
 
  
!!! Two special cases :
+
activate = to set focused & redraw the invalidated area
  
1. (spo_dockleft = spo_dockright = TRUE) && (linkleft = linkright = the_same_widget) :
+
oncreate
causes the "linkleft" widget to adjust to h-positiion & width of the splitter,
+
- fires before "Loaded" procedure is called
it's even possible that the widget doesn't touch the splitter
+
- fires after creating the widget & its subwidgets but before the final arrangement
 +
- forms arent' yet visible on return
  
(spo_docktop = spo_dockbottom = TRUE) && (linktop = linkbottom = the_same_widget) :
+
  Since "Loaded" procedure hasn't yet worked at this point then
causes the "linktop" widget to adjust to v-position & height of the splitter,
+
database contents, values of widget grid's subwidgets
 +
are invalid in this event ***
  
It's even possible in these cases that the widget doesn't touch the splitter
+
onloaded
 +
- fires once "Loaded" procedure of owns & all form's widgets finishes
 +
- processed  after "OnCreate"
 +
- on finishing, forms aren't yet visible
  
- optionsscale
+
oneventloopstart ( main forms only )
= see {tscalingwidget.optionsscale}
+
- only applicable to main forms
 +
- fires once all application GUI is built and shown
 +
( and ready to user's interaction )
 +
 +
onactivate
 +
- see {any_widget.OnActivate}
  
- optionswidget
+
onenter
= see {anywidget.optionswidget}
+
= see {any_widget.OnEnter}
  
- onactivate, onchildscaled, ondeactivate, ondefocus, onenter, onexit, onfocus,
+
onfocus
  onfontheightdelta, onmove, onpopup, onresize, onshowhint
+
- see {any_widget.OnFocus}
= see "tspacer"
+
 +
 
 +
onwindowactivechanged
 +
- fires on :
 +
= touching another window even on clicking in a behind-modal window ( or its title bar )
 +
= 1-st showing the window
 +
- reactivating the window
 +
 
 +
onbeforepaint
 +
- fires at the very beginning of "paint", before drawing canvas
 +
 
 +
onpaint
 +
- fires in "paint" procedure, between drawing canvas and contained widgets
  
- onupdatelayout
+
onafterpaint (doafterpaint)
fires :
+
- fires just on return from "paint" procedure
 
= on creating the splitter
 
= on any reposition of the linked widgets
 
( due to moving the splitter, resizing the parent,.. )
 
</pre>
 
  
=== TSpacer ===
+
        onapplicationactivechanged
* a regular widget which creates a kind of positional link between surrounding widgets
+
- fires :
* designed to maintain distances between widgets
+
= if the application gets/looses input focus
* may have GUI look, caption etc switched off by default
 
* resizing a spacer repositions its linked widgets
 
  
Properties:
+
onasyncevent (doasyncevent)
 +
- fires on calling {this_form}.asyncevent(atag) from any place of the application
 +
once delivered by the app even queue
  
- anchors
+
"atag" set by caller(s) helps to branch within "onasyncevent", to identify the caller, etc ***
= see {any_widget.anchors}
+
generally, doesn't fire instantly because these events are delivered through the app event queue ***
  
- bounds
 
= see {any_widget.bounds}
 
  
- color
+
onchildmouseevent
= see {any_widget.color}
+
- fires on any mouse activity over its child widget(s) not the (containing) widget oneself
  
- enabled
+
      for forms, it even fires on enetering "container" therefore it appears as if to be the form itself ***
= "false" turns color of the caption to gray
 
  
- visible
+
onchildscaled
= "true" allows displayable settings (caption text, face, frame etc) to take
+
- see {any_widget.OnChildScaled}
effect in run-time as well
 
 
- <face>
 
= see {any face}
 
  
- <frame>
+
onclientmouseevent
= see {any frame}
+
- fires on any mouse activity over areas expecting user's mouse input (not titlebars/frames/...)
  
- linkbottom
+
onclose
= widget linked down to most outer edge (incl. frame[.caption]) of the spacer
+
- fires in "CanClose" if "modalresult <> mr_none"
- linkleft
+
 
= widget linked left to most outer edge of the spacer
+
onclosequery
- linkright
+
- fires in "CanClose" before "OnClose"
= widget linked right to most outer edge of the spacer
+
- "mr_none" set on return prevents the window (and its parent) from closing
- linktop
+
( "OnClose" is also bypassed )
= widget linked up to most outer edge of the spacer
 
  
- dist_bottom, dist_left, dist_right, dist_top :
 
= margins between most outer edge the spacer
 
and the corresponding linked widget
 
  
- options :
+
ondeactivate
 +
- see {any_widget.OnDeactivate}
  
= spao_glueright
+
ondefocus
 +
- see {any_widget.OnDeFocus}
 +
 +
ondestroy
 +
- fires on in-code calling "BeforeDestruction"
  
  - if "false"
+
ondestroyed
 +
- fires on return from the form's destructor ( when all resources are freed )
  
h-repositioning or h-resizing the linkleft widget shifts
+
onterminatequery
the whole linked construction, it becomes the only way to h-shift
+
- fires on an attempt to terminate the app
 +
- by setting "var terminate:= false", allows to cancel termination
  
if {an_right IN linkright_widget.anchors} then the spacer
+
Termination by debugger/OS facilities can't be blocked this way ( win32 )***
may be right-resized with auto h-resizing the linkright widget
 
so that the right margin of that widget is kept
 
  
if NOT {an_right IN linkright_widget.anchors} then the spacer
+
onterminated
may be right-resized with auto h-shifting the linkright widget
+
- fires for not-yet-destroyed forms, once the app event loop finishes
so that width of that widget is kept
+
- may be caused by any closure of the main app form
 +
( app termination, WM/OS facilities, )
  
- if "true"
 
  
h-repositioning or h-resizing the linkright widget shifts
+
onwindowdestroyed
the whole linked construction, it becomes the only way to h-shift
+
- fires once a descendant window is destroyed
 +
( for a main form, when a modal simple form is closed by any way,.. )
  
if {an_left IN linkleft_widget.anchors} then the spacer
+
onevent
may be h-resized with auto h-resizing the linkleft widget
+
- fires on receiving an event
so that the left margin of that widget is kept
+
= for simple forms, it's only "ek_loaded"
  
if NOT {an_left IN linkleft_widget.anchors} then the spacer
+
There can be more if the form is connected to object_event sending
may be h-resized with auto h-shifting the linkleft widget
+
components or if the application uses object events, for example by calling
so that width of that widget is kept
+
tguicomponent.postcomponentevent. ****
  
= spao_gluebottom
+
onexit
 +
- see {any_widget.OnExit}
  
- if "false"  
+
onfocusedwidgetchanged
 +
- for a "prev-new" parent-wide focused wigdets pair, fires once installing new focus has finished,
 +
after "OnFocus"
 +
- resends for all contained widgets
 +
- doesn't fire if the "prev-new" pair don't really change
  
v-repositioning or v-resizing the linktop widget shifts
+
onfontheightdelta
the whole linked construction, it becomes the only way to v-shift
+
- see {any_widget.OnFontHeightDelta}
  
if {an_bottom IN linkbottom_widget.anchors} then the spacer
+
onhide
may be v-resized with auto v-resizing the linkbottom widget
+
- fires at beginnig of own/parent's
so that the bottom margin of that widget is kept
+
= hide
 +
= hidden
 +
= destroying
 +
= setting "visible:= false"
 +
= closing the window ( receiving event "ek_close",.. )
 +
= calling "window.close"
 +
 +
onidle
 +
- fires everytime when the app GUI event queue gets empty
 +
- to stop calling for a while, set "again" parameter to "false" (the initial value );
 +
 +
DON'T DO ANYTHING AFFECTING THE APP EVENT QUEUE ( MODAL WINDOWS, "ShowMessage", Sleep(N),... ) IN THIS HANDLER.
 +
MODAL WINDOWS CAUSE RECURSION !
 +
 +
A code fragment:
 +
 
 +
again:= i < 5;
 +
if not again then exit;
  
if NOT {an_bottom IN linkbottom_widget.anchors} then the spacer
+
onkeydown
may be v-resized with auto v-shifting the linkbottom widget
+
- fires on pressing down a keyboard key over the client area when none of child widgets is focused
so that height of that widget is kept
 
  
- if "true"
+
onkeyup
 +
- fires on releasing a keyboard key over the client area when none of child widgets is focused
  
        v-repositioning or v-resizing the linkbottom widget shifts
+
onmouseevent
the whole linked construction, it becomes the only way to v-shift
+
- fires on any mouse activity over the client area
  
if {an_top IN linktop_widget.anchors} then the spacer
+
onmove
may be v-resized with auto v-resizing the linktop widget
+
- see {any_window.OnMove}
so that the top margin of that widget is kept
 
  
if NOT {an_top IN linktop_widget.anchors} then the spacer
+
onpopup
may be v-resized with auto v-shifting the linktop widget
+
- see {any_widget.OnPopup}
so that height of that widget is kept
 
  
- optionsscale
+
onresize
= see {tscalingwidget.optionsscale}
+
- see {any_widget.OnResize}
  
- optionswidget
+
onshortcut
= see {anywidget.optionswidget}
+
- fires before built-in shorcut processing
 +
- "info.eventstate=es_processed" set in "OnShortcut" prevents
 +
the event from further auto-processing
  
- onactivate, onchildscaled, ondeactivate, ondefocus, onenter, onexit, onfocus,
+
The app
  onfontheightdelta, onpopup, onresize, onshowhint
+
- recognizes & takes registered shortcuts from app event queue
= see {any_widget.*}
+
- passes the shocrcut event to each of its windows until the event
 +
is processed otherwise processes it by oneself
 +
  
- onmove
+
onshow
= see {any_window.OnMove}
+
- fires if the widget is visible:
 +
= on calling "Show" method
 +
= on return from "Loaded" procedure
 +
= on showing the parent widget
 +
- since called at end, allows to adjust the default behavior
  
any "link*" option set disables the spacer to reposition solely,
+
onshowhint
repositioning is only controlled by a "glued" widget since then
+
- see {any_widget.OnShowHint}
  
=== TLayouter ===
+
onstatbeforeread
* a tspacer descendant designed to (auto)resize or/and move its contained widgets acc to some size/positon dependencies
+
- fires before loading statvars  from the disk file
* may have GUI look, frame caption etc switched off by default
 
* layouters may be nested to achieve complex layouts
 
  
Each layout change/assignment is divided into performing 3 consequent stages :
+
onstatafterread
 +
- fires once statvars are loaded from the disk file
  
==== Stage 1 ====
+
onstatupdate
 +
- fires at 1-st stage before updating GUI "state/pos" for read statvars
 +
or
 +
- fires at pre-last stage before saving GUI "state/pos"
  
Widgets auto resized using the following options:
+
onstatread
 +
- fires at 2-nd stage before updating GUI "state/pos" for read statvars
  
<pre>
+
onstatwrite
- if {lao_placex OR lao_placey} :
+
- fires at last stage before saving GUI "state/pos"
  
= if {plo_scalesize in optionslayout}  then
+
pon stat reading, non-minimized visible windows are shown,
* widgets with "osk_nopropwith" unset in their "optionsskin" are h-scaled
+
the active window is activated
    in the proportion of change of tlayouter's clientwidth
 
* widgets with "osk_nopropheight" unset in their "optionsskin" are v-scaled
 
    in the proportion  of change of tlayouter's clientheight
 
  
For h-resized layouter, the effect looks like :
+
</pre>
 +
=== TDockFormWidget ===
 +
=== TPaintbox ===
  
|--Widget__1---Widget__2--| => the initial look
+
How to draw line (or circle) on tpaintbox? In event onpaint:
  
  |--Widget_1--Widget_2--| => the layouter gets narrower
+
<syntaxhighlight lang=pascal>  
 +
procedure tmainfo.paintboxonpaint(const sender: twidget; const canvas: tcanvas);
 +
begin
 +
  with sender,canvas do begin
 +
  drawline(nullpoint,pointty(size),cl_yellow); 
 +
  //diagonal line across widget
 +
  drawellipse(makerect(makepoint(bounds_cx div 2,bounds_cy div 2), size),cl_red);
 +
  //circle (or ellipse) centered in widget                           
 +
  end;
 +
end;
 +
</syntaxhighlight>
 +
 +
Makepoint and makerect are in msegraphutils.
  
  |---Widget___1---Widget___2---| => the layouter gets wider
+
=== TEventWidget ===
 +
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.
  
*** both widget sizes & margins are affected ***
+
=== TButton ===
*** Widget_N may generally situate on different y-levels ***
+
* A rectangular clickable area that can show text/bitmap.
 
+
- Main properties:
otherwise :
+
Caption: read/write the text that appear on top of it.
 +
onexecute: read/write the address of a procedure (event handler) to be executed when clicked.
  
= if lao_scalewidth in optionslayout :
+
=== TStockGlyphButton ===
* widgets with "osk_nopropwith" unset in their "optionsskin" enters in the mode
+
=== TRichButton ===
  ( not applied until the layouter resizes! ) when they are h-scaled in the proportion
+
=== TLabel ===
  as far as clientwidth of the tlayouter changes, then stages 2 & 3 are reapplied
+
* Draws a piece of text on the given surface (canvas: screen/printer/bitmap).
 +
- Main properties:
 +
Caption: read/write the piece of text.
  
For h-resized layouter, the effect looks like :
+
See also [[Reference:_MSEgui/TLabel|TLabel]]
  
  |--Single____widget????| => the initial look
+
=== TGroupBox ===
 +
=== TStepBox ===
 +
=== TStringDisp ===
 +
*A read only version of TStringEdit, difference from TLabel: has a frame around it.
 +
-Main properties:
 +
Value: read/write the text that are showed.
 +
Caption: A label normally describing the purpose or meaning of the presented text, it can be positioned around the frame.
  
  |--Single__widget???| => the layouter gets narrower
+
=== TByteStringDisp ===
 
+
=== TIntegerDisp ===
  |--Single_______widget?????| => the layouter gets wider
+
=== TRealDisp ===
 
+
=== TDateTimeDisp ===
* also, if {lao_scaleleft in optionslayout} then left margins of the widgets  
+
=== TBooleanDisp ===
  with unset "optionsskin.osk_nopropleft" resize too otherwise retain
+
=== TToolBar ===
 +
=== TDrawGrid ===
 +
=== TStringGrid ===
 +
=== TTabBar ===
 +
=== TTabPage ===
 +
=== TTabWidget ===
 +
=== TDockHandle ===
 +
=== TDockPanel ===
 +
=== TSpliter ===
 +
<pre>
 +
      A widget very similar to "tspacer" but :
 +
- designed to rearrange areas occupied by adjacent widgets
 +
- a linked widget may only enlarge by "eating" the opposite one,
 +
so the summary area of both widgets don't change
 +
- has GUI look ( hatched grip, color etc) switched on by default
 +
- facilitates run-time repositioning oneself and linked widgets
 +
- linked widgets may even be other splitters, spacers (with their linked widgets ),..
 +
 +
        Properties:
  
= if lao_scaleheight in optionslayout :
+
- color
* widgets with "osk_nopropheight" unset in their "optionsskin" enters in the mode
+
= see {any_widget.color}
  ( not applied until the layouter resizes! ) when they are v-scaled in the proportion
 
    as far as clientheight of the tlayouter changes, then stages 2 & 3 are reapplied
 
  
* also, if {lao_scaletop in optionslayout} then top margins of the widgets
+
- cursor
  with unset "optionsskin.osk_noproptop" resize too otherwise retain
+
= see {any_widget.cursor}
  
*** only widget sizes & margins not distances between them are affected ***
+
- enabled
 +
= "false" stops user interaction
  
</pre>
+
- face
 +
= see {any_face}
  
==== Stage 2 ====
+
- frame
 +
= see {any_frame}
  
Widgets may be auto resized in 5 consequent steps using the following options:
+
- colorgrip
 +
= color of grip hatching
 +
 
 +
- grip
 +
= defines hatching pattern of the grip
  
<pre>
+
* stb_dens(N) : the pattern is of rhombuses, the painted rhombs occupy "N" persents of the grip
  
1. if plo_syncmaxautosize in place_options :
+
* stb_block(N) : the pattern is of squares, painted & unpainted squares are equally sized and  
  = all widgets are autosized then their client areas are synchronised to the
+
both have "N" pixels sides
    clientareas of the highest and the widest of the widget
+
  * calls "msegui.syncmaxautosize"
+
* stb_hatchup(N) : the pattern is of right-tilted lines of 1 pixel width,
 +
each "N"-th pixel forms these lines
  
2. if plo_syncpaintwidth in place_options :
+
* stb_hatchdown(N) : the pattern is of left-tilted lines of 1 pixel width,
  = the paintwidths of all widgets are synchronized to the widget with the
+
each "N"-th pixel forms these lines
    widest outer frame width ( ex. width of "frame.caption" )
 
  * mainly makes sense if "lao_alignx" set and {align_glue = wam_start or wam_end}
 
    ( see below ) when the widgets will be adjusted in order to fit into the
 
    inner client width of tlayouter:
 
  
                                  x-align level         
+
* stb_crosshatch(N) : the pattern is of crossing (left & right) tilted lines of 1 pixel width,
                                        V               
+
each "N"-th pixel forms these lines
                        +----------------------------------+
 
                        | Widget_1 the_widest_frame_caption|
 
                        | Widget_2 frame_caption2          |
 
                        | Widget_N wider_frame_captionN    |
 
                        +----------------------------------+
 
  
  here, the effect is shown for "cp_right" frame captions
 
    // otherwise syncronizes to the outer ( of the frame except its caption ) width
 
    // of the Z-top widget
 
  * calls "msegui.syncpaintwidth"
 
  * paintwidth is the outer width
 
  
3. if plo_syncpaintheight in place_options :
+
- linkbottom/linkleft/linkright/linktop
  = the paintheights of all widgets are synchronized to the widget with the
+
= see {tspacer.*}
    highest outer frame width ( ex. width of "frame.caption" ).
 
  * mainly makes sense if lao_aligny set and {align_glue = wam_start or wam_end}
 
    ( see below ) the widgets will be adjusted in order to fit into the inner
 
    client height of tlayouter :
 
  
                        +------------------------------+
+
- options
                        | The_                        |
 
                        | tallest_            taller_  |
 
                        | frame_    frame_    frame_  |
 
                        | caption  caption2  captionN | 
 
                        |                              |
 
                        | Widget1  Widget_2  Widget_N |<== y-align level
 
                        +------------------------------+   
 
  
  here, the effect is shown for "cp_topleft" frame captions
+
= spo_hmove
    // otherwise syncronizes to the outer ( of the frame except its caption )
+
* "true" allows the spliter to move horizontally
    // height of the Z-top widget
 
  * calls "msegui.syncpaintheight"
 
 
4. plo_synccaptiondistx in place_options :
 
  = causes all widgets to have the widest common room for their cp_(left/right)* frame captions
 
  * calls "msegui.synccaptiondistx"
 
 
5. plo_synccaptiondisty in place_options :
 
  = causes all widgets to have the highest common room for their cp_(top/bottom)* frame captions
 
  * calls "msegui.synccaptiondisty"
 
</pre>
 
  
==== Stage 3 ====
+
= spo_hprop
 +
* "true" : keep the left position proportional ( on the ratio of creation time )
 +
to weigth of the client area of parent
 +
 
 +
= spo_hsizeprop
 +
* "true" : keep width of the spacer proportional ( on the ratio of creation time )
 +
to weigth of the client area of parent
 +
* the width stops shrinking on one set in design time
  
The widgets may be (re)arranged within the layouter.
+
= spo_vmove
 +
* "true" allows the spliter to move vertically
  
<pre>
+
= spo_vprop
There're 2 modes of such (re)arrangement which can be partially (orthogonally)
+
* "true" : keep the top position proportional ( on the ratio of creation time )  
combined (see later):
+
to height of the client area of parent
  
1) The place(ment) mode ( lao_place* in optionslayout ) :
+
= spo_vsizeprop
 +
* "true" : keep height of the spacer proportional ( on the ratio of creation time )  
 +
to height of the client area of parent
 +
* the height stops shrinking on one set in design time
  
- widgets are placed at some distances between each other, possibly with some
+
= spo_dockleft
  margins, rooms of invisible widgets ( having visible=false) are also allocated
+
* causes the "linkleft" widget to dock to the left border of splitter
  unless "plo_noinvisible in place_options"
+
* make sence only if linkleft "widget.bounds_x" less than "splitter.bounds_x"
  
  * the widgets are placed in the order of decreasing their "widgetrect.x"
+
= spo_docktop
coordinates before alignment
+
* causes the "linktop" widget to dock to the top border of splitter
 
+
* make sence only if linktop "widget.bounds_y" less than "splitter.bounds_y"
  * the inter-widget distances and the side margins ( if apllied ) in both
+
 
dimentions are identical and limited between "place_mindist" and
+
= spo_dockright
"place_maxdist"
+
* causes the "linkright" widget to dock to the right border of splitter
 
+
* make sence only if linkright "widget.(bounds_x+bounds_cx)" more than "splitter.(bounds_x+bounds_cx)"
  = if {lao_placex in optionslayout} and {place_mode <> wam_none} then the
+
 
following relevant settings apply:
+
= spo_dockbottom
 
+
* causes the "linkbottom" widget to dock to the bottom border of splitter
* non-limiting value of "place_maxdist" :
+
* make sence only if linkbottom "widget.(bounds_y+bounds_cy)" more than "splitter.(bounds_y+bounds_cy)"
+
 
# |Widget_1------Widget_2------Widget_3|
+
!!! Two special cases :
+
 
* non-limiting value of "place_maxdist" and {plo_propmargin in place_options} :
+
1. (spo_dockleft = spo_dockright = TRUE) && (linkleft = linkright = the_same_widget) :
+
causes the "linkleft" widget to adjust to h-positiion & width of the splitter,
# |---Widget_1---Widget_2---Widget_3---|
+
it's even possible that the widget doesn't touch the splitter
+
 
* limiting value of "place_maxdist" and {place_mode = wam_start} :
+
(spo_docktop = spo_dockbottom = TRUE) && (linktop = linkbottom = the_same_widget) :  
+
causes the "linktop" widget to adjust to v-position & height of the splitter,
# |Widget_1----Widget_2----Widget_3????|
+
 
+
It's even possible in these cases that the widget doesn't touch the splitter
* limiting value of "place_maxdist" and {place_mode = wam_start} and
+
 
  {plo_propmargin in place_options} :
+
- optionsscale
+
= see {tscalingwidget.optionsscale}
# |---Widget_1---Widget_2---Widget_3???|
+
 
 +
- optionswidget
 +
= see {anywidget.optionswidget}
 +
 
 +
- onactivate, onchildscaled, ondeactivate, ondefocus, onenter, onexit, onfocus,
 +
  onfontheightdelta, onmove, onpopup, onresize, onshowhint
 +
= see "tspacer"
 +
 
 +
- onupdatelayout
 +
fires :
 
 
* limiting value of "place_maxdist" and {place_mode = wam_end} :
+
= on creating the splitter
+
= on any reposition of the linked widgets  
# |??????Widget_1---Widget_2---Widget_3|
+
( due to moving the splitter, resizing the parent,.. )
+
</pre>
* limiting value of "place_maxdist" and {place_mode = wam_end} and
+
 
  {plo_propmargin in place_options} :
+
=== TSpacer ===
+
* a regular widget which creates a kind of positional link between surrounding widgets
# |???Widget_1---Widget_2---Widget_3---|
+
* designed to maintain distances between widgets
+
* may have GUI look, caption etc switched off by default
* limiting value of "place_maxdist" and {place_mode = wam_center} :
+
* resizing a spacer repositions its linked widgets
 
# |???Widget_1---Widget_2---Widget_3???|
 
 
* limiting value of "place_maxdist" and {plo_endmargin in place_options} :
 
 
# |Widget_1----Widget_2----Widget_____3|, or
 
 
# |Widget_1----Widget_____2----Widget_3|, or
 
 
# |Widget_____1----Widget_2----Widget_3|, here, the most left amongst
 
widgets having both [an_left,an_right] set is expanded otherwise the most
 
right widget ( Widget_3 in the example )
 
 
* limiting value of "place_maxdist" and {place_mode = wam_end} and
 
  {plo_propmargin in place_options} and {plo_endmargin in place_options} :
 
 
 
# |--Widget_1--Widget_____2--Widget_3--|,
 
 
 
The Legend:
 
===========
 
limiting value of "place_maxdist" : such value which produce some visual
 
effect on the layouter
 
 
  "----" :          distance ( = number of minuses, limited by place_maxdis )
 
  "????" :          some remaining space ( = number of questmarks )
 
  "Widget_1" :      widget of the original size
 
  "Widget__..__1" : (auto)resized widget
 
 
 
  = if {lao_placey in optionslayout} and {place_mode <> wam_none} then the things
 
are handled in the same manner as with "lao_placex" but for the vertical
 
"top2bottom" direction of placement instead of the horizontal "left2right" one.
 
  
2) the align(ment) mode ( optionslayout.lao_align* ) :
+
Properties:
  
- widgets are gathered into a visual group to a dedicated "leader" widget of
+
- anchors
  the layout ( set by "align_leader" and defaults to the lowest in
+
= see {any_widget.anchors}
  Z-Order = twidget.widgets[0] ) the leader stays in place while the others :
+
 
 +
- bounds
 +
= see {any_widget.bounds}
  
  = if lao_alignx in optionslayout ( the hor alignment mode ):
+
- color
  * if align_mode = wam_start :
+
= see {any_widget.color}
snap their left borders to the left border of leader
 
  * else if align_mode = wam_end :
 
snap their right borders to the right border of leader
 
  * else if align_mode = wam_center :
 
snap their v-axes to the v-axis of leader after that,
 
  = if lao_aligny in optionslayout ( the vert alignment mode ):
 
  * if align_mode = wam_start :
 
snap their top borders to the top border of leader
 
  * else if align_mode = wam_end :
 
snap their bottom borders to the bottom border of leader
 
  * else if align_mode = wam_center :
 
snap their h-axes to the h-axis of leader
 
  
- after that, the whole widget group can be aligned within the layouter:
+
- enabled
 +
= "false" turns color of the caption to gray
  
  = if align_glue =  wam_start
+
- visible
  * if lao_alignx in optionslayout:
+
= "true" allows displayable settings (caption text, face, frame etc) to take
the left extent of group snaps to the left border of layouter
+
effect in run-time as well
  * if lao_aligny in optionslayout:
+
the top extent of group snaps to the top border of layouter
+
- <face>
  = else if align_glue = wam_end
+
= see {any face}
  * if lao_alignx in optionslayout:
 
the right extent of group snaps to the right border of layouter
 
  * if lao_aligny in optionslayout:
 
the bottom extent of group snaps to the bottom border of layouter
 
  = else if align_glue =  wam_center
 
  * if lao_alignx in optionslayout:
 
the v-axis of group snaps to the v-axis of layouter
 
  * if lao_aligny in optionslayout:
 
the h-axis of group snaps to the h-axis of layouter
 
  
Mutually exclusive settings:
+
- <frame>
* only one of "align_mode" can be choosen
+
= see {any frame}
* only one of  "glue_mode" can be choosen
 
* "optionslayout.lao_alignx" & "optionslayout.lao_placex"
 
* "optionslayout.lao_aligny" & "optionslayout.lao_placey"
 
  
V-alignment ( optionslayout.lao_aligny ) may be combined with h-placement
+
- linkbottom
( optionslayout.lao_placex ), and h-alignment ( optionslayout.lao_alignx ) may
+
= widget linked down to most outer edge (incl. frame[.caption]) of the spacer
be combined with v-placement ( optionslayout.lao_placey )
+
- linkleft
 +
= widget linked left to most outer edge of the spacer
 +
- linkright
 +
= widget linked right to most outer edge of the spacer
 +
- linktop
 +
= widget linked up to most outer edge of the spacer
  
NOTE:
+
- dist_bottom, dist_left, dist_right, dist_top :
  The effects of the above described { resizing / placement / alignment } are
+
= margins between most outer edge the spacer
  irreversible. So, the only way to revert is to set "wan_none" then to revert
+
and the corresponding linked widget
  manually.
 
</pre>
 
  
=== TListView ===
+
- options :
=== TImage ===
 
<pre>
 
<any image>
 
  
*** Note that switch to the monochrome mode is irerreversible ! ***
+
= spao_glueright
  
alignment:
+
  - if "false"
  
By default, images are top-left aligned, with the original size preserved.
+
h-repositioning or h-resizing the linkleft widget shifts
 +
the whole linked construction, it becomes the only way to h-shift
  
al_xcentered = centers the image horizontally
+
if {an_right IN linkright_widget.anchors} then the spacer
al_ycentered = centers the image vertically
+
may be right-resized with auto h-resizing the linkright widget
 +
so that the right margin of that widget is kept
  
al_right = docks the image to the right border of placeholder
+
if NOT {an_right IN linkright_widget.anchors} then the spacer
al_bottom = docks the image to the bottom border of placeholder
+
may be right-resized with auto h-shifting the linkright widget
 +
so that width of that widget is kept
  
al_grayed = fills non-transparent areas with the selected color
+
- if "true"
  
al_stretchx = adjusts size so that to fill the placeholder in width
+
h-repositioning or h-resizing the linkright widget shifts
al_stretchy = adjusts size so that to fill the placeholder in height
+
the whole linked construction, it becomes the only way to h-shift
al_fit = adjusts size so that to fill the placeholder in both width & height
 
  
al_tiled = spawns the image & tile the whole  placeholder with the copies
+
if {an_left IN linkleft_widget.anchors} then the spacer
 +
may be h-resized with auto h-resizing the linkleft widget
 +
so that the left margin of that widget is kept
  
Interpolation mode while stretching
+
if NOT {an_left IN linkleft_widget.anchors} then the spacer
 +
may be h-resized with auto h-shifting the linkleft widget
 +
so that width of that widget is kept
  
al_intpol = antialiases as far as the size changes
+
= spao_gluebottom
(the only working in Linux)
 
al_or = interpolation pixel operation is "or" -> 1's are extended
 
al_and = interpolation pixel operation is "and" -> 0's are extended
 
( al_or and al_and only on win32, mainly useful for stretching of monochrome bitmaps) :
 
  
colorbackground = color of image transparent ( masked ) areas in monochrome
+
- if "false"
non-masked mode
 
colorforeground = color of non-transparent areas in monochrome mode 
 
  
options:
+
v-repositioning or v-resizing the linktop widget shifts
 +
the whole linked construction, it becomes the only way to v-shift
  
bmo_monochrome = fills non-transparent areas with "colorforeground",
+
if {an_bottom IN linkbottom_widget.anchors} then the spacer
also, in non-masked mode, fills transparent areas
+
may be v-resized with auto v-resizing the linkbottom widget
with "colorbackground"
+
so that the bottom margin of that widget is kept
  
bmo_masked = activates built-in image transparency {it "hides" transparent (masked) areas}
+
if NOT {an_bottom IN linkbottom_widget.anchors} then the spacer
bmo_colormask = applies faded edge transparency on the color masked areas in the image
+
may be v-resized with auto v-shifting the linkbottom widget
 +
so that height of that widget is kept
  
transparency = makes the image transparent as long as enlights areas behind
+
-  if "true"
the image with the selected color
 
  
transparentcolor = for a non-masked image, assigns a color indicate transparency areas
+
        v-repositioning or v-resizing the linkbottom widget shifts
( on matching areas, the image will be seen through )
+
the whole linked construction, it becomes the only way to v-shift
<pre/>
 
  
=== TDial ===
+
if {an_top IN linktop_widget.anchors} then the spacer
=== TChart ===
+
may be v-resized with auto v-resizing the linktop widget
=== TChartRecorder ===
+
so that the top margin of that widget is kept
=== TPolygon ===
 
=== TPickWidget ===
 
=== TOpenglWidget ===
 
  
== Edit ==
+
if NOT {an_top IN linktop_widget.anchors} then the spacer
=== TStringEdit ===
+
may be v-resized with auto v-shifting the linktop widget
=== TMemoEdit ===
+
so that height of that widget is kept
=== THexStringEdit ===
 
=== TDropdownListEdit ===
 
A tstringedit with a dropdownlist to choose text values. Important dropdown.options members:
 
- deo_autodropdown dropdown on keypress
 
- deo_selectonly don't allow entering arbitrary text.
 
- deo_forceselect don't allow entering empty text.
 
  
=== THistoryEdit ===
+
- optionsscale
A tstringedit which shows the previously entered values in a dropdownlist for selection.
+
= see {tscalingwidget.optionsscale}
  
=== TIntegerEdit ===
+
- optionswidget
=== TKeyStringEdit ===
+
= see {anywidget.optionswidget}
Maps string to string.
 
  
=== TEnumEdit ===
+
- onactivate, onchildscaled, ondeactivate, ondefocus, onenter, onexit, onfocus,
Maps integer to string, zero based and sequencial (first item 0, next 1, ...).
+
  onfontheightdelta, onpopup, onresize, onshowhint
 +
= see {any_widget.*}
  
=== TEnumTypeEdit ===
+
- onmove
A tenumedit which maps Pascal enums to their names. Use oninit to store the typeinfo pointer of the enum type into sender.typeinfopo.
+
= see {any_window.OnMove}
  
=== TSelector ===
+
any "link*" option set disables the spacer to reposition solely,
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
+
repositioning is only controlled by a "glued" widget since then
only.
+
 
 +
=== TLayouter ===
 +
* a tspacer descendant designed to (auto)resize or/and move its contained widgets acc to some size/positon dependencies
 +
* may have GUI look, frame caption etc switched off by default
 +
* layouters may be nested to achieve complex layouts
  
=== TRealEdit ===
+
Each layout change/assignment is divided into performing 3 consequent stages :
=== TRealSpinEdit ===
 
=== TDateTimeEdit ===
 
=== TCalendarDateTimeEdit ===
 
=== TEdit ===
 
MSEgui counterpart of Delphi TEdit. You will never use it.
 
  
=== TWidgetGrid ===
+
==== Stage 1 ====  
=== TItemEdit ===
 
=== TDropDownItemEdit ===
 
A tstringedit with a dropdownlist to choose text values. Important dropdown.options members:
 
- deo_autodropdown dropdown on keypress
 
- deo_selectonly don't allow entering arbitrary text.
 
- deo_forceselect don't allow entering empty text.
 
  
=== TMBDropDownItemEdit ===
+
Widgets auto resized using the following options:
=== TTreeItemEdit ===
 
=== TRecordFieldEdit ===
 
Used in twidgetgrid in order to edit fields of a ttreeitemedit. Example is MSEide projecttreeform.pas.
 
  
=== TDialogStringEdit ===
+
<pre>
A tstringedit with an ellipse button. Use "onexecute" to show the dialog.
+
- if {lao_placex OR lao_placey} :
  
=== TPointerEdit ===
+
= if {plo_scalesize in optionslayout}  then
=== TSlider ===
+
* widgets with "osk_nopropwith" unset in their "optionsskin" are h-scaled
=== TProgressBar ===
+
    in the proportion of change of tlayouter's clientwidth
=== TBooleanEdit ===
+
* widgets with "osk_nopropheight" unset in their "optionsskin" are v-scaled
=== TBooleanEditRadio ===
+
    in the proportion  of change of tlayouter's clientheight
=== TDataButton ===
 
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".
 
  
=== TStockGlyphDataButton ===
+
For h-resized layouter, the effect looks like :
=== TDataIcon ===
 
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.
 
  
=== TTextEdit ===
+
|--Widget__1---Widget__2--| => the initial look
Only useful if inserted into a twidgetgrid, builds a text editor, used in MSEide source editor.
 
  
=== TDataImage ===
+
  |--Widget_1--Widget_2--| => the layouter gets narrower
A pixmap display widget which can be inserted into twidgetgrid.
 
  
=== TTerminal ===
+
  |---Widget___1---Widget___2---| => the layouter gets wider
Only useful if inserted into a twidgetgrid, builds a very simple terminal emulator. Used in MSEide target console.
 
  
== NoGui ==
+
*** both widget sizes & margins are affected ***
=== TAction ===
+
*** Widget_N may generally situate on different y-levels ***
<pre>
+
 
Shortcut processing order :
+
otherwise :
  
- the smallest piece of processing is "doshortcut" procedure which
+
= if lao_scalewidth in optionslayout :
is called until processed:
+
* widgets with "osk_nopropwith" unset in their "optionsskin" enters in the mode
= starting from the sender up to the toplevel widget
+
  ( not applied until the layouter resizes! ) when they are h-scaled in the proportion
= then by all child widgets with non-set "ow_noparentshortcut"  
+
  as far as clientwidth of the tlayouter changes, then stages 2 & 3 are reapplied
= then, if "ow_nochildshortcut" isn't set, by the parent widget
 
= then by the widget oneself
 
 
- "doshortcut" is checked in the following order:
 
= starting from form's main menu
 
= then from the owning window ( the widget oneself )
 
= then from the application
 
  
 +
For h-resized layouter, the effect looks like :
  
*** A shortcut is bound to a widget by :
+
  |--Single____widget????| => the initial look
- placing an action component on the widget ***
 
- direct assigning the shortcut to the widget (menus,..)
 
---------------------------
 
  
caption, color, colorglyph, helpcontext, hint, imagecheckedoffset,
+
  |--Single__widget???| => the layouter gets narrower
imagelist <see "timagelist">, imagenr, imagenrdisabled
 
  
- sets look of "clients" (buttons, menu/toolbar items,..), unless
+
  |--Single_______widget?????| => the layouter gets wider
these clients have "state.as_local*" set :
 
  
*** For meaning of these options, see help on the "client" widgets ***
+
* also, if {lao_scaleleft in optionslayout} then left margins of the widgets
 +
  with unset "optionsskin.osk_nopropleft" resize too otherwise retain
  
group
+
= if lao_scaleheight in optionslayout :
- default value for one-named property of the bound widgets
+
* widgets with "osk_nopropheight" unset in their "optionsskin" enters in the mode
( menu items,... )
+
  ( not applied until the layouter resizes! ) when they are v-scaled in the proportion
 +
    as far as clientheight of the tlayouter changes, then stages 2 & 3 are reapplied
  
options :
+
* also, if {lao_scaletop in optionslayout} then top margins of the widgets
ao_updateonidle
+
  with unset "optionsskin.osk_noproptop" resize too otherwise retain
- runs this action in cycle, waiting for no gui events everytime
 
  
ao_globalshortcut
+
*** only widget sizes & margins not distances between them are affected ***
- allows the action to trigger on a non-main form
 
  (the shortcut is triggered whatever form of the applicatin it was pressed on,
 
  otherwise only when the form where the aption is placed on is focused )
 
  
ao_nocandefocus
+
</pre>
- causes the action not to call "CanDefocus" for focused edit widget of active form
 
  before executing own code
 
  ( it helps to avoid the effect of cancelling changes in these widgets
 
  on activating the bound shortcut )
 
  
shortcut
+
==== Stage 2 ====
- keyboard combination triggering the action
 
  
shortcut
+
Widgets may be auto resized in 5 consequent steps using the following options:
- alternative "shortcut" and handled identically
 
  
state :
+
<pre>
  
as_disabled
+
1. if plo_syncmaxautosize in place_options :
- prevents the action from triggering, also puts the bound widgets to "disabled" look
+
  = all widgets are autosized then their client areas are synchronised to the
 +
    clientareas of the highest and the widest of the widget
 +
  * calls "msegui.syncmaxautosize"
  
as_invisible
+
2. if plo_syncpaintwidth in place_options :
- in run-time, hides the bound widget, still reacting on the shortcut or direct call
+
  = the paintwidths of all widgets are synchronized to the widget with the
 +
    widest outer frame width ( ex. width of "frame.caption" )
 +
  * mainly makes sense if "lao_alignx" set and {align_glue = wam_start or wam_end}
 +
    ( see below ) when the widgets will be adjusted in order to fit into the
 +
    inner client width of tlayouter:
  
as_checked
+
                                  x-align level         
- selects the bound menu item if it has "mao_checkbox" option set
+
                                        V               
 +
                        +----------------------------------+
 +
                        | Widget_1 the_widest_frame_caption|
 +
                        | Widget_2 frame_caption2          |
 +
                        | Widget_N wider_frame_captionN    |
 +
                        +----------------------------------+
  
as_default
+
  here, the effect is shown for "cp_right" frame captions
as_local*
+
    // otherwise syncronizes to the outer ( of the frame except its caption ) width
 +
    // of the Z-top widget
 +
  * calls "msegui.syncpaintwidth"
 +
  * paintwidth is the outer width
  
statfile
+
3. if plo_syncpaintheight in place_options :
<see "tstatfile">
+
  = the paintheights of all widgets are synchronized to the widget with the
 +
    highest outer frame width ( ex. width of "frame.caption" ).
 +
  * mainly makes sense if lao_aligny set and {align_glue = wam_start or wam_end}
 +
    ( see below ) the widgets will be adjusted in order to fit into the inner
 +
    client height of tlayouter :
  
stavarname
+
                        +------------------------------+
 +
                        | The_                        |
 +
                        | tallest_            taller_  |
 +
                        | frame_    frame_    frame_  |
 +
                        | caption  caption2  captionN | 
 +
                        |                              |
 +
                        | Widget1  Widget_2  Widget_N |<== y-align level
 +
                        +------------------------------+   
  
+
  here, the effect is shown for "cp_topleft" frame captions
tagaction
+
    // otherwise syncronizes to the outer ( of the frame except its caption )
onasyncevent
+
    // height of the Z-top widget
onchange
+
  * calls "msegui.syncpaintheight"
onexecute
+
onupdate
+
4. plo_synccaptiondistx in place_options :
<pre/>
+
  = causes all widgets to have the widest common room for their cp_(left/right)* frame captions
 +
  * calls "msegui.synccaptiondistx"
 +
 +
5. plo_synccaptiondisty in place_options :
 +
  = causes all widgets to have the highest common room for their cp_(top/bottom)* frame captions
 +
  * calls "msegui.synccaptiondisty"
 +
</pre>
  
=== TActivator ===
+
==== Stage 3 ====
=== TThreadComp ===
 
=== TStatFile ===
 
- so that to be in effect, it should also be assigned to the form where the widget using the stafile is placed on
 
- in design, if "onstatwrite" is set and "filedir" is not yet created, deactivate exception "ECreateError" in project settings ( "Debugger" tab )
 
- "filedir" may contain "~/" indicating the user's home directory
 
- options "oe_savestate" & "oe_savevalue" of "client" widgets define what to store to the file
 
- position etc changes or/and value changes
 
- 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
 
- each "tstafile" owns:
 
= tstatwriter:
 
* provides methods of writing sections & statvars to a memory/file stream
 
- tstatreader:
 
* holds list of sections with statvars each
 
* provides search & check & reading interface to the statvars
 
* provides reading statvars from a memory/file stream
 
  
Positioning to a section speeds up accessing its statvars
+
The widgets may be (re)arranged within the layouter.
  
- there also is "tstatfiler" ( exposed by some "tstatfile" events ) which:
+
<pre>
= may present or "tstatwriter" or "tstatreader" ( there's a check method )
+
There're 2 modes of such (re)arrangement which can be partially (orthogonally)
= provides directionless "update" methods with internal switch to needed direction of processing
+
combined (see later):
- "reading" or "writing" statvars on per-section basis
+
 
 +
1) The place(ment) mode ( lao_place* in optionslayout ) :
  
=== TTimer ===
+
- widgets are placed at some distances between each other, possibly with some
=== TNoGuiAction ===
+
  margins, rooms of invisible widgets ( having visible=false) are also allocated
=== TPipeReadercomp ===
+
  unless "plo_noinvisible in place_options"
=== TSysEnvManager ===
 
=== TProcessMonitor ===
 
=== TFilechangeNotifier ===
 
=== TShortCutController ===
 
=== TPostscriptPrinter ===
 
=== TGdiPrinter ===
 
=== TWmfPrinter ===
 
=== TSkinController ===
 
=== TGuiThreadComp ===
 
  
== Font ==
+
  * the widgets are placed in the order of decreasing their "widgetrect.x"
=== Any Font ===
+
coordinates before alignment
<pre>
+
 
    charset { ANSI/ DEFAULT/ SYMBOL /SHIFTJIS /HANGEUL /GB2312 /CHINESEBIG5 /OEM
+
  * the inter-widget distances and the side margins ( if apllied ) in both
/JOHAB / HEBREW/ ARABIC/ GREEK/ TURKISH/ VIETNAMESE/ THAI/ EASTEUROPE/
+
dimentions are identical and limited between "place_mindist" and
RUSSIAN/ MAC/ BALTIC }
+
"place_maxdist"
- changes the font to the nearest containing the selected encoding(charset)
+
 
- no font change made if the supplied encoding doesn't match any font
+
  = if {lao_placex in optionslayout} and {place_mode <> wam_none} then the
color
+
following relevant settings apply:
- color of the glyphs contours
+
 
colorbackground
+
* non-limiting value of "place_maxdist" :
- fill color of the glyph cells ( not including extraspace )
+
colorshadow
+
# |Widget_1------Widget_2------Widget_3|
- color of SE glyph "edges" ( if not "cl_none", deactivates "colorbackground" )
+
extraspace
+
* non-limiting value of "place_maxdist" and {plo_propmargin in place_options} :
- v-space between glyph cells of adjacent text rows (negative values cause the cells to overlap )
+
height
+
# |---Widget_1---Widget_2---Widget_3---|
- v-size of glyph cells, in pixels
+
name
+
* limiting value of "place_maxdist" and {place_mode = wam_start} :
- initially, font is choosen by { "family" = this name }
+
options:
+
# |Widget_1----Widget_2----Widget_3????|
foo_fixed
+
- changes the font to the nearest "mono" spaced (usually = Courier)
+
* limiting value of "place_maxdist" and {place_mode = wam_start} and
foo_proportional
+
  {plo_propmargin in place_options} :
- changes the font to the nearest "proportionally" spaced (usually = Helvetica)
+
foo_helvetica
+
# |---Widget_1---Widget_2---Widget_3???|
- changes the font to the nearest in "sans" category (usually = Helvetica)
+
foo_roman
+
* limiting value of "place_maxdist" and {place_mode = wam_end} :
- changes the font to the nearest in "serif" category (usually = Times[ New Roman])
+
foo_script
+
# |??????Widget_1---Widget_2---Widget_3|
- Win32 only, changes the font to the nearest in "script" category
+
foo_decorative
+
* limiting value of "place_maxdist" and {place_mode = wam_end} and
- Win32 only, changes the font to the nearest in "decorative" category
+
  {plo_propmargin in place_options} :
foo_antialiased
+
- Linux-only, enables antialiasing (if disabled by Xft globally)
+
# |???Widget_1---Widget_2---Widget_3---|
foo_nonantialiased
+
- Linux-only, disables antialiasing (if enabled by Xft globally)
+
* limiting value of "place_maxdist" and {place_mode = wam_center} :
usually making glyph extents (not cells !) a bit wider
+
style:
+
# |???Widget_1---Widget_2---Widget_3???|
fs_bold
+
- gives the font a "bold" look
+
* limiting value of "place_maxdist" and {plo_endmargin in place_options} :
fs_italic
+
- gives the font an "italic" look
+
# |Widget_1----Widget_2----Widget_____3|, or
fs_underline
+
- gives the font an "underlined" look
+
# |Widget_1----Widget_____2----Widget_3|, or
fs_strikeout
+
- gives the font a "striked out" look
+
# |Widget_____1----Widget_2----Widget_3|, here, the most left amongst
fs_selected
+
widgets having both [an_left,an_right] set is expanded otherwise the most
- "TRUE" here combined with {tf_noselect:=FALSE}, causes the text described by this font
+
right widget ( Widget_3 in the example )
to be initially selected ( with the clipboard operations available ),
+
currently applicable only to richstrings
+
* limiting value of "place_maxdist" and {place_mode = wam_end} and
 +
  {plo_propmargin in place_options} and {plo_endmargin in place_options} :
 +
 
 +
# |--Widget_1--Widget_____2--Widget_3--|,
 +
 
 +
The Legend:
 +
===========
 +
limiting value of "place_maxdist" : such value which produce some visual
 +
effect on the layouter
 +
 +
  "----" :          distance ( = number of minuses, limited by place_maxdis )
 +
  "????" :          some remaining space ( = number of questmarks )
 +
  "Widget_1" :      widget of the original size
 +
  "Widget__..__1" : (auto)resized widget
 +
 
 +
  = if {lao_placey in optionslayout} and {place_mode <> wam_none} then the things
 +
are handled in the same manner as with "lao_placex" but for the vertical
 +
"top2bottom" direction of placement instead of the horizontal "left2right" one.
  
width
+
2) the align(ment) mode ( optionslayout.lao_align* ) :
- 10*{ glyph cell width, average in pixels }, 0 = {font default}
 
  
xscale
+
- widgets are gathered into a visual group to a dedicated "leader" widget of
- width ratio of each glyph {cell & contour}, the effect is similar to "width"
+
  the layout ( set by "align_leader" and defaults to the lowest in
 +
  Z-Order = twidget.widgets[0] ) the leader stays in place while the others :
  
*** "foo_*" font selection overrides one made with "name"
+
  = if lao_alignx in optionslayout ( the hor alignment mode ):
 +
  * if align_mode = wam_start :
 +
snap their left borders to the left border of leader
 +
  * else if align_mode = wam_end :
 +
snap their right borders to the right border of leader
 +
  * else if align_mode = wam_center :
 +
snap their v-axes to the v-axis of leader after that,
 +
  = if lao_aligny in optionslayout ( the vert alignment mode ):
 +
  * if align_mode = wam_start :
 +
snap their top borders to the top border of leader
 +
  * else if align_mode = wam_end :
 +
snap their bottom borders to the bottom border of leader
 +
  * else if align_mode = wam_center :
 +
snap their h-axes to the h-axis of leader
  
*** if change with "foo_*" is usuccessful then the nearest "sans" font is usually choosen
+
- after that, the whole widget group can be aligned within the layouter:
  
*** The categories :
+
  = if align_glue =  wam_start
 +
  * if lao_alignx in optionslayout:
 +
the left extent of group snaps to the left border of layouter
 +
  * if lao_aligny in optionslayout:
 +
the top extent of group snaps to the top border of layouter
 +
  = else if align_glue = wam_end
 +
  * if lao_alignx in optionslayout:
 +
the right extent of group snaps to the right border of layouter
 +
  * if lao_aligny in optionslayout:
 +
the bottom extent of group snaps to the bottom border of layouter
 +
  = else if align_glue =  wam_center
 +
  * if lao_alignx in optionslayout:
 +
the v-axis of group snaps to the v-axis of layouter
 +
  * if lao_aligny in optionslayout:
 +
the h-axis of group snaps to the h-axis of layouter
  
sans => have no serifs and have strokes of even thickness
+
Mutually exclusive settings:
serif => have serifs at glyph contours and made up of strokes of varying thickness
+
* only one of "align_mode" can be choosen
script => resemble handwriting
+
* only one of "glue_mode" can be choosen
decorative => flashy styles to be used sparingly in headlines or posters
+
* "optionslayout.lao_alignx" & "optionslayout.lao_placex"
 +
* "optionslayout.lao_aligny" & "optionslayout.lao_placey"
 +
 
 +
V-alignment ( optionslayout.lao_aligny ) may be combined with h-placement
 +
( optionslayout.lao_placex ), and h-alignment ( optionslayout.lao_alignx ) may
 +
be combined with v-placement ( optionslayout.lao_placey )
  
<pre/>
+
NOTE:
 +
  The effects of the above described { resizing / placement / alignment } are
 +
  irreversible. So, the only way to revert is to set "wan_none" then to revert
 +
  manually.
 +
</pre>
  
== GUI ==
+
=== TListView ===
=== TWindow ===
+
=== TImage ===
 
<pre>
 
<pre>
twindow = class(teventobject,icanvas)
+
<any image>
  public
 
  
// releases mouse, unlinks from the canvas, processes all pending events of the window
+
*** Note that switch to the monochrome mode is irerreversible ! ***
// if called from within main thead then destroys the window directly
 
// otherwise posts a window destroy event for oneself and waits for it to be processed
 
procedure destroywindow;
 
  
// registers the instance of onself in the "owner" widget, allocates the canvas,
+
alignment:
// adds a reference to oneself,
 
// then prepares the "owner" hierarchy to be invalidated ( "owner.rootchanged" )
 
// since now, the window is allocated and belongs to the "aowner" widget
 
constructor create(aowner: twidget);
 
  
destructor destroy; override;
+
By default, images are top-left aligned, with the original size preserved.
  
// adds "method" to the internal list of scroll dependants
+
al_xcentered = centers the image horizontally
procedure registeronscroll(const method: notifyeventty);
+
al_ycentered = centers the image vertically
  
// removes "method" from the internal list of scroll dependants
+
al_right = docks the image to the right border of placeholder
procedure unregisteronscroll(const method: notifyeventty);
+
al_bottom = docks the image to the bottom border of placeholder
  
// releases mouse if captured, resets the cursor, then enters an event loop for the window,
+
al_grayed = fills non-transparent areas with the selected color
// TRUE on return if the window is destroyed
 
function beginmodal: boolean;
 
 
  * checks if the "sender" window is already modal to avoid circularity,
 
    if not then starts an event loop  for the "sender" where the "sender" is a receiver of GUI events,
 
      once the loop is terminated reactivates the previously active window if it was,
 
    TRUE if modalwindow destroyed 
 
  
  function tinternalapplication.beginmodal(const sender: twindow): boolean;
+
al_stretchx = adjusts size so that to fill the placeholder in width
 +
al_stretchy = adjusts size so that to fill the placeholder in height
 +
al_fit = adjusts size so that to fill the placeholder in both width & height
  
// removes the internal stuff which indicates the modal state
+
al_tiled = spawns the image & tile the whole  placeholder with the copies
procedure endmodal;
 
  
// if the window is visible,
+
Interpolation mode while stretching
// deactivates the previously active window, shows the window (see below),
 
// if no active window in the app or the window or its Z-predescessor is modal and
 
// the app has no focused widget then prepares the bound widget to be focused,
 
// then addresses the WM to put the window to foreground
 
procedure activate;
 
  
  // if the bound widget has visible=true then:
+
al_intpol = antialiases as far as the size changes
  //  - if NOT windowevent then :
+
(the only working in Linux)
  //    = address the WM to set size of the window acc to window opts
+
al_or = interpolation pixel operation is "or" -> 1's are extended
  //      wp_maximized, wp_fullscreen or normal size otherwise
+
al_and = interpolation pixel operation is "and" -> 0's are extended
  // = if the window is normally sized, moves it to its default position is specified ( screen centered etc )
+
( al_or and al_and only on win32, mainly useful for stretching of monochrome bitmaps) :
  // - unhides/unminimizes the window if needed
 
  // - shows other windows of the applications acc to state of the window group
 
  // ( in normal size or minimized )
 
  
  private
+
colorbackground = color of image transparent ( masked ) areas in monochrome
procedure twindow.show(windowevent: boolean);
+
non-masked mode
 +
colorforeground = color of non-transparent areas in monochrome mode 
  
// TRUE if this window currently grabs user input
+
options:
( a widget drawn within the window(=form) is in focus,.. )
 
function active: boolean;
 
  
// if the window was active then deactivates the window  & remembers it as the previous active ( to restore leater if requested ),
+
bmo_monochrome = fills non-transparent areas with "colorforeground",  
// returns TRUE if that storage occured
+
also, in non-masked mode, fills transparent areas
function deactivateintermediate: boolean;
+
with "colorbackground"
  
// makes the window active & clears the above app reference to it ( "active before deactivating" )
+
bmo_masked = activates built-in image transparency {it "hides" transparent (masked) areas}
procedure reactivate; //clears app.finactivewindow
+
bmo_colormask = applies faded edge transparency on the color masked areas in the image
  
// scans the app event queue for "ek_expose" event[s] addressed to the window,
+
transparency = makes the image transparent as long as enlights areas behind
// if found then redraws that part of the window which the event describes
+
the image with the selected color
// ( processed events are then deleted )
 
procedure update;
 
  
// TRUE if the window :
+
transparentcolor = for a non-masked image, assigns a color indicate transparency areas
// 1) doesn't have an inner widget grabbing input focus
+
( on matching areas, the image will be seen through )
// or
+
</pre>
// 2) has such widget, and this widget ( and all its descendants )
+
 
//    pass "CanClose" check
+
=== TDial ===
//
+
=== TChart ===
// *** see also "twidget.CanClose" ***
+
 
//
+
There are demos here:
function candefocus: boolean;
 
  
// tries to defocus the currently focused widget if it belongs to the window,
+
https://github.com/mse-org/mseuniverse/tree/master/attic/msedocumenting/mse/trunk/help/tutorials/widgets/charts
// if succeeds then executes code of virtual "DoDefocus" of the widget descessor
 
// ( this code defines behaviour & look of the widget on defocusing );
 
//
 
// no defocusing is done if the focused widget ( or its descendants )
 
// doesn't pass "CanClose" check
 
//
 
procedure nofocus;
 
 
 
  // setfocusedwidget(widget)
 
 
 
  property focuscount: cardinal read ffocuscount;
 
  function close: boolean; //true if ok
 
  procedure beginmoving; //lock window rect modification
 
  procedure endmoving;
 
  procedure bringtofront;
 
  procedure sendtoback;
 
  procedure stackunder(const predecessor: twindow);
 
      //stacking is performed in mainloop idle, nil means top
 
  procedure stackover(const predecessor: twindow);
 
      //stacking is performed in mainloop idle, nil means bottom
 
  function stackedunder: twindow; //nil if top
 
  function stackedover: twindow;  //nil if bottom
 
  function hastransientfor: boolean;
 
  
  procedure capturemouse;
+
=== TChartRecorder ===
  procedure releasemouse;
+
=== TPolygon ===
  procedure postkeyevent(const akey: keyty;
+
=== TPickWidget ===
        const ashiftstate: shiftstatesty = []; const release: boolean = false;
+
=== TOpenglWidget ===
                  const achars: msestring = '');
 
  
  function winid: winidty;
+
== Edit ==
  function haswinid: boolean;
+
=== TStringEdit ===
  function state: windowstatesty;
+
=== TMemoEdit ===
  function visible: boolean;
+
=== THexStringEdit ===
  function activating: boolean; //in internalactivate proc
+
=== TDropdownListEdit ===
  function normalwindowrect: rectty;
+
A tstringedit with a dropdownlist to choose text values. Important dropdown.options members:
  property updateregion: regionty read fupdateregion;
+
- deo_autodropdown dropdown on keypress
  function updaterect: rectty;
+
- deo_selectonly don't allow entering arbitrary text.
 +
- deo_forceselect don't allow entering empty text.
  
  procedure registermovenotification(sender: iobjectlink);
+
=== THistoryEdit ===
  procedure unregistermovenotification(sender: iobjectlink);
+
A tstringedit which shows the previously entered values in a dropdownlist for selection.
  
  property options: windowoptionsty read foptions;
+
=== TIntegerEdit ===
 +
=== TKeyStringEdit ===
 +
Maps string to string.
  
// widget
+
=== TEnumEdit ===
property owner: twidget read fowner;
+
Maps integer to string, zero based and sequencial (first item 0, next 1, ...).
  
  property focusedwidget: twidget read ffocusedwidget;
+
=== TEnumTypeEdit ===
  property transientfor: twindow read ftransientfor;
 
  property modalresult: modalresultty read fmodalresult write setmodalresult;
 
  property buttonendmodal: boolean read getbuttonendmodal write setbuttonendmodal;
 
  property globalshortcuts: boolean read getglobalshortcuts write setglobalshortcuts;
 
  property localshortcuts: boolean read getlocalshortcuts write setlocalshortcuts;
 
  property windowpos: windowposty read getwindowpos write setwindowpos;
 
  property caption: msestring read fcaption write setcaption;
 
  
 +
A TEnumEdit which maps Pascal enums to their names. Use OnInit event to store the typeinfo pointer of the enum type into '''sender.typeinfopo'''.
  
windowoptionty = (wo_popup,wo_message,wo_buttonendmodal,wo_groupleader,
+
<syntaxhighlight lang=pascal>
                  wo_windowcentermessage); //showmessage centered in window
+
procedure tmainfo.enumtypeeditinit(const sender: tenumtypeedit);
 +
begin
 +
  sender.typeinfopo := PTypeInfo(TypeInfo(TMyEnumeratedType));
 +
end;
 +
</syntaxhighlight>
  
 +
=== TSelector ===
 +
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.
  
optionswindow:
+
=== TRealEdit ===
wo_popup
+
=== TRealSpinEdit ===
- in run-time, hides all OS windows-manager ( WM ) decorations (title bar, buttons "Close/Resize,Min/Max" etc),
+
=== TDateTimeEdit ===
letting only its client area to appear
+
=== TCalendarDateTimeEdit ===
so :
+
=== TEdit ===
= the window should have own facilities to replace the deactivated WM functionality if needed
+
MSEgui counterpart of Delphi TEdit. You will never use it.
= can't be resized/maximize/minimized/moved
 
wo_message
 
- similar to "wo_popup" but allows WM to close ( with "Close" button ) & move the window
 
  
wo_groupleader
+
=== TWidgetGrid ===
- keeps on the WM taskbar a shortcut to the window
+
=== TItemEdit ===
( if the parent window is a groupleader too then dislpays a step upper in its group )
+
=== TDropDownItemEdit ===
 +
A tstringedit with a dropdownlist to choose text values. Important dropdown.options members:
 +
- deo_autodropdown dropdown on keypress
 +
- deo_selectonly don't allow entering arbitrary text.
 +
- deo_forceselect don't allow entering empty text.
  
Event handlers:
+
=== TMBDropDownItemEdit ===
 +
=== TTreeItemEdit ===
 +
=== TRecordFieldEdit ===
 +
Used in twidgetgrid in order to edit fields of a ttreeitemedit. Example is MSEide projecttreeform.pas.
  
- onmove
+
=== TDialogStringEdit ===
= fires once the (window/widget) is created/moved ( with check if really moved by a distance)
+
A tstringedit with an ellipse button. Use "onexecute" to show the dialog.
  
<pre/>
+
=== TPointerEdit ===
=== TFormScrollbox ===
+
=== TSlider ===
<pre>
+
=== TProgressBar ===
- presents client area of form & parent of its widgets,
+
=== TBooleanEdit ===
initially stretched to fit the form & bound with anchoring
+
=== TBooleanEditRadio ===
but may be adjusted with "bounds" & "anchors"
+
=== TDataButton ===
 
+
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".
    Properties:
 
               
 
anchors
 
bounds
 
 
color
 
- color of the whole container area ( except its frame ) & form widgets
 
if their color is "cl_parent"
 
  
name = container
+
=== TStockGlyphDataButton ===
 +
=== TDataIcon ===
 +
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.
  
cursor, enabled, face, frame, helpcontext, hint, optionswidget, popupmenu,
+
=== TTextEdit ===
taborder, tag, visible, onactivate, onafterpaint, onbeforepaint,
+
Only useful if inserted into a twidgetgrid, builds a text editor, used in MSEide source editor.
onchildmouseevent, onclientmouseevent, ondeativate, ondefocus, onenter,
 
onexit, onfocus, onfontheightdelta, onmouseevent, onpaint, onpopup
 
onresize, onshowhint
 
- the same meaning as for the served form
 
  
 +
=== TDataImage ===
 +
A pixmap display widget which can be inserted into twidgetgrid.
  
oncalcminscrollsize
+
=== TTerminal ===
onscroll
+
Only useful if inserted into a twidgetgrid, builds a very simple terminal emulator. Used in MSEide target console.
onchildscaled
 
<pre/>
 
=== TFaceList ===
 
=== TFrameComp ===
 
 
Terminilogy :
 
  
{client area = area of the widget which interacts with a user}
+
== NoGui ==
 +
=== TAction ===
 +
<pre>
 +
Shortcut processing order :
  
{bevelling = additional facets rising/sinking frame & client area,
+
- the smallest piece of processing is "doshortcut" procedure which
constists of two parts -  
+
is called until processed:
- external: between frame and widget
+
= starting from the sender up to the toplevel widget
- internal: between frame and client area
+
= then by all child widgets with non-set "ow_noparentshortcut"
}
+
= then, if "ow_nochildshortcut" isn't set, by the parent widget
 +
= then by the widget oneself
 +
 +
- "doshortcut" is checked in the following order:
 +
= starting from form's main menu
 +
= then from the owning window ( the widget oneself )
 +
= then from the application
  
{frame= flat space between external & internal facets,
 
floats at the inner level of the external facet
 
}
 
  
*** Both frame & bevelling affect the client area ***
+
*** A shortcut is bound to a widget by :
 +
- placing an action component on the widget ***
 +
- direct assigning the shortcut to the widget (menus,..)
 +
---------------------------
  
--------------------------
+
caption, color, colorglyph, helpcontext, hint, imagecheckedoffset,
template:
+
imagelist <see "timagelist">, imagenr, imagenrdisabled
  
colorclient = color of the client area
+
- sets look of "clients" (buttons, menu/toolbar items,..), unless
 +
these clients have "state.as_local*" set :
  
colorframe = color of the frame
+
*** For meaning of these options, see help on the "client" widgets ***
colorframeactive = used instead of colorframe if the widget is
 
active; "cl_default" means same as colorframe.
 
  
works if (leveli/levelo <> 0 that's the facets exist :
+
group
 +
- default value for one-named property of the bound widgets
 +
( menu items,... )
  
colorshadow = color of facets screened from the NW light source
+
options :
colordkshadow = color of shadows dropped by the NW light source
+
ao_updateonidle
                colordkwidth = width of the shadows in pixel, -1=default
+
- runs this action in cycle, waiting for no gui events everytime
  
colorlight = color of facets exposed to the NW light source
+
ao_globalshortcut
colorhighlight = color of brighter edges of the facets
+
- allows the action to trigger on a non-main form
                colorhlwidth = width of the brighter edges in pixel, -1=default
+
  (the shortcut is triggered whatever form of the applicatin it was pressed on,
 +
  otherwise only when the form where the aption is placed on is focused )
  
        extraspace = if applied to menu items, adds more space between these items
+
ao_nocandefocus
 +
- causes the action not to call "CanDefocus" for focused edit widget of active form
 +
  before executing own code
 +
  ( it helps to avoid the effect of cancelling changes in these widgets
 +
  on activating the bound shortcut )
  
framei_:
+
shortcut
(for extendable widgets like menus, these settings widen the widget,
+
- keyboard combination triggering the action
for non-extendable like buttons - they squeeze the text area )
 
  
bottom= lower margin of text to the client area
+
shortcut
left = left margin of text to the client area
+
- alternative "shortcut" and handled identically
right = margin of text to the client area
 
top = upper margin of text to the client area
 
  
framewidth= width of the frame
+
state :
leveli = {width=height} of the internal facet, positive -> raised, negative -> sunken
 
levelo = {width=height} of the external facet, positive -> raised, negative -> sunken
 
  
<any frame>
+
as_disabled
 +
- prevents the action from triggering, also puts the bound widgets to "disabled" look
  
*** extends & customizes "tframecomp" ***
+
as_invisible
 +
- in run-time, hides the bound widget, still reacting on the shortcut or direct call
  
template
+
as_checked
- "tframecomp" supplying the initial settings
+
- selects the bound menu item if it has "mao_checkbox" option set
  
colorclient,colordkshadow,colordkwidth,colorframe,colorframeactive,
+
as_default
colorhighlight,colorhlwidth,colorlight,colorshadow,framewidth,
+
as_local*
leveli, levelo, framei_*,
+
 
 +
statfile
 +
<see "tstatfile">
  
<see "tframecomp">
+
stavarname
  
font
+
<see "tfont">
+
tagaction
 +
onasyncevent
 +
onchange
 +
onexecute
 +
onupdate
 +
</pre>
  
caption
+
=== TActivator ===
- some descriptive text( function name, user prompt,...) placed
+
=== TCustomLookupbuffer ===
in a N/W/S/E-combination to the widget's client area
+
<pre>
 +
- provides a group of parallel arrays of float(=datetime), integer and widestring types,
 +
and facilities to :
 +
= search in any array
 +
= on found position, quickly obtain corresponding value in another array
 +
- for each type, several arrays  may be kept
 +
- each array is integer-indexed, even string ones ( case[in]sensitive )
 +
- uses two way of accessing arrays data, through :
 +
= physic : array storage index ( row number ) directly
 +
= logical : the integer index ( see above ):
 +
first, physic row number is known for the logical index then the data
 +
are accessed with the found number
  
***  
+
*** logical index values are built automatically based on array values,
non-empty caption if (captionpos <> cp_center) & (captiondistouter=false & captiondist>0) enlarges the framed widget
+
on updating its data ***
by the corresponding size of caption
+
- dont' have interface to load data ( see its descendants for that )
 +
 +
fieldcountfloat - number of float arrays
 +
fieldcountinteger - number of integer arrays
 +
fieldcounttext - number of widestring arrays
  
***
+
Event handlers:
 +
- onchange
  
captiondist - margin between the caption & the client area
+
Public interface:
  
captiondistouter :
+
  procedure beginupdate; - marks beginning of "update"
 +
  procedure endupdate; - if all "update" finished, fires "onchange" event
 +
procedure clearbuffer; - clears all arrays then fires "onchange"
  
- if "false"(by default), the distance is measured between
+
  procedure checkbuffer;
the inner (facing the client area) extent of the caption
+
  - [re]loads the arrays with most actual data
and the client area outward the area,
+
  - just a stub here since doesn't have a data source
the caption is placed outside of the client area
 
  
- if "true", the caption is mirrored against the edge of client area as
+
  function find(const fieldno: integer; const avalue: integer/realty/msestring;
to the position when "false"
+
        out aindex: integer; const filter: lbfiltereventty = nil): boolean;
 +
- applies external filtering ("filter" procedure) then incrementally searches integer/realty(datetime) array "fieldno"
 +
for value "avalue" starting from logical index "aindex", returns "true" and the updated logical index
 +
if found else next bigger;
 +
 
 +
  function find(const fieldno: integer; const avalue: msestring;
 +
                out aindex: integer;
 +
                const caseinsensitive: boolean;
 +
                const filter: lbfiltereventty = nil): boolean; overload;
 +
- applies external filtering ("filter" procedure) then incrementally searches widestring array "fieldno" for value "avalue",  
 +
in "caseinsensitive" manner, starting from logical index "aindex", returns "true" and the updated logical index
 +
if found else next bigger;
  
*** nagative values of "captiondist" visually inverse "out of" and within ***
+
  function findphys(const fieldno: integer; const avalue: integer;
 +
        out aindex: integer; const filter: lbfiltereventty = nil): boolean; overload;
 +
- applies external filtering ("filter" procedure) then incrementally searches integer/realty(datetime) array "fieldno"
 +
for value "avalue" starting from row number "aindex", returns "true" and the updated row number
 +
if found else next bigger;
  
      captionnoclip - do not clip frame and client area for caption background
+
function findphys(const fieldno: integer; const avalue: msestring;  out aindex: integer; const caseinsensitive: boolean;
( the client area preserves own background under the caption text)
+
                const filter: lbfiltereventty = nil): boolean; overload;
 +
- applies external filtering ("filter" procedure) then incrementally searches widestring array "fieldno" for value "avalue",
 +
in "caseinsensitive" manner, starting from row number "aindex", returns "true" and the updated row number 
 +
if found else next bigger;
  
captionnooffset - shift orthogonal to "captiondist"
+
The external filtering ("filter") procedure takes the arguments of the caller
 +
togehther with physical row number found in the caller which allows
 +
to check several values at once for that number, within the filter
 +
 +
function integervaluephys(const fieldno,aindex: integer): integer;
 +
-  returns value of integer array "fieldno" at row number "aindex"
 +
             
 +
function integervaluelog(const fieldno,aindex: integer): integer;
 +
- returns value of integer array "fieldno" where the array index equals to "aindex"  
  
captionpos - "corner" where to place the caption
+
function integerindex(const fieldno,aindex: integer): integer;
 +
- returns row number of integer array "fieldno" where the array index equals to "aindex"
  
localprops :
+
function integerindexar(const fieldno: integer): integerarty;
 +
- returns all bunch of indexes of integer array "fiedlno"
  
frl_levelo - "levelo" overrides "template.levelo"
+
function integerar(const fieldno: integer): integerarty;
frl_leveli - "leveli" overrides "template.leveli"
+
- returns all bunch of data of integer array "fiedlno"
frl_framewidth - "framewidth" overrides "template.framewidth"
+
 
frl_colorclient - "colorclient" overrides "template.colorclient"
+
function floatvaluephys(const fieldno,aindex: integer): realty;
frl_colorframe - "colorframe" overrides "template.colorframe"
+
- returns value of real/datetime array "fieldno" at row number "aindex"  
frl_colorframeactive - "colorframeactive" overrides "template.colorframeactive"
 
frl_colordkshadow - "colordkshadow" overrides "template.colordkshadow"
 
frl_colorshadow - "colorshadow" overrides "template.colorshadow"
 
frl_colorlight - "colorlight" overrides "template.colorlight"
 
frl_colorhighlight - "colorhighlight" overrides "template.colorhighlight"
 
frl_colordkwidth - "colordkwidth" overrides "template.colordkwidth"
 
frl_colorhlwidth - "colorhlwidth" overrides "template.colorhlwidth"
 
frl_fileft - "framei_left" overrides "template.framei_left"
 
frl_firight - "framei_right" overrides "template.framei_right"
 
frl_fitop - "framei_top" overrides "template.framei_top"
 
frl_fibottom - "framei_bottom" overrides "template.framei_bottom"
 
  
frl_nodisable
+
function floatvaluelog(const fieldno,aindex: integer): realty;
 +
-  returns value of real/datetime array "fieldno" where the array index equals to "aindex"
  
=== TFaceComp ===
+
function floatindex(const fieldno,aindex: integer): integer;
- doesn't affect the widget frame but client area of the frame
+
- returns row number of real/datetime array "fieldno" where the array index equals to "aindex"
  
 +
function floatindexar(const fieldno: integer): integerarty;
 +
- returns all bunch of indexes of real/datetime array "fiedlno"
  
template:
+
function floatar(const fieldno: integer): realarty;
fade:
+
- returns all bunch of data of real/datetime array "fiedlno" 
color[i]: = colors forming the fade
 
direction: = direction where the fade grows to
 
gd_(right/up/left/down)
 
  
pos[i]: = relational position of color[i] on the direction (0.0..1.0) extent
+
function textvaluephys(const fieldno,aindex: integer): msestring;
 +
-  returns value of widestring array "fieldno" at row number "aindex"
  
transparency = makes the face half-transparent and enlight the underlying widget 
+
function textvaluelog(const fieldno,aindex: integer;
with a light source of the selected color
+
                      const caseinsensitive: boolean): msestring;
( in this case, colors of the face & the widget & the light source
+
-  returns value of widestring array "fieldno" where the array index equals to "aindex"
simply summarize to higher brightness )
+
 
 +
function textindex(const fieldno,aindex: integer;
 +
                      const caseinsensitive: boolean): integer;
 +
- returns row number of widestring array "fieldno" where the array index equals to "aindex"
 +
 
 +
function textindexar(const fieldno: integer;
 +
                            const caseinsensitive: boolean): integerarty;
 +
- returns all bunch of indexes of widestring array "fiedlno"
 +
 
 +
function textar(const fieldno: integer): msestringarty;
 +
- returns all bunch of data of widestring array "fiedlno" 
 +
 
 +
 
 +
function lookupinteger(const integerkeyfieldno,integerfieldno,
 +
                                keyvalue: integer): integer; overload;
 +
- returns value of integer array "integerfieldno" at position where
 +
value of parallel integer array "integerkeyfieldno" equals to "keyvalue"
 +
                ( 0 if not found )
  
image:
+
function lookupinteger(const stringkeyfieldno,integerfieldno: integer;
see <any image>
+
                        const keyvalue: msestring): integer; overload;
 +
- returns value of integer array "integerfieldno" at position where
 +
value of parallel widestring array "stringkeyfieldno" equals to "keyvalue"
 +
                ( 0 if not found )
  
options:
+
function lookuptext(const integerkeyfieldno,textfieldno,
 +
                                keyvalue: integer): msestring; overload;
 +
- returns value of integer array "textfieldno" at position where
 +
value of parallel integer array "integerkeyfieldno" equals to "keyvalue"
 +
                ( '' if not found )
  
        *** The fade colors are used not as colors but RGB alpha values ($00 -> opaque, $ff -> transparent)  
+
function lookuptext(const stringkeyfieldno,textfieldno: integer;
if fao_alpha* are set *** :
+
                      const keyvalue: msestring): msestring; overload;
 +
- returns value of integer array "textfieldno" at position where
 +
value of parallel integer array "integerkeyfieldno" equals to "keyvalue"
 +
                ( '' if not found )
  
fao_alphafadeall = applies blending to the widget & all its childs
 
fao_alphafadenochildren = preserves child widgets from blending
 
                fao_alphafadeimage = applies blending to "face.image"
 
  
 +
function lookupfloat(const integerkeyfieldno,floatfieldno,
 +
                                keyvalue: integer): realty; overload;
 +
- returns value of real/datetime array "floatfieldno" at position where
 +
value of parallel integer array "integerkeyfieldno" equals to "keyvalue"
 +
                ( emptyreal if not found )
  
<any face>
+
function lookupfloat(const stringkeyfieldno,floatfieldno: integer;
 +
                                keyvalue: msestring): realty; overload;
  
*** extends & customizes "tfacecomp" ***
+
- returns value of real/datetime array "floatfieldno" at position where
 +
value of parallel widestring array "stringkeyfieldno" equals to "keyvalue"
 +
                ( emptyreal if not found )
  
fade, image, option
+
function count: integer; - returns number of data rows
- see "tfacecomp"
 
 
template
 
- "tfacecomp" supplying the initial settings
 
  
localprops :
+
property fieldcounttext: integer; - returns/sets number of widestring arrays
fal_options - "options" overrides "template.options"
+
property fieldcountfloat: integer; - returns/sets number of real/datetime arrays
fal_fadirection - "fade.direction" overrides "template.fade.direction"
+
property fieldcountinteger: integer; - returns/sets number of integer arrays
fal_image - "image" overrides "template.image"
 
fal_fapos - "fade.pos[i]" overrides "template.fade.pos[i]"
 
fal_facolor - "fade.color[i]" overrides "template.fade.color[i]"
 
fal_fatransparency - "fade.transparency" overrides "template.fade.transparency"
 
  
=== TBitmapComp ===
+
the above "fieldcount*" props clear the buffer on setting a value
=== TImageList ===
 
=== TPopupMenu ===
 
=== TMainMenu ===
 
  
== Dialog ==
+
property integervalue[const fieldno,aindex: integer]: integer; - a shortcut to "integervaluephys"
=== TFileListview ===
+
property floatvalue[const fieldno,aindex: integer]: realty; - a shortcut to "floatvaluephys"
=== TFileDialog ===
+
property textvalue[const fieldno,aindex: integer]: msestring; - a shortcut to "textvaluephys"
=== TFaceComp ===
+
 
=== TFileNameEdit ===
+
property onchange: notifyeventty;
=== TDirDropdownEdit ===
+
- called in "changed" wich in turn is called in :
=== TColorEdit ===
+
= clearbuffer
=== TMemoDialogEdit ===
+
= endupdate
=== TPageSizeSelector ===
+
= doasyncevent
=== TPageOrientationSelector ===
+
= loaded
 +
= tlookupbuffer.addrow
 +
 
 +
</pre>
  
== Application ==
+
=== TLookupBuffer ===
=== TGuiApplication ===
 
 
<pre>
 
<pre>
tguiapplication = class(tcustomapplication)
+
tlookupbuffer = class(tcustomlookupbuffer)
  public
 
  
  // [re]starts the system timer with the new period and
+
- extends "tcustomlookupbuffer" with methods of run-time data filling
  // subscribes the application to be a receiver of the modified "ek_timer" event
 
  // ( can check for it in the event queue )
 
  procedure settimer(const us: integer);
 
  
  // finds a window by its winID
+
- see <tcustomlookupbuffer>
  function findwindow(id: winidty; out window: twindow): boolean;
 
  
  // finds a window by its ID & adjusts "rect" so that it
+
+= Extentions to the public interface:
  // fits "bounds_minc*" & "bounds_maxc*" of the found window
 
  procedure checkwindowrect(winid: winidty; var rect: rectty);
 
  
  // inits the timer and "megraphics"
+
procedure addrow(const integervalues: array of integer;
  procedure initialize;
+
                    const textvalues: array of msestring;
 +
                    const floatvalues: array of realty);
  
  // frees the allocated system resources (GDI, event subsription, the timer)
+
- adds one row to each of widestring arrays, integer arrays and real/datetime arrays,
  procedure deinitialize;
+
array size of  "{type}values" equals to number of {type} arrays
  
  // creates a form instance, it will be shown in "application.run"
+
  procedure addrows(const integervalues: array of integerarty;
  procedure createform(instanceclass: widgetclassty; var reference);
+
                    const textvalues: array of msestringarty;
 +
                    const floatvalues: array of realarty);
  
  // invalidates all registered forms ( all their widgets will be redrawn )
+
- adds many data rows  to each of widestring arrays, integer arrays and real/datetime arrays,
  procedure invalidate;
+
only min length of the input data arrays are inserted, longer data are truncated
 
+
array size of  "{type}values" equals to number of {type} arrays and the size of "{type}values[i]"
  // calls a nested main eventloop, forces processing any pending messages,
+
describes number od data elements in the array
  procedure processmessages; override; //handle with care!
+
 +
</pre>
  
  // TRUE if no pending events to process for the application
+
=== TDBLookupBuffer ===
  function idle: boolean; override;
+
<pre>
 
+
tdblookupbuffer = class(tcustomdblookupbuffer -> tcustomlookupbuffer)
  // requests to indicate waiting ( to show the "watches" cursos )
 
  procedure beginwait; override;
 
  
  // removes the "watches" if no unclosed requests for displaying them,
+
- extends "tcustomlookupbuffer" with interface to fill arrays with DB-data
  // otherwise closes the currently active request
+
- see <tcustomlookupbuffer> & <tcustomdblookupbuffer>
  procedure endwait; override;
 
  
  // TRUE if there're unclosed requests for displaying "watches"
+
Extentions to the public interface:
  function waiting: boolean;
 
  
  // TRUE if ESC has just been pressed
+
  procedure checkbuffer; - if data obsolete ("invalid") then reloads them from "datasource"
  //  - if all requests for displaying "watches" are closed then refreshes
+
    
   //    the internal list of events ( the GUI-queue -> the app event list)
+
property datasource: tdatasource; - sets/returns DB data source where to load data from
  function waitescaped: boolean; //true if escape pressed while waiting
+
property textfields: tdbfieldnamearrayprop; - allows to assign a {datasource:datafield} to each of widestring arrays
 +
property integerfields: tdbfieldnamearrayprop; - allows to assign a {datasource:datafield} to each of integer arrays
 +
property floatfields: tdbfieldnamearrayprop; - allows to assign a {datasource:datafield} to each of real/datetime arrays
  
  // sets state of the current wait dialogue ( but doesn't close one ) to undefined
+
property optionsdb: lbdboptionsty; - tunes some DB behaviour apects
  procedure resetwaitdialog; 
+
- olbdb_closedataset :
 +
= once data obsolete, opens (if needed) the supplier dataset (disabling its bound controls)  
 +
then [re]loads data from it then closes it
  
  // runs "aexecuteaction" in the main thread in OnIdle mode,
+
- olbdb_invalidateifmodified :
  // then shows a cancellable message,
+
= gets marked "invalid" once contents of the bound dataset change,  
  // if the one is cancelled then runs "acancelaction" then
+
it signals to reload the buffer with the new data just before next accessing
  // either fully clears (if exceptions occur )
+
( for any purpose - searching, lookuping, getting value/(array of values),..)
  // or terminates the execution otherwise,
 
  // true if not cancelled;
 
  // "application.processmessages" must be called regularly if "aexecuteaction" is used here,
 
  // alternatively "aidleaction" can be used, call sleep ( some time ) in order to minimize
 
  // processor load.  
 
  // If athread <> nil the function starts and terminates the thread   
 
  function waitdialog(const athread: tthreadcomp = nil; const atext: msestring = '';
 
                  const caption: msestring = '';
 
                  const acancelaction: notifyeventty = nil;
 
                  const aexecuteaction: notifyeventty = nil): boolean; override;
 
  
  // closes the currently modal waitdialogue with "cancelled" state
+
</pre>
  procedure cancelwait;
 
  
  // closes the currently modal waitdialogue with "ok" state
+
=== TDBmemoLookupbuffer ===
  procedure terminatewait;
+
<pre>
 +
- allows to use  for lookup-ing any text-convertable DB-fields
 +
- an analog of tdblookupbuffer, but :
 +
- "integerfields" may be names of any integer-convertable DB-fields
 +
- "floatfields" may be names of any (real/datetime)-convertable DB-fields
 +
- "textfields" may be names of any text-presentable DB-fields
  
  function waitstarted: boolean;  // the last waitdialogue is currently showing for some requests
+
- each DB-field value ( presenting a memo generally of many lines ) may supply many data rows at once
  function waitcanceled: boolean;  // the last waitdialogue has been cancelled for some request (but can be shown fot others ?)
+
to the bound array of the buffer, since this value will be internally splitted & turned into native array values,
  function waitterminated: boolean; // the last waitdialogue has been terminated for some request (but can be shown fot others ?)
+
and the resulting "count" (arrays row count) of the whole buffer will be the minimal rows count amongst arrays
 +
of the buffer, the rest data are truncated
  
  // if called from the main app thread then shows as a modal message describing the exception  
+
- when loading widestring arrays, also checks for & performs "utf8-to-widestring" conversion of values of
  // otherwise posts an async event for which the message will be called
+
the bound DB-fields so that these arrays always store widestrings
  procedure showexception(e: exception; const leadingtext: string = ''); override;
+
</pre>
 +
 
 +
=== TThreadComp ===
 +
=== TStatFile ===
 +
<pre>
 +
- so that to be in effect, it should also be assigned to the form where the widget using the stafile is placed on
 +
- in design, if "onstatwrite" is set and "filedir" is not yet created, deactivate exception "ECreateError" in project settings ( "Debugger" tab )
 +
- "filedir" may contain "~/" indicating the user's home directory
 +
- options "oe_savestate" & "oe_savevalue" of "client" widgets define what to store to the file
 +
- position etc changes or/and value changes
 +
- 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
 +
- each "tstafile" owns:
 +
= tstatwriter:
 +
* provides methods of writing sections & statvars to a memory/file stream
 +
- tstatreader:
 +
* holds list of sections with statvars each
 +
* provides search & check & reading interface to the statvars
 +
* provides reading statvars from a memory/file stream
 +
 
 +
Positioning to a section speeds up accessing its statvars
  
  // posts an async event for which the message describing the exception will be called
+
- there also is "tstatfiler" ( exposed by some "tstatfile" events ) which:
  procedure showasyncexception(e: exception; const leadingtext: string = '');
+
= may present or "tstatwriter" or "tstatreader" ( there's a check method )
 +
= provides directionless "update" methods with internal switch to needed direction of processing
 +
- "reading" or "writing" statvars on per-section basis
  
  // "application.errormessage" shows standard error message ( with "ERROR" title )
 
  procedure errormessage(const amessage: msestring); override;
 
  
  // [re]calculates timings & position of hint for "ahintedwidget"
+
activator :
  // if "ow_timedhint" in "ahintedwidget.foptionswidget" then iys showtime will be
+
<see tactivator> : NOT YET DONE
  // "defaulthintshowtime" ( an app wide setting, 3sec by default) 
 
  procedure inithintinfo(var info: hintinfoty; const ahintedwidget: twidget);
 
  
 +
encoding = "en_utf8" selected here, allows to store non-Latin text in the file
 +
      filedir = directory where to keep the file ( by default - the current working directory )
 +
filename = name of the file
  
  // shows the supplied hint text within "aposrect" with alignment "aplacement" during "ashowtime",
+
options:
  // the avail ( but not used currenly ) flags are : hfl_show,hfl_custom,hfl_noautohidemove,hfl_noautohidemove 
+
sfo_memory = reads & writes not from a disk file but from a named memory stream
  procedure showhint(const sender: twidget; const hint: msestring;
+
( there's an exclusion - see below "sfo_savedata" ),
              const aposrect: rectty; const aplacement: captionposty = cp_bottomleft;
+
mostly useful for presenting last used values on recalling
              const ashowtime: integer = defaulthintshowtime; //0 -> inifinite,
+
non-main forms etc ( data even survive recreating forms),
                // -1 defaultshowtime if ow_timedhint in sender.optionswidget
+
or even for data "exchange" between non-main modal( non-concurring ) forms
              const aflags: hintflagsty = defaulthintflags
+
in case of the target widgets share same statvarnames
                      ); overload;
 
  
  // shows the supplied hint text at left-top position"apos" during "ashowtime",
+
sfo_createpath = creates "filedir" if necessary
  // the avail ( but not used currenly ) flags are : hfl_show,hfl_custom,hfl_noautohidemove,hfl_noautohidemove 
+
sfo_savedata = used only with "sfo_memory", commands to save
  procedure showhint(const sender: twidget; const hint: msestring;
+
the memory data to the master statfile (see below)
              const apos: pointty;
 
              const ashowtime: integer = defaulthintshowtime; //0 -> inifinite,
 
                // -1 defaultshowtime if ow_timedhint in sender.optionswidget
 
              const aflags: hintflagsty = defaulthintflags
 
                      ); overload;
 
  
  // shows the hint fully defined in "info" for the widget "sender"
+
sfo_activatorread = activator activate triggers reading ???
  procedure showhint(const sender: twidget; const info: hintinfoty); overload;
+
sfo_activatorwrite = activator deactivate triggers writing ???
  
  // removes the current hint widget & frees its resources & stops its stop timer
+
statfile = a master statfile
  procedure hidehint;
+
statvarname = name of section of this file in the upper statfile
 +
Tag = an integer property for misc purposes
  
  // restarts the current hint and its stop timer
+
Event handlers:
  procedure restarthint(const sender: twidget);
+
onstatafterread - fires on return from "readstat"
 +
onstatafterwrite - fires on return from "writestat"
 +
onstatbeforeread - fires on beginning of "readstat"
 +
onstatbeforewrite - fires on beginning of "writestat"
 +
onstatread = fires after reading state data
 +
onstatwrite = fires after writing state data
 +
onstatupdate = fires after reading/writing state data just before
 +
"onstatread" & "onstatwrite"
  
  function hintedwidget: twidget; //last hinted widget
+
Public methods:
  function activehintedwidget: twidget; //nil if no hint active
 
  
   // returns helpcontext of active widget, '' if none; 
+
  procedure initnewcomponent(const ascale: real); override;
   function activehelpcontext: msestring;
+
  - does nothing but fixes the default file name as the statfile default
 +
    
 +
  procedure readstat(stream: ttextstream = nil); overload;
 +
  - rereads all statvars of the stafile/memorystream
 +
    
 +
  procedure readstat(const aname: msestring; const statreader: tstatreader); overload;
 +
  - rereads "aname" statvar of the statfile
  
   // returns helpcontext of the widget under mouse, '' if none;
+
  procedure writestat(const stream: ttextstream = nil); overload;
  function mousehelpcontext: msestring;
+
  - rewrites all statvars to the stafile/memorystream
 +
  (if neccessary, prepares to writting - creates "filedir", stafile,...)
 +
    
 +
  procedure writestat(const aname: msestring; const statwriter: tstatwriter); overload;
 +
  - overwrites "aname" statvar of the statfile
 +
 
 +
  procedure updatestat(const aname: msestring; const statfiler: tstatfiler);
 +
  - depending on kind of "statfiler" ( writer/reader ), writes/reads
 +
    the most up-to-date stat data
 +
</pre>
  
  // TRUE if one of the app's window/console is in input focus
+
=== TTimer ===
  function active: boolean;
+
=== TNoGuiAction ===
 +
=== TPipeReadercomp ===
 +
=== TSysEnvManager ===
 +
=== TProcessMonitor ===
 +
=== TFilechangeNotifier ===
 +
=== TShortCutController ===
 +
=== TPostscriptPrinter ===
 +
=== TGdiPrinter ===
 +
=== TWmfPrinter ===
 +
=== TSkinController ===
 +
=== TGuiThreadComp ===
  
  // returns the desktop resolution ( or the virtual one if used )
+
== Font ==
  function screensize: sizety;
+
See also : [[Reference:_MSEgui/TFont]]
  
  // returns the (virtual) desktop resolution except the tray area,
+
=== Any Font ===
  // nil -> current active window
+
<pre>
  function workarea(const awindow: twindow = nil): rectty;
+
    charset { ANSI/ DEFAULT/ SYMBOL /SHIFTJIS /HANGEUL /GB2312 /CHINESEBIG5 /OEM
 
+
/JOHAB / HEBREW/ ARABIC/ GREEK/ TURKISH/ VIETNAMESE/ THAI/ EASTEUROPE/
  // returns which application window ( a form not an eventwidget, an openglwidget or a windowwidget !)  
+
RUSSIAN/ MAC/ BALTIC }
  // is active ( provides the input focus ),
+
- changes the font to the nearest containing the selected encoding(charset)
  // it's same for all widgets of the form served by this window
+
- no font change made if the supplied encoding doesn't match any font
  function activewindow: twindow;
+
color
 
+
- color of the glyphs contours
/ * A transient window is a descendant of ( "transientfor" ) another window in the stacking order hierarchy */
+
colorbackground
 
+
- fill color of the glyph cells ( not including extraspace )
  // returns a first non-transient ( on top of the app stacking order ) window upward
+
colorshadow
  // from the currently active window of the application.
+
- color of SE glyph "edges" ( if not "cl_none", deactivates "colorbackground" )
  // or that active window if no such
+
extraspace
  function regularactivewindow: twindow;
+
- v-space between glyph cells of adjacent text rows (negative values cause the cells to overlap )
 
+
height
  // same as "activewindow" but the window must not be released (?)
+
- v-size of glyph cells, in pixels
  function unreleasedactivewindow: twindow;
+
name
 
+
- initially, font is choosen by { "family" = this name }
  // returns the focused widget of the currently active window if one exists
+
options:
  function activewidget: twidget;
+
foo_fixed
 
+
- changes the font to the nearest "mono" spaced (usually = Courier)
  // returns the widget presenteing the currently active window
+
foo_proportional
  function activerootwidget: twidget;
+
- changes the font to the nearest "proportionally" spaced (usually = Helvetica)
 
+
foo_helvetica
  // returns the window ( not hidden or disabled !) under the screen point "pos"
+
- changes the font to the nearest in "sans" category (usually = Helvetica)
  function windowatpos(const pos: pointty): twindow;
+
foo_roman
 
+
- changes the font to the nearest in "serif" category (usually = Times[ New Roman])
  // puts to "awidget" the container of widget pointed by "namepath"
+
foo_script
  // ( finalizing "." is discarded if found ) ,
+
- Win32 only, changes the font to the nearest in "script" category
  // FALSE if not found, and NIL and TRUE if "namepath" = ''
+
foo_decorative
  function findwidget(const namepath: string; out awidget: twidget): boolean;
+
- Win32 only, changes the font to the nearest in "decorative" category
 +
foo_antialiased
 +
- Linux-only, enables antialiasing (if disabled by Xft globally)
 +
foo_nonantialiased
 +
- Linux-only, disables antialiasing (if enabled by Xft globally)
 +
usually making glyph extents (not cells !) a bit wider
 +
style:
 +
fs_bold
 +
- gives the font a "bold" look
 +
fs_italic
 +
- gives the font an "italic" look
 +
fs_underline
 +
- gives the font an "underlined" look
 +
fs_strikeout
 +
- gives the font a "striked out" look
 +
fs_selected
 +
- "TRUE" here combined with {tf_noselect:=FALSE}, causes the text described by this font
 +
to be initially selected ( with the clipboard operations available ),
 +
currently applicable only to richstrings
  
  // rebuilds the application's window list accorrding to the current on-screen Z-order of its windows;
+
width
  // window list is ordered by "z" - bottom first & top last;
+
- 10*{ glyph cell width, average in pixels }, 0 = {font default}
  // invisibles first
 
  procedure sortzorder;
 
  
  // returns a copy of the internal window list of application
+
xscale
  function windowar: windowarty;
+
- width ratio of each glyph {cell & contour}, the effect is similar to "width"
  
  // returns the list of application window winIDs
+
*** "foo_*" font selection overrides one made with "name"
  function winidar: winidarty;
 
  
  // returns the count of the application windows   
+
*** if change with "foo_*" is unsuccessful then the nearest "sans" font is usually chosen
  function windowcount: integer;
 
  
  // returns the window by its number ( "index" >= 0) in the application window list
+
*** The categories :
  property windows[const index: integer]: twindow read getwindows;
 
  
  // returns the lowest visible window in stackorder,
+
sans => have no serifs and have strokes of even thickness
  // calls "sortzorder" within
+
serif => have serifs at glyph contours and made up of strokes of varying thickness
  function bottomwindow: twindow;
+
script => resemble handwriting
 +
decorative => flashy styles to be used sparingly in headlines or posters
  
  // returns the highest visible window in stackorder,
+
</pre>
  // calls "sortzorder" within
 
  function topwindow: twindow;
 
  
 +
== GUI ==
 +
=== TWindow ===
 +
<pre>
 +
twindow = class(teventobject,icanvas)
 +
  public
  
  // TRUE if all owned windows pass "CanClose" check or
+
// releases mouse, unlinks from the canvas, processes all pending events of the window
  // don't have focused widgets
+
// if called from within main thread then destroys the window directly
  function candefocus: boolean;
+
// otherwise posts a window destroy event for oneself and waits for it to be processed
 +
procedure destroywindow;
  
  // subscribes the handler "method" to receive keyboard events
+
// registers the instance of onself in the "owner" widget, allocates the canvas,
  procedure registeronkeypress(const method: keyeventty);
+
// adds a reference to oneself,
 +
// then prepares the "owner" hierarchy to be invalidated ( "owner.rootchanged" )
 +
// since now, the window is allocated and belongs to the "aowner" widget
 +
constructor create(aowner: twidget);
  
  // unsubscribes the handler "method" from receiving keyboard events
+
destructor destroy; override;
  procedure unregisteronkeypress(const method: keyeventty);
 
  
  // subscribes the handler "method" to receive shortcut events
+
// adds "method" to the internal list of scroll dependants
  procedure registeronshortcut(const method: keyeventty);
+
procedure registeronscroll(const method: notifyeventty);
  
  // unsubscribes the handler "method" from receiving shortcut events
+
// removes "method" from the internal list of scroll dependants
  procedure unregisteronshortcut(const method: keyeventty);
+
procedure unregisteronscroll(const method: notifyeventty);
  
  // subscribes the handler "method" to receive "OnWindowActiveChanged" event ( form-wide )
+
// releases mouse if captured, resets the cursor, then enters an event loop for the window,
  procedure registeronactivechanged(const method: activechangeeventty);
+
// TRUE on return if the window is destroyed
 +
function beginmodal: boolean;
 +
 +
  * checks if the "sender" window is already modal to avoid circularity,
 +
    if not then starts an event loop  for the "sender" where the "sender" is a receiver of GUI events,
 +
      once the loop is terminated reactivates the previously active window if it was,
 +
    TRUE if modalwindow destroyed 
  
  // unsubscribes the handler "method" from receiving "OnWindowActiveChanged" event ( form-wide )
+
  function tinternalapplication.beginmodal(const sender: twindow): boolean;
  procedure unregisteronactivechanged(const method: activechangeeventty);
 
  
  // subscribes the handler "method" to receive "OnDestroyed" events ( form-wide )
+
// removes the internal stuff which indicates the modal state
  procedure registeronwindowdestroyed(const method: windoweventty);
+
procedure endmodal;
  
  // unsubscribes the handler "method" from receiving "OnDestroyed" events ( form-wide )
+
// if the window is visible,
  procedure unregisteronwindowdestroyed(const method: windoweventty);
+
// deactivates the previously active window, shows the window (see below),
 +
// if no active window in the app or the window or its Z-predecessor is modal and
 +
// the app has no focused widget then prepares the bound widget to be focused,
 +
// then addresses the WM to put the window to foreground
 +
procedure activate;
  
   // subscribes the handler "method" to receive "OnWindowDestroyed" events ( form-wide )
+
  // if the bound widget has visible=true then:
  procedure registeronwiniddestroyed(const method: winideventty);
+
  //  - if NOT windowevent then :
 +
  //   = address the WM to set size of the window acc to window opts
 +
  //      wp_maximized, wp_fullscreen or normal size otherwise
 +
  // = if the window is normally sized, moves it to its default position is specified ( screen centered etc )
 +
  // - unhides/unminimizes the window if needed
 +
  // - shows other windows of the applications acc to state of the window group
 +
  // ( in normal size or minimized )
  
  // unsubscribes the handler "method" form receiving "OnWindowDestroyed" events ( form-wide )
+
  private
  procedure unregisteronwiniddestroyed(const method: winideventty);
+
procedure twindow.show(windowevent: boolean);
  
  // subscribes the handler "method" to receive "ApplicationActiveChanged" events ( form-wide )
+
// TRUE if this window currently grabs user input
  procedure registeronapplicationactivechanged(const method: booleaneventty);
+
( a widget drawn within the window(=form) is in focus,.. )
 +
function active: boolean;
  
  // unsubscribes the handler "method" from receiving "ApplicationActiveChanged" events ( form-wide )
+
// if the window was active then deactivates the window  & remembers it as the previous active ( to restore leater if requested ),
  procedure unregisteronapplicationactivechanged(const method: booleaneventty);
+
// returns TRUE if that storage occurred
 +
function deactivateintermediate: boolean;  
  
// tcustomapplication
+
// makes the window active & clears the above app reference to it ( "active before deactivating" )
 +
procedure reactivate; //clears app.finactivewindow
  
  // subscribes the handler "method" to receive "OnTerminated" event ( form-wide )
+
// scans the app event queue for "ek_expose" event[s] addressed to the window,
  procedure registeronterminated(const method: notifyeventty);
+
// if found then redraws that part of the window which the event describes
 +
// ( processed events are then deleted )
 +
procedure update;
  
  // unsubscribes the handler "method" from receiving "OnTerminated" events ( form-wide )
+
// TRUE if the window :
  procedure unregisteronterminated(const method: notifyeventty);
+
// 1) doesn't have an inner widget grabbing input focus
 
+
// or
  // subscribes the handler "method" to receive "OnTerminateQuery" event ( form-wide )
+
// 2) has such widget, and this widget ( and all its descendants )  
  procedure registeronterminate(const method: terminatequeryeventty);
+
//   pass "CanClose" check
 +
//
 +
// *** see also "twidget.CanClose" ***
 +
//
 +
function candefocus: boolean;
  
  // unsubscribes the handler "method" from receiving "OnTerminateQuery" event ( form-wide )
+
// tries to defocus the currently focused widget if it belongs to the window,
   procedure unregisteronterminate(const method: terminatequeryeventty);
+
// if succeeds then executes code of virtual "DoDefocus" of the widget descessor
 +
// ( this code defines behaviour & look of the widget on defocusing );
 +
//
 +
// no defocusing is done if the focused widget ( or its descendants )
 +
// doesn't pass "CanClose" check
 +
//
 +
procedure nofocus;
 +
 
 +
  // setfocusedwidget(widget)
 +
 
 +
  property focuscount: cardinal read ffocuscount;
 +
  function close: boolean; //true if ok
 +
  procedure beginmoving; //lock window rect modification
 +
  procedure endmoving;
 +
  procedure bringtofront;
 +
  procedure sendtoback;
 +
  procedure stackunder(const predecessor: twindow);
 +
      //stacking is performed in mainloop idle, nil means top
 +
   procedure stackover(const predecessor: twindow);
 +
      //stacking is performed in mainloop idle, nil means bottom
 +
  function stackedunder: twindow; //nil if top
 +
  function stackedover: twindow;  //nil if bottom
 +
  function hastransientfor: boolean;
  
   // subscribes the handler "method" to receive "OnIdle" event ( form-wide )
+
   procedure capturemouse;
   procedure registeronidle(const method: idleeventty);
+
  procedure releasemouse;
 +
   procedure postkeyevent(const akey: keyty;
 +
        const ashiftstate: shiftstatesty = []; const release: boolean = false;
 +
                  const achars: msestring = '');
  
   // unsubscribes the handler "method" from receiving "OnIdle" events ( form-wide )
+
   function winid: winidty;
   procedure unregisteronidle(const method: idleeventty);
+
  function haswinid: boolean;
 +
  function state: windowstatesty;
 +
  function visible: boolean;
 +
  function activating: boolean; //in internalactivate proc
 +
  function normalwindowrect: rectty;
 +
  property updateregion: regionty read fupdateregion;
 +
   function updaterect: rectty;
  
   // calls "canclose" of all application windows except the "sender" window
+
   procedure registermovenotification(sender: iobjectlink);
  // if all "canclose"are TRUE then checks "OnTerminateQuery"
+
   procedure unregistermovenotification(sender: iobjectlink);
  // for all its subscribers ( usually forms of the application )
 
   procedure terminate(const sender: twindow = nil);  
 
  
   // TRUE as long as a "terminate" call is in progress
+
   property options: windowoptionsty read foptions;
  function terminating: boolean;
 
  
  // TRUE as long as a "deinitialize" call is in progress
+
// widget
  function deinitializing: boolean;
+
property owner: twidget read fowner;
 
 
  // returns the current caret object ( the text input focus indicator ) of the application
 
  / ( this object provides facitities to control position & appearance & visibility & timings of the caret )
 
  property caret: tcaret read fcaret;
 
  
   // returns the current mouse object of the application
+
   property focusedwidget: twidget read ffocusedwidget;
   / ( this object provides facitities to control position & appearance of the mouse ) 
+
  property transientfor: twindow read ftransientfor;
   property mouse: tmouse read fmouse;
+
  property modalresult: modalresultty read fmodalresult write setmodalresult;
 +
   property buttonendmodal: boolean read getbuttonendmodal write setbuttonendmodal;
 +
  property globalshortcuts: boolean read getglobalshortcuts write setglobalshortcuts;
 +
  property localshortcuts: boolean read getlocalshortcuts write setlocalshortcuts;
 +
  property windowpos: windowposty read getwindowpos write setwindowpos;
 +
   property caption: msestring read fcaption write setcaption;
  
  // simulates mouseparkevent
 
  // ( an adjusting mouse movement without user intervention - grid snapping, docking etc ?)
 
  procedure mouseparkevent;
 
  
  // sets mouse position correction for further mouse events,
+
windowoptionty = (wo_popup,wo_message,wo_buttonendmodal,wo_groupleader,
  // the real position is less the visual one by the supplied shift
+
                  wo_windowcentermessage); //showmessage centered in window
  procedure delayedmouseshift(const ashift: pointty);
 
  
  // returns/sets a cursor shape used for widgets having their cursor shape set to "cr_default";
 
  // setting it to "cr_default" restores the individual widget cursor(s)
 
  property widgetcursorshape: cursorshapety read fwidgetcursorshape write
 
                                        fwidgetcursorshape;
 
  
  // returns/sets the current application-wide cursor shape ( not "watches" if a waiting dialogue is curerntly displayed ! )
+
optionswindow:
  // or request to set a new cursor shape ( app-wide );
+
wo_popup
  // doesn't change when changing mouse widgets
+
- in run-time, hides all OS windows-manager ( WM ) decorations (title bar, buttons "Close/Resize,Min/Max" etc),
  //  
+
letting only its client area to appear
  // if called from a non-main app thread & no waiting dialogue displayed then redraws
+
so :
  // the cursor immediately;
+
= the window should have own facilities to replace the deactivated WM functionality if needed
  // set it to "cr_default" to restore the shape to one set by "widgetcursorshape"
+
= can't be resized/maximize/minimized/moved
  //
+
wo_message
  property cursorshape: cursorshapety; // cr_arrow, cr_*
+
- similar to "wo_popup" but allows WM to close ( with "Close" button ) & move the window
  
  // assures the displayed mouse cursor shape to be the shape assigned to the currently under-mouse widget,
+
wo_groupleader
  // otherwise "cr_default"
+
- keeps on the WM taskbar a shortcut to the window
  procedure updatecursorshape; //restores cursorshape of mousewidget
+
( if the parent window is a groupleader too then displays a step upper in its group )
  
  // returns a widget of the application where the mouse is currently positioned over
+
Event handlers:
  property mousewidget: twidget read fmousewidget;
 
  
  // returns a widget of the application currently "owning" the mouse ( grabbing all mouse input )
+
- onmove
  property mousecapturewidget: twidget read fmousecapturewidget;
+
= fires once the (window/widget) is created/moved ( with check if really moved by a distance)
  
 +
</pre>
  
  // returns/sets a window to become the main window of the application
+
=== TFormScrollbox ===
   // then resets all other application windows to the window group it belongs to ( Linux only );
+
<pre>
  //
+
- presents client area of form & parent of its widgets,
  // the main window minimizes all windows if minimized;
+
initially stretched to fit the form & bound with anchoring
  property mainwindow: twindow read fmainwindow write setmainwindow;
+
but may be adjusted with "bounds" & "anchors"
 +
    
 +
    Properties:
 +
               
 +
anchors
 +
bounds
 +
 +
color
 +
- color of the whole container area ( except its frame ) & form widgets
 +
if their color is "cl_parent"
  
  // returns which system thread was allocated to the application on its start
+
name = container
  // ( the main thread )
 
  property thread: threadty read fthread;
 
  
  // returns teh widget where a mouse button click occured last time
+
cursor, enabled, face, frame, helpcontext, hint, optionswidget, popupmenu,
  // ( to compare with when determinibg whether another widget is clicked )
+
taborder, tag, visible, onactivate, onafterpaint, onbeforepaint,
  property buttonpresswidgetbefore: twidget read fbuttonpresswidgetbefore;
+
onchildmouseevent, onclientmouseevent, ondeativate, ondefocus, onenter,
 +
onexit, onfocus, onfontheightdelta, onmouseevent, onpaint, onpopup
 +
onresize, onshowhint
 +
- the same meaning as for the served form
  
  // returns teh widget where a mouse button release occured last time
 
  // ( to compare with when determinibg whether another widget is clicked )
 
  property buttonreleasewidgetbefore: twidget read fbuttonreleasewidgetbefore;
 
  
 +
oncalcminscrollsize
 +
onscroll
 +
onchildscaled
 +
</pre>
  
  // returns/sets the interval of mouse double click recognition ( in microsecs),
+
=== TFaceList ===
  // defaults to 0.4 sec
+
=== TFrameComp ===
  property dblclicktime: integer read fdblclicktime write fdblclicktime default
 
                defaultdblclicktime; //us
 
  
// tcustomapplication
+
See also here: [[Reference:_MSEgui/TFrame]].
  
  // creates a datamodule instance ( its startup code including "OnLoaded" is executed )
+
  procedure createdatamodule(instanceclass: msecomponentclassty; var reference);
+
<pre>
 +
Terminology :
  
 +
{client area = area of the widget which interacts with a user}
  
  // enters the application event loop;
+
{bevelling = additional facets rising/sinking frame & client area,
  //
+
constists of two parts -
  // once the loop finishes, performs "OnTerminated" for all its subscribers,
+
- external: between frame and widget
  // destroys all application forms ( components & windows )
+
- internal: between frame and client area
  procedure run;
+
}
  
  // TRUE if the eventloop is entered
+
{frame= flat space between external & internal facets,
  function running: boolean;
+
floats at the inner level of the external facet
 +
}
  
  // returns/sets the application name
+
*** Both frame & bevelling affect the client area ***
  // ( defaults to the full path to application executable in the native OS format );
 
  // currently, only for informatiion query purposes
 
  property applicationname: msestring read fapplicationname write fapplicationname;
 
 
 
  
  // if exclusive "rights" are satisfied for the main thread ( a mutex lock is OK )  & the event loop is in progress
+
--------------------------
  // then posts the "event" to the main application thread for asyc processing,
+
template:
  // otherwise adds the event to the internal list for further handling as soon as the above conditions meet
 
  procedure postevent(event: tevent);
 
  
  // TRUE if never idle since last call,
+
colorclient = color of the client area
  // unlocks the application and calls sleep if not mainthread and asleepus >= 0
 
  function checkoverload(const asleepus: integer = 100000): boolean;
 
  
  // returns/sets the application exception handler
+
colorframe = color of the frame
  property onexception: exceptioneventty read fonexception write fonexception;
+
colorframeactive = used instead of colorframe if the widget is
 +
active; "cl_default" means same as colorframe.
  
  // if not "eabort" & no unhandled exceptions,
+
works if (leveli/levelo <> 0 that's the facets exist :
  // executes the above "OnException" code if assigned
 
  // or shows an exception message otherwise;
 
  procedure handleexception(sender: tobject = nil;
 
                                      const leadingtext: string = '');
 
  
  // synchronizes the calling thread with the main event loop ( via a mutex),
+
colorshadow = color of facets screened from the NW light source
  // TRUE if the calling thread allready holds the mutex,
+
colordkshadow = color of shadows dropped by the NW light source
  // the mutex is recursive
+
                colordkwidth = width of the shadows in pixel, -1=default
  function lock: boolean;
+
 
 +
colorlight = color of facets exposed to the NW light source
 +
colorhighlight = color of brighter edges of the facets
 +
                colorhlwidth = width of the brighter edges in pixel, -1=default
 +
 
 +
        extraspace = if applied to menu items, adds more space between these items
  
  // tries to synchronize the calling thread with the main event loop ( via a mutex)
+
framei_:
  function trylock: boolean;
+
(for extendable widgets like menus, these settings widen the widget,
 +
for non-extendable like buttons - they squeeze the text area )
  
  // releases the mutex if the calling thread holds the mutex,
+
bottom= lower margin of text to the client area
  // TRUE if no unlock done
+
left = left margin of text to the client area
  function unlock: boolean;
+
right = margin of text to the client area
 +
top = upper margin of text to the client area
  
  // releases the mutex recursively if the calling thread holds the mutex,
+
framewidth= width of the frame
  // returns "count" for the below "relockall"
+
leveli = {width=height} of the internal facet, positive -> raised, negative -> sunken
  function unlockall: integer;
+
levelo = {width=height} of the external facet, positive -> raised, negative -> sunken
  
  // regains the mutex to serve "count" locks
+
<any frame>
  procedure relockall(count: integer);
 
  
  // 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,
+
*** extends & customizes "tframecomp" ***
  // then frees all locks temporarily then posts the event to the app event queue & waits fot it to be processed the resores the locks;
 
  //
 
  // TRUE if not aborted, quiet -> shows no exceptions if occurs
 
  //
 
  // the "syncronize event" is an event owning a semaphore which can be touched by another thread
 
  // thus causing "event.waitfo" to return & to exec the event handler code
 
  //
 
  function synchronize(const proc: objectprocty;
 
                      const quite: boolean = false): boolean;
 
  
  // TRUE if the calling ( this function ) thread is the application main thread
+
template
  function ismainthread: boolean;
+
- "tframecomp" supplying the initial settings
  
  // TRUE if the currently locked thread is the application main thread
+
colorclient,colordkshadow,colordkwidth,colorframe,colorframeactive,
  function islockthread: boolean;
+
colorhighlight,colorhlwidth,colorlight,colorshadow,framewidth,
 +
leveli, levelo, framei_*,
  
  // waith for "athread" to terminate,
+
<see "tframecomp">
  // does "unlock-relock" around waiting
 
  procedure waitforthread(athread: tmsethread);
 
  
  // post a "nothing-to-do" event for asynchronous processing in the main thread
+
font
  procedure wakeupmainthread;
+
<see "tfont">
  
  // invalidates all registered forms of the application so that their widgets redraw land-specific captions
+
caption
  // ( changed by "mseconsts.setlangconsts" ),
+
- some descriptive text( function name, user prompt,...) placed
  // called internally in "setlangconsts" before return
+
in a N/W/S/E-combination to the widget's client area
  procedure langchanged; virtual;
 
  
  // returns/sets "aps_terminated" state flag ( no actions ? )
+
***
  // this flag is also set internally by "terminate" if not cancelled
+
non-empty caption if (captionpos <> cp_center) & (captiondistouter=false & captiondist>0) enlarges the framed widget
  property terminated: boolean read getterminated write setterminated;
+
by the corresponding size of caption
  
  // returns the number of "handleexception" calls having an effect ( a message or the handler code )
+
***
  property exceptioncount: longword read fexceptioncount;
 
  
 +
captiondist - margin between the caption & the client area
  
private
+
captiondistouter :
// function tinternalapplication.beginmodal(const sender: twindow): boolean;
 
  
<pre/>
+
- if "false"(by default), the distance is measured between
 +
the inner (facing the client area) extent of the caption
 +
and the client area outward the area,
 +
the caption is placed outside of the client area
  
== DB ==
+
- if "true", the caption is mirrored against the edge of client area as
 +
to the position when "false"
  
=== DBedit ===
+
*** nagative values of "captiondist" visually inverse "out of" and within ***
=== DBfields ===
 
=== TDBwidgetgrid ===
 
<pre>
 
  Properties:
 
  
        anchors - ...
+
      captionnoclip - do not clip frame and client area for caption background
bounds - ...
+
( the client area preserves own background under the caption text)
  
color
+
captionnooffset - shift orthogonal to "captiondist"
- color of the grid's client area
 
cursor
 
- cursor shape when the mouse is over the client area
 
  
datacols
+
captionpos - "corner" where to place the caption
colorselect
 
linecolor
 
linecolorfix
 
linewidth
 
newrowcol
 
  
options
+
localprops :
co_readonly
 
co_nofocus
 
co_invisible
 
co_disabled
 
co_drawfocus
 
co_mousemovefocus
 
co_lefbuttonfocusonly
 
co_focusselect
 
co_mouseselect
 
co_keyselect
 
co_multiselect
 
co_resetselectionexit
 
co_rowselect
 
co_fixwidth
 
co_fixpos
 
co_fill
 
co_proportional
 
co_nohscroll
 
co_savevalue
 
co_savestate
 
co_rowfont
 
co_rowcolor
 
co_zebracolor
 
co_nosort
 
co_sortdescent
 
co_norearrange
 
co_cancopy
 
co_canpaste
 
co_mousescrollrow
 
co_rowdatachange
 
  
sortcol
+
frl_levelo - "levelo" overrides "template.levelo"
width
+
frl_leveli - "leveli" overrides "template.leveli"
 +
frl_framewidth - "framewidth" overrides "template.framewidth"
 +
frl_colorclient - "colorclient" overrides "template.colorclient"
 +
frl_colorframe - "colorframe" overrides "template.colorframe"
 +
frl_colorframeactive - "colorframeactive" overrides "template.colorframeactive"
 +
frl_colordkshadow - "colordkshadow" overrides "template.colordkshadow"
 +
frl_colorshadow - "colorshadow" overrides "template.colorshadow"
 +
frl_colorlight - "colorlight" overrides "template.colorlight"
 +
frl_colorhighlight - "colorhighlight" overrides "template.colorhighlight"
 +
frl_colordkwidth - "colordkwidth" overrides "template.colordkwidth"
 +
frl_colorhlwidth - "colorhlwidth" overrides "template.colorhlwidth"
 +
frl_fileft - "framei_left" overrides "template.framei_left"
 +
frl_firight - "framei_right" overrides "template.framei_right"
 +
frl_fitop - "framei_top" overrides "template.framei_top"
 +
frl_fibottom - "framei_bottom" overrides "template.framei_bottom"
 +
 
 +
frl_nodisable
 +
</pre>
 +
 
 +
=== TFaceComp ===
  
items[N]
+
See also here: https://wiki.freepascal.org/Reference:_MSEgui/TFace
color
 
colorselect
 
datalist - ???
 
face - see <any face>
 
fontselect - see <any font>
 
frame - see <any frame>
 
linecolor
 
linecolorfix
 
linewidth
 
name
 
 
options
 
 
<pre/>
 
=== Report ===
 
  
==== TRepSpacer ====
+
<pre>
==== TRecordBand ====
+
- doesn't affect the widget frame but client area of the frame
==== TrepValueDisp ====
 
==== TRepPageNumdisp ====
 
==== TRepPrintDateDisp ====
 
==== TBandGroup ====
 
==== TTileArea ====
 
  
== Design ==
 
  
=== TGdbMi ===
+
template:
=== TSyntaxEdit ===
+
fade:
=== TSyntaxPainter ===
+
color[i]: = colors forming the fade
 +
direction: = direction where the fade grows to
 +
gd_(right/up/left/down)
  
== Comm ==
+
pos[i]: = relational position of color[i] on the direction (0.0..1.0) extent
  
=== TCommPort ===
+
transparency = makes the face half-transparent and enlighten the underlying widget 
=== TAsciiCommPort ===
+
with a light source of the selected color
=== TAsciiProtPort ===
+
( in this case, colors of the face & the widget & the light source
=== TCommSelector ===
+
simply summarize to higher brightness )
  
== General stuff==
+
image:
 +
see <any image>
  
=== Properties for all widgets ===
+
options:
<pre>
 
  
name
+
        *** The fade colors are used not as colors but RGB alpha values ($00 -> opaque, $ff -> transparent)
 +
if fao_alpha* are set *** :
  
anchors
+
fao_alphafadeall = applies blending to the widget & all its children
 +
fao_alphafadenochildren = preserves child widgets from blending
 +
                fao_alphafadeimage = applies blending to "face.image"
  
-----------
 
  
- they control of design/runtime sticking widgets to their parents
+
<any face>
  
- dimention pair ( top/bottom or left/right ) both set to "false" cause
+
*** extends & customizes "tfacecomp" ***
the widget to fit the parent's client area in that dimention;
 
this effect may be partial in case of "bounds_c*max" settings limit the extents
 
  
*** Return to the look "before dimention fit" is only possible by manual resizing or setting "bounds_*"
+
fade, image, option
-----------
+
- see "tfacecomp"
an_left
+
- on run-time, resizes/shifts left the widget to keep the design-set distance
+
template
between the widget's left border and the left side of parent's client area
+
- "tfacecomp" supplying the initial settings
as the parent resizes, until scrolling begins
 
  
an_top
+
localprops :
- on run-time, resizes/shifts up the widget to keep the design-set distance
+
fal_options - "options" overrides "template.options"
between the widget's top border and the upper side of parent's client area
+
fal_fadirection - "fade.direction" overrides "template.fade.direction"
as the parent resizes, until scrolling begins
+
fal_image - "image" overrides "template.image"
 +
fal_fapos - "fade.pos[i]" overrides "template.fade.pos[i]"
 +
fal_facolor - "fade.color[i]" overrides "template.fade.color[i]"
 +
fal_fatransparency - "fade.transparency" overrides "template.fade.transparency"
 +
</pre>
  
an_right
+
=== TBitmapComp ===
- on run-time, resizes/shifts right the widget to keep the design-set distance
+
=== TScalingwidget ===
between the widget's right border and the right side of parent's client area
+
<pre>
as the parent resizes, until scrolling begins
+
  optionsscale :
 +
autosizing to provide room for :
 +
= {"frame.caption" + "offset_*"}
 +
= "offset_*" if "frame.caption" is unset and "osc_shrink*" is set
 +
 +
= osc_expandx
 +
- makes the widget wider to fit the caption if needed
  
an_bottom
+
= osc_shrinkx
- on run-time, resizes/shifts down the widget to keep the design-set distance
+
- makes the widget narrower to have no space left & right to the "frame.caption"
between the widget's bottom border and the lower side of parent's client area
 
as the parent resizes, until scrolling begins
 
  
bounds
+
= osc_expandy
 +
- makes the widget taller to fit the caption if needed
  
cx - width of the widget
+
= osc_shrinky
cxmax, cxmin - design/runtime width of the widget is enforced between "cxmax" and "cxmin"
+
- makes the widget lower to have no space up & down to the "frame.caption"
cy - height of the widget
 
cymax, cymin - design/runtime height of the widget is enforced between "cymax" and "cymin"
 
x - distance between the widget's left border and the left side of parent's client area
 
y - distance between the widget's top border and the upper side of parent's client area
 
  
 +
= osc_invisishrinkx
 +
- fully h-collapses if "visible=false" ( run-time only )
  
autosize
+
= osc_invisishrinky
 +
- fully v-collapses if "visible=false" ( run-time only )
  
-----------
+
</pre>
- only appliable to widgets with "ow_autosize" set
 
- the effect may be partial in case when "bounds_c*max" settings limit the extents
 
-----------
 
  
cx - addition to width of the widget (with h-centering post applied)
+
=== TImageList ===
cy - addition to height of the widget (with v-centering post applied)
+
=== TPopupMenu ===
 +
=== TMainMenu ===
  
- color
+
== Dialog ==
= the default color of client area & caption text background
+
=== TFileListview ===
= may be overwtitten:
+
=== TFileDialog ===
* the client area - with "frame.colorclient"
+
=== TFaceComp ===
* the caption BG - with "frame.font.colorbackground"
+
=== TFileNameEdit ===
 +
=== TDirDropdownEdit ===
 +
=== TColorEdit ===
 +
=== TMemoDialogEdit ===
 +
=== TPageSizeSelector ===
 +
=== TPageOrientationSelector ===
  
- font
+
== Application ==
= see {any font}
+
=== TGuiApplication ===
 +
<pre>
 +
tguiapplication = class(tcustomapplication)
 +
  public
  
- frame
+
  // [re]starts the system timer with the new period and
= see {any frame}
+
  // subscribes the application to be a receiver of the modified "ek_timer" event
 +
  // ( can check for it in the event queue )
 +
  procedure settimer(const us: integer);
  
- face
+
  // finds a window by its winID
= see {any face}
+
  function findwindow(id: winidty; out window: twindow): boolean;
  
- hint
+
  // finds a window by its ID & adjusts "rect" so that it
= descriptive text appearing when mouse pointer enters the widget
+
  // fits "bounds_minc*" & "bounds_maxc*" of the found window
 +
  procedure checkwindowrect(winid: winidty; var rect: rectty);
  
- cursor
+
  // initialises the timer and "megraphics"
= shape of the mouse pointer over the client area of widget (run-time only)
+
  procedure initialize;
  
- visible
+
  // frees the allocated system resources (GDI, event subscription, the timer)
= "true" allow the widget to appear ( run-time only )
+
  procedure deinitialize;
  
- enabled
+
  // creates a form instance, it will be shown in "application.run"
= "true" allows the widget to participate in GUI interaction
+
  procedure createform(instanceclass: widgetclassty; var reference);
= "false" disallows the widget & its childs :
 
* processing all events & shortcuts & menu calls
 
* auto "CanClose" check
 
  
Also "false" usually aints the widget in color marking
+
  // invalidates all registered forms ( all their widgets will be redrawn )
the "disabled" state ( usually light gray font color )
+
  procedure invalidate;
 +
 
 +
  // calls a nested main event loop, forces processing any pending messages,
 +
  procedure processmessages; override; //handle with care!
  
- popupmenu
+
  // TRUE if no pending events to process for the application
= reference to a preset tpopupmenu widget serving the right-click menu
+
  function idle: boolean; override;
 +
 
 +
  // requests to indicate waiting ( to show the "watches" cursors )
 +
  procedure beginwait; override;
  
- taborder
+
  // removes the "watches" if no unclosed requests for displaying them,
- {0..N} order number when TAB-key cycling through widgets in the container
+
  // otherwise closes the currently active request
 +
  procedure endwait; override;
  
- tag
+
  // TRUE if there are unclosed requests for displaying "watches"
- an integer value bound to this widget instance
+
  function waiting: boolean;
  
- helpcontext
+
  // TRUE if ESC has just been pressed
= a string returned by "(active/mouse)helpcontext" methods of the owning form
+
  //  - if all requests for displaying "watches" are closed then refreshes
  when this widget is focued or under mouse in the active window
+
  //   the internal list of events ( the GUI-queue -> the app event list)
 +
  function waitescaped: boolean; //true if escape pressed while waiting
  
- zorder
+
  // sets state of the current wait dialogue ( but doesn't close one ) to undefined
= reading: finds the current Z-order of the widget's window
+
  procedure resetwaitdialog; 
= setting: if the value = 0 then lowers the widget's window in the stacking hierarchy, otherwise rises
 
  
 +
  // runs "aexecuteaction" in the main thread in OnIdle mode,
 +
  // then shows a cancellable message,
 +
  // if the one is cancelled then runs "acancelaction" then
 +
  // either fully clears (if exceptions occur )
 +
  // or terminates the execution otherwise,
 +
  // true if not cancelled;
 +
  // "application.processmessages" must be called regularly if "aexecuteaction" is used here,
 +
  // alternatively "aidleaction" can be used, call sleep ( some time ) in order to minimize
 +
  // processor load.
 +
  // If athread <> nil the function starts and terminates the thread   
 +
  function waitdialog(const athread: tthreadcomp = nil; const atext: msestring = '';
 +
                  const caption: msestring = '';
 +
                  const acancelaction: notifyeventty = nil;
 +
                  const aexecuteaction: notifyeventty = nil): boolean; override;
  
optionswidget:
+
  // closes the currently modal waitdialogue with "cancelled" state
 
+
  procedure cancelwait;
ow_background
 
- keeps the window/widget on bottom of the Z-order stack.
 
 
 
ow_top
 
- keeps the window/widget in foreground
 
  
ow_noautosizing
+
  // closes the currently modal waitdialogue with "ok" state
- when docking, not to resize for the docking area
+
  procedure terminatewait;
  
ow_mousefocus
+
  function waitstarted: boolean;  // the last waitdialogue is currently showing for some requests
- "false" here disables focusing the widget with mouse
+
  function waitcanceled: boolean;  // the last waitdialogue has been cancelled for some request (but can be shown fot others ?)
  ( and "OnFocus" doesn't fire on mouse clicks )
+
  function waitterminated: boolean; // the last waitdialogue has been terminated for some request (but can be shown fot others ?)  
  
ow_tabfocus
+
  // if called from the main app thread then shows as a modal message describing the exception
- "false" here disables focusing the widget with "TAB" key
+
  // otherwise posts an async event for which the message will be called
  ( and "OnFocus" doesn't fire on TAB pressed )
+
  procedure showexception(e: exception; const leadingtext: string = ''); override;
  
ow_parenttabfocus
+
  // posts an async event for which the message describing the exception will be called
- enters the childs on TAB-focusing then returns to the widget after
+
  procedure showasyncexception(e: exception; const leadingtext: string = '');
sequential TAB-ing through its child widgets,
 
otherwise TAB-ing cycles on the childs if entered
 
  
ow_arrowfocus
+
  // "application.errormessage" shows standard error message ( with "ERROR" title )
- allows the widget ( and its childs in turn ) to be focused with
+
  procedure errormessage(const amessage: msestring); override;
the arrow keys
 
  
ow_subfocus, ow_arrowfocusin, ow_arrowfocusout
+
  // [re]calculates timings & position of hint for "ahintedwidget"
- in case of arrow keys focusing enabled for child-containing widget,  
+
  // if "ow_timedhint" in "ahintedwidget.foptionswidget" then iys showtime will be
determine behaviour on entering & leaving the widget, see the below table:
+
  // "defaulthintshowtime" ( an app wide setting, 3sec by default) 
 +
  procedure inithintinfo(var info: hintinfoty; const ahintedwidget: twidget);
  
ow_subfocus | ow_arrowfocusin | ow_arrowfocusout | effect
 
  
  FALSE          FALSE            FALSE        entering-/leaving-
+
  // shows the supplied hint text within "aposrect" with alignment "aplacement" during "ashowtime",
  FALSE          FALSE            TRUE          entering-/leaving+
+
  // the avail ( but not used currenly ) flags are : hfl_show,hfl_custom,hfl_noautohidemove,hfl_noautohidemove 
  FALSE          TRUE              FALSE        entering(nearest)+/leaving-
+
  procedure showhint(const sender: twidget; const hint: msestring;
  FALSE          TRUE              TRUE          entering(nearest)+/leaving+
+
              const aposrect: rectty; const aplacement: captionposty = cp_bottomleft;
  TRUE            FALSE            FALSE        entering(last focused)+/leaving-
+
              const ashowtime: integer = defaulthintshowtime; //0 -> inifinite,
  TRUE            FALSE            TRUE          entering(last focused)+/leaving+
+
                // -1 defaultshowtime if ow_timedhint in sender.optionswidget
  TRUE            TRUE              FALSE        entering(nearest)+/leaving-
+
              const aflags: hintflagsty = defaulthintflags
  TRUE            TRUE              TRUE          entering(nearest)+/leaving+
+
                      ); overload;
  
- "entering" is focusing on a child within the widget
+
  // shows the supplied hint text at left-top position"apos" during "ashowtime",
- "leaving" is return from last child onto the widget's level
+
  // the avail ( but not used currenly ) flags are : hfl_show,hfl_custom,hfl_noautohidemove,hfl_noautohidemove 
- "nearest" is the child closest on the arrow direction
+
  procedure showhint(const sender: twidget; const hint: msestring;
- "last focused" is the child focused on last leaving the widget
+
              const apos: pointty;
+
              const ashowtime: integer = defaulthintshowtime; //0 -> inifinite,
*** The Up/Down arrow keys can leave from the childs circle,  
+
                // -1 defaultshowtime if ow_timedhint in sender.optionswidget
but Left/Right can only toggle between the childs ***
+
              const aflags: hintflagsty = defaulthintflags
 +
                      ); overload;
  
*** mouse entering/leaving isn't controllable by these options
+
  // shows the hint fully defined in "info" for the widget "sender"
 +
  procedure showhint(const sender: twidget; const info: hintinfoty); overload;
  
 +
  // removes the current hint widget & frees its resources & stops its stop timer
 +
  procedure hidehint;
  
ow_focusbackonesc
+
  // restarts the current hint and its stop timer
- on pressing "Esc", returns input focus to the previously focused widget
+
  procedure restarthint(const sender: twidget);
  
ow_noparentshortcut
+
  function hintedwidget: twidget; //last hinted widget
 +
  function activehintedwidget: twidget; //nil if no hint active
  
*** disables processing of delegated ( from the parent ) shortcuts ***
+
  // returns helpcontext of active widget, '' if none; 
 +
  function activehelpcontext: msestring;
  
- "true" here disables processing shortcuts if they're delegated
+
  // returns helpcontext of the widget under mouse, '' if none;
from the parent widget ( obviously, not processed by the parent )
+
  function mousehelpcontext: msestring;
  
ow_nochildshortcut
+
  // TRUE if one of the app's window/console is in input focus
 +
  function active: boolean;
  
*** disables delegating shortcuts to the parent for taking desision ***
+
  // returns the desktop resolution ( or the virtual one if used )
 +
  function screensize: sizety;
  
- if "true" then the widget tries to process it by oneself
+
  // returns the (virtual) desktop resolution except the tray area,
otherwise it's passed to the parent widget for further chaining
+
  // nil -> current active window
 +
  function workarea(const awindow: twindow = nil): rectty;
  
*** A shortcut can only be processed once ( by one widget ) ***
+
  // returns which application window ( a form not an eventwidget, an openglwidget or a windowwidget !)
 +
  // is active ( provides the input focus ),
 +
  // it's same for all widgets of the form served by this window
 +
  function activewindow: twindow;
  
ow_canclosenil
+
/ * A transient window is a descendant of ( "transientfor" ) another window in the stacking order hierarchy */
- "true" here allows to continue even if there's contained widget(s)  
 
not passing "CanClose" check
 
  
ow_mousetransparent
+
  // returns a first non-transient ( on top of the app stacking order ) window upward
- "true" here causes the widget oneself ( not its contained ones )  
+
  // from the currently active window of the application.
not to react to mouse events ( just allow them through to the childs )
+
  // or that active window if no such
 +
  function regularactivewindow: twindow;
  
ow_mousewheel
+
  // same as "activewindow" but the window must not be released (?)
- enables/disables {scrolling/navigating} with wheel of ImPS/2 etc mouse
+
  function unreleasedactivewindow: twindow;
  
ow_noscroll
+
  // returns the focused widget of the currently active window if one exists
- don't use screen image scrolling for twidget.scrollrect,
+
  function activewidget: twidget;
redraw the whole scrolled widget rectangle instead;
 
sometimes needed with background fades.
 
  
ow_nochildpaintclip
+
  // returns the widget presenteing the currently active window
-
+
  function activerootwidget: twidget;
 +
 
 +
  // returns the window ( not hidden or disabled !) under the screen point "pos"
 +
  function windowatpos(const pos: pointty): twindow;
  
ow_destroywidgets
+
  // puts to "awidget" the container of widget pointed by "namepath"
- "true" here causes calling "free" for all containing widgets as well
+
  // ( finalizing "." is discarded if found ) ,
 +
  // FALSE if not found, and NIL and TRUE if "namepath" = ''
 +
  function findwidget(const namepath: string; out awidget: twidget): boolean;
  
ow_hinton
+
  // rebuilds the application's window list accorrding to the current on-screen Z-order of its windows;
- to show the hint even in case of hinting is disabled on the parent
+
  // window list is ordered by "z" - bottom first & top last;
( "parent.ow_hintoff= true & parent.ow_hinton= false" )
+
  // invisibles first
 +
  procedure sortzorder;
  
ow_hintoff
+
  // returns a copy of the internal window list of application
- "true" here combined with "ow_hinton=false" fully disables displaying the hint
+
  function windowar: windowarty;
  
ow_multiplehint
+
  // returns the list of application window winIDs
- "true" here causes the widget to redisplay its hint on each {>3px} move within the widget oneself
+
  function winidar: winidarty;
  
        ow_timedhint
+
  // returns the count of the application windows   
- "true" here causes hint of the widget to disappear after a timed inteval (about 2 secs by default)
+
  function windowcount: integer;
  
ow_fontlineheight (design-time only)
+
  // returns the window by its number ( "index" >= 0) in the application window list
- causes "extraspace" of the last text line to be drawn,
+
  property windows[const index: integer]: twindow read getwindows;
in turn it causes adjustment of widget height if "ow_autoscale" is set
 
 
*** makes sence only if "ow_autoscale=true" & ow_autosize=false & "extraspace <> 0" ***
 
  
ow_fontglyphheight (design-time only)
+
  // returns the lowest visible window in stackorder,
- causes only interline "extraspace"-s to be drawn, opposite to "ow_fontlineheight"  
+
  // calls "sortzorder" within
 +
  function bottomwindow: twindow;
  
ow_autoscale (design-time only)
+
  // returns the highest visible window in stackorder,
- causes that if the contents change (design OR run-time) so that its' height changes
+
  // calls "sortzorder" within
then the widget will be v-scaled as well
+
  function topwindow: twindow;
  
ow_autosize (design-time only)
 
- causes that widget's heigh & width & client area adjust so that to provide space for contents of the client area
 
- no desing-time change of height/width are possible as long as this option is in effect
 
  
ow_autosizeanright
+
  // TRUE if all owned windows pass "CanClose" check or
- when autosizing & {an_right isn't set}, the design-set right margin against the parent is preserved
+
  // don't have focused widgets
 +
  function candefocus: boolean;
  
ow_autosizeanbottom
+
  // subscribes the handler "method" to receive keyboard events
- when autosizing & {an_bottom isn't set}, the design-set bottom margin against the parent is preserved
+
  procedure registeronkeypress(const method: keyeventty);
  
optionsskin:
+
  // unsubscribes the handler "method" from receiving keyboard events
 +
  procedure unregisteronkeypress(const method: keyeventty);
  
- osc_noskin
+
  // subscribes the handler "method" to receive shortcut events
- osc_framebuttononly
+
  procedure registeronshortcut(const method: keyeventty);
- osc_container
 
  
 +
  // unsubscribes the handler "method" from receiving shortcut events
 +
  procedure unregisteronshortcut(const method: keyeventty);
  
Methods:
+
  // subscribes the handler "method" to receive "OnWindowActiveChanged" event ( form-wide )
 +
  procedure registeronactivechanged(const method: activechangeeventty);
  
  // tmsecomponent
+
  // unsubscribes the handler "method" from receiving "OnWindowActiveChanged" event ( form-wide )
 +
  procedure unregisteronactivechanged(const method: activechangeeventty);
  
// (re)draws the widget according to the related skin if apllicable;
+
  // subscribes the handler "method" to receive "OnDestroyed" events ( form-wide )
//
+
  procedure registeronwindowdestroyed(const method: windoweventty);
// also called internally by "loaded" procedure ( before "OnLoaded" code ),
 
// by ShowMessage ( for the internal widgets of the message dialogue ),
 
// when creating tab & form & menu widgets
 
procedure updateskin(const recursive: boolean = false);
 
  
// TRUE if the instance is created but not yet ready
+
  // unsubscribes the handler "method" from receiving "OnDestroyed" events ( form-wide )
// for interaction & accessing data & appearance change & receiving events etc
+
  procedure unregisteronwindowdestroyed(const method: windoweventty);
// ( the stage between firing "OnCreate" & "OnLoaded" )
 
function loading: boolean;
 
 
{$ifdef FPC}
 
procedure setinline(value: boolean); // ?
 
procedure setancestor(value: boolean); // ?
 
{$endif}
 
  
// TRUE if all conditios are OK for executing the code of "event" ( a handler must be assigned to the event )
+
  // subscribes the handler "method" to receive "OnWindowDestroyed" events ( form-wide )
function canevent(const event: tmethod): boolean;
+
  procedure registeronwiniddestroyed(const method: winideventty);
  
 +
  // unsubscribes the handler "method" form receiving "OnWindowDestroyed" events ( form-wide )
 +
  procedure unregisteronwiniddestroyed(const method: winideventty);
  
// Shortly, replaces the persistent storage of the widget
+
  // subscribes the handler "method" to receive "ApplicationActiveChanged" events ( form-wide )
//
+
   procedure registeronapplicationactivechanged(const method: booleaneventty);
// if {value <> nil} then
 
// - if "instance" is nil then calls "createproc" to create the instance,
 
//   then assigns the instance's value:= "value"
 
// otherwise frees "instance"
 
procedure setoptionalobject(const value: tpersistent; var instance;
 
                        createproc: createprocty);
 
  
// creates the persistent storage of the widget via calling "createproc"
+
  // unsubscribes the handler "method" from receiving "ApplicationActiveChanged" events ( form-wide )
procedure getoptionalobject(const instance: tobject; createproc: createprocty);
+
  procedure unregisteronapplicationactivechanged(const method: booleaneventty);
  
// obtains & puts to "obj" a CORBA interface entry for "aintf" (GUID,...)
+
// tcustomapplication
function getcorbainterface(const aintf: ptypeinfo; out obj) : boolean;
 
  
        // TRUE if the widget is owned, or "self" otherwise
+
  // subscribes the handler "method" to receive "OnTerminated" event ( form-wide )
function checkowned(component: tcomponent): boolean;  
+
  procedure registeronterminated(const method: notifyeventty);
  
        // TRUE if the widget is owner, or "self" otherwise
+
  // unsubscribes the handler "method" from receiving "OnTerminated" events ( form-wide )
function checkowner(component: tcomponent): boolean;  
+
  procedure unregisteronterminated(const method: notifyeventty);
  
// return the top-most widget in owner chain starting from this widget
+
  // subscribes the handler "method" to receive "OnTerminateQuery" event ( form-wide )
function rootowner: tcomponent;
+
  procedure registeronterminate(const method: terminatequeryeventty);
  
// return the array of owning widgets starting from this widget
+
  // unsubscribes the handler "method" from receiving "OnTerminateQuery" event ( form-wide )
// componentarty[0] is the widget oneself
+
  procedure unregisteronterminate(const method: terminatequeryeventty);
function getrootcomponentpath: componentarty;
 
  
        // returns items of objeclinker ( which notify this widget )
+
  // subscribes the handler "method" to receive "OnIdle" event ( form-wide )
        // and free notify list ( which are notified by this widget ),
+
  procedure registeronidle(const method: idleeventty);
        // duplicates are removed.
 
        //
 
        // Notifies mainly relate to insertion/removal operation on widgets
 
        // The notify list is maintained by FreeNotification & RemoveFreeNotification
 
function linkedobjects: objectarty;
 
  
// sends "event" recursively to child widgets until no more childs or
+
  // unsubscribes the handler "method" from receiving "OnIdle" events ( form-wide )
// the event is processed ( cea_processed ) by one of the childs,
+
  procedure unregisteronidle(const method: idleeventty);
// "event" will be destroyed if destroyevent= true and not async
 
procedure sendcomponentevent(const event: tcomponentevent;
 
                                        const destroyevent: boolean = true);
 
  
// sends "event" to each of owning widgets downward from the root owner,
+
  // calls "canclose" of all application windows except the "sender" window
// "event" will be destroyed if destroyevent= true and not async
+
  // if all "canclose"are TRUE then checks "OnTerminateQuery"  
procedure sendrootcomponentevent(const event: tcomponentevent;
+
  // for all its subscribers ( usually forms of the application )
                                        const destroyevent: boolean = true);
+
  procedure terminate(const sender: twindow = nil);  
  
// posts an async "atag"-ged event to be handled by oneself
+
  // TRUE as long as a "terminate" call is in progress
procedure asyncevent(atag: integer = 0);
+
  function terminating: boolean;
  
// posts a "tcomponentevent" instance from sender=self,
+
  // TRUE as long as a "deinitialize" call is in progress
// "kind" is defined when creating the event,
+
  function deinitializing: boolean;
// and "tag" may be adjusted after creation
+
 
procedure postcomponentevent(const event: tcomponentevent);
+
  // returns the current caret object ( the text input focus indicator ) of the application
 +
  / ( this object provides facilities to control position & appearance & visibility & timings of the caret )
 +
  property caret: tcaret read fcaret;
  
// returns the classname of the widget if the widget is toplevel,
+
  // returns the current mouse object of the application
// and "tmsecomponent" otherwise )
+
  / ( this object provides facitities to control position & appearance of the mouse )  
property moduleclassname: string read getmoduleclassname;
+
  property mouse: tmouse read fmouse;
  
// returns the classname of the widget as the entry of its constructor
+
  // simulates mouseparkevent
// ( button => tbutton, datamodule => tdm1mo, form => ttstfo, dbstringedit => tdbstringedit,.. )
+
  // ( an adjusting mouse movement without user intervention - grid snapping, docking etc ?)
property actualclassname: string read getactualclassname;
+
  procedure mouseparkevent;
  
// returns "fmsecomponentstate"
+
  // sets mouse position correction for further mouse events,
// ( a set of cs_ismodule,cs_endreadproc,cs_loadedproc,cs_noload, cs_hasskin,cs_noskin )
+
  // the real position is less the visual one by the supplied shift
property msecomponentstate: msecomponentstatesty read fmsecomponentstate;
+
  procedure delayedmouseshift(const ashift: pointty);
  
// returns/sets a pointer associated with the widget
+
  // returns/sets a cursor shape used for widgets having their cursor shape set to "cr_default";
// ( contrary to the integer "tag", allows to use an arbitary data type
+
  // setting it to "cr_default" restores the individual widget cursor(s)
// for associating data )
+
  property widgetcursorshape: cursorshapety read fwidgetcursorshape write
property tagpo: pointer read ftagpo write ftagpo;
+
                                        fwidgetcursorshape;
  
// returns/sets a string identifying the widget in the help system
+
  // returns/sets the current application-wide cursor shape ( not "watches" if a waiting dialog is currently displayed ! )
property helpcontext: msestring read gethelpcontext write fhelpcontext;
+
  // or request to set a new cursor shape ( app-wide );
 +
  // doesn't change when changing mouse widgets
 +
  //
 +
  // if called from a non-main app thread & no waiting dialogue displayed then redraws
 +
  // the cursor immediately;
 +
  // set it to "cr_default" to restore the shape to one set by "widgetcursorshape"
 +
  //
 +
  property cursorshape: cursorshapety; // cr_arrow, cr_*
  
// twidget
+
  // assures the displayed mouse cursor shape to be the shape assigned to the currently under-mouse widget,
 +
  // otherwise "cr_default"
 +
  procedure updatecursorshape; //restores cursorshape of mousewidget
  
// creates an instance of the widget, owned by "aowner" if not NIL
+
  // returns a widget of the application where the mouse is currently positioned over
constructor create(aowner: tcomponent); override;
+
  property mousewidget: twidget read fmousewidget;
  
destructor destroy; override;
+
  // returns a widget of the application currently "owning" the mouse ( grabbing all mouse input )
 +
  property mousecapturewidget: twidget read fmousecapturewidget;
  
// ??
 
procedure afterconstruction; override;
 
  
// rescales the widget frame ( if assigned ) then owned widgets ( if exist, recursively ) then bounds_* then the font ( if assigned )
+
  // returns/sets a window to become the main window of the application
// called before inserting in parentwidget,
+
  // then resets all other application windows to the window group it belongs to ( Linux only );
// calls "scale(ascale)",
+
  //
// no visual repainting
+
  // the main window minimizes all windows if minimized;
procedure initnewcomponent(const ascale: real); virtual;
+
  property mainwindow: twindow read fmainwindow write setmainwindow;
  
// restores the "fontheight" to "font.glyphheight" if "ow_fontglyphheight" or
+
  // returns which system thread was allocated to the application on its start
// to "font.lineheight" if "ow_fontlineheight" otherwise,
+
  // ( the main thread )
// ascale is ignored ?
+
  property thread: threadty read fthread;
// calls "synctofontheight->setfontheight",
+
 
// called after inserting in parentwidget,
+
  // returns teh widget where a mouse button click occured last time
// no visual repainting
+
  // ( to compare with when determinibg whether another widget is clicked )
procedure initnewwidget(const ascale: real); virtual;
+
  property buttonpresswidgetbefore: twidget read fbuttonpresswidgetbefore;
 +
 
 +
  // returns teh widget where a mouse button release occured last time
 +
  // ( to compare with when determinibg whether another widget is clicked )
 +
  property buttonreleasewidgetbefore: twidget read fbuttonreleasewidgetbefore;
  
// creates the widget frame if not yet created
 
procedure createframe;
 
  
// creates the widget face if not yet  created
+
  // returns/sets the interval of mouse double click recognition ( in microsecs ),
procedure createface;
+
  // defaults to 0.4 sec
 +
  property dblclicktime: integer read fdblclicktime write fdblclicktime default
 +
                defaultdblclicktime; //us
  
// creates the widget font if not yet  created
+
// tcustomapplication
procedure createfont;
 
  
// checks ws_loadlock and csdestroing too
+
  // creates a datamodule instance ( its startup code including "OnLoaded" is executed )
function isloading: boolean;
+
  procedure createdatamodule(instanceclass: msecomponentclassty; var reference);
  
// returns "widgetstatety" - a set of (
 
// ws_visible,ws_enabled,ws_active,ws_entered,ws_entering,ws_exiting,
 
// ws_focused,ws_mouseinclient,ws_wantmousebutton,ws_wantmousemove,
 
// ws_wantmousefocus,ws_iswidget,ws_opaque,ws_nopaint,
 
// ws_clicked,ws_mousecaptured,ws_clientmousecaptured,
 
// ws_loadlock,ws_loadedproc,ws_showproc,ws_minclientsizevalid,
 
// ws_showed,ws_hidden, //used in tcustomeventwidget
 
// ws_destroying,ws_staticframe,ws_staticface,ws_isvisible
 
//
 
// iframe
 
function widgetstate: widgetstatesty;
 
  
// returns "widgetstate1ty" - a set of (
+
  // enters the application event loop;
// (ws1_childscaled,ws1_fontheightlock,
+
  //
// ws1_widgetregionvalid,ws1_rootvalid,
+
  // once the loop finishes, performs "OnTerminated" for all its subscribers,
// ws1_anchorsizing,ws1_isstreamed,
+
  // destroys all application forms ( components & windows )
// ws1_scaled, //used in tcustomscalingwidget
+
  procedure run;
// ws1_noclipchildren,
 
// ws1_nodesignvisible,ws1_nodesignframe,ws1_nodesignhandles,
 
// ws1_nodesigndelete,ws1_designactive,
 
// ws1_fakevisible,ws1_nominsize //used for report size calculations
 
// )
 
property widgetstate1: widgetstates1ty read fwidgetstate1;
 
 
* this set of states is needed because the max FPC set size is 32
 
  thus "widgetstate1ty" can't fit all states
 
  
// TRUE if the widget is contained within another widget
+
  // TRUE if the eventloop is entered
// ( tcomponent stuff )
+
  function running: boolean;
function hasparent: boolean; override;             
 
  
// returns the parent component if it's a widget or the grandparent otherwise
+
  // returns/sets the application name
function getparentcomponent: tcomponent; override;  //tcomponent
+
  // ( defaults to the full path to application executable in the native OS format );
 
+
  // currently, only for informatiion query purposes
// TRUE if "awidget" is an ascendant or the widget or they are the same widget
+
  property applicationname: msestring read fapplicationname write fapplicationname;
function checkdescendent(awidget: twidget): boolean;
+
 
+
 
// TRUE if app is running and the widget owns the caret or the caret widget
+
  // if exclusive "rights" are satisfied for the main thread ( a mutex lock is OK ) & the event loop is in progress
function hascaret: boolean;
+
  // then posts the "event" to the main application thread for asyc processing,
 +
  // otherwise adds the event to the internal list for further handling as soon as the above conditions meet
 +
  procedure postevent(event: tevent);
  
        // TRUE if "winid" allocated and not loading and not destroying,
+
  // TRUE if never idle since last call,
        // all widgets on a form have "winid" of this form ( a real window allocated by the OS )
+
  // unlocks the application and calls sleep if not mainthread and asleepus >= 0
        // thus have this function TRUE
+
  function checkoverload(const asleepus: integer = 100000): boolean;
function windowallocated: boolean;
 
  
// TRUE if presents a valid toplevelwindow with assigned "winid"
+
  // returns/sets the application exception handler
function ownswindow: boolean;
+
  property onexception: exceptioneventty read fonexception write fonexception;
  
// invalidated area of the widget, the origin is "clientpos" against the roor widget
+
  // if not "eabort" & no unhandled exceptions,  
function updaterect: rectty;  
+
  // executes the above "OnException" code if assigned
 +
  // or shows an exception message otherwise;
 +
  procedure handleexception(sender: tobject = nil;
 +
                                      const leadingtext: string = '');
  
// calls recursively "canclose" for all contained widgets ( the widget oneself excluded! ),
+
  // synchronizes the calling thread with the main event loop ( via a mutex),
// TRUE if none of the widgets return FALSE
+
  // TRUE if the calling thread allready holds the mutex,
//
+
  // the mutex is recursive
// more specialized widgets may have "canclose" overridden
+
  function lock: boolean;
// to perform more work than just this call recursion
 
// ( not null or range check,.. )
 
//
 
// "onclosequery" must also pass the check if assigned, for the function to succeed
 
function canclose(const newfocus: twidget = nil): boolean; virtual;
 
  
        // checks "canclose" first for focused widget of the window ( form,.. )
+
  // tries to synchronize the calling thread with the main event loop ( via a mutex)
        // if it is a descendant of the widget or the widget oneself,
+
  function trylock: boolean;
        // then continues with subwidgets of the widget;
 
        // also - finishes editing ( snapshots "value" ) in the focused widget before checking
 
function canparentclose(const newfocus: twidget): boolean; overload;
 
  
// the above function but with the preserved focus
+
  // releases the mutex if the calling thread holds the mutex,
function canparentclose: boolean; overload;
+
  // TRUE if no unlock done
                  //newfocus = window.focusedwidget     
+
  function unlock: boolean;
  
function canfocus: boolean; virtual;
+
  // releases the mutex recursively if the calling thread holds the mutex,
function setfocus(aactivate: boolean = true): boolean; virtual;//true if ok
+
  // returns "count" for the below "relockall"
procedure nextfocus; //sets inputfocus to then next appropriate widget
+
  function unlockall: integer;
  
function findtabfocus(const ataborder: integer): twidget;
+
  // regains the mutex to serve "count" locks
                      //nil if can not focus
+
  procedure relockall(count: integer);
  
function firsttabfocus: twidget;
+
  // 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,
function lasttabfocus: twidget;
+
  // then frees all locks temporarily then posts the event to the app event queue & waits fot it to be processed the resores the locks;
function nexttaborder(const down: boolean = false): twidget;
+
  //
 +
  // TRUE if not aborted, quiet -> shows no exceptions if occurs
 +
  //
 +
  // the "syncronize event" is an event owning a semaphore which can be touched by another thread
 +
  // thus causing "event.waitfo" to return & to exec the event handler code
 +
  //
 +
  function synchronize(const proc: objectprocty;
 +
                      const quite: boolean = false): boolean;
  
function focusback(const aactivate: boolean = true): boolean;
+
  // TRUE if the calling ( this function ) thread is the application main thread
                              //false if focus not changed
+
  function ismainthread: boolean;
  
function parentcolor: colorty;
+
  // TRUE if the currently locked thread is the application main thread
function actualcolor: colorty; virtual;
+
  function islockthread: boolean;
function actualopaquecolor: colorty;
 
function backgroundcolor: colorty;
 
function translatecolor(const acolor: colorty): colorty;
 
  
procedure widgetevent(const event: twidgetevent); virtual;
+
  // waith for "athread" to terminate,
 +
  // does "unlock-relock" around waiting
 +
  procedure waitforthread(athread: tmsethread);
  
procedure sendwidgetevent(const event: twidgetevent);
+
  // post a "nothing-to-do" event for asynchronous processing in the main thread
                              //event will be destroyed
+
  procedure wakeupmainthread;
  
procedure release; override;
+
  // invalidates all registered forms of the application so that their widgets redraw land-specific captions
 +
  // ( changed by "mseconsts.setlangconsts" ),
 +
  // called internally in "setlangconsts" before return
 +
  procedure langchanged; virtual;
  
function show(const modal: boolean = false; const transientfor: twindow = nil): modalresultty; virtual;
+
  // returns/sets "aps_terminated" state flag ( no actions ? )
 +
  // this flag is also set internally by "terminate" if not cancelled
 +
  property terminated: boolean read getterminated write setterminated;
  
procedure hide;
+
  // returns the number of "handleexception" calls having an effect ( a message or the handler code )
procedure activate(const abringtofront: boolean = true); virtual;
+
  property exceptioncount: longword read fexceptioncount;
                            //show and setfocus
 
  
procedure bringtofront;
 
procedure sendtoback;
 
procedure stackunder(const predecessor: twidget);
 
  
procedure paint(const canvas: tcanvas); virtual;
+
private
procedure update; virtual;
+
// function tinternalapplication.beginmodal(const sender: twindow): boolean;
procedure scrollwidgets(const dist: pointty);
 
  
procedure scrollrect(const dist: pointty; const rect: rectty; scrollcaret: boolean);
+
</pre>
                            //origin = paintrect.pos
 
  
procedure scroll(const dist: pointty);
+
== DB ==
                            //scrolls paintrect and widgets
 
  
procedure getcaret;
+
=== DBedit ===
procedure scrollcaret(const dist: pointty);
+
=== DBfields ===
function mousecaptured: boolean;
+
=== TDBwidgetgrid ===
procedure capturemouse(grab: boolean = true);
+
<pre>
procedure releasemouse;
+
  Properties:
procedure capturekeyboard;
 
procedure releasekeyboard;
 
procedure synctofontheight; virtual;
 
  
procedure dragevent(var info: draginfoty); virtual;
+
        anchors - ...
procedure dochildscaled(const sender: twidget); virtual;
+
bounds - ...
  
procedure invalidatewidget;    //invalidates whole widget
+
color
procedure invalidate;          //invalidates clientrect
+
- color of the grid's client area
procedure invalidaterect(const rect: rectty; org: originty = org_client);
+
cursor
procedure invalidateframestate;
+
- cursor shape when the mouse is over the client area
  
procedure invalidateframestaterect(const rect: rectty;
+
datacols
                                        const org: originty = org_client); 
+
colorselect
function hasoverlappingsiblings(arect: rectty): boolean; //origin = pos
+
linecolor
 +
linecolorfix
 +
linewidth
 +
newrowcol
  
function window: twindow;
+
options
function rootwidget: twidget;
+
co_readonly
 
+
co_nofocus
function parentofcontainer: twidget;
+
co_invisible
            //parentwidget.parentwidget if parentwidget has not ws_iswidget,
+
co_disabled
            //parentwidget otherwise
+
co_drawfocus
 
+
co_mousemovefocus
property parentwidget: twidget read fparentwidget write setparentwidget;
+
co_lefbuttonfocusonly
function getrootwidgetpath: widgetarty; //root widget is last
+
co_focusselect
 
+
co_mouseselect
// number of contained widgets ( the widget oneself excluded ! )
+
co_keyselect
function widgetcount: integer;
+
co_multiselect
 +
co_resetselectionexit
 +
co_rowselect
 +
co_fixwidth
 +
co_fixpos
 +
co_fill
 +
co_proportional
 +
co_nohscroll
 +
co_savevalue
 +
co_savestate
 +
co_rowfont
 +
co_rowcolor
 +
co_zebracolor
 +
co_nosort
 +
co_sortdescent
 +
co_norearrange
 +
co_cancopy
 +
co_canpaste
 +
co_mousescrollrow
 +
co_rowdatachange
  
function parentwidgetindex: integer; //index in parentwidget.widgets, -1 if none
+
sortcol
property widgets[const index: integer]: twidget read getwidgets;
+
width
function widgetatpos(var info: widgetatposinfoty): twidget; overload;
 
function widgetatpos(const pos: pointty): twidget; overload;
 
  
function widgetatpos(const pos: pointty;
+
items[N]
                  const state: widgetstatesty): twidget; overload;
+
color
 
+
colorselect
property taborderedwidgets: widgetarty read gettaborderedwidgets;
+
datalist - ???
 +
face - see <any face>
 +
fontselect - see <any font>
 +
frame - see <any frame>
 +
linecolor
 +
linecolorfix
 +
linewidth
 +
name
 +
 +
options
 +
 +
</pre>
  
function findtagwidget(const atag: integer; const aclass: widgetclassty): twidget;
+
=== Report ===
              //returns first matching descendent
 
  
property container: twidget read getcontainer;
+
==== TRepSpacer ====
function containeroffset: pointty;
+
==== TRecordBand ====
function childrencount: integer; virtual;
+
==== TrepValueDisp ====
property children[const index: integer]: twidget read getchildwidgets; default;
+
==== TRepPageNumdisp ====
 +
==== TRepPrintDateDisp ====
 +
==== TBandGroup ====
 +
==== TTileArea ====
  
function childatpos(const pos: pointty;
+
== Design ==
                  const clientorigin: boolean = true): twidget; virtual;
 
  
function getsortxchildren: widgetarty;
+
=== TGdbMi ===
function getsortychildren: widgetarty;
+
=== TSyntaxEdit ===
property focusedchild: twidget read ffocusedchild;
+
=== TSyntaxPainter ===
property focusedchildbefore: twidget read ffocusedchildbefore;
 
  
function mouseeventwidget(const info: mouseeventinfoty): twidget;
+
== Comm ==
  
function checkdescendent(widget: twidget): boolean;
+
=== TCommPort ===
                    //true if widget is descendent or self
+
=== TAsciiCommPort ===
 +
=== TAsciiProtPort ===
 +
=== TCommSelector ===
  
function checkancestor(widget: twidget): boolean;
+
== General stuff==
                    //true if widget is ancestor or self
 
  
function containswidget(awidget: twidget): boolean;
+
=== Properties for all widgets ===
 +
<pre>
  
procedure insertwidget(const awidget: twidget); overload;
+
name
  
procedure insertwidget(const awidget: twidget; const apos: pointty); overload; virtual;
+
anchors
                //widget can be child
 
  
function iswidgetclick(const info: mouseeventinfoty; const caption: boolean = false): boolean;
+
-----------
//true if eventtype = et_butonrelease, button is mb_left, clicked and pos in clientrect
 
//or in frame.caption if caption = true, origin = pos
 
  
function isclick(const info: mouseeventinfoty): boolean;
+
- they control of design/runtime sticking widgets to their parents
//true if eventtype = et_butonrelease, button is mb_left, clicked and pos in clientrect
 
  
function isdblclick(const info: mouseeventinfoty): boolean;
+
- dimention pair ( top/bottom or left/right ) both set to "false" cause
//true if eventtype = et_butonpress, button is mb_left, pos in clientrect
+
the widget to fit the parent's client area in that dimention;
// and timedlay to last buttonpress is short
+
this effect may be partial in case of "bounds_c*max" settings limit the extents
  
function isdblclicked(const info: mouseeventinfoty): boolean;
+
*** Return to the look "before dimention fit" is only possible by manual resizing or setting "bounds_*"
//true if eventtype in [et_buttonpress,et_butonrelease], button is mb_left,
+
-----------
// and timedlay to last same buttonevent is short
+
an_left
 +
- on run-time, resizes/shifts left the widget to keep the design-set distance
 +
between the widget's left border and the left side of parent's client area
 +
as the parent resizes, until scrolling begins
  
function isleftbuttondown(const info: mouseeventinfoty): boolean;
+
an_top
//true if eventtype = et_butonpress, button is mb_left, pos in clientrect
+
- on run-time, resizes/shifts up the widget to keep the design-set distance
//origin = paintrect.pos
+
between the widget's top border and the upper side of parent's client area
 +
as the parent resizes, until scrolling begins
  
widgetrect: the widget on-screen area including its frame & frame caption
+
an_right
 +
- on run-time, resizes/shifts right the widget to keep the design-set distance
 +
between the widget's right border and the right side of parent's client area  
 +
as the parent resizes, until scrolling begins
  
paintrect: the widget on-screen area except its frame & frame caption
+
an_bottom
 +
- on run-time, resizes/shifts down the widget to keep the design-set distance
 +
between the widget's bottom border and the lower side of parent's client area  
 +
as the parent resizes, until scrolling begins
  
clientrect: virtual area which
+
bounds
- for non-scrolling widgets, equals to "paintrect", with its "pos:= (0,0)"
 
- for scrolling widgets, may be bigger than "paintrect",
 
  also may shift ( change its "pos" ) when scrolling
 
 
// the coord of outer top-left corner against the toplevel form = the window owner,
 
// including the frame & frame caption
 
function rootpos: pointty;
 
  
// the coord of the outer top-left corner against the screen ( the WM decorations aren't counted in )
+
cx - width of the widget
// includes the frame & frame caption
+
cxmax, cxmin - design/runtime width of the widget is enforced between "cxmax" and "cxmin"
property screenpos: pointty;
+
cy - height of the widget
 +
cymax, cymin - design/runtime height of the widget is enforced between "cymax" and "cymin"
 +
x - distance between the widget's left border and the left side of parent's client area
 +
y - distance between the widget's top border and the upper side of parent's client area
  
//  the coord of the outer top-left corner against the parent widget,
 
// including the frame & frame caption
 
property widgetrect: rectty;
 
property pos: pointty; // =widgetrect.pos
 
property size: sizety; // =widgetrect.size
 
property left: integer; // =bounds_x
 
property right: integer; //widgetrect.x + widgetrect.cx, sets cx;
 
property top: integer;  // =bounds_y
 
property bottom: integer; //widgetrect.y + widgetrect.cy, sets cy;
 
property width: integer; // =bounds_cx
 
property height: integer; // =bounds_cy
 
function widgetsizerect: rectty;          //pos = nullpoint
 
  
    // the coord of the paint area ( paintrect ) against own outer top-left corner ( against "widgetrect=pos" )
+
autosize
    //  except the frame & frame caption
 
function paintrect: rectty;
 
function paintpos: pointty;
 
function paintsize: sizety;
 
function innerpaintrect: rectty; // mainly equals to paintrect
 
function clientwidgetrect: rectty; // mainly equals to paintrect
 
function clientwidgetpos: pointty;
 
function clippedpaintrect: rectty; // mainly equals to  but clipped by all parentpaintrects
 
function innerwidgetrect: rectty;    // mainly equals to paintrect
 
function innerclientwidgetpos: pointty;
 
  
    // the coord of the paint area ( paintrect ) against own outer top-left corner ( against "widgetrect=pos" )
+
-----------
    //  except the frame caption
+
- only applicable to widgets with "ow_autosize" set
function framerect: rectty; // =paintrect except the frame caption area
+
- the effect may be partial in case when "bounds_c*max" settings limit the extents
function framepos: pointty;
+
-----------
function framesize: sizety;
 
  
    // the coord of the client area ( clientrect ) against the paint area ( paintrect )
+
cx - addition to width of the widget (with h-centering post applied)
    //  usually these areas match
+
cy - addition to height of the widget (with v-centering post applied)
function clientrect: rectty;
 
property clientsize: sizety;
 
property clientwidth: integer;
 
property clientheight: integer;
 
property clientpos: pointty;
 
  
    // the coord of the paint area of the parent against the paint area of this widget
+
- color
function paintrectparent: rectty; //nullrect if parent = nil,
+
= the default color of client area & caption text background
 +
= may be overwritten:
 +
* the client area - with "frame.colorclient"
 +
* the caption BG - with "frame.font.colorbackground"
  
    // the coord of the client area of the parent against the paint area of this widget
+
- font
function clientrectparent: rectty; //nullrect if parent = nil,
+
= see {any font}
  
// the coord of the inner area against the client area ( clientrect )
+
- frame
function innerclientrect: rectty;  // mainly equals to clientrect
+
= see {any frame}
function innerclientsize: sizety;
 
function innerclientpos: pointty;
 
  
function framewidth: sizety;              //widgetrect.size - paintrect.size
+
- face
function clientframewidth: sizety;        //widgetrect.size - clientrect.size
+
= see {any face}
function innerclientframewidth: sizety;  //widgetrect.size - innerclientrect.size
 
function innerframewidth: sizety;        //clientrect.size - innerclientrect.size 
 
  
    // the coord of the paint area against the widgetrect(pos) of the parent
+
- hint
function paintparentpos: pointty;    //origin = parentwidget.pos
+
= descriptive text appearing when mouse pointer enters the widget
  
    // the coord of the client area against the widgetrect(pos) of the parent
+
- cursor
function clientparentpos: pointty;  //origin = parentwidget.pos
+
= shape of the mouse pointer over the client area of widget (run-time only)
  
    // the coord of the widgetrect(pos) against the client area of parent
+
- visible
property parentclientpos: pointty;
+
= "true" allow the widget to appear ( run-time only )
  
 +
- enabled
 +
= "true" allows the widget to participate in GUI interaction
 +
= "false" disallows the widget & its children :
 +
* processing all events & shortcuts & menu calls
 +
* auto "CanClose" check
  
function clientpostowidgetpos(const apos: pointty): pointty;
+
Also "false" usually paints the widget in color marking
function widgetpostoclientpos(const apos: pointty): pointty;
+
the "disabled" state ( usually light gray font color )
function widgetpostopaintpos(const apos: pointty): pointty;
 
function paintpostowidgetpos(const apos: pointty): pointty;
 
procedure scale(const ascale: real); virtual;
 
  
 +
- popupmenu
 +
= reference to a preset tpopupmenu widget serving the right-click menu
  
property minsize: sizety read fminsize write setminsize;
+
- taborder
property maxsize: sizety read fmaxsize write setmaxsize;
+
- {0..N} order number when TAB-key cycling through widgets in the container
function maxclientsize: sizety; virtual;
 
  
 +
- tag
 +
- an integer value bound to this widget instance
  
property anchors: anchorsty read fanchors write setanchors default defaultanchors;
+
- helpcontext
property defaultfocuschild: twidget read getdefaultfocuschild write setdefaultfocuschild;
+
= a string returned by "(active/mouse)helpcontext" methods of the owning form
 +
  when this widget is focused or under mouse in the active window
  
 +
- zorder
 +
= reading: finds the current Z-order of the widget's window
 +
= setting: if the value = 0 then lowers the widget's window in the stacking hierarchy, otherwise rises
  
procedure changeclientsize(const delta: sizety); //asynchronous
 
  
function getcanvas(aorigin: originty = org_client): tcanvas;
+
optionswidget:
  
function showing: boolean;
+
ow_background
              //true if self and all ancestors visible and window allocated
+
- keeps the window/widget on bottom of the Z-order stack.
 +
 
 +
ow_top
 +
- keeps the window/widget in foreground
  
function isenabled: boolean;
+
ow_noautosizing
              //true if self and all ancestors enabled
+
- when docking, not to resize for the docking area
  
function active: boolean;
+
ow_mousefocus
function entered: boolean;
+
- "false" here disables focusing the widget with mouse
 +
  ( and "OnFocus" doesn't fire on mouse clicks )
  
function activeentered: boolean;
+
ow_tabfocus
//true if entered and window is regularactivewindow or inactivated
+
- "false" here disables focusing the widget with "TAB" key
 +
  ( and "OnFocus" doesn't fire on TAB pressed )
  
function focused: boolean;
+
ow_parenttabfocus
function clicked: boolean;
+
- enters the childs on TAB-focusing then returns to the widget after
 +
sequential TAB-ing through its child widgets,
 +
otherwise TAB-ing cycles on the children if entered
  
function indexofwidget(const awidget: twidget): integer;
+
ow_arrowfocus
 +
- allows the widget ( and its children in turn ) to be focused with
 +
the arrow keys
  
procedure changedirection(const avalue: graphicdirectionty;
+
ow_subfocus, ow_arrowfocusin, ow_arrowfocusout
                                            var dest: graphicdirectionty); virtual;
+
- in case of arrow keys focusing enabled for child-containing widget,
 +
determine behaviour on entering & leaving the widget, see the below table:
  
// (re)arranges "awidgets" horizontally within the parent's client area
+
ow_subfocus | ow_arrowfocusin | ow_arrowfocusout | effect
// so that awidget[i] were placed next each other
+
 
// at h-space dist[i], starting from "startx" with the right margin "endmargin";
+
  FALSE          FALSE            FALSE        entering-/leaving-
//  
+
  FALSE          FALSE            TRUE          entering-/leaving+
// if the number of "dist" is fewer than the number of "awidgets" then the remaining h-spaces are taken
+
  FALSE          TRUE              FALSE        entering(nearest)+/leaving-
// as the last "dist[i]" or "0" if none;
+
  FALSE          TRUE              TRUE          entering(nearest)+/leaving+
// if the number of "dist" is more than the number of "awidgets" then the extra dist[i] are discarded
+
  TRUE            FALSE            FALSE        entering(last focused)+/leaving-
//
+
  TRUE            FALSE            TRUE          entering(last focused)+/leaving+
// non-zero "endmargin" causes one of awdidget[i] to h-resize to provide the margin :
+
  TRUE            TRUE              FALSE        entering(nearest)+/leaving-
// - if one or more of awidgets[i] have [an_left,an_right] set then the first of such is resized
+
  TRUE            TRUE              TRUE          entering(nearest)+/leaving+
//    otherwise the last awidgets[i] is h-resized
+
 
//  
+
- "entering" is focusing on a child within the widget
procedure placexorder(
+
- "leaving" is return from last child onto the widget's level
const startx: integer;
+
- "nearest" is the child closest on the arrow direction
const dist: array of integer;
+
- "last focused" is the child focused on last leaving the widget
                const awidgets: array of twidget;
+
   
                const endmargin: integer = minint);
+
*** The Up/Down arrow keys can leave from the children circle,
 +
but Left/Right can only toggle between the children ***
 +
 
 +
*** mouse entering/leaving isn't controllable by these options
  
// (re)arranges "awidgets" vertically within the parent's client area
 
// so that awidget[i] were placed upper/lower each other
 
// at v-space dist[i], starting from "starty" with the bottom margin "endmargin";
 
//
 
// if the number of "dist" is fewer than the number of "awidgets" then the remaining v-spaces are taken
 
// as the last "dist[i]" or "0" if none;
 
// if the number of "dist" is more than the number of "awidgets" then the extra dist[i] are discarded
 
//
 
// non-zero "endmargin" causes one of awdidget[i] to v-resize to provide the margin :
 
//  - if one or more of awidgets[i] have [an_top,an_bottom] set then the first of such is resized
 
//    otherwise the last awidgets[i] is v-resized
 
//
 
procedure placeyorder(
 
const starty: integer;
 
const dist: array of integer;
 
                const awidgets: array of twidget;
 
                const endmargin: integer = minint);
 
              //origin = clientpos, endmargin by size adjust of widgets
 
              //with [an_top,an_bottom], minint -> no change
 
  
// if {mode <> wam_none} then (re)arranges "awidgets" horizontally  within the parent's client area so that
+
ow_focusbackonesc
// awidgets[0] stays on its place but awidgets[1..N] :
+
- on pressing "Esc", returns input focus to the previously focused widget
// - 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]
 
// - 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]
 
// - if {mode = wam_center} then awidgets[i>=1] move so that they Y-axes match the Y-axe of awidgets[0]
 
//
 
// mainly applicable for v-stacked widgets since h-stacked may overlap after such alignment
 
//
 
        // returns the reference point ( the coord of awidgets[0] )
 
function alignx(const mode: widgetalignmodety;
 
                        const awidgets: array of twidget): integer;
 
  
 +
ow_noparentshortcut
  
// if {mode <> wam_none} then (re)arranges "awidgets" vertically within the parent's client area so that
+
*** disables processing of delegated ( from the parent ) shortcuts ***
// awidgets[0] stays on its place but awidgets[1..N] :
 
// - 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]
 
// - 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]
 
// - if {mode = wam_center} then awidgets[i>=1] move so that they X-axes match the X-axe of awidgets[0]
 
//
 
// mainly applicable for h-stacked widgets since v-stacked may overlap after such alignment
 
//
 
        // returns the reference point ( the coord of awidgets[0] )
 
function aligny(const mode: widgetalignmodety;
 
                        const awidgets: array of twidget): integer;
 
  
function actualcursor: cursorshapety; virtual;
+
- "true" here disables processing shortcuts if they're delegated
 +
from the parent widget ( obviously, not processed by the parent )
  
 +
ow_nochildshortcut
  
Event handlers:
+
*** disables delegating shortcuts to the parent for taking decision ***
  
- onactivate
+
- if "true" then the widget tries to process it by oneself
 +
otherwise it's passed to the parent widget for further chaining
  
fires :
+
*** A shortcut can only be processed once ( by one widget ) ***
  
= on receiving input focus, just before "OnFocus"
+
ow_canclosenil
+
- "true" here allows to continue even if there's contained widget(s)  
= forms specific :
+
not passing "CanClose" check
* on 1-st display of the form after "OnLoaded" ( from "Loaded" procedure)
 
* on switch back from another apllication/WM ( "oe_activate" event )
 
* after closure of a descendant form
 
* on minimizing/maximizing the form
 
  
- onchildscaled
+
ow_mousetransparent
 +
- "true" here causes the widget oneself ( not its contained ones )
 +
not to react to mouse events ( just allow them through to the children )
  
fires :
+
ow_mousewheel
 +
- enables/disables {scrolling/navigating} with wheel of ImPS/2 etc mouse
  
= on child(s) resizing due to font height change
+
ow_noscroll
 +
- don't use screen image scrolling for twidget.scrollrect,
 +
redraw the whole scrolled widget rectangle instead;
 +
sometimes needed with background fades.
  
= form widget: once "form.container" {scrolling widget} is loaded
+
ow_nochildpaintclip
 +
-
  
- ondeactivate
+
ow_destroywidgets
fires
+
- "true" here causes calling "free" for all containing widgets as well
= form widget: when the form looses input focus
 
= non-form widget: when the widget looses input focus
 
  
- ondefocus
+
ow_hinton
 +
- to show the hint even in case of hinting is disabled on the parent
 +
( "parent.ow_hintoff= true & parent.ow_hinton= false" )
  
fires
+
ow_hintoff
= on disabling the widget
+
- "true" here combined with "ow_hinton=false" fully disables displaying the hint
  
= form widget: if another form is focused
+
ow_multiplehint
= non-form widget: if another widget is focused
+
- "true" here causes the widget to redisplay its hint on each {>3px} move within the widget oneself
  
- onenter
+
        ow_timedhint
= fires on any way of taking parent-wide focus as soon as
+
- "true" here causes hint of the widget to disappear after a timed inteval (about 2 secs by default)
the parent stores the new child's order, before "OnActivate" & "OnFocus"
 
  
- onexit
+
ow_fontlineheight (design-time only)
= fires last on parent-wide lossing focus, after "OnDefocus" & "OnDeactivate"
+
- causes "extraspace" of the last text line to be drawn,  
= for top-level ( not in a container ) forms, doesn't fire
+
in turn it causes adjustment of widget height if "ow_autoscale" is set
 +
 +
*** makes sence only if "ow_autoscale=true" & ow_autosize=false & "extraspace <> 0" ***
  
- onfocus
+
ow_fontglyphheight (design-time only)
fires
+
- causes only interline "extraspace"-s to be drawn, opposite to "ow_fontlineheight"  
= once the existing widget takes the focus
 
= on showing the widget's form if the widget has the lowest "TabOrder"
 
  
- onfontheightdelta
+
ow_autoscale (design-time only)
fires
+
- causes that if the contents change (design OR run-time) so that its' height changes
= if [ow_fontglyphheight OR ow_fontlineheight ] AND {the
+
then the widget will be v-scaled as well
new font height differs from the previos one}
 
= before the parent redraws this widget
 
  
- onpopup
+
ow_autosize (design-time only)
fires :
+
- causes that widget's height & width & client area adjust so that to provide space for contents of the client area
= on calling a popup-menu ( with "RightClick" ), once the menu items of the current level are loaded
+
- no design-time change of height/width are possible as long as this option is in effect
( before building the submenus )
 
  
- onresize
+
ow_autosizeanright
 +
- when autosizing & {an_right isn't set}, the design-set right margin against the parent is preserved
  
= fires on creating/(changing size)/(min-max restoring) of widget,  
+
ow_autosizeanbottom
before actual redrawing
+
- when autosizing & {an_bottom isn't set}, the design-set bottom margin against the parent is preserved
  
= rechecks if there's real work to do
+
optionsskin:
  
- onshowhint
+
- osc_noskin
= fires when a installed hint is activated or on "aplication.showint" called
+
- osc_framebuttononly
= since called last, allows to adjust the default behavior
+
- osc_container
  
- onbeforeupdateskin
 
= fires in "updateskin" ( the widget is loaded etc ) before applying the skin
 
  
- onafterupdateskin
+
Methods:
= fires in "updateskin" ( the widget is loaded etc ) once the skin is applied
 
  
<pre/>
+
  // tmsecomponent
 +
 
 +
// (re)draws the widget according to the related skin if apllicable;
 +
//
 +
// also called internally by "loaded" procedure ( before "OnLoaded" code ),
 +
// by ShowMessage ( for the internal widgets of the message dialogue ),
 +
// when creating tab & form & menu widgets
 +
procedure updateskin(const recursive: boolean = false);
 +
 
 +
// TRUE if the instance is created but not yet ready
 +
// for interaction & accessing data & appearance change & receiving events etc
 +
// ( the stage between firing "OnCreate" & "OnLoaded" )
 +
function loading: boolean;
 +
 +
{$ifdef FPC}
 +
procedure setinline(value: boolean); // ?
 +
procedure setancestor(value: boolean); // ?
 +
{$endif}
  
=== TWidget stuff ===
+
// TRUE if all conditios are OK for executing the code of "event" ( a handler must be assigned to the event )
<pre>
+
function canevent(const event: tmethod): boolean;
  Properties:   
 
- name
 
- anchors
 
- bounds
 
- color
 
- enabled
 
- visible
 
- <face> : see {any face}
 
- <frame> : see {any frame}
 
    - hint
 
    - helpcontext
 
    - tag
 
    - taborder
 
    - cursor
 
    - optionswidget
 
    - optionsskin
 
    - popupmenu
 
   
 
twidget's event handlers:
 
   
 
- on(de)activate
 
- onbeforeupdateskin
 
- onafterupdateskin
 
- onchildscaled
 
- onfontheightdelta
 
- on(de)focus
 
- onenter
 
- onmove
 
- onpopup
 
- onresize
 
- onshowhint
 
     
 
align_glue :  
 
  ( outer anchoring mode for widget group, in the align mode )
 
- wam_none
 
- wam_start
 
- wan_center
 
- wm_end
 
  
align_leader :
 
the widget ( incl another spacer, splitter or layouter ) against which the aligment applies ( the reference widget )
 
  
align_mode :
+
// Shortly, replaces the persistent storage of the widget
  ( inner anchoring mode within widget group, in the align mode )
+
//
- wam_none
+
// if {value <> nil} then
- wam_start
+
// - if "instance" is nil then calls "createproc" to create the instance,
- wan_center
+
//    then assigns the instance's value:= "value"
- wm_end
+
// otherwise frees "instance"
 +
procedure setoptionalobject(const value: tpersistent; var instance;
 +
                        createproc: createprocty);
  
// Place mode:
+
// creates the persistent storage of the widget via calling "createproc"
 +
procedure getoptionalobject(const instance: tobject; createproc: createprocty);
  
     
+
// obtains & puts to "obj" a CORBA interface entry for "aintf" (GUID,...)
place_mindist, place_maxdist:
+
function getcorbainterface(const aintf: ptypeinfo; out obj) : boolean;
- in the place(ment) mode, limits distance between widgets
 
  ( these distance once calclated also define side margins if aplicable )
 
  
place_mode:
+
        // TRUE if the widget is owned, or "self" otherwise
  ( outer anchoring mode for widget group, in the place mode )
+
function checkowned(component: tcomponent): boolean;
- wam_none
 
- wam_start
 
- wan_center
 
- wm_end
 
  
place_options:
+
        // TRUE if the widget is owner, or "self" otherwise
- plo_endmargin
+
function checkowner(component: tcomponent): boolean;
= to resize a widget so that it "eats" extra space if it occurs
 
 
* only applicable in the place mode, with a limiting value of "place_maxdist" and:
 
  
  1) {place_mode <> wam_none}
+
// return the top-most widget in owner chain starting from this widget
or
+
function rootowner: tcomponent;
  2) {place_mode = wam_end} and {plo_propmargin in place_options}
 
  
For the exact look, see above
+
// return the array of owning widgets starting from this widget
 +
// componentarty[0] is the widget oneself
 +
function getrootcomponentpath: componentarty;
  
 +
        // returns items of objeclinker ( which notify this widget )
 +
        // and free notify list ( which are notified by this widget ),
 +
        // duplicates are removed.
 +
        //
 +
        // Notifies mainly relate to insertion/removal operation on widgets
 +
        // The notify list is maintained by FreeNotification & RemoveFreeNotification
 +
function linkedobjects: objectarty;
  
- plo_propmargin
+
// sends "event" recursively to child widgets until no more children or
= виджеты расставляются теснее так, чтобы образовались отступы перед и после,
+
// the event is processed ( cea_processed ) by one of the children,
  причем расстояние между центрами виджетов было бы таким же,
+
// "event" will be destroyed if destroyevent= true and not async
  как и растояние между серединами крайних виджетов и соотв. границами зоны расстановки
+
procedure sendcomponentevent(const event: tcomponentevent;
 +
                                        const destroyevent: boolean = true);
  
- plo_syncmaxautosize
+
// sends "event" to each of owning widgets downward from the root owner,
= see above
+
// "event" will be destroyed if destroyevent= true and not async
 +
procedure sendrootcomponentevent(const event: tcomponentevent;
 +
                                        const destroyevent: boolean = true);
  
- plo_synccaptiondistx
+
// posts an async "atag"-ged event to be handled by oneself
= see above
+
procedure asyncevent(atag: integer = 0);
  
  * affects widgets with opposite cp_left/right set as well
+
// posts a "tcomponentevent" instance from sender=self,
  * the minimal before-adjustment "captiondist" amongst all widgets limits "captiondist" for each of the widget
+
// "kind" is defined when creating the event,
              * don't set cfo_captiondistouter here !
+
// and "tag" may be adjusted after creation
 +
procedure postcomponentevent(const event: tcomponentevent);
  
- plo_synccaptiondisty
+
// returns the classname of the widget if the widget is toplevel,
= see above
+
// and "tmsecomponent" otherwise )
 +
property moduleclassname: string read getmoduleclassname;
  
  * affects also widgets with opposite cp_top/bottom set
+
// returns the classname of the widget as the entry of its constructor
  * the minimal before-adjustment "captiondist" amongst all widgets limits "captiondist" for each of the widget
+
// ( button => tbutton, datamodule => tdm1mo, form => ttstfo, dbstringedit => tdbstringedit,.. )
 +
property actualclassname: string read getactualclassname;
  
              ! here, don't set "cfo_captiondistouter" for affected widgets !
+
// returns "fmsecomponentstate"
 +
// ( a set of cs_ismodule,cs_endreadproc,cs_loadedproc,cs_noload, cs_hasskin,cs_noskin )
 +
property msecomponentstate: msecomponentstatesty read fmsecomponentstate;
  
- plo_syncpaintwidth
+
// returns/sets a pointer associated with the widget
= see above
+
// ( contrary to the integer "tag", allows to use an arbitary data type
 +
// for associating data )
 +
property tagpo: pointer read ftagpo write ftagpo;
  
- plo_syncpaintheight
+
// returns/sets a string identifying the widget in the help system
= see above
+
property helpcontext: msestring read gethelpcontext write fhelpcontext;
  
- plo_scalesize
+
// twidget
= see above
 
  
 +
// creates an instance of the widget, owned by "aowner" if not NIL
 +
constructor create(aowner: tcomponent); override;
  
dist_left, dist_right, dist_top, dist_bottom :
+
destructor destroy; override;
= margins between most outer edge the layouter and
 
  the corresponding linked widget
 
  
* see "tspacer" for detail
+
// ??
 +
procedure afterconstruction; override;
  
linkleft,linkright,linktop,linkbottom : see "tspacer"
+
// rescales the widget frame ( if assigned ) then owned widgets ( if exist, recursively ) then bounds_* then the font ( if assigned )
 +
// called before inserting in parentwidget,
 +
// calls "scale(ascale)",
 +
// no visual repainting
 +
procedure initnewcomponent(const ascale: real); virtual;
  
options:
+
// restores the "fontheight" to "font.glyphheight" if "ow_fontglyphheight" or
- spao_glueright, spao_gluebottom:  
+
// to "font.lineheight" if "ow_fontlineheight" otherwise,
= set the adjustment dependencies between the layouter an its link_* widgets
+
// ascale is ignored ?
 +
// calls "synctofontheight->setfontheight",
 +
// called after inserting in parentwidget,
 +
// no visual repainting
 +
procedure initnewwidget(const ascale: real); virtual;
  
* see "tspacer" for more details
+
// creates the widget frame if not yet created
 +
procedure createframe;
  
// which mode of widget placement to apply - see above
+
// creates the widget face if not yet  created
optionslayout:
+
procedure createface;
- lao_alignx
 
- lao_aligny
 
- lao_placex
 
- lao_placey
 
- lao_scalewidth
 
- lao_scaleheight
 
- lao_scaleleft
 
- lao_scaletop
 
 
* lao_place* & lao_align* can't be combined for one direction
 
  
optionsscale:
+
// creates the widget font if not yet  created
 
+
procedure createfont;
  * cause the layouter to provide full space for the widgets as long as they expand/shrink/move
 
  
- osc_expandx
+
// checks ws_loadlock and csdestroing too
= allocates more h-space if needed
+
function isloading: boolean;
  
- osc_shrinkx
+
// returns "widgetstatety" - a set of (
= removes extra h-space if occured
+
// ws_visible,ws_enabled,ws_active,ws_entered,ws_entering,ws_exiting,
 +
// ws_focused,ws_mouseinclient,ws_wantmousebutton,ws_wantmousemove,
 +
// ws_wantmousefocus,ws_iswidget,ws_opaque,ws_nopaint,
 +
// ws_clicked,ws_mousecaptured,ws_clientmousecaptured,
 +
// ws_loadlock,ws_loadedproc,ws_showproc,ws_minclientsizevalid,
 +
// ws_showed,ws_hidden, //used in tcustomeventwidget
 +
// ws_destroying,ws_staticframe,ws_staticface,ws_isvisible
 +
//
 +
// iframe
 +
function widgetstate: widgetstatesty;
  
- osc_expandy
+
// returns "widgetstate1ty" - a set of (
= allocates more v-space if needed
+
// (ws1_childscaled,ws1_fontheightlock,
 +
// ws1_widgetregionvalid,ws1_rootvalid,
 +
// ws1_anchorsizing,ws1_isstreamed,
 +
// ws1_scaled, //used in tcustomscalingwidget
 +
// ws1_noclipchildren,
 +
// ws1_nodesignvisible,ws1_nodesignframe,ws1_nodesignhandles,
 +
// ws1_nodesigndelete,ws1_designactive,
 +
// ws1_fakevisible,ws1_nominsize //used for report size calculations
 +
// )
 +
property widgetstate1: widgetstates1ty read fwidgetstate1;
 +
 +
* this set of states is needed because the max FPC set size is 32
 +
  thus "widgetstate1ty" can't fit all states
  
- osc_shrinky
+
// TRUE if the widget is contained within another widget
= removes extra v-space if occured
+
// ( tcomponent stuff )
 +
function hasparent: boolean; override;             
  
- osc_invisishrinkx
+
// returns the parent component if it's a widget or the grandparent otherwise
= fully h-collapses the layouter if "visible=false" ( run-time only )
+
function getparentcomponent: tcomponent; override;  // tcomponent
  
- osc_invisishrinky
+
// TRUE if "awidget" is an ascendant or the widget or they are the same widget
= fully v-collapses the layoter if "visible=false" ( run-time only )
+
function checkdescendent(awidget: twidget): boolean;
 +
 +
// TRUE if app is running and the widget owns the caret or the caret widget
 +
function hascaret: boolean;
  
optionsskin:
+
        // TRUE if "winid" allocated and not loading and not destroying,
= see <any widget>
+
        // all widgets on a form have "winid" of this form ( a real window allocated by the OS )
 +
        // thus have this function TRUE
 +
function windowallocated: boolean;
  
 +
// TRUE if presents a valid toplevelwindow with assigned "winid"
 +
function ownswindow: boolean;
  
Methods:
+
// invalidated area of the widget, the origin is "clientpos" against the roor widget
 +
function updaterect: rectty;
  
constructor create(aowner: tcomponent); override;
+
// calls recursively "canclose" for all contained widgets ( the widget oneself excluded! ),
 +
// TRUE if none of the widgets return FALSE
 +
//
 +
// more specialized widgets may have "canclose" overridden
 +
// to perform more work than just this call recursion
 +
// ( not null or range check,.. )
 +
//
 +
// "onclosequery" must also pass the check if assigned, for the function to succeed
 +
function canclose(const newfocus: twidget = nil): boolean; virtual;
  
=== Public stuff ===
+
        // checks "canclose" first for focused widget of the window ( form,.. )  
<pre/> (f)window:
+
        // if it is a descendant of the widget or the widget oneself,
the OS-allocated ( root = toplevel ) window common for all widgets of this window
+
        // then continues with subwidgets of the widget;
+
        // also - finishes editing ( snapshots "value" ) in the focused widget before checking
* "widget.fwindow.fowner = widget.self" in case of the widget present the root "fwindow"
+
function canparentclose(const newfocus: twidget): boolean; overload;
  ( owns the window )
 
  
(f)rootpos:
+
// the above function but with the preserved focus
position of the widget in the coord of toplevel window not the nearest parent widget alone,
+
function canparentclose: boolean; overload;
calculated as sum of such positions ( fwidgetrect.pos ) starting from the toplevel through the chain of all parents
+
                  //newfocus = window.focusedwidget     
up to the current widget;
 
"nullpoint" (0,0) for toplevel widgets ( window-owning forms,..)
 
  
screenpos:
+
function canfocus: boolean; virtual;
- coord aginst the top-left corner of screen
+
function setfocus(aactivate: boolean = true): boolean; virtual;//true if ok
- WM decoration & title aren't parts of the widget !
+
procedure nextfocus; //sets inputfocus to then next appropriate widget
  
widgetrect:  
+
function findtabfocus(const ataborder: integer): twidget;
the widget on-screen area including its frame & frame caption
+
                      //nil if cannot focus
  
paintrect:  
+
function firsttabfocus: twidget;
the widget on-screen area except its frame & frame caption
+
function lasttabfocus: twidget;
 +
function nexttaborder(const down: boolean = false): twidget;
  
clientrect:
+
function focusback(const aactivate: boolean = true): boolean;
virtual area which
+
                              //false if focus not changed
- for non-scrolling widgets, equals to "paintrect", with its "pos:= (0,0)"
 
- for scrolling widgets, may be bigger than "paintrect",
 
  also may shift ( change its "pos" ) when scrolling
 
  
* "t*grid" aren't such scrollable widgets since their virtual height would be limited by
+
function parentcolor: colorty;
  the X11 "+-32000" limitation,
+
function actualcolor: colorty; virtual;
  so example of such widgets are tscrollbox, "tform.container" etc
+
function actualopaquecolor: colorty;
 +
function backgroundcolor: colorty;
 +
function translatecolor(const acolor: colorty): colorty;
  
framerect:  
+
procedure widgetevent(const event: twidgetevent); virtual;
the widget on-screen area except its frame caption but including inner & outer frame
 
  
****************
+
procedure sendwidgetevent(const event: twidgetevent);
 +
                              //event will be destroyed
  
// releases all thread locks then post the event to the app event queue and
+
procedure release; override;
// waits for the event handler finishes ( signalled by "sye_ok on a semaphore )
 
// finally restores the locks
 
    // true if the handler is not aborted
 
function synchronizeevent(const aevent: tsynchronizeevent): boolean;
 
  
    // translates "point" coord against "source" widgetrect to "dest" widgetrect
+
function show(const modal: boolean = false; const transientfor: twindow = nil): modalresultty; virtual;
//
 
//  * nil "source" = from screen coord
 
//  * nil "dest" = to screen coord
 
procedure translatewidgetpoint1(var point: pointty; const source,dest: twidget);
 
  
// the function-framed version of "translatewidgetpoint1"
+
procedure hide;
function translatewidgetpoint(const point: pointty; const source,dest: twidget): pointty;
+
procedure activate(const abringtofront: boolean = true); virtual;
 +
                            //show and setfocus
  
// rect isntead of point,
+
procedure bringtofront;
// if dest = nil then to screen
+
procedure sendtoback;
    // if source = nil then against screen
+
procedure stackunder(const predecessor: twidget);
function translatewidgetrect(const rect: rectty; const source,dest: twidget): rectty;
 
//-----------------
 
    // translates "point" coord against "source" paintrect to "dest" paintrect
 
//  * nil "source" = from screen coord
 
//  * nil "dest" = to screen coord
 
procedure translatepaintpoint1(var point: pointty; const source,dest: twidget);
 
  
// the function-framed version of "translatepaintpoint1"
+
procedure paint(const canvas: tcanvas); virtual;
function translatepaintpoint(const point: pointty; const source,dest: twidget): pointty;
+
procedure update; virtual;
 +
procedure scrollwidgets(const dist: pointty);
 +
 
 +
procedure scrollrect(const dist: pointty; const rect: rectty; scrollcaret: boolean);
 +
                            //origin = paintrect.pos
 +
 
 +
procedure scroll(const dist: pointty);
 +
                            //scrolls paintrect and widgets
  
// rect isntead of point,
+
procedure getcaret;
// if dest = nil then to screen
+
procedure scrollcaret(const dist: pointty);
    // if source = nil then against screen
+
function mousecaptured: boolean;
function translatepaintrect(const rect: rectty;const source,dest: twidget): rectty;
+
procedure capturemouse(grab: boolean = true);
    //-----------------
+
procedure releasemouse;
    // translates "point" coord against "source" clientrect to "dest" clienttrect
+
procedure capturekeyboard;
//  * nil "source" = from screen coord
+
procedure releasekeyboard;
//  * nil "dest" = to screen coord
+
procedure synctofontheight; virtual;
procedure translateclientpoint1(var point: pointty;
 
                    const source,dest: twidget);
 
  
// the function-framed version of "translateclientpoint1"
+
procedure dragevent(var info: draginfoty); virtual;
function translateclientpoint(const point: pointty; const source,dest: twidget): pointty;
+
procedure dochildscaled(const sender: twidget); virtual;
  
// rect isntead of point,  
+
procedure invalidatewidget;    //invalidates whole widget
// if dest = nil then to screen  
+
procedure invalidate;          //invalidates clientrect
 +
procedure invalidaterect(const rect: rectty; org: originty = org_client);
 +
procedure invalidateframestate;
 +
 
 +
procedure invalidateframestaterect(const rect: rectty;
 +
                                        const org: originty = org_client); 
 +
function hasoverlappingsiblings(arect: rectty): boolean; //origin = pos
 +
 
 +
function window: twindow;
 +
function rootwidget: twidget;
 +
 
 +
function parentofcontainer: twidget;
 +
            //parentwidget.parentwidget if parentwidget has not ws_iswidget,
 +
            //parentwidget otherwise
 +
 
 +
property parentwidget: twidget read fparentwidget write setparentwidget;
 +
function getrootwidgetpath: widgetarty; //root widget is last
 +
 
 +
// number of contained widgets ( the widget oneself excluded ! )
 +
function widgetcount: integer;
 +
 
 +
function parentwidgetindex: integer; //index in parentwidget.widgets, -1 if none
 +
property widgets[const index: integer]: twidget read getwidgets;
 +
function widgetatpos(var info: widgetatposinfoty): twidget; overload;
 +
function widgetatpos(const pos: pointty): twidget; overload;
 +
 
 +
function widgetatpos(const pos: pointty;
 +
                  const state: widgetstatesty): twidget; overload;
 +
 
 +
property taborderedwidgets: widgetarty read gettaborderedwidgets;
 +
 
 +
function findtagwidget(const atag: integer; const aclass: widgetclassty): twidget;
 +
              //returns first matching descendent
 +
 
 +
property container: twidget read getcontainer;
 +
function containeroffset: pointty;
 +
function childrencount: integer; virtual;
 +
property children[const index: integer]: twidget read getchildwidgets; default;
 +
 
 +
function childatpos(const pos: pointty;
 +
                  const clientorigin: boolean = true): twidget; virtual;
 +
 
 +
function getsortxchildren: widgetarty;
 +
function getsortychildren: widgetarty;
 +
property focusedchild: twidget read ffocusedchild;
 +
property focusedchildbefore: twidget read ffocusedchildbefore;
 +
 
 +
function mouseeventwidget(const info: mouseeventinfoty): twidget;
 +
 
 +
function checkdescendent(widget: twidget): boolean;
 +
                    //true if widget is descendent or self
 +
 
 +
function checkancestor(widget: twidget): boolean;
 +
                    //true if widget is ancestor or self
 +
 
 +
function containswidget(awidget: twidget): boolean;
 +
 
 +
procedure insertwidget(const awidget: twidget); overload;
 +
 
 +
procedure insertwidget(const awidget: twidget; const apos: pointty); overload; virtual;
 +
                //widget can be child
 +
 
 +
function iswidgetclick(const info: mouseeventinfoty; const caption: boolean = false): boolean;
 +
//true if eventtype = et_butonrelease, button is mb_left, clicked and pos in clientrect
 +
//or in frame.caption if caption = true, origin = pos
 +
 
 +
function isclick(const info: mouseeventinfoty): boolean;
 +
//true if eventtype = et_butonrelease, button is mb_left, clicked and pos in clientrect
 +
 
 +
function isdblclick(const info: mouseeventinfoty): boolean;
 +
//true if eventtype = et_butonpress, button is mb_left, pos in clientrect
 +
// and timedlay to last buttonpress is short
 +
 
 +
function isdblclicked(const info: mouseeventinfoty): boolean;
 +
//true if eventtype in [et_buttonpress,et_butonrelease], button is mb_left,
 +
// and timedlay to last same buttonevent is short
 +
 
 +
function isleftbuttondown(const info: mouseeventinfoty): boolean;
 +
//true if eventtype = et_butonpress, button is mb_left, pos in clientrect
 +
//origin = paintrect.pos
 +
 
 +
widgetrect: the widget on-screen area including its frame & frame caption
 +
 
 +
paintrect: the widget on-screen area except its frame & frame caption
 +
 
 +
clientrect: virtual area which
 +
- for non-scrolling widgets, equals to "paintrect", with its "pos:= (0,0)"
 +
- for scrolling widgets, may be bigger than "paintrect",
 +
  also may shift ( change its "pos" ) when scrolling
 +
 +
// the coord of outer top-left corner against the toplevel form = the window owner,
 +
// including the frame & frame caption
 +
function rootpos: pointty;
 +
 
 +
// the coord of the outer top-left corner against the screen ( the WM decorations aren't counted in )
 +
// includes the frame & frame caption
 +
property screenpos: pointty;
 +
 
 +
//  the coord of the outer top-left corner against the parent widget,
 +
// including the frame & frame caption
 +
property widgetrect: rectty;
 +
property pos: pointty; // =widgetrect.pos
 +
property size: sizety; // =widgetrect.size
 +
property left: integer; // =bounds_x
 +
property right: integer; //widgetrect.x + widgetrect.cx, sets cx;
 +
property top: integer;  // =bounds_y
 +
property bottom: integer; //widgetrect.y + widgetrect.cy, sets cy;
 +
property width: integer; // =bounds_cx
 +
property height: integer; // =bounds_cy
 +
function widgetsizerect: rectty;          //pos = nullpoint
 +
 
 +
    // the coord of the paint area ( paintrect ) against own outer top-left corner ( against "widgetrect=pos" )
 +
    //  except the frame & frame caption
 +
function paintrect: rectty;
 +
function paintpos: pointty;
 +
function paintsize: sizety;
 +
function innerpaintrect: rectty; // mainly equals to paintrect
 +
function clientwidgetrect: rectty; // mainly equals to paintrect
 +
function clientwidgetpos: pointty;
 +
function clippedpaintrect: rectty; // mainly equals to  but clipped by all parentpaintrects
 +
function innerwidgetrect: rectty;    // mainly equals to paintrect
 +
function innerclientwidgetpos: pointty;
 +
 
 +
    // the coord of the paint area ( paintrect ) against own outer top-left corner ( against "widgetrect=pos" )
 +
    //  except the frame caption
 +
function framerect: rectty; // =paintrect except the frame caption area
 +
function framepos: pointty;
 +
function framesize: sizety;
 +
 
 +
    // the coord of the client area ( clientrect )  against the paint area ( paintrect )
 +
    //  usually these areas match
 +
function clientrect: rectty;
 +
property clientsize: sizety;
 +
property clientwidth: integer;
 +
property clientheight: integer;
 +
property clientpos: pointty;
 +
 
 +
    // the coord of the paint area of the parent against the paint area of this widget
 +
function paintrectparent: rectty; //nullrect if parent = nil,
 +
 
 +
    // the coord of the client area of the parent against the paint area of this widget
 +
function clientrectparent: rectty; //nullrect if parent = nil,
 +
 
 +
// the coord of the inner area against the client area ( clientrect )
 +
function innerclientrect: rectty;  // mainly equals to clientrect
 +
function innerclientsize: sizety;
 +
function innerclientpos: pointty;
 +
 
 +
function framewidth: sizety;              //widgetrect.size - paintrect.size
 +
function clientframewidth: sizety;        //widgetrect.size - clientrect.size
 +
function innerclientframewidth: sizety;  //widgetrect.size - innerclientrect.size
 +
function innerframewidth: sizety;        //clientrect.size - innerclientrect.size 
 +
 
 +
    // the coord of the paint area against the widgetrect(pos) of the parent
 +
function paintparentpos: pointty;    //origin = parentwidget.pos
 +
 
 +
    // the coord of the client area against the widgetrect(pos) of the parent
 +
function clientparentpos: pointty;  //origin = parentwidget.pos
 +
 
 +
    // the coord of the widgetrect(pos) against the client area of parent
 +
property parentclientpos: pointty;
 +
 
 +
 
 +
function clientpostowidgetpos(const apos: pointty): pointty;
 +
function widgetpostoclientpos(const apos: pointty): pointty;
 +
function widgetpostopaintpos(const apos: pointty): pointty;
 +
function paintpostowidgetpos(const apos: pointty): pointty;
 +
procedure scale(const ascale: real); virtual;
 +
 
 +
 
 +
property minsize: sizety read fminsize write setminsize;
 +
property maxsize: sizety read fmaxsize write setmaxsize;
 +
function maxclientsize: sizety; virtual;
 +
 
 +
 
 +
property anchors: anchorsty read fanchors write setanchors default defaultanchors;
 +
property defaultfocuschild: twidget read getdefaultfocuschild write setdefaultfocuschild;
 +
 
 +
 
 +
procedure changeclientsize(const delta: sizety); //asynchronous
 +
 
 +
function getcanvas(aorigin: originty = org_client): tcanvas;
 +
 
 +
function showing: boolean;
 +
              //true if self and all ancestors visible and window allocated
 +
 
 +
function isenabled: boolean;
 +
              //true if self and all ancestors enabled
 +
 
 +
function active: boolean;
 +
function entered: boolean;
 +
 
 +
function activeentered: boolean;
 +
//true if entered and window is regularactivewindow or inactivated
 +
 
 +
function focused: boolean;
 +
function clicked: boolean;
 +
 
 +
function indexofwidget(const awidget: twidget): integer;
 +
 
 +
procedure changedirection(const avalue: graphicdirectionty;
 +
                                            var dest: graphicdirectionty); virtual;
 +
 
 +
// (re)arranges "awidgets" horizontally within the parent's client area
 +
// so that awidget[i] were placed next each other
 +
// at h-space dist[i], starting from "startx" with the right margin "endmargin";
 +
//
 +
// if the number of "dist" is fewer than the number of "awidgets" then the remaining h-spaces are taken
 +
// as the last "dist[i]" or "0" if none;
 +
// if the number of "dist" is more than the number of "awidgets" then the extra dist[i] are discarded
 +
//
 +
// non-zero "endmargin" causes one of awdidget[i] to h-resize to provide the margin :
 +
//  - if one or more of awidgets[i] have [an_left,an_right] set then the first of such is resized
 +
//    otherwise the last awidgets[i] is h-resized
 +
//
 +
procedure placexorder(
 +
const startx: integer;
 +
const dist: array of integer;
 +
                const awidgets: array of twidget;
 +
                const endmargin: integer = minint);
 +
 
 +
// (re)arranges "awidgets" vertically within the parent's client area
 +
// so that awidget[i] were placed upper/lower each other
 +
// at v-space dist[i], starting from "starty" with the bottom margin "endmargin";
 +
//
 +
// if the number of "dist" is fewer than the number of "awidgets" then the remaining v-spaces are taken
 +
// as the last "dist[i]" or "0" if none;
 +
// if the number of "dist" is more than the number of "awidgets" then the extra dist[i] are discarded
 +
//
 +
// non-zero "endmargin" causes one of awdidget[i] to v-resize to provide the margin :
 +
//  - if one or more of awidgets[i] have [an_top,an_bottom] set then the first of such is resized
 +
//    otherwise the last awidgets[i] is v-resized
 +
//
 +
procedure placeyorder(
 +
const starty: integer;
 +
const dist: array of integer;
 +
                const awidgets: array of twidget;
 +
                const endmargin: integer = minint);
 +
              //origin = clientpos, endmargin by size adjust of widgets
 +
              //with [an_top,an_bottom], minint -> no change
 +
 
 +
// if {mode <> wam_none} then (re)arranges "awidgets" horizontally  within the parent's client area so that
 +
// awidgets[0] stays on its place but awidgets[1..N] :
 +
// - 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]
 +
// - 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]
 +
// - if {mode = wam_center} then awidgets[i>=1] move so that they Y-axes match the Y-axe of awidgets[0]
 +
//
 +
// mainly applicable for v-stacked widgets since h-stacked may overlap after such alignment
 +
//
 +
        // returns the reference point ( the coord of awidgets[0] )
 +
function alignx(const mode: widgetalignmodety;
 +
                        const awidgets: array of twidget): integer;
 +
 
 +
 
 +
// if {mode <> wam_none} then (re)arranges "awidgets" vertically within the parent's client area so that
 +
// awidgets[0] stays on its place but awidgets[1..N] :
 +
// - 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]
 +
// - 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]
 +
// - if {mode = wam_center} then awidgets[i>=1] move so that they X-axes match the X-axe of awidgets[0]
 +
//
 +
// mainly applicable for h-stacked widgets since v-stacked may overlap after such alignment
 +
//
 +
        // returns the reference point ( the coord of awidgets[0] )
 +
function aligny(const mode: widgetalignmodety;
 +
                        const awidgets: array of twidget): integer;
 +
 
 +
function actualcursor: cursorshapety; virtual;
 +
 
 +
 
 +
Event handlers:
 +
 
 +
- onactivate
 +
 
 +
fires :
 +
 
 +
= on receiving input focus, just before "OnFocus"
 +
 +
= forms specific :
 +
* on 1-st display of the form after "OnLoaded" ( from "Loaded" procedure)
 +
* on switch back from another apllication/WM ( "oe_activate" event )
 +
* after closure of a descendant form
 +
* on minimizing/maximizing the form
 +
 
 +
- onchildscaled
 +
 
 +
fires :
 +
 
 +
= on child/children resizing due to font height change
 +
 
 +
= form widget: once "form.container" {scrolling widget} is loaded
 +
 
 +
- ondeactivate
 +
fires
 +
= form widget: when the form looses input focus
 +
= non-form widget: when the widget looses input focus
 +
 
 +
- ondefocus
 +
 
 +
fires
 +
= on disabling the widget
 +
 
 +
= form widget: if another form is focused
 +
= non-form widget: if another widget is focused
 +
 
 +
- onenter
 +
= fires on any way of taking parent-wide focus as soon as
 +
the parent stores the new child's order, before "OnActivate" & "OnFocus"
 +
 
 +
- onexit
 +
= fires last on parent-wide lossing focus, after "OnDefocus" & "OnDeactivate"
 +
= for top-level ( not in a container ) forms, doesn't fire
 +
 
 +
- onfocus
 +
fires
 +
= once the existing widget takes the focus
 +
= on showing the widget's form if the widget has the lowest "TabOrder"
 +
 
 +
- onfontheightdelta
 +
fires
 +
= if [ow_fontglyphheight OR ow_fontlineheight ] AND {the
 +
new font height differs from the previos one}
 +
= before the parent redraws this widget
 +
 
 +
- onpopup
 +
fires :
 +
= on calling a popup-menu ( with "RightClick" ), once the menu items of the current level are loaded
 +
( before building the submenus )
 +
 
 +
- onresize
 +
 
 +
= fires on creating/(changing size)/(min-max restoring) of widget,
 +
before actual redrawing
 +
 
 +
= rechecks if there's real work to do
 +
 
 +
- onshowhint
 +
= fires when a installed hint is activated or on "aplication.showint" called
 +
= since called last, allows to adjust the default behavior
 +
 
 +
- onbeforeupdateskin
 +
= fires in "updateskin" ( the widget is loaded etc ) before applying the skin
 +
 
 +
- onafterupdateskin
 +
= fires in "updateskin" ( the widget is loaded etc ) once the skin is applied
 +
 
 +
</pre>
 +
 
 +
=== TWidget stuff ===
 +
<pre>
 +
  Properties:   
 +
- name
 +
- anchors
 +
- bounds
 +
- color
 +
- enabled
 +
- visible
 +
- <face> : see {any face}
 +
- <frame> : see {any frame}
 +
    - hint
 +
    - helpcontext
 +
    - tag
 +
    - taborder
 +
    - cursor
 +
    - optionswidget
 +
    - optionsskin
 +
    - popupmenu
 +
   
 +
twidget's event handlers:
 +
   
 +
- on(de)activate
 +
- onbeforeupdateskin
 +
- onafterupdateskin
 +
- onchildscaled
 +
- onfontheightdelta
 +
- on(de)focus
 +
- onenter
 +
- onmove
 +
- onpopup
 +
- onresize
 +
- onshowhint
 +
     
 +
align_glue :
 +
  ( outer anchoring mode for widget group, in the align mode )
 +
- wam_none
 +
- wam_start
 +
- wan_center
 +
- wm_end
 +
 
 +
align_leader :
 +
the widget ( incl another spacer, splitter or layouter ) against which the alignment applies ( the reference widget )
 +
 
 +
align_mode :
 +
  ( inner anchoring mode within widget group, in the align mode )
 +
- wam_none
 +
- wam_start
 +
- wan_center
 +
- wm_end
 +
 
 +
// Place mode:
 +
 
 +
     
 +
place_mindist, place_maxdist:
 +
- in the place(ment) mode, limits distance between widgets
 +
  ( these distance once calculated also define side margins if applicable )
 +
 
 +
place_mode:
 +
  ( outer anchoring mode for widget group, in the place mode )
 +
- wam_none
 +
- wam_start
 +
- wan_center
 +
- wm_end
 +
 
 +
place_options:
 +
- plo_endmargin
 +
= to resize a widget so that it "eats" extra space if it occurs
 +
 +
* only applicable in the place mode, with a limiting value of "place_maxdist" and:
 +
 
 +
  1) {place_mode <> wam_none}
 +
or
 +
  2) {place_mode = wam_end} and {plo_propmargin in place_options}
 +
 
 +
For the exact look, see above
 +
 
 +
 
 +
- plo_propmargin
 +
= виджеты расставляются теснее так, чтобы образовались отступы перед и после,
 +
  причем расстояние между центрами виджетов было бы таким же,
 +
  как и растояние между серединами крайних виджетов и соотв. границами зоны расстановки
 +
 
 +
- plo_syncmaxautosize
 +
= see above
 +
 
 +
- plo_synccaptiondistx
 +
= see above
 +
 
 +
  * affects widgets with opposite cp_left/right set as well
 +
  * the minimal before-adjustment "captiondist" among all widgets limits "captiondist" for each of the widget
 +
              * don't set cfo_captiondistouter here !
 +
 
 +
- plo_synccaptiondisty
 +
= see above
 +
 
 +
  * affects also widgets with opposite cp_top/bottom set
 +
  * the minimal before-adjustment "captiondist" amongst all widgets limits "captiondist" for each of the widget
 +
 
 +
              ! here, don't set "cfo_captiondistouter" for affected widgets !
 +
 
 +
- plo_syncpaintwidth
 +
= see above
 +
 
 +
- plo_syncpaintheight
 +
= see above
 +
 
 +
- plo_scalesize
 +
= see above
 +
 
 +
 
 +
dist_left, dist_right, dist_top, dist_bottom :
 +
= margins between most outer edge the layouter and
 +
  the corresponding linked widget
 +
 
 +
* see "tspacer" for detail
 +
 
 +
linkleft,linkright,linktop,linkbottom : see "tspacer"
 +
 
 +
options:
 +
- spao_glueright, spao_gluebottom:
 +
= set the adjustment dependencies between the layouter and its link_* widgets
 +
 
 +
* see "tspacer" for more details
 +
 
 +
// which mode of widget placement to apply - see above
 +
optionslayout:
 +
- lao_alignx
 +
- lao_aligny
 +
- lao_placex
 +
- lao_placey
 +
- lao_scalewidth
 +
- lao_scaleheight
 +
- lao_scaleleft
 +
- lao_scaletop
 +
 +
* lao_place* & lao_align* can't be combined for one direction
 +
 
 +
optionsscale:
 +
 
 +
  * cause the layouter to provide full space for the widgets as long as they expand/shrink/move
 +
 
 +
- osc_expandx
 +
= allocates more h-space if needed
 +
 
 +
- osc_shrinkx
 +
= removes extra h-space if occurred
 +
 
 +
- osc_expandy
 +
= allocates more v-space if needed
 +
 
 +
- osc_shrinky
 +
= removes extra v-space if occurred
 +
 
 +
- osc_invisishrinkx
 +
= fully h-collapses the layouter if "visible=false" ( run-time only )
 +
 
 +
- osc_invisishrinky
 +
= fully v-collapses the layoter if "visible=false" ( run-time only )
 +
 
 +
optionsskin:
 +
= see <any widget>
 +
 
 +
 
 +
Methods:
 +
 
 +
constructor create(aowner: tcomponent); override;
 +
</pre>
 +
 
 +
=== Public stuff ===
 +
<pre>
 +
(f)window:
 +
the OS-allocated ( root = toplevel ) window common for all widgets of this window
 +
 +
* "widget.fwindow.fowner = widget.self" in case of the widget present the root "fwindow"
 +
  ( owns the window )
 +
 
 +
(f)rootpos:
 +
position of the widget in the coord of toplevel window not the nearest parent widget alone,
 +
calculated as sum of such positions ( fwidgetrect.pos ) starting from the toplevel through the
 +
                chain of all parents up to the current widget;
 +
"nullpoint" (0,0) for toplevel widgets ( window-owning forms,..)
 +
 
 +
screenpos:
 +
- coord aginst the top-left corner of screen
 +
- WM decoration & title aren't parts of the widget !
 +
 
 +
widgetrect:
 +
the widget on-screen area including its frame & frame caption
 +
 
 +
paintrect:
 +
the widget on-screen area except its frame & frame caption
 +
 
 +
clientrect:
 +
virtual area which
 +
- for non-scrolling widgets, equals to "paintrect", with its "pos:= (0,0)"
 +
- for scrolling widgets, may be bigger than "paintrect",
 +
  also may shift ( change its "pos" ) when scrolling
 +
 
 +
* "t*grid" aren't such scrollable widgets since their virtual height would be limited by
 +
  the X11 "+-32000" limitation,
 +
  so example of such widgets are tscrollbox, "tform.container" etc
 +
 
 +
framerect:
 +
the widget on-screen area except its frame caption but including inner & outer frame
 +
 
 +
****************
 +
 
 +
// releases all thread locks then post the event to the app event queue and
 +
// waits for the event handler finishes ( signalled by "sye_ok on a semaphore )
 +
// finally restores the locks
 +
    // true if the handler is not aborted
 +
function synchronizeevent(const aevent: tsynchronizeevent): boolean;
 +
 
 +
    // translates "point" coord against "source" widgetrect to "dest" widgetrect
 +
//
 +
//  * nil "source" = from screen coord
 +
//  * nil "dest" = to screen coord
 +
procedure translatewidgetpoint1(var point: pointty; const source,dest: twidget);
 +
 
 +
// the function-framed version of "translatewidgetpoint1"
 +
function translatewidgetpoint(const point: pointty; const source,dest: twidget): pointty;
 +
 
 +
// rect isntead of point,
 +
// if dest = nil then to screen
 +
    // if source = nil then against screen
 +
function translatewidgetrect(const rect: rectty; const source,dest: twidget): rectty;
 +
//-----------------
 +
    // translates "point" coord against "source" paintrect to "dest" paintrect
 +
//  * nil "source" = from screen coord
 +
//  * nil "dest" = to screen coord
 +
procedure translatepaintpoint1(var point: pointty; const source,dest: twidget);
 +
 
 +
// the function-framed version of "translatepaintpoint1"
 +
function translatepaintpoint(const point: pointty; const source,dest: twidget): pointty;
 +
 
 +
// rect isntead of point,  
 +
// if dest = nil then to screen  
 
     // if source = nil then against screen
 
     // if source = nil then against screen
function translateclientrect(const rect: rectty; const source,dest: twidget): rectty;
+
function translatepaintrect(const rect: rectty;const source,dest: twidget): rectty;
     //-----------------
+
    //-----------------
 
+
    // translates "point" coord against "source" clientrect to "dest" clienttrect
// (re)sorts "awidgets" in order of increasing their "widgetrect.x" coords
+
//  * nil "source" = from screen coord
//  - if parent = nil then the coords are against individual parent of each of "awidgets"
+
//  * nil "dest" = to screen coord
//  - if parent is supplied then the coords are against this parent
+
procedure translateclientpoint1(var point: pointty;
procedure sortwidgetsxorder(var awidgets: widgetarty; const parent: twidget = nil);
+
                    const source,dest: twidget);
 
+
 
// (re)sorts "awidgets" in order of increasing their "widgetrect.y" coords
+
// the function-framed version of "translateclientpoint1"
//  - if parent = nil then the coords are against individual parent of each of "awidgets"
+
function translateclientpoint(const point: pointty; const source,dest: twidget): pointty;
//  - if parent is supplied then the coords are against this parent
+
 
procedure sortwidgetsyorder(var awidgets: widgetarty; const parent: twidget = nil);
+
// rect isntead of point,
 
+
// if dest = nil then to screen
// for each  of "widgets", calculates its autosized client area ( min size rect to fit the caption, etc )
+
    // if source = nil then against screen
     //  - both hor & ver sizes of client area of each of "widgets" are adjusted to the max of the above calculated areas,
+
function translateclientrect(const rect: rectty; const source,dest: twidget): rectty;
//   as the result - client areas of all widgets become identically v+h sized
+
     //-----------------
     //  
+
 
     //  * right & bottom anchored margins of each widget are preserved
+
// (re)sorts "awidgets" in order of increasing their "widgetrect.x" coords
procedure syncmaxautosize(const widgets: array of twidget);
+
//  - if parent = nil then the coords are against individual parent of each of "awidgets"
 +
//  - if parent is supplied then the coords are against this parent
 +
procedure sortwidgetsxorder(var awidgets: widgetarty; const parent: twidget = nil);
 +
 
 +
// (re)sorts "awidgets" in order of increasing their "widgetrect.y" coords
 +
//  - if parent = nil then the coords are against individual parent of each of "awidgets"
 +
//  - if parent is supplied then the coords are against this parent
 +
procedure sortwidgetsyorder(var awidgets: widgetarty; const parent: twidget = nil);
 +
 
 +
// for each  of "widgets", calculates its autosized client area ( min size rect to fit the caption, etc )
 +
     //  - both hor & ver sizes of client area of each of "widgets" are adjusted to the max of the above calculated areas,
 +
//   as the result - client areas of all widgets become identically v+h sized
 +
     //  
 +
     //  * right & bottom anchored margins of each widget are preserved
 +
procedure syncmaxautosize(const widgets: array of twidget);
 +
 
 +
// for each  of "widgets", width of client area of each of "widgets" is adjusted so that
 +
    // external ( by the outer border of frame ) widths of all widgets become identical
 +
    // to the external widht of the widest widget
 +
    //   
 +
    //  * if "awidth" >= 0 then no determining the widest widget is taken and
 +
    //    "awidth" is adjusted to instead, for all widgets
 +
    //  * right anchored margins of each widget are lost
 +
procedure syncminframewidth(const awidgets: array of twidget;
 +
                              const awidth: integer = -1);
 +
 
 +
// for each  of "widgets", height of client area of each of "widgets" is adjusted so that
 +
    // external ( by the outer border of frame ) heights of all widgets become identical
 +
    // to the external height of the highest widget
 +
    //   
 +
    //  * if "aheight" >= 0 then no determining the highest widget is taken and
 +
    //    "aheight" is adjusted to instead, for all widgets
 +
    //  * bottom anchored margins of each widget are lost
 +
procedure syncminframeheight(const awidgets: array of twidget; const aheight: integer = -1);
 +
</pre>
  
// for each  of "widgets", width of client area of each of "widgets" is adjusted so that
+
== Projects using MSEgui ==
    // external ( by the outer border of frame ) widths of all widgets become identical
 
    // to the external widht of the widest widget
 
    //   
 
    //  * if "awidth" >= 0 then no determining the widest widget is taken and
 
    //    "awidth" is adjusted to instead, for all widgets
 
    //  * right anchored margins of each widget are lost
 
procedure syncminframewidth(const awidgets: array of twidget;
 
                              const awidth: integer = -1);
 
  
// for each  of "widgets", height of client area of each of "widgets" is adjusted so that
+
* [[Projects using MSEgui]]
    // external ( by the outer border of frame ) heights of all widgets become identical
 
    // to the external height of the highest widget
 
    //   
 
    //  * if "aheight" >= 0 then no determining the highest widget is taken and
 
    //    "aheight" is adjusted to instead, for all widgets
 
    //  * bottom anchored margins of each widget are lost
 
procedure syncminframeheight(const awidgets: array of twidget; const aheight: integer = -1);
 
<pre/>
 

Latest revision as of 23:07, 9 April 2021

English (en)

Widgets

TSimpleWidget

see also Reference:_MSEgui/TSimpleWidget

TMainMenuWidget

TSimpleWidget

TMseFormWidget

Use it in order to insert a tcustomform descendant into another widget at designtime. Does not try to load resources in "create".

        tmseform descendants ( MainForm, SimpleForm,.. )

	Client area of the form & parent of its widgets ( against which the widgets 
	are placed and colored ) is presented by the "container" property 
	not "container.frame.clientarea"

	CanClose is called :

		- on receiving "ek_close" by window
		- for modal window, on focus change

		- within parent window's "CanClose"	where all nested windows are  
		checked for OnCloseQuery & OnClose - if any sets "mr_none" then the parent window 
		can't close as well
			
		- from nested window's "CanParentClose"
		- from own "CanParentClose"

		- some componnets build oneself in own "Loaded" procedure :
			= widget grids
			= database access components
			= ...

	The "form.show" has parameter "transientfor".
	The window Z-order is above the "transientfor" window. The exact behaviour
	depends on the window manager.
        
        caption
		- run-time caption on the title bar

	color
		- color behind the client ( contaner ) area

	container
		- the real parent of form's widgets, <see "tformscrollbox">

	cursor
		- the mouse over cursor shape

	enabled - "false" disables all child widgets

	face
		<see "tfacecomp"> + some more options

	font
		<see "tfont">

	frame
		<see "tframecomp"> + some more options
		
	icon 
		<see "timage">

	mainmenu
		<see tmainmenu>

	name
		- name to refer when programming

	options:

		fo_main 
			- assigns this from as the aplication GUI-face & event receiver
			- causes the icon of this form to be icon of the application 

		fo_terminateonclose
			- causes the application to terminate once the form has closed ( doesn't depend on "fo_main" )


		fo_freeonclose
			- causes the form (even being modal) to release its memory on closure or OK-return from "CanClose"

		fo_defaultpos
			- lets the WM to position the form initially

		fo_screencentered
			- causes the form initially to show in center of the apllication work area

		fo_closeonesc
			- causes the form to close on "Esc" key pressed ( with MR_ESCAPE & "OnCloseQuery" firing )

		fo_cancelonesc
			- causes the form to close on "Esc" key pressed ( with MR_CANCEL & "OnCloseQuery" firing )

		fo_closeonenter
			- causes the form to close on "Enter" key pressed ( with MR_OK & "OnCloseQuery" firing )

		fo_closeonf10
			- causes the form to close on "F10" key pressed ( with MR_F10 & "OnCloseQuery" firing )

		fo_globalshortcuts
			- allows on-this-form "ao_globalshortcut" actions to trigger

			  Notes :
				= shortcuts for modal not "fo_localshortcut" forms are processed by app
				= shortcuts for "fo_globalshorcut" forms are processed by the owning window 

		fo_localshortcuts
			- disables triggering shortcuts of on-this-form actions

		fo_autoreadstat
			- for "cs_ismodule" forms, before "OnLoaded" fires, rereads all statvars from the bound stafile/memorystream

		fo_autowritestat
			- in "CanClose", after "OnClose" fires [ and before app termination for "fo_terminateonlose" form ], 
			rewrites all statvars to the stafile/memorystream
			- for datamodules, does this before "OnDestroy" fires

		fo_savepos
			- saves/restores Z-order, size & scree coordinates of the form 
			as soon as the stat data are ready

		fo_savestate
			- for top-level form, saves/restores "VSize", "Active" & "Visible" 
			as soon as the stat data are ready

	optionswidget
		<see "any widget">
	optionswindow
		<see "any window">
	popupmenu
		<see "tpopupmenu">
	stafile
		<see "tstafile">
	stavarname
	taborder
	tag

	visible - for a form, only affects its childs widgets

	Events:

		activate = to set focused & redraw the invalidated area

		oncreate
			- fires before "Loaded" procedure is called
			- fires after creating the widget & its subwidgets but before the final arrangement
			- forms arent' yet visible on return

		  Since "Loaded" procedure hasn't yet worked at this point then 
			database contents, values of widget grid's subwidgets 
			are invalid in this event ***

		onloaded
			- fires once "Loaded" procedure of owns & all form's widgets finishes
			- processed  after "OnCreate"
			- on finishing, forms aren't yet visible

		oneventloopstart ( main forms only )
			- only applicable to main forms
			- fires once all application GUI is built and shown 
			( and ready to user's interaction )
			
		onactivate 
			- see {any_widget.OnActivate}

		onenter
			= see {any_widget.OnEnter}

		onfocus
			- see {any_widget.OnFocus}
			

		onwindowactivechanged
			- fires on :
				= touching another window even on clicking in a behind-modal window ( or its title bar )
				= 1-st showing the window
				- reactivating the window

		onbeforepaint
			- fires at the very beginning of "paint", before drawing canvas

		onpaint
			- fires in "paint" procedure, between drawing canvas and contained widgets

		onafterpaint (doafterpaint)
			- fires just on return from "paint" procedure

        	onapplicationactivechanged 
			- fires :
				= if the application gets/looses input focus

		onasyncevent (doasyncevent)
			- fires on calling {this_form}.asyncevent(atag) from any place of the application
			once delivered by the app even queue

			 "atag" set by caller(s) helps to branch within "onasyncevent", to identify the caller, etc ***
			 generally, doesn't fire instantly because these events are delivered through the app event queue ***


		onchildmouseevent
			- fires on any mouse activity over its child widget(s) not the (containing) widget oneself

		      for forms, it even fires on enetering "container" therefore it appears as if to be the form itself ***

		onchildscaled
			- see {any_widget.OnChildScaled}

		onclientmouseevent
			- fires on any mouse activity over areas expecting user's mouse input (not titlebars/frames/...)

		onclose
			- fires in "CanClose" if "modalresult <> mr_none"

		onclosequery
			- fires in "CanClose" before "OnClose"
			- "mr_none" set on return prevents the window (and its parent) from closing 
			( "OnClose" is also bypassed )


		ondeactivate
			- see {any_widget.OnDeactivate}

		ondefocus
			- see {any_widget.OnDeFocus}
			
		ondestroy
			- fires on in-code calling "BeforeDestruction"

		ondestroyed
			- fires on return from the form's destructor ( when all resources are freed )

		onterminatequery
			- fires on an attempt to terminate the app
			- by setting "var terminate:= false", allows to cancel termination 

			 Termination by debugger/OS facilities can't be blocked this way ( win32 )***

		onterminated
			- fires for not-yet-destroyed forms, once the app event loop finishes 
			- may be caused by any closure of the main app form 
			( app termination, WM/OS facilities, )


		onwindowdestroyed
			- fires once a descendant window is destroyed 
			( for a main form, when a modal simple form is closed by any way,.. )

		onevent
			- fires on receiving an event 
				= for simple forms, it's only "ek_loaded"

			There can be more if the form is connected to object_event sending
			components or if the application uses object events, for example by calling
			tguicomponent.postcomponentevent. ****

		onexit
			- see {any_widget.OnExit}

		onfocusedwidgetchanged
			- for a "prev-new" parent-wide focused wigdets pair, fires once installing new focus has finished, 
			after "OnFocus"
			- resends for all contained widgets
			- doesn't fire if the "prev-new" pair don't really change

		onfontheightdelta
			- see {any_widget.OnFontHeightDelta}

		onhide
			- fires at beginnig of own/parent's 
				= hide
				= hidden
				= destroying
				= setting "visible:= false"
				= closing the window ( receiving event "ek_close",.. )
				= calling "window.close" 
				
		onidle
			- fires everytime when the app GUI event queue gets empty
			- to stop calling for a while, set "again" parameter to "false" (the initial value );
			
			 DON'T DO ANYTHING AFFECTING THE APP EVENT QUEUE ( MODAL WINDOWS, "ShowMessage", Sleep(N),... ) IN THIS HANDLER. 
				MODAL WINDOWS CAUSE RECURSION ! 
			
			A code fragment:

				again:= i < 5;
				if not again then exit;

		onkeydown
			- fires on pressing down a keyboard key over the client area when none of child widgets is focused

		onkeyup
			- fires on releasing a keyboard key over the client area when none of child widgets is focused

		onmouseevent
			- fires on any mouse activity over the client area

		onmove
			- see {any_window.OnMove}

		onpopup
			- see {any_widget.OnPopup}

		onresize
			- see {any_widget.OnResize}

		onshortcut
			- fires before built-in shorcut processing
			- "info.eventstate=es_processed" set in "OnShortcut" prevents 
			the event from further auto-processing

			The app 
				- recognizes & takes registered shortcuts from app event queue
				- passes the shocrcut event to each of its windows until the event 
				is processed otherwise processes it by oneself 
			

		onshow
			- fires if the widget is visible:
				= on calling "Show" method
				= on return from "Loaded" procedure
				= on showing the parent widget
			- since called at end, allows to adjust the default behavior

		onshowhint
			- see {any_widget.OnShowHint}

		onstatbeforeread 
			- fires before loading statvars  from the disk file

		onstatafterread
			- fires once statvars are loaded from the disk file

		onstatupdate 
			- fires at 1-st stage before updating GUI "state/pos" for read statvars
			or 
			- fires at pre-last stage before saving GUI "state/pos"

		onstatread 
			- fires at 2-nd stage before updating GUI "state/pos" for read statvars

		onstatwrite
			- fires at last stage before saving GUI "state/pos"

		pon stat reading, non-minimized visible windows are shown, 
		the active window is activated 

TDockFormWidget

TPaintbox

How to draw line (or circle) on tpaintbox? In event onpaint:

 
 procedure tmainfo.paintboxonpaint(const sender: twidget; const canvas: tcanvas); 
 begin 
  with sender,canvas do begin 
   drawline(nullpoint,pointty(size),cl_yellow);  
   //diagonal line across widget 
   drawellipse(makerect(makepoint(bounds_cx div 2,bounds_cy div 2), size),cl_red); 
   //circle (or ellipse) centered in widget                             
  end; 
 end;

Makepoint and makerect are in msegraphutils.

TEventWidget

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.

TButton

  • A rectangular clickable area that can show text/bitmap.

- Main properties:

Caption: read/write the text that appear on top of it.
onexecute: read/write the address of a procedure (event handler) to be executed when clicked.

TStockGlyphButton

TRichButton

TLabel

  • Draws a piece of text on the given surface (canvas: screen/printer/bitmap).

- Main properties:

Caption: read/write the piece of text.

See also TLabel

TGroupBox

TStepBox

TStringDisp

  • A read only version of TStringEdit, difference from TLabel: has a frame around it.

-Main properties:

Value: read/write the text that are showed.
Caption: A label normally describing the purpose or meaning of the presented text, it can be positioned around the frame.

TByteStringDisp

TIntegerDisp

TRealDisp

TDateTimeDisp

TBooleanDisp

TToolBar

TDrawGrid

TStringGrid

TTabBar

TTabPage

TTabWidget

TDockHandle

TDockPanel

TSpliter

	       A widget very similar to "tspacer" but :
		- designed to rearrange areas occupied by adjacent widgets
		- a linked widget may only enlarge by "eating" the opposite one, 
		so the summary area of both widgets don't change
		- has GUI look ( hatched grip, color etc) switched on by default
		- facilitates run-time repositioning oneself and linked widgets
		- linked widgets may even be other splitters, spacers (with their linked widgets ),..
	
        Properties:

	- color
		= see {any_widget.color}

	- cursor
		= see {any_widget.cursor}

	- enabled
		= "false" stops user interaction

	- face
		= see {any_face}

	- frame
		= see {any_frame}

	- colorgrip
		= color of grip hatching

	- grip
		= defines hatching pattern of the grip

			* stb_dens(N) : the pattern is of rhombuses, the painted rhombs occupy "N" persents of the grip

			* stb_block(N) : the pattern is of squares, painted & unpainted squares are equally sized and 
			both have "N" pixels sides
			
			* stb_hatchup(N) : the pattern is of right-tilted lines of 1 pixel width,
			each "N"-th pixel forms these lines

			* stb_hatchdown(N) : the pattern is of left-tilted lines of 1 pixel width,
			each "N"-th pixel forms these lines

			* stb_crosshatch(N) : the pattern is of crossing (left & right) tilted lines of 1 pixel width,
			each "N"-th pixel forms these lines


	- linkbottom/linkleft/linkright/linktop 
		= see {tspacer.*}

	- options

		= spo_hmove
			* "true" allows the spliter to move horizontally

		= spo_hprop
			* "true" : keep the left position proportional ( on the ratio of creation time ) 
			to weigth of the client area of parent

		= spo_hsizeprop
			* "true" : keep width of the spacer proportional ( on the ratio of creation time ) 
			to weigth of the client area of parent
			* the width stops shrinking on one set in design time

		= spo_vmove
			* "true" allows the spliter to move vertically

		= spo_vprop
			* "true" : keep the top position proportional ( on the ratio of creation time ) 
			to height of the client area of parent

		= spo_vsizeprop
			* "true" : keep height of the spacer proportional ( on the ratio of creation time ) 
			to height of the client area of parent
			* the height stops shrinking on one set in design time

		= spo_dockleft
			* causes the "linkleft" widget to dock to the left border of splitter
			* make sence only if linkleft "widget.bounds_x" less than "splitter.bounds_x"

		= spo_docktop
			* causes the "linktop" widget to dock to the top border of splitter
			* make sence only if linktop "widget.bounds_y" less than "splitter.bounds_y"

		= spo_dockright
			* causes the "linkright" widget to dock to the right border of splitter
			* make sence only if linkright "widget.(bounds_x+bounds_cx)" more than "splitter.(bounds_x+bounds_cx)"

		= spo_dockbottom
			* causes the "linkbottom" widget to dock to the bottom border of splitter
			* make sence only if linkbottom "widget.(bounds_y+bounds_cy)" more than "splitter.(bounds_y+bounds_cy)"

		!!! Two special cases :

		1. (spo_dockleft = spo_dockright = TRUE) && (linkleft = linkright = the_same_widget) : 
			causes the "linkleft" widget to adjust to h-positiion & width of the splitter, 
			it's even possible that the widget doesn't touch the splitter

			(spo_docktop = spo_dockbottom = TRUE) && (linktop = linkbottom = the_same_widget) : 
			causes the "linktop" widget to adjust to v-position & height of the splitter, 

			It's even possible in these cases that the widget doesn't touch the splitter

	- optionsscale
		= see {tscalingwidget.optionsscale}

	- optionswidget
		= see {anywidget.optionswidget}

	- onactivate, onchildscaled, ondeactivate, ondefocus, onenter, onexit, onfocus,
	  onfontheightdelta, onmove, onpopup, onresize, onshowhint
		= see "tspacer"

	- onupdatelayout
		fires :
		
		= on creating the splitter
		= on any reposition of the linked widgets 
		( due to moving the splitter, resizing the parent,.. )

TSpacer

* a regular widget which creates a kind of positional link between surrounding widgets
* designed to maintain distances between widgets
* may have GUI look, caption etc switched off by default
* resizing a spacer repositions its linked widgets

Properties:

- anchors = see {any_widget.anchors}

- bounds = see {any_widget.bounds}

- color = see {any_widget.color}

- enabled = "false" turns color of the caption to gray

- visible = "true" allows displayable settings (caption text, face, frame etc) to take effect in run-time as well

- <face> = see {any face}

- <frame> = see {any frame}

- linkbottom = widget linked down to most outer edge (incl. frame[.caption]) of the spacer - linkleft = widget linked left to most outer edge of the spacer - linkright = widget linked right to most outer edge of the spacer - linktop = widget linked up to most outer edge of the spacer

- dist_bottom, dist_left, dist_right, dist_top : = margins between most outer edge the spacer and the corresponding linked widget

- options :

= spao_glueright

- if "false"

h-repositioning or h-resizing the linkleft widget shifts the whole linked construction, it becomes the only way to h-shift

if {an_right IN linkright_widget.anchors} then the spacer may be right-resized with auto h-resizing the linkright widget so that the right margin of that widget is kept

if NOT {an_right IN linkright_widget.anchors} then the spacer may be right-resized with auto h-shifting the linkright widget so that width of that widget is kept

- if "true"

h-repositioning or h-resizing the linkright widget shifts the whole linked construction, it becomes the only way to h-shift

if {an_left IN linkleft_widget.anchors} then the spacer may be h-resized with auto h-resizing the linkleft widget so that the left margin of that widget is kept

if NOT {an_left IN linkleft_widget.anchors} then the spacer may be h-resized with auto h-shifting the linkleft widget so that width of that widget is kept

= spao_gluebottom

- if "false"

v-repositioning or v-resizing the linktop widget shifts the whole linked construction, it becomes the only way to v-shift

if {an_bottom IN linkbottom_widget.anchors} then the spacer may be v-resized with auto v-resizing the linkbottom widget so that the bottom margin of that widget is kept

if NOT {an_bottom IN linkbottom_widget.anchors} then the spacer may be v-resized with auto v-shifting the linkbottom widget so that height of that widget is kept

- if "true"

v-repositioning or v-resizing the linkbottom widget shifts the whole linked construction, it becomes the only way to v-shift

if {an_top IN linktop_widget.anchors} then the spacer may be v-resized with auto v-resizing the linktop widget so that the top margin of that widget is kept

if NOT {an_top IN linktop_widget.anchors} then the spacer may be v-resized with auto v-shifting the linktop widget so that height of that widget is kept

- optionsscale = see {tscalingwidget.optionsscale}

- optionswidget = see {anywidget.optionswidget}

- onactivate, onchildscaled, ondeactivate, ondefocus, onenter, onexit, onfocus, onfontheightdelta, onpopup, onresize, onshowhint = see {any_widget.*}

- onmove = see {any_window.OnMove}

any "link*" option set disables the spacer to reposition solely, repositioning is only controlled by a "glued" widget since then

TLayouter

  • a tspacer descendant designed to (auto)resize or/and move its contained widgets acc to some size/positon dependencies
  • may have GUI look, frame caption etc switched off by default
  • layouters may be nested to achieve complex layouts

Each layout change/assignment is divided into performing 3 consequent stages :

Stage 1

Widgets auto resized using the following options:

- if {lao_placex OR lao_placey} :

		= if {plo_scalesize in optionslayout}  then
			* widgets with "osk_nopropwith" unset in their "optionsskin" are h-scaled 
		  	  in the proportion of change of tlayouter's clientwidth
			* widgets with "osk_nopropheight" unset in their "optionsskin" are v-scaled 
		  	  in the proportion  of change of tlayouter's clientheight

			For h-resized layouter, the effect looks like :

		 	 |--Widget__1---Widget__2--|		=> the initial look

		  	 |--Widget_1--Widget_2--|			=> the layouter gets narrower

		  	 |---Widget___1---Widget___2---|	=> the layouter gets wider

			*** both widget sizes & margins are affected ***
			*** Widget_N may generally situate on different y-levels *** 
		  	
	otherwise :

		= if lao_scalewidth in optionslayout :
			* widgets with "osk_nopropwith" unset in their "optionsskin" enters in the mode 
		 	  ( not applied until the layouter resizes! ) when they are h-scaled in the proportion 
		 	  as far as clientwidth of the tlayouter changes, then stages 2 & 3 are reapplied

			For h-resized layouter, the effect looks like :

			  |--Single____widget????|		=> the initial look

			  |--Single__widget???|			=> the layouter gets narrower

			  |--Single_______widget?????|	=> the layouter gets wider

			* also, if {lao_scaleleft in optionslayout} then left margins of the widgets 
			  with unset "optionsskin.osk_nopropleft" resize too otherwise retain

		= if lao_scaleheight in optionslayout :
			* widgets with "osk_nopropheight" unset in their "optionsskin" enters in the mode 
		 	  ( not applied until the layouter resizes! ) when they are v-scaled in the proportion 
		  	  as far as clientheight of the tlayouter changes, then stages 2 & 3 are reapplied

			* also, if {lao_scaletop in optionslayout} then top margins of the widgets 
			  with unset "optionsskin.osk_noproptop" resize too otherwise retain

			*** only widget sizes & margins not distances between them are affected ***

Stage 2

Widgets may be auto resized in 5 consequent steps using the following options:


1. if plo_syncmaxautosize in place_options :
   = all widgets are autosized then their client areas are synchronised to the
     clientareas of the highest and the widest of the widget
   * calls "msegui.syncmaxautosize"

2. if plo_syncpaintwidth in place_options :
   = the paintwidths of all widgets are synchronized to the widget with the
     widest outer frame width ( ex. width of "frame.caption" )
   * mainly makes sense if "lao_alignx" set and {align_glue = wam_start or wam_end}
     ( see below ) when the widgets will be adjusted in order to fit into the
     inner client width of tlayouter:

                                   x-align level           
                                         V                 
                        +----------------------------------+
                        | Widget_1 the_widest_frame_caption|
                        | Widget_2 frame_caption2          |
                        | Widget_N wider_frame_captionN    |
                        +----------------------------------+

   here, the effect is shown for "cp_right" frame captions
     // otherwise syncronizes to the outer ( of the frame except its caption ) width 
     // of the Z-top widget
   * calls "msegui.syncpaintwidth"
   * paintwidth is the outer width

3. if plo_syncpaintheight in place_options :
   = the paintheights of all widgets are synchronized to the widget with the
     highest outer frame width ( ex. width of "frame.caption" ).
   * mainly makes sense if lao_aligny set and {align_glue = wam_start or wam_end}
     ( see below ) the widgets will be adjusted in order to fit into the inner
     client height of tlayouter :

                        +------------------------------+
                        | The_                         |
                        | tallest_            taller_  |
                        | frame_    frame_    frame_   |
                        | caption   caption2  captionN |  
                        |                              |
                        | Widget1   Widget_2  Widget_N |<== y-align level 
                        +------------------------------+     		

  here, the effect is shown for "cp_topleft" frame captions
    // otherwise syncronizes to the outer ( of the frame except its caption ) 
    // height of the Z-top widget
  * calls "msegui.syncpaintheight"
 
4. plo_synccaptiondistx in place_options :
   = causes all widgets to have the widest common room for their cp_(left/right)* frame captions
   * calls "msegui.synccaptiondistx"
 
5. plo_synccaptiondisty in place_options :
   = causes all widgets to have the highest common room for their cp_(top/bottom)* frame captions
   * calls "msegui.synccaptiondisty"

Stage 3

The widgets may be (re)arranged within the layouter.

There're 2 modes of such (re)arrangement which can be partially (orthogonally)
combined (see later):

1) The place(ment) mode ( lao_place* in optionslayout ) :

- widgets are placed at some distances between each other, possibly with some
  margins, rooms of invisible widgets ( having visible=false) are also allocated
  unless "plo_noinvisible in place_options"

  * the widgets are placed in the order of decreasing their "widgetrect.x"
	coordinates before alignment
  
  * the inter-widget distances and the side margins ( if apllied ) in both
	dimentions are identical and limited between "place_mindist" and
	"place_maxdist"
  
  = if {lao_placex in optionslayout} and {place_mode <> wam_none} then the
	following relevant settings apply:
  
	* non-limiting value of "place_maxdist" :
	
		# |Widget_1------Widget_2------Widget_3| 
	
	* non-limiting value of "place_maxdist" and {plo_propmargin in place_options} :
	
		# |---Widget_1---Widget_2---Widget_3---|
		
	* limiting value of "place_maxdist" and {place_mode = wam_start} :
	
		# |Widget_1----Widget_2----Widget_3????|
		
	* limiting value of "place_maxdist" and {place_mode = wam_start} and
	  {plo_propmargin in place_options} :
	
		# |---Widget_1---Widget_2---Widget_3???|
		
	* limiting value of "place_maxdist" and {place_mode = wam_end} :
	
		# |??????Widget_1---Widget_2---Widget_3|
		
	* limiting value of "place_maxdist" and {place_mode = wam_end} and
	  {plo_propmargin in place_options} :
	
		# |???Widget_1---Widget_2---Widget_3---|
		
	* limiting value of "place_maxdist" and {place_mode = wam_center} :
	
		# |???Widget_1---Widget_2---Widget_3???|
		
	* limiting value of "place_maxdist" and {plo_endmargin in place_options} :
	
		# |Widget_1----Widget_2----Widget_____3|, or
		
		# |Widget_1----Widget_____2----Widget_3|, or
		
		# |Widget_____1----Widget_2----Widget_3|, here, the most left amongst
		widgets having both [an_left,an_right] set is expanded otherwise the most
		right widget ( Widget_3 in the example )
		
	* limiting value of "place_maxdist" and {place_mode = wam_end} and
	  {plo_propmargin in place_options} and {plo_endmargin in place_options} :
	  
		# |--Widget_1--Widget_____2--Widget_3--|,
		  
	The Legend:
	===========
	limiting value of "place_maxdist" : such value which produce some visual
	effect on the layouter
	
	  "----" :           distance ( = number of minuses, limited by place_maxdis )
	  "????" :           some remaining space ( = number of questmarks )
	  "Widget_1" :       widget of the original size
	  "Widget__..__1" : (auto)resized widget
  
  = if {lao_placey in optionslayout} and {place_mode <> wam_none} then the things
	are handled in the same manner as with "lao_placex" but for the vertical
	"top2bottom" direction of placement instead of the horizontal "left2right" one.

2) the align(ment) mode ( optionslayout.lao_align* ) :

- widgets are gathered into a visual group to a dedicated "leader" widget of
  the layout ( set by "align_leader" and defaults to the lowest in
  Z-Order = twidget.widgets[0] ) the leader stays in place while the others :

  = if lao_alignx in optionslayout ( the hor alignment mode ):
	  * if align_mode = wam_start :
		snap their left borders to the left border of leader
	  * else if align_mode = wam_end :
		snap their right borders to the right border of leader
	  * else if align_mode = wam_center :
		snap their v-axes to the v-axis of leader after that,
  = if lao_aligny in optionslayout ( the vert alignment mode ):
	  * if align_mode = wam_start :
		snap their top borders to the top border of leader
	  * else if align_mode = wam_end :
		snap their bottom borders to the bottom border of leader
	  * else if align_mode = wam_center :
		snap their h-axes to the h-axis of leader

- after that, the whole widget group can be aligned within the layouter:

  = if align_glue =  wam_start
	  * if lao_alignx in optionslayout:
		the left extent of group snaps to the left border of layouter
	  * if lao_aligny in optionslayout:
		the top extent of group snaps to the top border of layouter
  = else if align_glue = wam_end
	  * if lao_alignx in optionslayout:
		the right extent of group snaps to the right border of layouter
	  * if lao_aligny in optionslayout:
		the bottom extent of group snaps to the bottom border of layouter
  = else if align_glue =  wam_center
	  * if lao_alignx in optionslayout:
		the v-axis of group snaps to the v-axis of layouter
	  * if lao_aligny in optionslayout:
		the h-axis of group snaps to the h-axis of layouter

Mutually exclusive settings:
* only one of "align_mode" can be choosen
* only one of  "glue_mode" can be choosen
* "optionslayout.lao_alignx" & 	"optionslayout.lao_placex"
* "optionslayout.lao_aligny" & 	"optionslayout.lao_placey"

V-alignment ( optionslayout.lao_aligny ) may be combined with h-placement
( optionslayout.lao_placex ), and h-alignment ( optionslayout.lao_alignx ) may
be combined with v-placement ( optionslayout.lao_placey )

NOTE:
  The effects of the above described { resizing / placement / alignment } are
  irreversible. So, the only way to revert is to set "wan_none" then to revert
  manually.

TListView

TImage

<any image>

	*** Note that switch to the monochrome mode is irerreversible ! ***

	alignment:

		By default, images are top-left aligned, with the original size preserved.

		al_xcentered = centers the image horizontally
		al_ycentered = centers the image vertically

		al_right = docks the image to the right border of placeholder
		al_bottom = docks the image to the bottom border of placeholder

		al_grayed = fills non-transparent areas with the selected color

		al_stretchx = adjusts size so that to fill the placeholder in width
		al_stretchy = adjusts size so that to fill the placeholder in height
		al_fit = adjusts size so that to fill the placeholder in both width & height

		al_tiled = spawns the image & tile the whole  placeholder with the copies 

		Interpolation mode while stretching

			al_intpol =	antialiases as far as the size changes 
						(the only working in Linux)
			al_or = interpolation pixel operation is "or" -> 1's are extended
			al_and = interpolation pixel operation is "and" -> 0's are extended
		( al_or and al_and only on win32, mainly useful for stretching of monochrome bitmaps) :

	colorbackground = color of image transparent ( masked ) areas in monochrome 
						non-masked mode 
	colorforeground = color of non-transparent areas in monochrome mode  

	options:

		bmo_monochrome = fills non-transparent areas with "colorforeground", 
						also, in non-masked mode, fills transparent areas 
						with "colorbackground"

		bmo_masked = activates built-in image transparency {it "hides" transparent (masked) areas}
		bmo_colormask = applies faded edge transparency on the color masked areas in the image

	transparency = makes the image transparent as long as enlights areas behind 
					the image with the selected color

	transparentcolor = for a non-masked image, assigns a color indicate transparency areas
					( on matching areas, the image will be seen through )

TDial

TChart

There are demos here:

https://github.com/mse-org/mseuniverse/tree/master/attic/msedocumenting/mse/trunk/help/tutorials/widgets/charts

TChartRecorder

TPolygon

TPickWidget

TOpenglWidget

Edit

TStringEdit

TMemoEdit

THexStringEdit

TDropdownListEdit

A tstringedit with a dropdownlist to choose text values. Important dropdown.options members:
- deo_autodropdown dropdown on keypress
- deo_selectonly don't allow entering arbitrary text.
- deo_forceselect don't allow entering empty text.

THistoryEdit

A tstringedit which shows the previously entered values in a dropdownlist for selection.

TIntegerEdit

TKeyStringEdit

Maps string to string.

TEnumEdit

Maps integer to string, zero based and sequencial (first item 0, next 1, ...).

TEnumTypeEdit

A TEnumEdit which maps Pascal enums to their names. Use OnInit event to store the typeinfo pointer of the enum type into sender.typeinfopo.

 
procedure tmainfo.enumtypeeditinit(const sender: tenumtypeedit);
begin
  sender.typeinfopo := PTypeInfo(TypeInfo(TMyEnumeratedType));
end;

TSelector

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.

TRealEdit

TRealSpinEdit

TDateTimeEdit

TCalendarDateTimeEdit

TEdit

MSEgui counterpart of Delphi TEdit. You will never use it.

TWidgetGrid

TItemEdit

TDropDownItemEdit

A tstringedit with a dropdownlist to choose text values. Important dropdown.options members:
- deo_autodropdown dropdown on keypress
- deo_selectonly don't allow entering arbitrary text.
- deo_forceselect don't allow entering empty text.

TMBDropDownItemEdit

TTreeItemEdit

TRecordFieldEdit

Used in twidgetgrid in order to edit fields of a ttreeitemedit. Example is MSEide projecttreeform.pas.

TDialogStringEdit

A tstringedit with an ellipse button. Use "onexecute" to show the dialog.

TPointerEdit

TSlider

TProgressBar

TBooleanEdit

TBooleanEditRadio

TDataButton

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".

TStockGlyphDataButton

TDataIcon

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.

TTextEdit

Only useful if inserted into a twidgetgrid, builds a text editor, used in MSEide source editor.

TDataImage

A pixmap display widget which can be inserted into twidgetgrid.

TTerminal

Only useful if inserted into a twidgetgrid, builds a very simple terminal emulator. Used in MSEide target console.

NoGui

TAction

	Shortcut processing order :

	- the smallest piece of processing is "doshortcut" procedure which 
	is called until processed:
		= starting from the sender up to the toplevel widget
		= then by all child widgets with non-set "ow_noparentshortcut" 
		= then, if "ow_nochildshortcut" isn't set, by the parent widget
		= then by the widget oneself
	
	- "doshortcut" is checked in the following order:
		= starting from form's main menu
		= then from the owning window ( the widget oneself ) 
		= then from the application


		*** A shortcut is bound to a widget by :
			- placing an action component on the widget ***
			- direct assigning the shortcut to the widget (menus,..) 
	---------------------------

		caption, color, colorglyph, helpcontext, hint, imagecheckedoffset,
		imagelist <see "timagelist">, imagenr, imagenrdisabled

			- sets look of "clients" (buttons, menu/toolbar items,..), unless 
			these clients have "state.as_local*" set :

		*** For meaning of these options, see help on the "client" widgets ***

	group
		- default value for one-named property of the bound widgets
		( menu items,... )

	options :
		ao_updateonidle
			- runs this action in cycle, waiting for no gui events everytime

		ao_globalshortcut 
			- allows the action to trigger on a non-main form
			  (the shortcut is triggered whatever form of the applicatin it was pressed on, 
			  otherwise only when the form where the aption is placed on is focused )

		ao_nocandefocus 
			- causes the action not to call "CanDefocus" for focused edit widget of active form
			  before executing own code
			  ( it helps to avoid the effect of cancelling changes in these widgets 
			  on activating the bound shortcut )

	shortcut
		- keyboard combination triggering the action

	shortcut
		- alternative "shortcut" and handled identically

	state :

		as_disabled
			- prevents the action from triggering, also puts the bound widgets to "disabled" look

		as_invisible
			- in run-time, hides the bound widget, still reacting on the shortcut or direct call

		as_checked
			- selects the bound menu item if it has "mao_checkbox" option set

		as_default
		as_local*

	statfile	
		<see "tstatfile">

	stavarname

	
	tagaction
	onasyncevent
	onchange
	onexecute
	onupdate

TActivator

TCustomLookupbuffer

	-	provides a group of parallel arrays of float(=datetime), integer and widestring types,
		and facilities to :
			= search in any array
			= on found position, quickly obtain corresponding value in another array
	-	for each type, several arrays  may be kept
	- 	each array is integer-indexed, even string ones ( case[in]sensitive )
	-	uses two way of accessing arrays data, through :
			= physic : array storage index ( row number ) directly
			= logical : the integer index ( see above ):
				first, physic row number is known for the logical index then the data 
				are accessed with the found number

			*** logical index values are built automatically based on array values, 
			on updating its data ***
	- dont' have interface to load data ( see its descendants for that )
	
	fieldcountfloat - number of float arrays
	fieldcountinteger - number of integer arrays
	fieldcounttext - number of widestring arrays

	Event handlers:
		- onchange

	Public interface:

   		procedure beginupdate; - marks beginning of "update"
   		procedure endupdate; - if all "update" finished, fires "onchange" event
	 	procedure clearbuffer; - clears all arrays then fires "onchange"

   		procedure checkbuffer; 
   			- [re]loads the arrays with most actual data
   			- just a stub here since doesn't have a data source

   		function find(const fieldno: integer; const avalue: integer/realty/msestring;
         	out aindex: integer; const filter: lbfiltereventty = nil): boolean;
			- applies external filtering ("filter" procedure) then incrementally searches integer/realty(datetime) array "fieldno" 
			for value "avalue" starting from logical index "aindex", returns "true" and the updated logical index 
			if found else next bigger; 

   		function find(const fieldno: integer; const avalue: msestring;
                 out aindex: integer;
                 const caseinsensitive: boolean;
                 const filter: lbfiltereventty = nil): boolean; overload;
			- applies external filtering ("filter" procedure) then incrementally searches widestring array "fieldno" for value "avalue", 
			in "caseinsensitive" manner, starting from logical index "aindex", returns "true" and the updated logical index 
			if found else next bigger;

   		function findphys(const fieldno: integer; const avalue: integer;
         	out aindex: integer; const filter: lbfiltereventty = nil): boolean; overload;
			- applies external filtering ("filter" procedure) then incrementally searches integer/realty(datetime) array "fieldno" 
			for value "avalue" starting from row number "aindex", returns "true" and the updated row number 
			if found else next bigger; 

		function findphys(const fieldno: integer; const avalue: msestring;  out aindex: integer; const caseinsensitive: boolean;
                 const filter: lbfiltereventty = nil): boolean; overload;
			- applies external filtering ("filter" procedure) then incrementally searches widestring array "fieldno" for value "avalue", 
			in "caseinsensitive" manner, starting from row number "aindex", returns "true" and the updated row number  
			if found else next bigger;

			The external filtering ("filter") procedure takes the arguments of the caller 
			togehther with physical row number found in the caller which allows 
			to check several values at once for that number, within the filter
			
		function integervaluephys(const fieldno,aindex: integer): integer;
			-  returns value of integer array "fieldno" at row number "aindex" 
              
		function integervaluelog(const fieldno,aindex: integer): integer;
			-  returns value of integer array "fieldno" where the array index equals to "aindex" 

		function integerindex(const fieldno,aindex: integer): integer;
			- returns row number of integer array "fieldno" where the array index equals to "aindex"

		function integerindexar(const fieldno: integer): integerarty;
			- returns all bunch of indexes of integer array "fiedlno"

		function integerar(const fieldno: integer): integerarty;
			- returns all bunch of data of integer array "fiedlno"
   
		function floatvaluephys(const fieldno,aindex: integer): realty;
			-  returns value of real/datetime array "fieldno" at row number "aindex" 

		function floatvaluelog(const fieldno,aindex: integer): realty;
			-  returns value of real/datetime array "fieldno" where the array index equals to "aindex" 

		function floatindex(const fieldno,aindex: integer): integer;
			- returns row number of real/datetime array "fieldno" where the array index equals to "aindex"

		function floatindexar(const fieldno: integer): integerarty;
			- returns all bunch of indexes of real/datetime array "fiedlno"

		function floatar(const fieldno: integer): realarty;
			- returns all bunch of data of real/datetime array "fiedlno"   

		function textvaluephys(const fieldno,aindex: integer): msestring;
			-  returns value of widestring array "fieldno" at row number "aindex" 

		function textvaluelog(const fieldno,aindex: integer;
                       const caseinsensitive: boolean): msestring;
			-  returns value of widestring array "fieldno" where the array index equals to "aindex" 

		function textindex(const fieldno,aindex: integer;
                      const caseinsensitive: boolean): integer;
			- returns row number of widestring array "fieldno" where the array index equals to "aindex"

		function textindexar(const fieldno: integer;
                            const caseinsensitive: boolean): integerarty;
			- returns all bunch of indexes of widestring array "fiedlno"

		function textar(const fieldno: integer): msestringarty;
			- returns all bunch of data of widestring array "fiedlno"   

   
		function lookupinteger(const integerkeyfieldno,integerfieldno,
                                keyvalue: integer): integer; overload;
			- returns value of integer array "integerfieldno" at position where
				value of parallel integer array "integerkeyfieldno" equals to "keyvalue"
                ( 0 if not found )

		function lookupinteger(const stringkeyfieldno,integerfieldno: integer;
                         const keyvalue: msestring): integer; overload;
			- returns value of integer array "integerfieldno" at position where
				value of parallel widestring array "stringkeyfieldno" equals to "keyvalue"
                ( 0 if not found )

		function lookuptext(const integerkeyfieldno,textfieldno,
                                keyvalue: integer): msestring; overload;
			- returns value of integer array "textfieldno" at position where
				value of parallel integer array "integerkeyfieldno" equals to "keyvalue"
                ( '' if not found )

		function lookuptext(const stringkeyfieldno,textfieldno: integer;
                      const keyvalue: msestring): msestring; overload;
			- returns value of integer array "textfieldno" at position where
				value of parallel integer array "integerkeyfieldno" equals to "keyvalue"
                ( '' if not found )


		function lookupfloat(const integerkeyfieldno,floatfieldno,
                                keyvalue: integer): realty; overload;
			- returns value of real/datetime array "floatfieldno" at position where
				value of parallel integer array "integerkeyfieldno" equals to "keyvalue"
                ( emptyreal if not found )

		function lookupfloat(const stringkeyfieldno,floatfieldno: integer;
                                keyvalue: msestring): realty; overload;

			- returns value of real/datetime array "floatfieldno" at position where
				value of parallel widestring array "stringkeyfieldno" equals to "keyvalue"
                ( emptyreal if not found )

		function count: integer; - returns number of data rows

		property fieldcounttext: integer; -  returns/sets number of widestring arrays
		property fieldcountfloat: integer; - returns/sets number of real/datetime arrays
		property fieldcountinteger: integer; - returns/sets number of integer arrays

		 the above "fieldcount*" props clear the buffer on setting a value 

		property integervalue[const fieldno,aindex: integer]: integer; - a shortcut to "integervaluephys"
		property floatvalue[const fieldno,aindex: integer]: realty; - a shortcut to "floatvaluephys"
		property textvalue[const fieldno,aindex: integer]: msestring; - a shortcut to "textvaluephys"

		property onchange: notifyeventty; 
			- called in "changed" wich in turn is called in :
				= clearbuffer
				= endupdate
				= doasyncevent
				= loaded
				= tlookupbuffer.addrow

TLookupBuffer

tlookupbuffer = class(tcustomlookupbuffer)

	- extends "tcustomlookupbuffer" with methods of run-time data filling

	- see <tcustomlookupbuffer>

	+= Extentions to the public interface:

		procedure addrow(const integervalues: array of integer;
                    const textvalues: array of msestring;
                    const floatvalues: array of realty);

			- adds one row to each of widestring arrays, integer arrays and real/datetime arrays,
			array size of  "{type}values" equals to number of {type} arrays

   		procedure addrows(const integervalues: array of integerarty;
                    const textvalues: array of msestringarty;
                    const floatvalues: array of realarty);

			- adds many data rows  to each of widestring arrays, integer arrays and real/datetime arrays, 
			only min length of the input data arrays are inserted, longer data are truncated
			array size of  "{type}values" equals to number of {type} arrays and the size of "{type}values[i]"
			describes number od data elements in the array
		

TDBLookupBuffer

tdblookupbuffer = class(tcustomdblookupbuffer -> tcustomlookupbuffer)

	- extends "tcustomlookupbuffer" with interface to fill arrays with DB-data
	- see <tcustomlookupbuffer> & <tcustomdblookupbuffer>

	 Extentions to the public interface:

   		procedure checkbuffer; - if data obsolete ("invalid") then reloads them from "datasource"
   
		property datasource: tdatasource; - sets/returns DB data source where to load data from
		property textfields: tdbfieldnamearrayprop; - allows to assign a {datasource:datafield} to each of widestring arrays
		property integerfields: tdbfieldnamearrayprop; - allows to assign a {datasource:datafield} to each of integer arrays
		property floatfields: tdbfieldnamearrayprop; - allows to assign a {datasource:datafield} to each of real/datetime arrays

		property optionsdb: lbdboptionsty; - tunes some DB behaviour apects
			-	olbdb_closedataset : 
				= once data obsolete, opens (if needed) the supplier dataset (disabling its bound controls) 
				then [re]loads data from it then closes it

			-	olbdb_invalidateifmodified :
				= gets marked "invalid" once contents of the bound dataset change, 
				it signals to reload the buffer with the new data just before next accessing 
				( for any purpose - searching, lookuping, getting value/(array of values),..)

TDBmemoLookupbuffer

- allows to use  for lookup-ing any text-convertable DB-fields
	- an analog of tdblookupbuffer, but :
		- "integerfields" may be names of any integer-convertable DB-fields
		- "floatfields" may be names of any (real/datetime)-convertable DB-fields
		- "textfields"  may be names of any text-presentable DB-fields

		- each DB-field value ( presenting a memo generally of many lines ) may supply many data rows at once 
		to the bound array of the buffer, since this value will be internally splitted & turned into native array values,
		and the resulting "count" (arrays row count) of the whole buffer will be the minimal rows count amongst arrays 
		of the buffer, the rest data are truncated 

		- when loading widestring arrays, also checks for & performs "utf8-to-widestring" conversion of values of 
		the bound DB-fields so that these arrays always store widestrings

TThreadComp

TStatFile

- so that to be in effect, it should also be assigned to the form where the widget using the stafile is placed on
- in design, if "onstatwrite" is set and "filedir" is not yet created,	deactivate exception "ECreateError" in project settings ( "Debugger" tab )
- "filedir" may contain "~/" indicating the user's home directory
- options "oe_savestate" & "oe_savevalue" of "client" widgets define what to store to the file 
- position etc changes or/and value changes 
- 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
- each "tstafile" owns:
 = tstatwriter:
* provides methods of writing sections & statvars to a memory/file stream
- tstatreader:
* holds list of sections with statvars each
* provides search & check & reading interface to the statvars
* provides reading statvars from a memory/file stream

Positioning to a section speeds up accessing its statvars

- there also is "tstatfiler" ( exposed by some "tstatfile" events ) which:
= may present or "tstatwriter" or "tstatreader" ( there's a check method )
= provides directionless "update" methods with internal switch to needed direction of processing 
- "reading" or "writing" statvars on per-section basis


	activator :
		<see tactivator> : NOT YET DONE		

	encoding = "en_utf8" selected here, allows to store non-Latin text in the file
       filedir = directory where to keep the file ( by default - the current working directory )
	filename = name of the file

	options:
		sfo_memory = reads & writes not from a disk file but from a named memory stream 
					( there's an exclusion - see below "sfo_savedata" ),
					mostly useful for presenting last used values on recalling 
					non-main forms etc ( data even survive recreating forms),
					or even for data "exchange" between non-main modal( non-concurring ) forms 
					in case of the target widgets share same statvarnames

		sfo_createpath = creates "filedir" if necessary
		sfo_savedata =	used only with "sfo_memory", commands to save 
						the memory data to the master statfile (see below)						

	sfo_activatorread = activator activate triggers reading ???
	sfo_activatorwrite = activator deactivate triggers writing ???

	statfile = a master statfile
	statvarname = name of section of this file in the upper statfile
	Tag = an integer property for misc purposes

	Event handlers:
		onstatafterread - fires on return from "readstat"
		onstatafterwrite - fires on return from "writestat"
		onstatbeforeread - fires on beginning of "readstat"
		onstatbeforewrite - fires on beginning of "writestat"
		onstatread = fires after reading state data
		onstatwrite = fires after writing state data
		onstatupdate = fires after reading/writing state data just before 
					"onstatread" & "onstatwrite"

	Public methods:

   		procedure initnewcomponent(const ascale: real); override;
   			- does nothing but fixes the default file name as the statfile default
   
   		procedure readstat(stream: ttextstream = nil); overload;
   			- rereads all statvars of the stafile/memorystream
   
   		procedure readstat(const aname: msestring; const statreader: tstatreader); overload;
   			- rereads "aname" statvar of the statfile

   		procedure writestat(const stream: ttextstream = nil); overload;
		   	- rewrites all statvars to the stafile/memorystream
			  (if neccessary, prepares to writting - creates "filedir", stafile,...)
   
   		procedure writestat(const aname: msestring; const statwriter: tstatwriter); overload;
   			- overwrites "aname" statvar of the statfile
   		
   		procedure updatestat(const aname: msestring; const statfiler: tstatfiler);
   			- depending on kind of "statfiler" ( writer/reader ), writes/reads 
   			  the most up-to-date stat data

TTimer

TNoGuiAction

TPipeReadercomp

TSysEnvManager

TProcessMonitor

TFilechangeNotifier

TShortCutController

TPostscriptPrinter

TGdiPrinter

TWmfPrinter

TSkinController

TGuiThreadComp

Font

See also : Reference:_MSEgui/TFont

Any Font

    	charset { ANSI/ DEFAULT/ SYMBOL /SHIFTJIS /HANGEUL /GB2312 /CHINESEBIG5 /OEM 
		/JOHAB / HEBREW/ ARABIC/ GREEK/ TURKISH/ VIETNAMESE/ THAI/ EASTEUROPE/
		RUSSIAN/ MAC/ BALTIC }
		- changes the font to the nearest containing the selected encoding(charset)
		- no font change made if the supplied encoding doesn't match any font
	color
		- color of the glyphs contours
	colorbackground
		- fill color of the glyph cells ( not including extraspace )
	colorshadow
		- color of SE glyph "edges" ( if not "cl_none", deactivates "colorbackground" )
	extraspace
		- v-space between glyph cells of adjacent text rows (negative values cause the cells to overlap )
	height
		- v-size of glyph cells, in pixels
	name
		- initially, font is choosen by { "family" = this name }
	options:
		foo_fixed
			- changes the font to the nearest "mono" spaced (usually = Courier)
		foo_proportional
			- changes the font to the nearest "proportionally" spaced (usually = Helvetica)
		foo_helvetica
			- changes the font to the nearest in "sans" category (usually = Helvetica)
		foo_roman
			- changes the font to the nearest in "serif" category (usually = Times[ New Roman])
		foo_script
			- Win32 only, changes the font to the nearest in "script" category
		foo_decorative
			- Win32 only, changes the font to the nearest in "decorative" category
		foo_antialiased
			- Linux-only, enables antialiasing (if disabled by Xft globally)
		foo_nonantialiased
			- Linux-only, disables antialiasing (if enabled by Xft globally) 
			usually making glyph extents (not cells !) a bit wider
	style:
		fs_bold
			- gives the font a "bold" look
		fs_italic
			- gives the font an "italic" look
		fs_underline
			- gives the font an "underlined" look
		fs_strikeout
			- gives the font a "striked out" look
		fs_selected
			- "TRUE" here combined with {tf_noselect:=FALSE}, causes the text described by this font 
			to be initially selected ( with the clipboard operations available ), 
			currently applicable only to richstrings

	width
		- 10*{ glyph cell width, average in pixels }, 0 = {font default}

	xscale
		- width ratio of each glyph {cell & contour}, the effect is similar to "width"

		*** "foo_*" font selection overrides one made with "name" 

		*** if change with "foo_*" is unsuccessful then the nearest "sans" font is usually chosen

		*** The categories :

			sans		=> have no serifs and have strokes of even thickness
			serif		=> have serifs at glyph contours and made up of strokes of varying thickness
			script		=> resemble handwriting
			decorative	=> flashy styles to be used sparingly in headlines or posters

GUI

TWindow

twindow = class(teventobject,icanvas)
  public

	// releases mouse, unlinks from the canvas, processes all pending events of the window
	// if called from within main thread then destroys the window directly
	// otherwise posts a window destroy event for oneself and waits for it to be processed
	procedure destroywindow;

	// registers the instance of onself in the "owner" widget, allocates the canvas, 
	// adds a reference to oneself,
	// then prepares the "owner" hierarchy to be invalidated ( "owner.rootchanged" )
	// since now, the window is allocated and belongs to the "aowner" widget 
	constructor create(aowner: twidget);

	destructor destroy; override;

	// adds "method" to the internal list of scroll dependants
	procedure registeronscroll(const method: notifyeventty);

	// removes "method" from the internal list of scroll dependants
	procedure unregisteronscroll(const method: notifyeventty);

	// releases mouse if captured, resets the cursor, then enters an event loop for the window,
	// TRUE on return if the window is destroyed
	function beginmodal: boolean;
 
	  * checks if the "sender" window is already modal to avoid circularity, 
	    if not then starts an event loop  for the "sender" where the "sender" is a receiver of GUI events,
   	    once the loop is terminated reactivates the previously active window if it was,
	    TRUE if modalwindow destroyed  

	  function tinternalapplication.beginmodal(const sender: twindow): boolean;

	// removes the internal stuff which indicates the modal state
	procedure endmodal;

	// if the window is visible, 
	// deactivates the previously active window, shows the window (see below),
	// if no active window in the app or the window or its Z-predecessor is modal and 
	// the app has no focused widget then prepares the bound widget to be focused,
	// then addresses the WM to put the window to foreground
	procedure activate;

	  // if the bound widget has visible=true then:
	  //  - if NOT windowevent then :
	  //    = address the WM to set size of the window acc to window opts 
	  //      wp_maximized, wp_fullscreen or normal size otherwise
	  //	= if the window is normally sized, moves it to its default position is specified ( screen centered etc )
	  // - unhides/unminimizes the window if needed
	  // - shows other windows of the applications acc to state of the window group 
	  // ( in normal size or minimized )

	  private 
		procedure twindow.show(windowevent: boolean);

	// TRUE if this window currently grabs user input
	( a widget drawn within the window(=form) is in focus,.. )
	function active: boolean;

	// if the window was active then deactivates the window  & remembers it as the previous active ( to restore leater if requested ),
	// returns TRUE if that storage occurred
	function deactivateintermediate: boolean; 

	// makes the window active & clears the above app reference to it ( "active before deactivating" )
	procedure reactivate; //clears app.finactivewindow

	// scans the app event queue for "ek_expose" event[s] addressed to the window,
	// if found then redraws that part of the window which the event describes
	// ( processed events are then deleted )
	procedure update;

	// TRUE if the window :
	// 1) doesn't have an inner widget grabbing input focus
	// or
	// 2) has such widget, and this widget ( and all its descendants ) 
	//    pass "CanClose" check
	//
	// *** see also "twidget.CanClose" ***
	//
	function candefocus: boolean;

	// tries to defocus the currently focused widget if it belongs to the window,
	// if succeeds then executes code of virtual "DoDefocus" of the widget descessor
	// ( this code defines behaviour & look of the widget on defocusing );
	//
	// no defocusing is done if the focused widget ( or its descendants ) 
	// doesn't pass "CanClose" check
	//
	procedure nofocus;
   
   	// setfocusedwidget(widget)
   
   property focuscount: cardinal read ffocuscount;
   function close: boolean; //true if ok
   procedure beginmoving; //lock window rect modification
   procedure endmoving;
   procedure bringtofront;
   procedure sendtoback;
   procedure stackunder(const predecessor: twindow);
       //stacking is performed in mainloop idle, nil means top
   procedure stackover(const predecessor: twindow);
       //stacking is performed in mainloop idle, nil means bottom
   function stackedunder: twindow; //nil if top
   function stackedover: twindow;  //nil if bottom
   function hastransientfor: boolean;

   procedure capturemouse;
   procedure releasemouse;
   procedure postkeyevent(const akey: keyty; 
        const ashiftstate: shiftstatesty = []; const release: boolean = false;
                  const achars: msestring = '');

   function winid: winidty;
   function haswinid: boolean;
   function state: windowstatesty;
   function visible: boolean;
   function activating: boolean; //in internalactivate proc
   function normalwindowrect: rectty;
   property updateregion: regionty read fupdateregion;
   function updaterect: rectty;

   procedure registermovenotification(sender: iobjectlink);
   procedure unregistermovenotification(sender: iobjectlink);

   property options: windowoptionsty read foptions;

	// widget 
	property owner: twidget read fowner;

   property focusedwidget: twidget read ffocusedwidget;
   property transientfor: twindow read ftransientfor;
   property modalresult: modalresultty read fmodalresult write setmodalresult;
   property buttonendmodal: boolean read getbuttonendmodal write setbuttonendmodal;
   property globalshortcuts: boolean read getglobalshortcuts write setglobalshortcuts;
   property localshortcuts: boolean read getlocalshortcuts write setlocalshortcuts;
   property windowpos: windowposty read getwindowpos write setwindowpos;
   property caption: msestring read fcaption write setcaption;


 windowoptionty = (wo_popup,wo_message,wo_buttonendmodal,wo_groupleader,
                   wo_windowcentermessage); //showmessage centered in window


	optionswindow:
		wo_popup 
			- in run-time, hides all OS windows-manager ( WM ) decorations (title bar, buttons "Close/Resize,Min/Max" etc),
			letting only its client area to appear
			so :
				= the window should have own facilities to replace the deactivated WM functionality if needed
				= can't be resized/maximize/minimized/moved
		wo_message
			- similar to "wo_popup" but allows WM to close ( with "Close" button ) & move the window

		wo_groupleader
			- keeps on the WM taskbar a shortcut to the window 
			( if the parent window is a groupleader too then displays a step upper in its group )

	Event handlers:

	 - onmove
		= fires once the (window/widget) is created/moved ( with check if really moved by a distance)

TFormScrollbox

- presents client area of form & parent of its widgets, 
	initially stretched to fit the form & bound with anchoring 
	but may be adjusted with "bounds" & "anchors"
   
    Properties:
                
	anchors
	bounds
	
	color
		- color of the whole container area ( except its frame ) & form widgets 
		if their color is "cl_parent"

	name = container

	cursor,	enabled, face, frame, helpcontext, hint, optionswidget, popupmenu,
	taborder, tag, visible, onactivate, onafterpaint, onbeforepaint, 
	onchildmouseevent, onclientmouseevent, ondeativate, ondefocus, onenter,
	onexit, onfocus, onfontheightdelta, onmouseevent, onpaint, onpopup
	onresize, onshowhint
		- the same meaning as for the served form


	oncalcminscrollsize	
	onscroll
	onchildscaled	

TFaceList

TFrameComp

See also here: Reference:_MSEgui/TFrame.


	Terminology :

	{client area = area of the widget which interacts with a user}

	{bevelling = additional facets rising/sinking frame & client area, 
		constists of two parts - 
			- external: between frame and widget
			- internal: between frame and client area
	}

	{frame=	flat space between external & internal facets,
			floats at the inner level of the external facet
 	}

	*** Both frame & bevelling affect the client area ***

	--------------------------
	template:

		colorclient	=	color of the client area

		colorframe =	color of the frame
		colorframeactive =	used instead of colorframe if the widget is
							active; "cl_default" means same as colorframe.

		works if (leveli/levelo <> 0 that's the facets exist :

			colorshadow = color of facets screened from the NW light source
			colordkshadow =	color of shadows dropped by the NW light source
        	        colordkwidth =	width of the shadows in pixel, -1=default

			colorlight = color of facets exposed to the NW light source
			colorhighlight = color of brighter edges of the facets
                 	colorhlwidth = width of the brighter edges in pixel, -1=default

		        extraspace = if applied to menu items, adds more space between these items

		framei_:
			(for extendable widgets like menus, these settings widen the widget,
			for non-extendable like buttons - they squeeze the text area )

			bottom=	lower margin of text to the client area
			left =	left margin of text to the client area
			right =	margin of text to the client area
			top =	upper margin of text to the client area

		framewidth=	width of the frame
	leveli = {width=height} of the internal facet, positive -> raised, negative -> sunken
	levelo = {width=height} of the external facet, positive -> raised, negative -> sunken

<any frame>

	*** extends & customizes "tframecomp" ***

	template
		- "tframecomp" supplying the initial settings

	colorclient,colordkshadow,colordkwidth,colorframe,colorframeactive,
	colorhighlight,colorhlwidth,colorlight,colorshadow,framewidth, 
	leveli, levelo, framei_*,

		<see "tframecomp">

	font
		<see "tfont">

	caption	
		- some descriptive text( function name, user prompt,...) placed 
		in a N/W/S/E-combination to the widget's client area

		*** 
		non-empty caption if (captionpos <> cp_center) & (captiondistouter=false & captiondist>0) enlarges the framed widget 
		by the corresponding size of caption

		***

	captiondist - margin between the caption & the client area

	captiondistouter :

	- if "false"(by default), the distance is measured between 
		the inner (facing the client area) extent of the caption 
		and the client area outward the area, 
		the caption is placed outside of the client area

	- if "true", the caption is mirrored against the edge of client area as 
		to the position when "false"

		*** nagative values of "captiondist" visually inverse "out of" and within ***

       captionnoclip - do not clip frame and client area for caption background 
					( the client area preserves own background under the caption text)

	captionnooffset - shift orthogonal to "captiondist"

	captionpos - "corner" where to place the caption

	localprops :

		frl_levelo - "levelo" overrides "template.levelo"
		frl_leveli - "leveli" overrides "template.leveli"
		frl_framewidth - "framewidth" overrides "template.framewidth"
		frl_colorclient - "colorclient" overrides "template.colorclient"
		frl_colorframe - "colorframe" overrides "template.colorframe"
		frl_colorframeactive - "colorframeactive" overrides "template.colorframeactive"
		frl_colordkshadow - "colordkshadow" overrides "template.colordkshadow"
		frl_colorshadow - "colorshadow" overrides "template.colorshadow"
		frl_colorlight - "colorlight" overrides "template.colorlight"
		frl_colorhighlight - "colorhighlight" overrides "template.colorhighlight"
		frl_colordkwidth - "colordkwidth" overrides "template.colordkwidth"
		frl_colorhlwidth - "colorhlwidth" overrides "template.colorhlwidth"
		frl_fileft - "framei_left" overrides "template.framei_left"
		frl_firight - "framei_right" overrides "template.framei_right"
		frl_fitop - "framei_top" overrides "template.framei_top"
		frl_fibottom - "framei_bottom" overrides "template.framei_bottom"

		frl_nodisable

TFaceComp

See also here: https://wiki.freepascal.org/Reference:_MSEgui/TFace

	- doesn't affect the widget frame but client area of the frame


	template:
		fade:
			color[i]: = colors forming the fade
			direction: = direction where the fade grows to
			gd_(right/up/left/down)

		pos[i]: = relational position of color[i] on the direction (0.0..1.0) extent

			transparency = 	makes the face half-transparent and enlighten the underlying widget  
							with a light source of the selected color 
							( in this case, colors of the face & the widget & the light source 
							simply summarize to higher brightness )

		image:
			see <any image>

		options:

        	*** The fade colors are used not as colors but RGB alpha values ($00 -> opaque, $ff -> transparent) 
			if fao_alpha* are set *** :

				fao_alphafadeall = applies blending to the widget & all its children
				fao_alphafadenochildren = preserves child widgets from blending
		                fao_alphafadeimage = applies blending to "face.image" 


<any face>

	*** extends & customizes "tfacecomp" ***

	fade, image, option
		- see "tfacecomp"
	
	template
		- "tfacecomp" supplying the initial settings

	localprops :
		fal_options - "options" overrides "template.options"
		fal_fadirection - "fade.direction" overrides "template.fade.direction"
		fal_image - "image" overrides "template.image"
		fal_fapos - "fade.pos[i]" overrides "template.fade.pos[i]"
		fal_facolor - "fade.color[i]" overrides "template.fade.color[i]"
		fal_fatransparency - "fade.transparency" overrides "template.fade.transparency"

TBitmapComp

TScalingwidget

   optionsscale : 
		autosizing to provide room for :
		= {"frame.caption" + "offset_*"}
		= "offset_*" if "frame.caption" is unset and "osc_shrink*" is set
	
		= osc_expandx 
			- makes the widget wider to fit the caption if needed

		= osc_shrinkx
			- makes the widget narrower to have no space left & right to the "frame.caption"

		= osc_expandy
			- makes the widget taller to fit the caption if needed

		= osc_shrinky
			- makes the widget lower to have no space up & down to the "frame.caption"

		= osc_invisishrinkx
			- fully h-collapses if "visible=false" ( run-time only )

		= osc_invisishrinky
			- fully v-collapses if "visible=false" ( run-time only )

TImageList

TPopupMenu

TMainMenu

Dialog

TFileListview

TFileDialog

TFaceComp

TFileNameEdit

TDirDropdownEdit

TColorEdit

TMemoDialogEdit

TPageSizeSelector

TPageOrientationSelector

Application

TGuiApplication

 tguiapplication = class(tcustomapplication)
  public

   // [re]starts the system timer with the new period and 
   // subscribes the application to be a receiver of the modified "ek_timer" event 
   // ( can check for it in the event queue )
   procedure settimer(const us: integer);

   // finds a window by its winID
   function findwindow(id: winidty; out window: twindow): boolean;

   // finds a window by its ID & adjusts "rect" so that it 
   // fits "bounds_minc*" & "bounds_maxc*" of the found window
   procedure checkwindowrect(winid: winidty; var rect: rectty);

   // initialises the timer and "megraphics"
   procedure initialize;

   // frees the allocated system resources (GDI, event subscription, the timer)
   procedure deinitialize;

   // creates a form instance, it will be shown in "application.run"
   procedure createform(instanceclass: widgetclassty; var reference);

   // invalidates all registered forms ( all their widgets will be redrawn )
   procedure invalidate; 
   
   // calls a nested main event loop, forces processing any pending messages,
   procedure processmessages; override; //handle with care!

   // TRUE if no pending events to process for the application
   function idle: boolean; override;
   
   // requests to indicate waiting ( to show the "watches" cursors )
   procedure beginwait; override;

   // removes the "watches" if no unclosed requests for displaying them,
   // otherwise closes the currently active request
   procedure endwait; override;

   // TRUE if there are unclosed requests for displaying "watches"
   function waiting: boolean;

   // TRUE if ESC has just been pressed
   //  - if all requests for displaying "watches" are closed then refreshes 
   //    the internal list of events ( the GUI-queue -> the app event list)
   function waitescaped: boolean; //true if escape pressed while waiting

   // sets state of the current wait dialogue ( but doesn't close one ) to undefined
   procedure resetwaitdialog;   

   // runs "aexecuteaction" in the main thread in OnIdle mode,
   // then shows a cancellable message,
   // if the one is cancelled then runs "acancelaction" then 
   // either fully clears (if exceptions occur ) 
   // or terminates the execution otherwise,
   // true if not cancelled;
   // "application.processmessages" must be called regularly if "aexecuteaction" is used here,
   // alternatively "aidleaction" can be used, call sleep ( some time ) in order to minimize
   // processor load. 
   // If athread <> nil the function starts and terminates the thread    
   function waitdialog(const athread: tthreadcomp = nil; const atext: msestring = '';
                   const caption: msestring = '';
                   const acancelaction: notifyeventty = nil;
                   const aexecuteaction: notifyeventty = nil): boolean; override;

   // closes the currently modal waitdialogue with "cancelled" state
   procedure cancelwait;

   // closes the currently modal waitdialogue with "ok" state
   procedure terminatewait;

   function waitstarted: boolean;   // the last waitdialogue is currently showing for some requests
   function waitcanceled: boolean;  // the last waitdialogue has been cancelled for some request (but can be shown fot others ?)
   function waitterminated: boolean; // the last waitdialogue has been terminated for some request (but can be shown fot others ?) 

   // if called from the main app thread then shows as a modal message describing the exception 
   // otherwise posts an async event for which the message will be called
   procedure showexception(e: exception; const leadingtext: string = ''); override;

   // posts an async event for which the message describing the exception will be called
   procedure showasyncexception(e: exception; const leadingtext: string = '');

   // "application.errormessage" shows standard error message ( with "ERROR" title ) 
   procedure errormessage(const amessage: msestring); override;

   // [re]calculates timings & position of hint for "ahintedwidget"
   // if "ow_timedhint" in "ahintedwidget.foptionswidget" then iys showtime will be 
   // "defaulthintshowtime" ( an app wide setting, 3sec by default)   
   procedure inithintinfo(var info: hintinfoty; const ahintedwidget: twidget);


   // shows the supplied hint text within "aposrect" with alignment "aplacement" during "ashowtime",
   // the avail ( but not used currenly ) flags are : hfl_show,hfl_custom,hfl_noautohidemove,hfl_noautohidemove   
   procedure showhint(const sender: twidget; const hint: msestring;
              const aposrect: rectty; const aplacement: captionposty = cp_bottomleft;
              const ashowtime: integer = defaulthintshowtime; //0 -> inifinite,
                 // -1 defaultshowtime if ow_timedhint in sender.optionswidget
              const aflags: hintflagsty = defaulthintflags
                      ); overload;

   // shows the supplied hint text at left-top position"apos" during "ashowtime",
   // the avail ( but not used currenly ) flags are : hfl_show,hfl_custom,hfl_noautohidemove,hfl_noautohidemove   
   procedure showhint(const sender: twidget; const hint: msestring;
              const apos: pointty;
              const ashowtime: integer = defaulthintshowtime; //0 -> inifinite,
                 // -1 defaultshowtime if ow_timedhint in sender.optionswidget
              const aflags: hintflagsty = defaulthintflags
                      ); overload;

   // shows the hint fully defined in "info" for the widget "sender"
   procedure showhint(const sender: twidget; const info: hintinfoty); overload;

   // removes the current hint widget & frees its resources & stops its stop timer
   procedure hidehint;

   // restarts the current hint and its stop timer
   procedure restarthint(const sender: twidget);

   function hintedwidget: twidget; //last hinted widget
   function activehintedwidget: twidget; //nil if no hint active

   // returns helpcontext of active widget, '' if none;   
   function activehelpcontext: msestring;

   // returns helpcontext of the widget under mouse, '' if none;
   function mousehelpcontext: msestring;

   // TRUE if one of the app's window/console is in input focus
   function active: boolean;

   // returns the desktop resolution ( or the virtual one if used )
   function screensize: sizety;

   // returns the (virtual) desktop resolution except the tray area,
   // nil -> current active window
   function workarea(const awindow: twindow = nil): rectty;

   // returns which application window ( a form not an eventwidget, an openglwidget or a windowwidget !) 
   // is active ( provides the input focus ),
   // it's same for all widgets of the form served by this window
   function activewindow: twindow;

/ * A transient window is a descendant of ( "transientfor" ) another window in the stacking order hierarchy */

   // returns a first non-transient ( on top of the app stacking order ) window upward 
   // from the currently active window of the application.
   // or that active window if no such
   function regularactivewindow: twindow;

   // same as "activewindow" but the window must not be released (?)
   function unreleasedactivewindow: twindow;

   // returns the focused widget of the currently active window if one exists
   function activewidget: twidget;

   // returns the widget presenteing the currently active window
   function activerootwidget: twidget;
   
   // returns the window ( not hidden or disabled !) under the screen point "pos"
   function windowatpos(const pos: pointty): twindow;

   // puts to "awidget" the container of widget pointed by "namepath"
   // ( finalizing "." is discarded if found ) ,
   // FALSE if not found, and NIL and TRUE if "namepath" = ''
   function findwidget(const namepath: string; out awidget: twidget): boolean;

   // rebuilds the application's window list accorrding to the current on-screen Z-order of its windows;
   // window list is ordered by "z" - bottom first & top last;
   // invisibles first
   procedure sortzorder;

   // returns a copy of the internal window list of application
   function windowar: windowarty;

   // returns the list of application window winIDs
   function winidar: winidarty;

   // returns the count of the application windows    
   function windowcount: integer;

   // returns the window by its number ( "index" >= 0) in the application window list
   property windows[const index: integer]: twindow read getwindows;

   // returns the lowest visible window in stackorder, 
   // calls "sortzorder" within
   function bottomwindow: twindow;

   // returns the highest visible window in stackorder, 
   // calls "sortzorder" within
   function topwindow: twindow;


   // TRUE if all owned windows pass "CanClose" check or 
   // don't have focused widgets
   function candefocus: boolean;

   // subscribes the handler "method" to receive keyboard events
   procedure registeronkeypress(const method: keyeventty);

   // unsubscribes the handler "method" from receiving keyboard events
   procedure unregisteronkeypress(const method: keyeventty);

   // subscribes the handler "method" to receive shortcut events
   procedure registeronshortcut(const method: keyeventty);

   // unsubscribes the handler "method" from receiving shortcut events
   procedure unregisteronshortcut(const method: keyeventty);

   // subscribes the handler "method" to receive "OnWindowActiveChanged" event ( form-wide )
   procedure registeronactivechanged(const method: activechangeeventty);

   // unsubscribes the handler "method" from receiving "OnWindowActiveChanged" event ( form-wide )
   procedure unregisteronactivechanged(const method: activechangeeventty);

   // subscribes the handler "method" to receive "OnDestroyed" events ( form-wide )
   procedure registeronwindowdestroyed(const method: windoweventty);

   // unsubscribes the handler "method" from receiving "OnDestroyed" events ( form-wide )
   procedure unregisteronwindowdestroyed(const method: windoweventty);

   // subscribes the handler "method" to receive "OnWindowDestroyed" events ( form-wide )
   procedure registeronwiniddestroyed(const method: winideventty);

   // unsubscribes the handler "method" form receiving "OnWindowDestroyed" events ( form-wide )
   procedure unregisteronwiniddestroyed(const method: winideventty);

   // subscribes the handler "method" to receive "ApplicationActiveChanged" events ( form-wide )
   procedure registeronapplicationactivechanged(const method: booleaneventty);

   // unsubscribes the handler "method" from receiving "ApplicationActiveChanged" events ( form-wide )
   procedure unregisteronapplicationactivechanged(const method: booleaneventty);

// tcustomapplication

   // subscribes the handler "method" to receive "OnTerminated" event ( form-wide )
   procedure registeronterminated(const method: notifyeventty);

   // unsubscribes the handler "method" from receiving "OnTerminated" events ( form-wide )
   procedure unregisteronterminated(const method: notifyeventty);

   // subscribes the handler "method" to receive "OnTerminateQuery" event ( form-wide )
   procedure registeronterminate(const method: terminatequeryeventty);

   // unsubscribes the handler "method" from receiving "OnTerminateQuery" event ( form-wide )
   procedure unregisteronterminate(const method: terminatequeryeventty);

   // subscribes the handler "method" to receive "OnIdle" event ( form-wide )
   procedure registeronidle(const method: idleeventty);

   // unsubscribes the handler "method" from receiving "OnIdle" events ( form-wide )
   procedure unregisteronidle(const method: idleeventty);

   // calls "canclose" of all application windows except the "sender" window 
   // if all "canclose"are TRUE then checks "OnTerminateQuery" 
   // for all its subscribers ( usually forms of the application )
   procedure terminate(const sender: twindow = nil); 

   // TRUE as long as a "terminate" call is in progress
   function terminating: boolean;

   // TRUE as long as a "deinitialize" call is in progress
   function deinitializing: boolean;
   
   // returns the current caret object ( the text input focus indicator ) of the application
   / ( this object provides facilities to control position & appearance & visibility & timings of the caret )
   property caret: tcaret read fcaret;

   // returns the current mouse object of the application
   / ( this object provides facitities to control position & appearance of the mouse )   
   property mouse: tmouse read fmouse;

   // simulates mouseparkevent 
   // ( an adjusting mouse movement without user intervention - grid snapping, docking etc ?)
   procedure mouseparkevent;

   // sets mouse position correction for further mouse events,
   // the real position is less the visual one by the supplied shift
   procedure delayedmouseshift(const ashift: pointty);

   // returns/sets a cursor shape used for widgets having their cursor shape set to "cr_default";
   // setting it to "cr_default" restores the individual widget cursor(s)
   property widgetcursorshape: cursorshapety read fwidgetcursorshape write
                                        fwidgetcursorshape;

   // returns/sets the current application-wide cursor shape ( not "watches" if a waiting dialog is currently displayed ! )
   // or request to set a new cursor shape ( app-wide );
   // doesn't change when changing mouse widgets
   // 
   // if called from a non-main app thread & no waiting dialogue displayed then redraws 
   // the cursor immediately;
   // set it to "cr_default" to restore the shape to one set by "widgetcursorshape"
   //
   property cursorshape: cursorshapety; // cr_arrow, cr_*

   // assures the displayed mouse cursor shape to be the shape assigned to the currently under-mouse widget,
   // otherwise "cr_default" 
   procedure updatecursorshape; //restores cursorshape of mousewidget

   // returns a widget of the application where the mouse is currently positioned over
   property mousewidget: twidget read fmousewidget;

   // returns a widget of the application currently "owning" the mouse ( grabbing all mouse input )
   property mousecapturewidget: twidget read fmousecapturewidget;


   // returns/sets a window to become the main window of the application
   // then resets all other application windows to the window group it belongs to ( Linux only );
   //
   // the main window minimizes all windows if minimized;
   property mainwindow: twindow read fmainwindow write setmainwindow;

   // returns which system thread was allocated to the application on its start
   // ( the main thread )
   property thread: threadty read fthread;

   // returns teh widget where a mouse button click occured last time 
   // ( to compare with when determinibg whether another widget is clicked )
   property buttonpresswidgetbefore: twidget read fbuttonpresswidgetbefore;

   // returns teh widget where a mouse button release occured last time 
   // ( to compare with when determinibg whether another widget is clicked )
   property buttonreleasewidgetbefore: twidget read fbuttonreleasewidgetbefore;


   // returns/sets the interval of mouse double click recognition ( in microsecs ),
   // defaults to 0.4 sec
   property dblclicktime: integer read fdblclicktime write fdblclicktime default
                 defaultdblclicktime; //us

// tcustomapplication

   // creates a datamodule instance ( its startup code including "OnLoaded" is executed )
   procedure createdatamodule(instanceclass: msecomponentclassty; var reference);


   // enters the application event loop;
   //
   // once the loop finishes, performs "OnTerminated" for all its subscribers,
   // destroys all application forms ( components & windows )
   procedure run;

   // TRUE if the eventloop is entered
   function running: boolean;

   // returns/sets the application name 
   // ( defaults to the full path to application executable in the native OS format );
   // currently, only for informatiion query purposes
   property applicationname: msestring read fapplicationname write fapplicationname;
   

   // if exclusive "rights" are satisfied for the main thread ( a mutex lock is OK )  & the event loop is in progress 
   // then posts the "event" to the main application thread for asyc processing,
   // otherwise adds the event to the internal list for further handling as soon as the above conditions meet
   procedure postevent(event: tevent);

   // TRUE if never idle since last call,
   // unlocks the application and calls sleep if not mainthread and asleepus >= 0
   function checkoverload(const asleepus: integer = 100000): boolean;

   // returns/sets the application exception handler
   property onexception: exceptioneventty read fonexception write fonexception;

   // if not "eabort" & no unhandled exceptions, 
   // executes the above "OnException" code if assigned 
   // or shows an exception message otherwise;
   procedure handleexception(sender: tobject = nil; 
                                       const leadingtext: string = '');

   // synchronizes the calling thread with the main event loop ( via a mutex),
   // TRUE if the calling thread allready holds the mutex,
   // the mutex is recursive
   function lock: boolean;

   // tries to synchronize the calling thread with the main event loop ( via a mutex)
   function trylock: boolean;

   // releases the mutex if the calling thread holds the mutex,
   // TRUE if no unlock done
   function unlock: boolean;

   // releases the mutex recursively if the calling thread holds the mutex,
   // returns "count" for the below "relockall"
   function unlockall: integer;

   // regains the mutex to serve "count" locks
   procedure relockall(count: integer);

   // 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, 
   // then frees all locks temporarily then posts the event to the app event queue & waits fot it to be processed the resores the locks;
   // 
   // TRUE if not aborted, quiet -> shows no exceptions if occurs
   //
   // the "syncronize event" is an event owning a semaphore which can be touched by another thread 
   // thus causing "event.waitfo" to return & to exec the event handler code
   //
   function synchronize(const proc: objectprocty;
                       const quite: boolean = false): boolean;

   // TRUE if the calling ( this function ) thread is the application main thread
   function ismainthread: boolean;

   // TRUE if the currently locked thread is the application main thread
   function islockthread: boolean;

   // waith for "athread" to terminate,
   // does "unlock-relock" around waiting
   procedure waitforthread(athread: tmsethread);

   // post a "nothing-to-do" event for asynchronous processing in the main thread 
   procedure wakeupmainthread;

   // invalidates all registered forms of the application so that their widgets redraw land-specific captions 
   // ( changed by "mseconsts.setlangconsts" ),
   // called internally in "setlangconsts" before return
   procedure langchanged; virtual;

   // returns/sets "aps_terminated" state flag ( no actions ? )
   // this flag is also set internally by "terminate" if not cancelled
   property terminated: boolean read getterminated write setterminated;

   // returns the number of "handleexception" calls having an effect ( a message or the handler code )
   property exceptioncount: longword read fexceptioncount;


private
 // function tinternalapplication.beginmodal(const sender: twindow): boolean;

DB

DBedit

DBfields

TDBwidgetgrid

  Properties:

        anchors - ...
	bounds - ...

	color 
		- color of the grid's client area
	cursor 
		- cursor shape when the mouse is over the client area

	datacols
		colorselect
		linecolor
		linecolorfix
		linewidth
		newrowcol

		options
			co_readonly
			co_nofocus
			co_invisible
			co_disabled
			co_drawfocus
			co_mousemovefocus
			co_lefbuttonfocusonly
			co_focusselect
			co_mouseselect
			co_keyselect
			co_multiselect
			co_resetselectionexit
			co_rowselect
			co_fixwidth
			co_fixpos
			co_fill
			co_proportional
			co_nohscroll
			co_savevalue
			co_savestate
			co_rowfont
			co_rowcolor
			co_zebracolor
			co_nosort
			co_sortdescent
			co_norearrange
			co_cancopy
			co_canpaste
			co_mousescrollrow
			co_rowdatachange

		sortcol
		width

		items[N]
			color
			colorselect
			datalist - ???
			face - see <any face>
			fontselect - see <any font>
			frame - see <any frame>
			linecolor
			linecolorfix
			linewidth
			name
			
			options
	

Report

TRepSpacer

TRecordBand

TrepValueDisp

TRepPageNumdisp

TRepPrintDateDisp

TBandGroup

TTileArea

Design

TGdbMi

TSyntaxEdit

TSyntaxPainter

Comm

TCommPort

TAsciiCommPort

TAsciiProtPort

TCommSelector

General stuff

Properties for all widgets


	name

	anchors

		-----------

		- they control of design/runtime sticking widgets to their parents

		- dimention pair ( top/bottom or left/right ) both set to "false" cause 
		the widget to fit the parent's client area in that dimention;
		this effect may be partial in case of "bounds_c*max" settings limit the extents

		*** Return to the look "before dimention fit" is only possible by manual resizing or setting "bounds_*"
		-----------
		an_left 
			- on run-time, resizes/shifts left the widget to keep the design-set distance 
			between the widget's left border and the left side of parent's client area 
			as the parent resizes, until scrolling begins

		an_top
			- on run-time, resizes/shifts up the widget to keep the design-set distance 
			between the widget's top border and the upper side of parent's client area 
			as the parent resizes, until scrolling begins

		an_right
			- on run-time, resizes/shifts right the widget to keep the design-set distance 
			between the widget's right border and the right side of parent's client area 
			as the parent resizes, until scrolling begins

		an_bottom
			- on run-time, resizes/shifts down the widget to keep the design-set distance 
			between the widget's bottom border and the lower side of parent's client area 
			as the parent resizes, until scrolling begins

	bounds

		cx	- width of the widget
		cxmax, cxmin - design/runtime width of the widget is enforced between "cxmax" and "cxmin"
		cy	- height of the widget
		cymax, cymin - design/runtime height of the widget is enforced between "cymax" and "cymin"
		x	- distance between the widget's left border and the left side of parent's client area 
		y	- distance between the widget's top border and the upper side of parent's client area 


	autosize

		-----------
		- only applicable to widgets with "ow_autosize" set
		- the effect may be partial in case when "bounds_c*max" settings limit the extents
		-----------

		cx - addition to width of the widget (with h-centering post applied)
		cy - addition to height of the widget (with v-centering post applied)

	- color
		= the default color of client area & caption text background
		= may be overwritten:
			* the client area - with "frame.colorclient"
			* the caption BG - with "frame.font.colorbackground"

	- font
		= see {any font}

	- frame
		= see {any frame}

	- face
		= see {any face}

	- hint
		= descriptive text appearing when mouse pointer enters the widget

	- cursor
		= shape of the mouse pointer over the client area of widget (run-time only)

	- visible
		= "true" allow the widget to appear ( run-time only )

	- enabled
		= "true" allows the widget to participate in GUI interaction
		= "false" disallows the widget & its children :
			* processing all events & shortcuts & menu calls
			* auto "CanClose" check

			Also "false" usually paints the widget in color marking 
			the "disabled" state ( usually light gray font color )

	- popupmenu
		= reference to a preset tpopupmenu widget serving the right-click menu

	- taborder
		- {0..N} order number when TAB-key cycling through widgets in the container 

	- tag
		- an integer value bound to this widget instance

	- helpcontext
		= a string returned by "(active/mouse)helpcontext" methods of the owning form 
		  when this widget is focused or under mouse in the active window

	- zorder
		= reading: finds the current Z-order of the widget's window
		= setting: if the value = 0 then lowers the widget's window in the stacking hierarchy, otherwise rises


	optionswidget:

		ow_background
			- keeps the window/widget on bottom of the Z-order stack.

		ow_top
			- keeps the window/widget in foreground

		ow_noautosizing
			- when docking, not to resize for the docking area

		ow_mousefocus
			- "false" here disables focusing the widget with mouse
			  ( and "OnFocus" doesn't fire on mouse clicks )

		ow_tabfocus
			- "false" here disables focusing the widget with "TAB" key
			  ( and "OnFocus" doesn't fire on TAB pressed )

		ow_parenttabfocus
			- enters the childs on TAB-focusing then returns to the widget after 
			sequential TAB-ing through its child widgets,
			otherwise TAB-ing cycles on the children if entered

		ow_arrowfocus
			- allows the widget ( and its children in turn ) to be focused with 
			the arrow keys 

		ow_subfocus, ow_arrowfocusin, ow_arrowfocusout
			- in case of arrow keys focusing enabled for child-containing widget, 
			determine behaviour on entering & leaving the widget, see the below table:

			ow_subfocus	| ow_arrowfocusin |	ow_arrowfocusout | effect

			   FALSE           FALSE             FALSE         entering-/leaving-
			   FALSE           FALSE             TRUE          entering-/leaving+
			   FALSE           TRUE              FALSE         entering(nearest)+/leaving-
			   FALSE           TRUE              TRUE          entering(nearest)+/leaving+
			   TRUE            FALSE             FALSE         entering(last focused)+/leaving-
			   TRUE            FALSE             TRUE          entering(last focused)+/leaving+
			   TRUE            TRUE              FALSE         entering(nearest)+/leaving-
			   TRUE            TRUE              TRUE          entering(nearest)+/leaving+

			- "entering" is focusing on a child within the widget
			- "leaving"  is return from last child onto the widget's level
			- "nearest" is the child closest on the arrow direction
			- "last focused" is the child focused on last leaving the widget
 
			*** The Up/Down arrow keys can leave from the children circle, 
				but Left/Right can only toggle between the children ***

			*** mouse entering/leaving isn't controllable by these options


		ow_focusbackonesc 
			- on pressing "Esc", returns input focus to the previously focused widget

		ow_noparentshortcut

			*** disables processing of delegated ( from the parent ) shortcuts *** 

			- "true" here disables processing shortcuts	if they're delegated 
			from the parent widget ( obviously, not processed by the parent )

		ow_nochildshortcut

			*** disables delegating shortcuts to the parent for taking decision *** 

			- if "true" then the widget tries to process it by oneself 
			otherwise it's passed to the parent widget for further chaining

			*** A shortcut can only be processed once ( by one widget ) ***

		ow_canclosenil
			- "true" here allows to continue even if there's contained widget(s) 
			not passing "CanClose" check

		ow_mousetransparent
			- "true" here causes the widget oneself ( not its contained ones ) 
			not to react to mouse events ( just allow them through to the children )

		ow_mousewheel
			- enables/disables {scrolling/navigating} with wheel of ImPS/2 etc mouse

		ow_noscroll
			- don't use screen image scrolling for twidget.scrollrect, 
			redraw the whole scrolled widget rectangle instead;
			sometimes needed with background fades.

		ow_nochildpaintclip
			- 

		ow_destroywidgets
			- "true" here causes calling "free" for all containing widgets as well

		ow_hinton
			- to show the hint even in case of hinting is disabled on the parent
			( "parent.ow_hintoff= true & parent.ow_hinton= false" )

		ow_hintoff 
			- "true" here combined with "ow_hinton=false" fully disables displaying the hint

		ow_multiplehint 
			- "true" here causes the widget to redisplay its hint on each {>3px} move within the widget oneself

        	ow_timedhint 
			- "true" here causes hint of the widget to disappear after a timed inteval (about 2 secs by default)

		ow_fontlineheight (design-time only)
			- causes "extraspace" of the last text line to be drawn, 
			in turn it causes adjustment of widget height if "ow_autoscale" is set
			
			*** makes sence only if "ow_autoscale=true" & ow_autosize=false & "extraspace <> 0" ***

		ow_fontglyphheight (design-time only)
			- causes only interline "extraspace"-s to be drawn, opposite to "ow_fontlineheight" 

		ow_autoscale (design-time only)
			- causes that if the contents change (design OR run-time) so that its' height changes 
			then the widget will be v-scaled as well

		ow_autosize (design-time only)
			- causes that widget's height & width & client area adjust so that to provide space for contents of the client area
			- no design-time change of height/width are possible as long as this option is in effect

		ow_autosizeanright
			- when autosizing & {an_right isn't set}, the design-set right margin against the parent is preserved

		ow_autosizeanbottom
			- when autosizing & {an_bottom isn't set}, the design-set bottom margin against the parent is preserved

	optionsskin:

		- osc_noskin
		- osc_framebuttononly
		- osc_container


	Methods:

	  // tmsecomponent

		// (re)draws the widget according to the related skin if apllicable;
		//
		// also called internally by "loaded" procedure ( before "OnLoaded" code ),
		// by ShowMessage ( for the internal widgets of the message dialogue ), 
		// when creating tab & form & menu widgets
		procedure updateskin(const recursive: boolean = false);

		// TRUE if the instance is created but not yet ready 
		// for interaction & accessing data & appearance change & receiving events etc
		// ( the stage between firing "OnCreate" & "OnLoaded" )
		function loading: boolean;
	
	 {$ifdef FPC}
		procedure setinline(value: boolean); // ?
		procedure setancestor(value: boolean); // ?
	 {$endif}

		// TRUE if all conditios are OK for executing the code of "event" ( a handler must be assigned to the event )
		function canevent(const event: tmethod): boolean;


		// Shortly, replaces the persistent storage of the widget
		//
		// if {value <> nil} then 
		//	- if "instance" is nil then calls "createproc" to create the instance,
		//    then assigns the instance's value:= "value" 
		// otherwise frees "instance"
		procedure setoptionalobject(const value: tpersistent; var instance;
                        createproc: createprocty);

		// creates the persistent storage of the widget via calling "createproc"
		procedure getoptionalobject(const instance: tobject; createproc: createprocty);

		// obtains & puts to "obj" a CORBA interface entry for "aintf" (GUID,...)
		function getcorbainterface(const aintf: ptypeinfo; out obj) : boolean;

        // TRUE if the widget is owned, or "self" otherwise
		function checkowned(component: tcomponent): boolean; 

        // TRUE if the widget is owner, or "self" otherwise
		function checkowner(component: tcomponent): boolean; 

		// return the top-most widget in owner chain starting from this widget
		function rootowner: tcomponent;

		// return the array of owning widgets starting from this widget
		// componentarty[0] is the widget oneself
		function getrootcomponentpath: componentarty;

        // returns items of objeclinker ( which notify this widget )
        // and free notify list ( which are notified by this widget ),
        // duplicates are removed.
        //	
        // Notifies mainly relate to insertion/removal operation on widgets
        // The notify list is maintained by FreeNotification & RemoveFreeNotification
		function linkedobjects: objectarty;

		// sends "event" recursively to child widgets until no more children or 
		// the event is processed ( cea_processed ) by one of the children,
		// "event" will be destroyed if destroyevent= true and not async
		procedure sendcomponentevent(const event: tcomponentevent; 
                                        const destroyevent: boolean = true);

		// sends "event" to each of owning widgets downward from the root owner,
		// "event" will be destroyed if destroyevent= true and not async
		procedure sendrootcomponentevent(const event: tcomponentevent;
                                        const destroyevent: boolean = true);

		// posts an async "atag"-ged event to be handled by oneself
		procedure asyncevent(atag: integer = 0);

		// posts a "tcomponentevent" instance from sender=self, 
		// "kind" is defined when creating the event, 
		// and "tag" may be adjusted after creation
		procedure postcomponentevent(const event: tcomponentevent);

		// returns the classname of the widget if the widget is toplevel, 
		// and "tmsecomponent" otherwise )
		property moduleclassname: string read getmoduleclassname;

		// returns the classname of the widget as the entry of its constructor
		// ( button => tbutton, datamodule => tdm1mo, form => ttstfo, dbstringedit => tdbstringedit,.. )
		property actualclassname: string read getactualclassname;

		// returns "fmsecomponentstate"
		// ( a set of cs_ismodule,cs_endreadproc,cs_loadedproc,cs_noload, cs_hasskin,cs_noskin )
		property msecomponentstate: msecomponentstatesty read fmsecomponentstate;

		// returns/sets a pointer associated with the widget
		// ( contrary to the integer "tag", allows to use an arbitary data type 
		// for associating data )
		property tagpo: pointer read ftagpo write ftagpo;

		// returns/sets a string identifying the widget in the help system
		property helpcontext: msestring read gethelpcontext write fhelpcontext;

	// twidget

		// creates an instance of the widget, owned by "aowner" if not NIL
		constructor create(aowner: tcomponent); override;

		destructor destroy; override;

		// ??
		procedure afterconstruction; override;

		// rescales the widget frame ( if assigned ) then owned widgets ( if exist, recursively ) then bounds_* then the font ( if assigned )
		// called before inserting in parentwidget,
		// calls "scale(ascale)",
		// no visual repainting
		procedure initnewcomponent(const ascale: real); virtual;

 		// restores the "fontheight" to "font.glyphheight" if "ow_fontglyphheight" or
 		// to "font.lineheight" if "ow_fontlineheight" otherwise,
		// ascale is ignored ?
		// calls "synctofontheight->setfontheight",
		// called after inserting in parentwidget,
		// no visual repainting
		procedure initnewwidget(const ascale: real); virtual;

		// creates the widget frame if not yet created
		procedure createframe;

		// creates the widget face if not yet  created
		procedure createface;

		// creates the widget font if not yet  created
		procedure createfont;

		// checks ws_loadlock and csdestroing too
		function isloading: boolean;

		// returns "widgetstatety" - a set of (
		// ws_visible,ws_enabled,ws_active,ws_entered,ws_entering,ws_exiting,
		// ws_focused,ws_mouseinclient,ws_wantmousebutton,ws_wantmousemove,
		// ws_wantmousefocus,ws_iswidget,ws_opaque,ws_nopaint,
		// ws_clicked,ws_mousecaptured,ws_clientmousecaptured,
		// ws_loadlock,ws_loadedproc,ws_showproc,ws_minclientsizevalid,
		// ws_showed,ws_hidden, //used in tcustomeventwidget
		// ws_destroying,ws_staticframe,ws_staticface,ws_isvisible
		//
		// iframe
		function widgetstate: widgetstatesty;

		// returns "widgetstate1ty" - a set of (
		// (ws1_childscaled,ws1_fontheightlock,
		// ws1_widgetregionvalid,ws1_rootvalid,
		// ws1_anchorsizing,ws1_isstreamed,
		// ws1_scaled, //used in tcustomscalingwidget
		// ws1_noclipchildren,
		// ws1_nodesignvisible,ws1_nodesignframe,ws1_nodesignhandles,
		// ws1_nodesigndelete,ws1_designactive,
		// ws1_fakevisible,ws1_nominsize //used for report size calculations
		// )
		property widgetstate1: widgetstates1ty read fwidgetstate1;
		
			* this set of states is needed because the max FPC set size is 32 
			  thus "widgetstate1ty" can't fit all states

		// TRUE if the widget is contained within another widget
		// ( tcomponent stuff )
		function hasparent: boolean; override;               

		// returns the parent component if it's a widget or the grandparent otherwise
		function getparentcomponent: tcomponent; override;   // tcomponent

		// TRUE if "awidget" is an ascendant or the widget or they are the same widget
		function checkdescendent(awidget: twidget): boolean;
		
		// TRUE if app is running and the widget owns the caret or the caret widget
		function hascaret: boolean;

        // TRUE if "winid" allocated and not loading and not destroying,
        // all widgets on a form have "winid" of this form ( a real window allocated by the OS )
        // thus have this function TRUE
		function windowallocated: boolean;

		// TRUE if presents a valid toplevelwindow with assigned "winid"
		function ownswindow: boolean;

		// invalidated area of the widget, the origin is "clientpos" against the roor widget
		function updaterect: rectty; 

		// calls recursively "canclose" for all contained widgets ( the widget oneself excluded! ),
		// TRUE if none of the widgets return FALSE
		//
		// more specialized widgets may have "canclose" overridden 
		// to perform more work than just this call recursion
		// ( not null or range check,.. )
		//
		// "onclosequery" must also pass the check if assigned, for the function to succeed
		function canclose(const newfocus: twidget = nil): boolean; virtual;

        // checks "canclose" first for focused widget of the window ( form,.. ) 
        // if it is a descendant of the widget or the widget oneself,
        // then continues with subwidgets of the widget;
        // also - finishes editing ( snapshots "value" ) in the focused widget before checking
		function canparentclose(const newfocus: twidget): boolean; overload;

		// the above function but with the preserved focus
		function canparentclose: boolean; overload;
                   //newfocus = window.focusedwidget      

		function canfocus: boolean; virtual;
		function setfocus(aactivate: boolean = true): boolean; virtual;//true if ok
		procedure nextfocus; //sets inputfocus to then next appropriate widget

		function findtabfocus(const ataborder: integer): twidget;
                       //nil if cannot focus

		function firsttabfocus: twidget;
		function lasttabfocus: twidget;
		function nexttaborder(const down: boolean = false): twidget;

		function focusback(const aactivate: boolean = true): boolean;
                               //false if focus not changed

		function parentcolor: colorty;
		function actualcolor: colorty; virtual;
		function actualopaquecolor: colorty;
		function backgroundcolor: colorty;
		function translatecolor(const acolor: colorty): colorty;

		procedure widgetevent(const event: twidgetevent); virtual;

		procedure sendwidgetevent(const event: twidgetevent);
                              //event will be destroyed

		procedure release; override;

		function show(const modal: boolean = false; const transientfor: twindow = nil): modalresultty; virtual;

		procedure hide;
		procedure activate(const abringtofront: boolean = true); virtual;
                             //show and setfocus

		procedure bringtofront;
		procedure sendtoback;
		procedure stackunder(const predecessor: twidget);

		procedure paint(const canvas: tcanvas); virtual;
		procedure update; virtual;
		procedure scrollwidgets(const dist: pointty);

		procedure scrollrect(const dist: pointty; const rect: rectty; scrollcaret: boolean);
                             //origin = paintrect.pos

		procedure scroll(const dist: pointty);
                            //scrolls paintrect and widgets

		procedure getcaret;
		procedure scrollcaret(const dist: pointty);
		function mousecaptured: boolean;
		procedure capturemouse(grab: boolean = true);
		procedure releasemouse;
		procedure capturekeyboard;
		procedure releasekeyboard;
		procedure synctofontheight; virtual;

		procedure dragevent(var info: draginfoty); virtual;
		procedure dochildscaled(const sender: twidget); virtual;

		procedure invalidatewidget;     //invalidates whole widget
		procedure invalidate;           //invalidates clientrect
		procedure invalidaterect(const rect: rectty; org: originty = org_client);
		procedure invalidateframestate;

		procedure invalidateframestaterect(const rect: rectty; 
                                        const org: originty = org_client);   
		function hasoverlappingsiblings(arect: rectty): boolean; //origin = pos

		function window: twindow;
		function rootwidget: twidget;

		function parentofcontainer: twidget;
            //parentwidget.parentwidget if parentwidget has not ws_iswidget,
            //parentwidget otherwise

		property parentwidget: twidget read fparentwidget write setparentwidget;
		function getrootwidgetpath: widgetarty; //root widget is last

		// number of contained widgets ( the widget oneself excluded ! )
		function widgetcount: integer;

		function parentwidgetindex: integer; //index in parentwidget.widgets, -1 if none
		property widgets[const index: integer]: twidget read getwidgets;
		function widgetatpos(var info: widgetatposinfoty): twidget; overload;
		function widgetatpos(const pos: pointty): twidget; overload;

		function widgetatpos(const pos: pointty; 
                   const state: widgetstatesty): twidget; overload;

		property taborderedwidgets: widgetarty read gettaborderedwidgets;

		function findtagwidget(const atag: integer; const aclass: widgetclassty): twidget;
              //returns first matching descendent

		property container: twidget read getcontainer;
		function containeroffset: pointty;
		function childrencount: integer; virtual;
		property children[const index: integer]: twidget read getchildwidgets; default;

		function childatpos(const pos: pointty; 
                   const clientorigin: boolean = true): twidget; virtual;

		function getsortxchildren: widgetarty;
		function getsortychildren: widgetarty;
		property focusedchild: twidget read ffocusedchild;
		property focusedchildbefore: twidget read ffocusedchildbefore;

		function mouseeventwidget(const info: mouseeventinfoty): twidget;

		function checkdescendent(widget: twidget): boolean;
                    //true if widget is descendent or self

		function checkancestor(widget: twidget): boolean;
                    //true if widget is ancestor or self

		function containswidget(awidget: twidget): boolean;

		procedure insertwidget(const awidget: twidget); overload;

		procedure insertwidget(const awidget: twidget; const apos: pointty); overload; virtual;
                 //widget can be child

		function iswidgetclick(const info: mouseeventinfoty; const caption: boolean = false): boolean;
		//true if eventtype = et_butonrelease, button is mb_left, clicked and pos in clientrect
 		//or in frame.caption if caption = true, origin = pos

		function isclick(const info: mouseeventinfoty): boolean;
		//true if eventtype = et_butonrelease, button is mb_left, clicked and pos in clientrect

		function isdblclick(const info: mouseeventinfoty): boolean;
		//true if eventtype = et_butonpress, button is mb_left, pos in clientrect
		// and timedlay to last buttonpress is short

		function isdblclicked(const info: mouseeventinfoty): boolean;
		//true if eventtype in [et_buttonpress,et_butonrelease], button is mb_left,
		// and timedlay to last same buttonevent is short

		function isleftbuttondown(const info: mouseeventinfoty): boolean;
		//true if eventtype = et_butonpress, button is mb_left, pos in clientrect
		//origin = paintrect.pos

		widgetrect: the widget on-screen area including its frame & frame caption

			paintrect: the widget on-screen area except its frame & frame caption

			clientrect: virtual area which 
				- for non-scrolling widgets, equals to "paintrect", with its "pos:= (0,0)"
				- for scrolling widgets, may be bigger than "paintrect", 
				  also may shift ( change its "pos" ) when scrolling
		
	// the coord of outer top-left corner against the toplevel form = the window owner,
	// including the frame & frame caption 
		function rootpos: pointty; 

	// the coord of the outer top-left corner against the screen ( the WM decorations aren't counted in )
	// includes the frame & frame caption 
		property screenpos: pointty; 

	//  the coord of the outer top-left corner against the parent widget,
	// including the frame & frame caption 
		property widgetrect: rectty; 
		property pos: pointty; // =widgetrect.pos
		property size: sizety; // =widgetrect.size
		property left: integer; // =bounds_x
		property right: integer; //widgetrect.x + widgetrect.cx, sets cx;
		property top: integer;  // =bounds_y
		property bottom: integer; //widgetrect.y + widgetrect.cy, sets cy;
		property width: integer; // =bounds_cx
		property height: integer; // =bounds_cy
		function widgetsizerect: rectty;          //pos = nullpoint

    // the coord of the paint area ( paintrect ) against own outer top-left corner ( against "widgetrect=pos" )
    //  except the frame & frame caption 
		function paintrect: rectty;
		function paintpos: pointty;
		function paintsize: sizety;
		function innerpaintrect: rectty; // mainly equals to paintrect
		function clientwidgetrect: rectty; // mainly equals to paintrect
		function clientwidgetpos: pointty;
		function clippedpaintrect: rectty; // mainly equals to  but clipped by all parentpaintrects
		function innerwidgetrect: rectty;     // mainly equals to paintrect
		function innerclientwidgetpos: pointty;

    // the coord of the paint area ( paintrect ) against own outer top-left corner ( against "widgetrect=pos" )
    //  except the frame caption 
		function framerect: rectty; // =paintrect except the frame caption area
		function framepos: pointty;
		function framesize: sizety;

    // the coord of the client area ( clientrect )  against the paint area ( paintrect )
    //  usually these areas match
		function clientrect: rectty;
		property clientsize: sizety;
		property clientwidth: integer;
		property clientheight: integer;
		property clientpos: pointty;

    // the coord of the paint area of the parent against the paint area of this widget
		function paintrectparent: rectty; //nullrect if parent = nil,

    // the coord of the client area of the parent against the paint area of this widget
		function clientrectparent: rectty; //nullrect if parent = nil,

	// the coord of the inner area against the client area ( clientrect )
		function innerclientrect: rectty;  // mainly equals to clientrect
		function innerclientsize: sizety;
		function innerclientpos: pointty;

		function framewidth: sizety;              //widgetrect.size - paintrect.size
		function clientframewidth: sizety;        //widgetrect.size - clientrect.size
		function innerclientframewidth: sizety;   //widgetrect.size - innerclientrect.size
		function innerframewidth: sizety;         //clientrect.size - innerclientrect.size  

    // the coord of the paint area against the widgetrect(pos) of the parent
		function paintparentpos: pointty;    //origin = parentwidget.pos

    // the coord of the client area against the widgetrect(pos) of the parent
		function clientparentpos: pointty;   //origin = parentwidget.pos

    // the coord of the widgetrect(pos) against the client area of parent
		property parentclientpos: pointty;


		function clientpostowidgetpos(const apos: pointty): pointty;
		function widgetpostoclientpos(const apos: pointty): pointty;
		function widgetpostopaintpos(const apos: pointty): pointty;
		function paintpostowidgetpos(const apos: pointty): pointty;
		procedure scale(const ascale: real); virtual;


		property minsize: sizety read fminsize write setminsize;
		property maxsize: sizety read fmaxsize write setmaxsize;
		function maxclientsize: sizety; virtual;


		property anchors: anchorsty read fanchors write setanchors default defaultanchors;
		property defaultfocuschild: twidget read getdefaultfocuschild write setdefaultfocuschild;


		procedure changeclientsize(const delta: sizety); //asynchronous

		function getcanvas(aorigin: originty = org_client): tcanvas;

		function showing: boolean;
               //true if self and all ancestors visible and window allocated

		function isenabled: boolean;
               //true if self and all ancestors enabled

		function active: boolean;
		function entered: boolean;

		function activeentered: boolean; 
			//true if entered and window is regularactivewindow or inactivated

		function focused: boolean;
		function clicked: boolean;

		function indexofwidget(const awidget: twidget): integer;

		procedure changedirection(const avalue: graphicdirectionty;
                                            var dest: graphicdirectionty); virtual;

		// (re)arranges "awidgets" horizontally within the parent's client area 
		// so that awidget[i] were placed next each other 
		// at h-space dist[i], starting from "startx" with the right margin "endmargin";
		// 
		// if the number of "dist" is fewer than the number of "awidgets" then the remaining h-spaces are taken 
		// as the last "dist[i]" or "0" if none;
		// if the number of "dist" is more than the number of "awidgets" then the extra dist[i] are discarded
		// 
		// non-zero "endmargin" causes one of awdidget[i] to h-resize to provide the margin :
		//  - if one or more of awidgets[i] have [an_left,an_right] set then the first of such is resized
		//    otherwise the last awidgets[i] is h-resized 
		// 
		procedure placexorder(
				const startx: integer; 
				const dist: array of integer;
                const awidgets: array of twidget;
                const endmargin: integer = minint);

		// (re)arranges "awidgets" vertically within the parent's client area 
		// so that awidget[i] were placed upper/lower each other 
		// at v-space dist[i], starting from "starty" with the bottom margin "endmargin";
		// 
		// if the number of "dist" is fewer than the number of "awidgets" then the remaining v-spaces are taken 
		// as the last "dist[i]" or "0" if none;
		// if the number of "dist" is more than the number of "awidgets" then the extra dist[i] are discarded
		// 
		// non-zero "endmargin" causes one of awdidget[i] to v-resize to provide the margin :
		//  - if one or more of awidgets[i] have [an_top,an_bottom] set then the first of such is resized
		//    otherwise the last awidgets[i] is v-resized 
		// 
		procedure placeyorder(
				const starty: integer; 
				const dist: array of integer;
                const awidgets: array of twidget;
                const endmargin: integer = minint);
               //origin = clientpos, endmargin by size adjust of widgets 
               //with [an_top,an_bottom], minint -> no change

		// if {mode <> wam_none} then (re)arranges "awidgets" horizontally  within the parent's client area so that 
		// awidgets[0] stays on its place but awidgets[1..N] :
		// - 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]
		// - 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]
		// - if {mode = wam_center} then awidgets[i>=1] move so that they Y-axes match the Y-axe of awidgets[0]
		//
		// mainly applicable for v-stacked widgets since h-stacked may overlap after such alignment
		//
        // returns the reference point ( the coord of awidgets[0] )
		function alignx(const mode: widgetalignmodety;
                        const awidgets: array of twidget): integer;


		// if {mode <> wam_none} then (re)arranges "awidgets" vertically within the parent's client area so that 
		// awidgets[0] stays on its place but awidgets[1..N] : 
		// - 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]
		// - 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]
		// - if {mode = wam_center} then awidgets[i>=1] move so that they X-axes match the X-axe of awidgets[0]
		//
		// mainly applicable for h-stacked widgets since v-stacked may overlap after such alignment
		//
        // returns the reference point ( the coord of awidgets[0] )
		function aligny(const mode: widgetalignmodety;
                        const awidgets: array of twidget): integer;

		function actualcursor: cursorshapety; virtual;


	Event handlers:

	- onactivate

		 fires :

		= on receiving input focus, just before "OnFocus"
			
		= forms specific :
			* on 1-st display of the form after "OnLoaded" ( from "Loaded" procedure)
			* on switch back from another apllication/WM ( "oe_activate" event )
			* after closure of a descendant form
			* on minimizing/maximizing the form

	- onchildscaled

		 fires :

		= on child/children resizing due to font height change

		= form widget: once "form.container" {scrolling widget} is loaded

	- ondeactivate
		 fires 
			= form widget: when the form looses input focus
			= non-form widget: when the widget looses input focus

	- ondefocus

		fires 
		= on disabling the widget

	= form widget: if another form is focused
		= non-form widget: if another widget is focused

	- onenter
		= fires on any way of taking parent-wide focus as soon as 
		the parent stores the new child's order, before "OnActivate" & "OnFocus"

	- onexit
		= fires last on parent-wide lossing focus, after "OnDefocus" & "OnDeactivate"
		= for top-level ( not in a container ) forms, doesn't fire

	- onfocus
		fires 
			= once the existing widget takes the focus 
			= on showing the widget's form if the widget has the lowest "TabOrder"

	- onfontheightdelta
		fires
			= if [ow_fontglyphheight OR ow_fontlineheight ] AND {the
			new font height differs from the previos one}
			= before the parent redraws this widget

	- onpopup
		fires :
			= on calling a popup-menu ( with "RightClick" ), once the menu items of the current level are loaded
			( before building the submenus ) 

	- onresize

		= fires on creating/(changing size)/(min-max restoring) of widget, 
		before actual redrawing

		= rechecks if there's real work to do

	- onshowhint
		= fires when a installed hint is activated or on "aplication.showint" called
		= since called last, allows to adjust the default behavior

	- onbeforeupdateskin
		= fires in "updateskin" ( the widget is loaded etc ) before applying the skin

	- onafterupdateskin
		= fires in "updateskin" ( the widget is loaded etc ) once the skin is applied

TWidget stuff

   Properties:    
		- name
		- anchors
		- bounds
		- color
		- enabled
		- visible
		- <face> : see {any face}
		- <frame> : see {any frame}
	    - hint
	    - helpcontext
	    - tag
	    - taborder
	    - cursor
	    - optionswidget
	    - optionsskin
	    - popupmenu
    
		twidget's event handlers:
    
			- on(de)activate
			- onbeforeupdateskin
			- onafterupdateskin
			- onchildscaled
			- onfontheightdelta
			- on(de)focus
			- onenter
			- onmove
			- onpopup
			- onresize
			- onshowhint
      
	align_glue : 
	  ( outer anchoring mode for widget group, in the align mode )
		- wam_none
		- wam_start
		- wan_center
		- wm_end

	align_leader : 
		the widget ( incl another spacer, splitter or layouter ) against which the alignment applies ( the reference widget )

	align_mode : 
	  ( inner anchoring mode within widget group, in the align mode )
		- wam_none
		- wam_start
		- wan_center
		- wm_end

// Place mode:

      
	place_mindist, place_maxdist:
		- in the place(ment) mode, limits distance between widgets
		  ( these distance once calculated also define side margins if applicable )

	place_mode: 
	  ( outer anchoring mode for widget group, in the place mode )
		- wam_none
		- wam_start
		- wan_center
		- wm_end

	place_options:
		- plo_endmargin
			= to resize a widget so that it "eats" extra space if it occurs
			
			* only applicable in the place mode, with a limiting value of "place_maxdist" and:

			  1) {place_mode <> wam_none}
			or
			  2) {place_mode = wam_end} and {plo_propmargin in place_options}

			For the exact look, see above


		- plo_propmargin
			= виджеты расставляются теснее так, чтобы образовались отступы перед и после,
			  причем расстояние между центрами виджетов было бы таким же, 
			  как и растояние между серединами крайних виджетов и соотв. границами зоны расстановки

		- plo_syncmaxautosize
			= see above

		- plo_synccaptiondistx
			= see above

			  * affects widgets with opposite cp_left/right set as well	
			  * the minimal before-adjustment "captiondist" among all widgets limits "captiondist" for each of the widget
              * don't set cfo_captiondistouter here !

		- plo_synccaptiondisty
			= see above

			  * affects also widgets with opposite cp_top/bottom set	
			  * the minimal before-adjustment "captiondist" amongst all widgets limits "captiondist" for each of the widget

              ! here, don't set "cfo_captiondistouter" for affected widgets !

		- plo_syncpaintwidth
			= see above

		- plo_syncpaintheight
			= see above

		- plo_scalesize
			= see above


	dist_left, dist_right, dist_top, dist_bottom : 
		= margins between most outer edge the layouter and 
		  the corresponding linked widget

		* see "tspacer" for detail

	linkleft,linkright,linktop,linkbottom : see "tspacer"

	options:
		- spao_glueright, spao_gluebottom: 
			= set the adjustment dependencies between the layouter and its link_* widgets

			* see "tspacer" for more details

	// which mode of widget placement to apply - see above
	optionslayout: 
		- lao_alignx
		- lao_aligny
		- lao_placex
		- lao_placey
		- lao_scalewidth
		- lao_scaleheight
		- lao_scaleleft
		- lao_scaletop
		
		* lao_place* & lao_align* can't be combined for one direction

	optionsscale: 
	  
	  * cause the layouter to provide full space for the widgets as long as they expand/shrink/move

		- osc_expandx 
			= allocates more h-space if needed

		- osc_shrinkx
			= removes extra h-space if occurred

		- osc_expandy
			= allocates more v-space if needed

		- osc_shrinky
			= removes extra v-space if occurred

		- osc_invisishrinkx
			= fully h-collapses the layouter if "visible=false" ( run-time only )

		- osc_invisishrinky
			= fully v-collapses the layoter if "visible=false" ( run-time only )

	optionsskin:
		= see <any widget>


	Methods:

		constructor create(aowner: tcomponent); override;

Public stuff

	(f)window: 
		the OS-allocated ( root = toplevel ) window common for all widgets of this window
		
		* "widget.fwindow.fowner = widget.self" in case of the widget present the root "fwindow" 
		  ( owns the window )

	(f)rootpos: 
		position of the widget in the coord of toplevel window not the nearest parent widget alone,
		calculated as sum of such positions ( fwidgetrect.pos ) starting from the toplevel through the
                chain of all parents up to the current widget;
		"nullpoint" (0,0) for toplevel widgets ( window-owning forms,..)

	screenpos:
		- coord aginst the top-left corner of screen
		- WM decoration & title aren't parts of the widget !

	widgetrect: 
		the widget on-screen area including its frame & frame caption

	paintrect: 
		the widget on-screen area except its frame & frame caption

	clientrect: 
		virtual area which 
			- for non-scrolling widgets, equals to "paintrect", with its "pos:= (0,0)"
			- for scrolling widgets, may be bigger than "paintrect", 
		 	  also may shift ( change its "pos" ) when scrolling

			* "t*grid" aren't such scrollable widgets since their virtual height would be limited by 
			  the X11 "+-32000" limitation, 
			  so example of such widgets are tscrollbox, "tform.container" etc

	framerect: 
		the widget on-screen area except its frame caption but including inner & outer frame

	****************

	// releases all thread locks then post the event to the app event queue and
	// waits for the event handler finishes ( signalled by "sye_ok on a semaphore )
	// finally restores the locks
    // true if the handler is not aborted
	function synchronizeevent(const aevent: tsynchronizeevent): boolean;

    // translates "point" coord against "source" widgetrect to "dest" widgetrect
	//
	//   * nil "source" = from screen coord 
	//   * nil "dest" = to screen coord
	procedure translatewidgetpoint1(var point: pointty; const source,dest: twidget);

	// the function-framed version of "translatewidgetpoint1"
	function translatewidgetpoint(const point: pointty; const source,dest: twidget): pointty;

	// rect isntead of point, 
	// if dest = nil then to screen 
    // if source = nil then against screen
	function translatewidgetrect(const rect: rectty; const source,dest: twidget): rectty;
	//-----------------
    // translates "point" coord against "source" paintrect to "dest" paintrect
	//   * nil "source" = from screen coord 
	//   * nil "dest" = to screen coord
	procedure translatepaintpoint1(var point: pointty; const source,dest: twidget);

	// the function-framed version of "translatepaintpoint1"
	function translatepaintpoint(const point: pointty; const source,dest: twidget): pointty;

	// rect isntead of point, 
	// if dest = nil then to screen 
    // if source = nil then against screen
	function translatepaintrect(const rect: rectty;const source,dest: twidget): rectty;
    //-----------------
    // translates "point" coord against "source" clientrect to "dest" clienttrect
	//   * nil "source" = from screen coord 
	//   * nil "dest" = to screen coord
	procedure translateclientpoint1(var point: pointty;
                    const source,dest: twidget);

	// the function-framed version of "translateclientpoint1"
	function translateclientpoint(const point: pointty; const source,dest: twidget): pointty;

	// rect isntead of point, 
	// if dest = nil then to screen 
    // if source = nil then against screen
	function translateclientrect(const rect: rectty; const source,dest: twidget): rectty;
    //-----------------

	// (re)sorts "awidgets" in order of increasing their "widgetrect.x" coords
	//   - if parent = nil then the coords are against individual parent of each of "awidgets"
	//   - if parent is supplied then the coords are against this parent
	procedure sortwidgetsxorder(var awidgets: widgetarty; const parent: twidget = nil);

	// (re)sorts "awidgets" in order of increasing their "widgetrect.y" coords
	//   - if parent = nil then the coords are against individual parent of each of "awidgets"
	//   - if parent is supplied then the coords are against this parent
	procedure sortwidgetsyorder(var awidgets: widgetarty; const parent: twidget = nil);

	// for each  of "widgets", calculates its autosized client area ( min size rect to fit the caption, etc )
    //   - both hor & ver sizes of client area of each of "widgets" are adjusted to the max of the above calculated areas,
	//	   as the result - client areas of all widgets become identically v+h sized
    // 
    //   * right & bottom anchored margins of each widget are preserved
	procedure syncmaxautosize(const widgets: array of twidget);

	// for each  of "widgets", width of client area of each of "widgets" is adjusted so that 
    // external ( by the outer border of frame ) widths of all widgets become identical 
    // to the external widht of the widest widget
    //    
    //   * if "awidth" >= 0 then no determining the widest widget is taken and
    //     "awidth" is adjusted to instead, for all widgets
    //   * right anchored margins of each widget are lost
	procedure syncminframewidth(const awidgets: array of twidget;
                               const awidth: integer = -1);

	// for each  of "widgets", height of client area of each of "widgets" is adjusted so that 
    // external ( by the outer border of frame ) heights of all widgets become identical 
    // to the external height of the highest widget
    //    
    //   * if "aheight" >= 0 then no determining the highest widget is taken and
    //     "aheight" is adjusted to instead, for all widgets
    //   * bottom anchored margins of each widget are lost
	procedure syncminframeheight(const awidgets: array of twidget; const aheight: integer = -1);

Projects using MSEgui