Changes by FG
=============

The changes made can be split into three categories:

 - Cosmetic changes to give the library a more consistent coding style.
   These should not affect the API of the library at all.

 - Bug fixes that, obviously, make the library better and more robust.
   These, too, should not affect the API with the exception of the
   TextArea_GetText veneer which was bugged. The fix for it alters the
   value returned in some cases, see below.

 - New veneers that add support for Toolbox calls that were previously
   not supported. These obviously do change the API but as programs
   written against the previous version of the library didn't use them
   it shouldn't be a problem.


Cosmetic
--------

 - Make sure all FNs/PROCs are separated by 1 empty line

 - Move Tabs section to before TextArea so everything is in A-Z order

 - Have all calls to Toolbox_ObjectMiscOp followed by a REM with method name

 - Make sure SYS &44EC3 has a space between SYS and &

 - Wrapped all methods in 'REM {{{ <name>' & 'REM }}} <name>' lines
   to make identifying sections easier and to allow two level folding.

 - Make case of local variables consistent, lower case with underscore if
   more than one word (eg long_variable_name).

 - Use object% in all veneers to refer to the toolbox object rather than
   the object's name, eg 'DCS_ID%' or 'Menu%', as some veneers used.

 - Remove local variables buffer% & buffersize%, instead use WIMP% & 256
   directly (which part of the code already did anyway).

 - Window_WimpToToolbox (both PROC and FN) had unused 'LOCAL `f%' in it.

 - Removed all RESTORE ERROR lines, as ENDPROC restores error handler

 - Removed xxx = 0 for local variables, they're set to 0 on creation


Bug fixes
---------

 - Make PROCColourDbox_GetColour use SYS &44EC3 instead of SYS &64EC3.

 - PROCColourMenu_GetTitle read title from WIMP% rather than buffer%

 - PROCFontMenu_GetFont had its local error handler disabled. WHY?

 - PROCIconbar_SetEvent had an instance of SelectEvent% in it instead of
   the correct Select_Event%

 - PROCIconbar_GetSprite did not have RESTORE ERROR before ENDPROC
   (not really a problem, but inconsistent with rest of code)

 - FNMenu_AddEntry and FNMenu_AddEntryBefore had their local error handler
   declared after the SYS call to Menu_AddEntry so any errors from the SYS
   weren't being trapped

 - PROCNumberRange_GetValue - the variable used to read the precision,
   defined as a local integer, was missing the '%' at the end.

 - SaveAs veneers were all missing the local error handler that's
   present in all other veneers. (some other methods miss this too!)
   * FNActionButton_GetEvent
   * FNButton_GetFlags
   * PROCColourDbox_SetNone

 - PROCScrollList_GetSelected - passed flags in r0 had bit 0 set, but no
   flags are defined ATM (at least not in the RO5 toolbox)

 - Veneers for the Slider gadget didn't have ERROR after RESTORE so would
   reset the DATA pointer rather than restore the previous error handler.
   Might cause problems if the main program uses DATA statements

 - PROCStringSet_GetComponents didn't set any flags in r0, now it uses %11
   so icon numbers for both alphanumeric field & pop-up icon are returned

 - PROCTextArea_GetText would get the text length and then use that to read
   the text, ignoring the buffer size passed in. This could result in the
   buffer being overrun, which can cause various types of error.
   The fix for this changes the API slightly, but not a real problem.

 - PROCTextArea_InsertText`() had 2 lines that were accidentally joined

 - FNToolbox_GetObjectInfo had an erroneous 'ENDPROC' after it

 - PROCToolbox_GetTemplateName & FNToolbox_GetTemplateName error handlers
   used 'Toolbox_CreateObject' in error message, replaced with the correct
   'Toolbox_GetTemplateName' name

 - FNToolbox_IsShowing read the object's state using a global variable
   instead of a locally defined variable

 - PROCToolbox_ShowAndSetParent passed the block with coordinates in r6
   where it should be passed in r3.

 - PROCToolbox_ShowObjectAsMenu didn't pass the ptr -> coordinate block
   in r3 so object opens in wrong place for show types 1 and 2.

 - PROCToolbox_ShowObjectTopLeftAsMenu called PROCToolbox_ShowObjectAsMenu
   so suffered from the same problem.

 - PROCTreeView_GetNodePrivateWord - method code is 16433 not 16431.

 - PROCWindow_GetToolbars didn't set any flags in r0, now it uses 15 so
   all toolbars are returned (non-existent toolbars will return 0).


New methods
-----------

 - Added PROCScrollList_GetSelected` that uses the passed in index rather
   than a hardcoded -1 so that it's possible to enumerate all the
   selected items.

 - Added SetFont veneer for ActionButton, OptionButton, RadioButton and
   StringSet. Subject to change, see inconsistencies in setting a font below.
   Eg: PROCActionButton_SetFont(object%,component%,font$,width,height)


API changes
-----------

The TextArea_GetText veneer was bugged in that it could overrun the
supplied buffer. The code has been adjusted to fix this but that has
resulted in the returned value being different in some cases.

Previously the veneer would always return the size of the text + 1 (for
the terminator). In the fixed version the number of bytes written to
buffer (excl terminator) is returned if buffer is <> 0. If buffer = 0
then the size of the text + 1 (= size of buffer required) is returned.

Authors of AppBasic programs that use the TextArea_GetText veneer should
check how the return value is used and if necessary adjust the code so
that it works correctly with the fixed version of TextArea_GetText.


--------------------------------------------------------------------------------

Inconsistencies
---------------

 - Veneers that set an object's/gadget's font are not consistent. Some use
   width+height others use height+aspect, there's also floats vs integers.
   Should all veneers be changed to use the same basic implementation?
   CON: this changes the API which may cause problems for programs that were
   written against the current API.

 - PROCFontMenu_GetFont treats the returned string as a potential font
   identifier and extracts the font name, but PROCFontDbox_GetFont does not.
   (return string as is and add FNUtils_ExtractFontName(identifier$) ?)

 - Calls to Toolbox SWIs not wrapped in a local error handler

   * Various Toolbox SWIs
   * Various Window SWIs

 - Toolbox SYS calls use SWI names rather than numbers. Change to match all
   the other Toolbox veneers? Ie, change:

   SYS "Toolbox_HideObject",,object_id%

   to

   SYS &44ec4,,object_id : REM Toolbox_HideObject


Further thoughts
----------------

Currently routines that provide support code (eg FNButton_Click) are mixed in amongst the toolbox veneers, should there be a clear seperation?

Should local error handler in Toolbox veneers be wrapped around SYS call only? Other errors would then be reported through the standard error handler.

If we don't do the above then should RESTORE ERROR lines be removed given that BASIC automatically restores the previous error handler when exiting FNs/PROCs?

