'+---------------+---------------------------------------------------+
'| ###### ###### |     .--. .         .-.                            |
'| ##  ## ##   # |     |   )|        (   ) o                         |
'| ##  ##  ##    |     |--' |--. .-.  `-.  .  .-...--.--. .-.        |
'| ######   ##   |     |  \ |  |(   )(   ) | (   ||  |  |(   )       |
'| ##      ##    |     '   `'  `-`-'  `-'-' `-`-`|'  '  `-`-'`-      |
'| ##     ##   # |                            ._.'                   |
'| ##     ###### | Sources & Documents placed under the MIT License. |
'+---------------+---------------------------------------------------+
'|                                                                   |
'| === ReleaseNotes.txt ===                                          |
'|                                                                   |
'| == The GuiTools Framework's development TODO & HISTORY lists.     |
'|                                                                   |
'+-------------------------------------------------------------------+
'| Done by RhoSigma, R.Heyder, provided AS IS, use at your own risk. |
'| Find me in the QB64 Forum or mail to support@rhosigma-cw.net for  |
'| any questions or suggestions. Thanx for your interest in my work. |
'+-------------------------------------------------------------------+

TODO:
-----
- add a new GUI class to allow any GuiViews to be placed as part of other
  forms (like an <iframe> in HTML) in alternative for multiple windows
- continue work on the GuiTools Framwork documentation
  - if you have questions about anything what's not yet documented in any
    source file or the PDF, then please don't hesitate to ask for help in
    the forums or via e-mail (support@rhosigma-cw.net)
- add menus (pulldown and/or popup?)
  - placed on a hovering layer with autoclean when selection is done
  - low priority as I've no urgent need for it, using toolbars instead

HISTORY:
--------
>> 10/04/2021 v0.14
   - the entire GuiTools Framework got an overhaul to not longer relying
     on the old recursion bug, which got finally fixed in QB64 v2.0
     (https://www.qb64.org/forum/index.php?topic=4209), GuiTools now
     successfully runs on all QB64 versions from v0.954 (SDL) upto the
     latest v2.0 development builds
   - makes chunk routines SeekChunk&() and SizeUpdate() more compliant
     with the EA IFF-85 standard (https://1fish2.github.io/IFF/) and
     respectively adjusted all calls to it
   - improved ParseLine&() function to allow several separator and quoting
     chars and respectively adjusted all calls to it
   - several minor program flow changes under the hood
   - continued revision of sub/function documentation (work in progress)

>> 04/03/2021 v0.13 [silent release]
   - dropped old SHARED variable appDrives$, use new function CurrDrives$()
     instead, which returns available drives at calling time, hence also
     recognizing drives connected after application start/init
   - the SHARED variable appScreen& is no longer allowed for public access
     to protect the integrity of the GuiViews API, the only supported way
     for direct rendering into any GuiViews is from within the GUIREFRESH
     event handler using SUB SourceDestGuiView() first to designate the view
   - bugfix in GuiViews cleanup and minor changes in display logic, also
     added SUB DeleteGuiView() as counterpart to CreateGuiView()
   - replaced the old Format[n]$ functions with my new IndexFormat$() and
     accordingly adjusted all calls to it (new function is also available
     in the Forum's "Sample Gallery" board for standalone use)
   - replaced old INKEY$ workaround (for german keyboard layout) with an
     adapted version of forum member moises1953's enhanced InkeyHit$()
     routine (permission was granted), which has support for most western
     european (CP1252 based) languages
   - fixed Cut-/PasteBufBlock() functions in BufferSupport.bm, blocks
     were shifted by one byte due to the use of the wrong seek mode
   - several fixes in PackSupport.bm to avoid deadlock conditions when
     using the "hidden" progress indicator feature

>> 06/12/2020 v0.12
   - implemented GuiViews, GuiTools its new multiple forms support, no
     stuff like CHAINing from one to another form, or hiding one form and
     make another visible, but real multiple windows applications, each
     form in its own independent window on the desktop, but all controlled
     from within the same program using the same GUI object base, hence
     even realtime cross-form/cross-window object interconnections are
     possible without a hassle (see src_MultiWinDemo)
   - restored pre-v0.11 StringC class behavior, hence you'll receive the
     GADGETUP events on random unselection again, if you need it eg. for
     field verification, but it's much smarter now (will only fire the event,
     if the input field was changed since activation) and also you can
     explicitly force an input field to be quiet (new PASSIVE tag), hence
     it only fires the event on explicit user confirmation via ENTER press
   - added exception handler in FUNC RegexMatch%() in file GuiAppFrame.h
     to avoid application crashes due to invalid regular expressions
   - also added new FUNC RegexError$() to obtain a detailed error message
     for any error code which might be returned by RegexMatch%()
   - added functions to create and use shared memory objects for IPC in
     GuiAppFrame.h (required for the multiple windows communication)
   - added Bin$() number to binary string converter in file GuiAppFrame.bm
   - did rethink my label naming scheme and changed especially DATA labels
     to be more descriptive and unique in the global namespace

>> 10/01/2019 v0.11
   - changed StringC class behavior, random unselection of any active
     input field (eg. by TAB-cycling to next field or by clicking another
     object or by random mousewheel action on scrollable objects) does no
     longer trigger the GADGETUP event for the unselected string field,
     only explicit confirmation by the user (ENTER press) will do so
   - fixed a small bug in StringC class its editing logic, which could
     lead to partial reversion of the input string in certain cases
   - small change in hover layer logic, it's mostly internal behavior
   - implemented two new geometric symbols into class SymbolC, the names
     are Pentagon and Octagon (see also dev_storage\Symbols.png)
   - the ListviewC class its read-only mode can be changed on the fly now,
     as the READONLY tag is now allowed to be changed by the SET method
   - added keyboard controls to multiple choice objects CycleC, RadioC
     and ListviewC (arrow keys, Home, End, PageUp, PageDn as applicable)
     and to ScrollerC and SliderC (arrows + SHIFT and/or CTRL modifiers),
     as usual input does always flow into the currently focused object or
     into the last focused object if none has focus, however if there's
     an active string input field, then keyboard input will always flow
     into this field, ie. the key controls for the object types mentioned
     above will only work, as long as no string input field is active
   - some inprovements in FileSelect$() function, it's also keyboard
     controllable now within the limits mentioned above
   - fixed some minor inconsistencies in the init and cleanup procedures
   - improved the MakeDATA and MakeCARR applications for better speed
     and more meaningful variable names
   - created another demo application using GuiTools, this time it's a
     game called LogicTrainer, a clone of the well known Mastermind
   - continued revision of sub/function documentation (work in progress)

>> 06/09/2019 v0.10
   - The GuiTools Framework is officially under the MIT license now, also
     the licensing of 3rd party stuff was clearified (see license folder)
   - no different main source files for SDL/GL anymore, just one file for
     both QB64 branches (well, it works with the old SDL only, as long
     as you waive to commands/functions newly introduced in the GL branch)
   - some tweaks in init code and SUB SetupScreen() to automatically deal
     with the SDL-GL differences, as we only have one source for both now
   - added alternative input routine for Germany/Austria under QB64-GL,
     it will be used automatically, if the program was compiled with any
     QB64-GL version and a german keyboard layout is detected at runtime
   - optimized the remapping function RemapImageFS&() for best speed, it's
     about 22% faster in worst case, but even 79% in best case scenario,
     hence seen in average it's speed has been doubled now
   - revision of included libs Convert-, Image-, Pack- and PolygonSupport.bm
   - started revision of sub/function documentation (work in progress)

>> 12/27/2018 v0.9
   - added a window position brain which will remember each application's
     last window position by its EXE name (the SetupScreen() call can
     either center your app window or move it to its last known position)
   - added new common functions PathPart$(), FilePart$(), FileNamePart$()
     and FileExtension$() for easy parsing of path/file specifications
     in file GuiAppFrame.bm
   - bugfix in PackSupport.bm to avoid GOSUB/RETURN stack corruption
   - improved StringC class with free editing and cursor movement, find
     possible key controls in StringClass.bm
   - added MULFORMAT/DIVFORMAT tags for ModelC Ratio model to specify
     a PRINT USING (or IndexFormat$) style format for the model's output
   - changed default colors of some symbols (SymbolC class) to be in line
     with new GUI context pens (see dev_storage\Symbols.png)
   - old SCREEN 0 based MakeDATA/MakeCARR tools (dev_storage) are now
     implemented as GuiTools applications (src_MakeDATA/src_MakeCARR)

>> 11/23/2018 v0.8
   - added new MOUSEIN and MOUSEOUT events, which are maybe more useful
     than the already known MOUSEOVER event in some cases
   - added a tooltips feature for all object types it makes sense for,
     will show the text given via the TOOLTIP tag and/or the used object
     shortcut sequence (if any)
   - implemented a comprehensive user preferences system into all classes
     and wrote a prefs editor application to change settings easily
   - improved class PagerC to allow for a free definable wall area, also
     wall image behavior was changed to be in line with regular images
   - frameless TextC objects now using print mode _KEEPBACKGROUND, good
     to place independend texts anywhere
   - FrameC objects can use the regular object labeling now, good for
     cases where the regular frame text seems inappropriate
   - enhanced ListC class its "Store" method to allow for direct insertion
     into any list position, explicitly requires list sort mode "none"
   - fixed layout calculations in class ListviewC, sometimes the last
     entry was printed over the list area bounds or even outside, also
     Listviews can be created with a READONLY tag now, ie. the user may
     still browse the list, but can't select any entries
   - minor enhancements in class SliderC, using the new ALTMIN/ALTMAX tags
     it's possible to define alternative outputs for the min/max levels
   - added a trigger based increment/decrement model in class ModelC
   - added dev_framework\support\ImageSupport.bm, which contains some
     image processing functions used for drawing
   - added dev_framework\support\PackSupport.bm, which contains adaptive
     LZW packing and unpacking functions, which are used by MakeDATA.bas
     and MakeCARR.bas based file embedding
   - boolean tags now also support the words on/off beside the already
     known true/false and yes/no
   - improved the output of SUB DumpObjectArray(), you no longer need to
     have a wide window or use wordwrap to see all content
   - internal preparations for implementing menus

>> 04/11/2018 v0.7
   - added new object class ProgressC (progress indicator bars)
   - added new object class RadioC (mutually exclusive choices organized
     as vertically aligned radio buttons, good for just a few choices)
   - added new object class ListviewC (mutually exclusive choices viewed
     in a free scrollable list of any length, good for many choices)
   - added mouse scroll wheel support for several object types, will also
     use SHIFT as accelerator and CTRL as mode switch, scroll input does
     always flow into the currently focused object or into the last focused
     object if none has focus, if these objects do not support the wheel,
     then the scroll events fall through to the application's event handler
   - improved the image remapping function RemapImageFS&() to allow for
     source images of any color depth (1-32 bits)
   - implemented new object background logic, directly add a IMAGEFILE or
     IMAGEHANDLE tag and optionally the AREA tag to the object's init call,
     you no longer need to init an ImageC object yourself and assign it
   - pulled several recurring code sections into SUBs in order to keep
     the compiled EXEs filesize down
   - the entire tag string API internals reworked for better performance
   - added a FileRequest/Open dialog box function for easy file selection
   - added regex support, eg. used in the new FileSelect$() function,
     note that the regex stuff is experimental/limited in QB64 versions
     published before January, 5th 2019, as the used C/C++ compiler in
     older QB64 versions has issues with it, that's why it is not
     activated by default, to switch it on follow the instuctions given
     in file dev_framework\GuiAppFrame.h
   - improved the keyboard shortcut handling, the always use ALT requirement
     has been removed, hence you now can use ALT yourself to vary shortcuts
   - a couple of changes to the GuiAppDemo.bas program in order to showcase
     some of the new Objects and functions

>> 12/29/2017 v0.6 [not released]
   - once more changed the tag introducer, separator and terminator tokens
     to avoid not only any conflicts with regular writing, but also with
     Ctrl-Key based keyboard shortcuts
   - finetuned the event message system for better behavior with StringC
     objects and GADGETDOWN (immediate) events in general, these will also
     reported immediately now by ColorwheelC, SliderC and ScrollerC objects
     on any knob movements
   - added new routines UserInitHandler and UserExitHandler as contextual
     defined places for embedded files writeback and cleanup
   - added individual icons for MessageBox windows (its use is optional)
   - some detail changes in SUBs SetupScreen() and CloseScreen() and much
     more under the hood in almost every object class
   - StringC class does support cut/copy & paste via clipboard now, but
     entire content only, no partly selection (see descriptions in file
     StringClass.bm for a list of possible editing/control shortcuts)
   - Sliders/Scrollers now have an extended focus area when releasing the
     left mousebutton after moving the knob to a new position, avoiding
     the knob jump back to its old position, if the mousepointer is not
     exactly in object focus when the button is released, the area is
     extended by 50 pixels in each direction around the Slider/Scroller
   - improved the ScrollerC demo (Page 6 of GuiAppDemo.bas program),
     it's the old simulation where you can play around with the vital
     scroller values, but there's also a practical example scrolling
     around in the actual background image

>> 05/09/2017 v0.5a
   - Tag introducer, separator and terminator tokens changed to use some
     control chars in TagSupport.bi (this seems to be the best way now,
     to avoid any conflicts with regular written text (TagName&Data))
   - default _ICON image is easier replaceable now, as I moved it out to
     include files GuiAppIcon.h/.bm (made with MakeCARR.bas), some minor
     changes in Image Class for this
   - function MessageBox$() does preserve pre-formatted text (indention)
     now, also a leading dash (-) found in any line becomes a list bullet
   - some improvements in String Class, GADGETDOWN event is now send not
     only for selection of an input field, but also for each char entered
     into the active field, GADGETUP is send on unselection of any field,
     doesn't matter if this happend because of a RETURN press, cycling to
     another field or a mouseclick outside the active field, finally you
     can use the arrow up/down keys now in addition to the TAB key for
     cycling through available (visible) fields

>> 04/12/2017 v0.5
   - new folder structure to better match the contextual file assignments
     (if you already made own Apps, then you should adapt them to the new
     structure to make future updates easier)
   - now all SUBs/FUNCs are documented at least to a minimum extent within
     the source files (src_GuiAppDemo also contains a lot of useful comments)
   - complete rework of the keyboard shortcut handling to allow for
     additional shift, alt and ctrl modifiers (if you already made own Apps,
     then you have to rework all used SHORTCUT tags in your Apps)
   - the Tag String API got two new functions, UpdateTag% and UpdateTags%,
     see include file TagSupport.bm for a description
   - added new class CycleC, which is a simple mutually exclusive choice
     button, compareable with a drop down list, but without the drop down
     feature, it will just cycle through the list entries on each click
     (eg. the "Quit Button Text" object on Page 3 of GuiAppDemo.bas)
   - added new class ScrollerC, which provides horizontal and vertical
     scroller objects (see Page 6 in the GuiAppDemo.bas program)
   - added new class StringC, which provides single line text/number
     input fields, can limit input length and allowed chars and does
     also support fwd/bwd TAB-cycling if more than one field is visible,
     but does not yet support cut/copy&paste via clipboard (see Page 6)
   - some minor changes under the hood were required to smoothly implement
     the full ScrollerC functionality and to improve the ModelC behavior
   - now all operational objects (Button, Textfield, Slider etc.) accept
     a IMAGEOBJECT and/or SYMBOLOBJECT assigned to it, how much sense this
     makes for the one or other object type I'll leave up to your own
     imagination, the handling logic for it is now there at least
   - now works with "Output EXE to source folder" option in QB64-GL

>> 01/27/2017 v0.4
   - added new class CheckboxC, which provides checkboxes of course
   - added new class SliderC, which provides horizontal and vertical
     slider objects with free ajustable integer range
   - added new class ModelC, which provides GUI object interconnection,
     this is a simple way to establish an information exchange/alteration
     channel between related objects w/o any further required interaction
     by your application code (ie. it makes the objects talking to each
     other directly, rather than thru your applications event handler),
     the possibilities range from simple value forwarding to manipulations
     between objects of a complex object model (therefore ModelC) and
     more model schematics can be easily added in the future
   - implemented the first three models into class ModelC, the first will
     simply "Forward" a value between two objects, the second one is named
     "Ratio" and can be used to connect two objects with a certain ratio
     between their values (eg. for keeping aspect ratio between a width and
     a height slider, or for a currency/unit converter etc.), the third is
     an HSB <-> RGB colorspace converter model called "HsbRgb"
   - added new class ColorwheelC, which draws a HSB colorwheel of the
     specified size with a free movable knob which allows easy hue and
     saturation selection (color picker), together with some sliders and
     a ModelC interconnection (HSB<->RGB) a complete palette tool can be
     easily created (see Page 5 in the GuiAppDemo.bas program)

>> 12/17/2016 v0.3 [not released]
   - added a hovering layer in preparation for later menu implementation
   - changed IMAGEOBJECT/SYMBOLOBJECT behavior, so that images/symbols can
     be unassigned from parent objects without the need to reassign another
     image/symbol instead
   - added CLEARCOLOR tag to class ImageC to specify a transparent color
   - added IMAGEHANDLE tag to class ImageC to specify any existing image
     instead of loading an image from disk via the IMAGEFILE tag
   - added a star symbol to class SymbolC, also improved reference picture
     dev_storage\Symbols.png so that you see the nominal symbol width/height
     as well as the coordinate origin and used default colors

>> 10/29/2016 v0.2
   - added new class ImageC, which is used as container for all loaded and
     remapped Button/Wallpaper images, may also be used to place standalone
     images in the GUI, such as Logos/Banners etc.
   - easier define of a screen background image now, no fiddling in the
     GUI refresh code required anymore, just init an Image object with the
     BACKFILL tag set true and the Image class will do the magic
   - added new class SymbolC, which provides a number of simple but free
     scaleable polygon based images such as tapedeck symbols, checkmark,
     arrows etc. (see dev_storage\Symbols.png)
   - enhanced PagerC/ButtonC/TextC classes to allow for a ImageC/SymbolC
     object in addition to, or instead of the button text, so there are
     already the basics now to build image toolbars or filelist views
   - enhanced the MessageBox$() function to allow image/symbol specifications
     for its buttons

>> 04/10/2016 v0.1b
   - added SET/GET methods to all non-interactive classes, even if those
     methods are of minor use for these classes (for user tags only), but
     now all classes do support the four standard methods INIT/SET/GET/KILL
   - added some more wallpaper images, patterns and icons (image folder)
   - added dev_framework\support\PolygonSupport.bm, which contains some
     functions needed for the SymbolC class planed for the next release

>> 02/01/2016 v0.1a
   - reworked type casting in GuiAppFrame.h mutex functions
   - on QB64 level changed the affected function results to _OFFSET type
   - the project can be compiled with both QB64-GL build versions now,
     with x32 compiler and x64 compiler

>> 01/30/2016 v0.1
   - alpha development
   - tag strings API
   - class API incl. root/parent/child hierarchy
   - input/update handling following hierarchy
   - put framework files together
   - optimized Floyd-Steinberg image remapper
   - first demo release

