Notes

 
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

 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

 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

 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

==================================================================

autosize

 -----------
 - only appliable to widgets with "ow_autosize" set
 - the effect may be partial in case of "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)

==================================================================

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


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

 options
  ao_updateonidle
   - runs this action in cycle each time waiting for no gui events
  ao_globalshortcut
   - allows the action to trigger on a non-main form

 shortcut
  - keyboard combination triggering the action

 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


==================================================================

<any widget>
 optionswidget:
  ow_background
  ow_top
  ow_noautoresizing
  ow_mousefocus
  ow_tabfocus
  ow_parenttabfocus
  ow_arrowfocus
  ow_arrowfocusin
  ow_arrowfocusout
  ow_subfocus
  ow_focusbackonesc - on pressing "Esc", returns input focus
  ow_nochildshortcut
  ow_noparentshortcut
  ow_canclosenil
  ow_mousetransparent
  ow_mousewheel
  ow_noscroll
  ow_destroywidgets
  ow_hinton
  ow_hintoff
  ow_multiplehint
*mse ow_timedhint

  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 heigh & width & client area adjust so that to fit 
the client area contents
   - no desing-time change of height/width are possible as long as this 
option in effect

  ow_sizeanright
  ow_autosizeanbottom

==================================================================

<any 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 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 dislpays a step upper in 
its group )

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

 - controls of widget's placement & scrolling
 -------------
 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



==================================================================
"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
   - fires
    = on 1-st display of the form after "OnLoaded"
    = on switch back from another apllication/WM
    = after closure of a descendant form
    = on minimizing/maximizing the form

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

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

  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

*mse 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
   - fires :
    = on child(s) resizing due to font height change
    = once "form.container" {scrolling widget} is loaded

  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
   - fires
*mse   = if the form looses input focus

  ondefocus
   - fires
*mse   = if another form is focused
    = on disabling the widget

  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

   *** Termnation 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
   - fires last on parent-wide lossing focus, after "OnDefocus" & 
"OnDeactivate"
   - for top-level( not in a container ) forms, doesn't fire

  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
   - when (ow_fontglyphheight OR ow_fontlineheight ), fires if the
   new font height differs from the previos one
   - fires before the parent redraws this widget

  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
   - fires once the window is created/moved ( with a check if really moved )

  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 a real work to do

  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
   - fires when a installed hint is activated or on "aplication.showint" 
called
   - since called at end, allows to adjust the default behavior

  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"

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

==================================================================


<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)
*mse   al_or = interpolation pixel operation is "or" -> 1's are extended
*mse   al_and = interpolation pixel operation is "and" -> 0's are extended
*mse  ( 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 )

==================================================================

tfacecomp

 - 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
*mse   gd_(right/up/left/down)

*mse  pos{i}: = relational position of color{i} on the direction (0.0..1.0) 
extent

   transparency =  makes the face half-transparent and enlight 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:

*mse  *** 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 childs
    fao_alphafadenochildren = preserves child widgets from blending
*mse   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"


==================================================================

tframecomp:
 --------------------------

 Terminilogy :

 {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
*mse  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
*mse  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
*mse leveli = {width=height} of the internal facet, positive -> raised, 
negative -> sunken
*mse 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
 captiondist - margin between the caption & the client area
 captiondistouter :

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

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

distance is measured between
  the outer ( opposite to the facing ) extent of the caption
  and the client area

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

*mse 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 - placement "corner" for 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

==================================================================

tbitmap :
 image
  see <any image>

==================================================================
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
*mse 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)

*mse sfo_activatorread = activator activate triggers reading ???
*mse 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

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

==================================================================

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

===================================================================

==================================================================

<any font>
 charset
  - ANSI/ DEFAULT/ SYMBOL /SHIFTJIS /HANGEUL /GB2312 /CHINESEBIG5 /OEM
  /JOHAB / HEBREW/ ARABIC/ GREEK/ TURKISH/ VIETNAMESE/ THAI/ EASTEUROPE/
  RUSSIAN/ MAC/ BALTIC
  - ":encoding={enc_registry<-encoding>}"
 color
 colorbackground
 colorshadow
 extraspace
 height
  - size of the font in pixels
 name
  - ":family={name}" (Xft) / {family name}
 options:
  foo_fixed
   ":mono"
  foo_proportional
   ":proportional"
  foo_helvetica
   ":family=sans"
  foo_roman
   ":family=serif"
  foo_script
   - not used
  foo_decorative
   - not used
  foo_antialiased
   ":antialias=1"
  foo_nonantialiased
   ":antialias=0"
 style:
  fs_bold
   ":bold" (Xft) / "bold"
  fs_italic
   ":italic" (Xft) / "i"
  fs_underline
  fs_strikeout
  fs_selected
 width

==================================================================