Reference: MSEgui

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

 
 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;

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.

Caption: read/write the piece of text.

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.

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,.. )

* 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

- 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 ***

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"

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.

<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 )

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.

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

Maps string to string.

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

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

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.

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

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

-   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 = 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 = 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),..)

- 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

- 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

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

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)

- 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

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

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

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 )

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;