VX-REXX EXTRAS
  Version 1.3.2 (2018-04-14)

  VX-REXX Extras is an extension library for Watcom VX-REXX version 2.1.  It
  contains a number of useful functions and several new object classes (a 
  Warp 4 style notebook control, an improved graphical pushbutton, a progress
  bar, and a tooltip control).  See the descriptions in VROBJEX.INF for
  details.


Files

  README.TXT      This file.
  VROBJEX.DLL     The VX-REXX Extras library (developers and runtime).
  DEVELOP.ZIP     The developer-specific files, zipped.  Contains:
  - ICONBUTT.MTO  IconButton drag-and-drop information for VX-REXX designer.
  - PROGRESS.MTO  Progress drag-and-drop information for VX-REXX designer.
  - TABBEDDI.MTO  TabbedDialog drag-and-drop information for VX-REXX designer.
  - TOOLTIP.MTO   ToolTip drag-and-drop information for VX-REXX designer.
  - TTIPMTHD.VRM  Drag-and-drop designer macro used by TOOLTIP.MTO.
  - TTIPMTHD.VRW  Drag-and-drop designer macro used by TOOLTIP.MTO.
  - VROBJEX.INF   Online help & programming reference.
  - VROBJEX.SYM   Symbol file for support.
  - VROBJEX.VXO   Library loader for VX-REXX designer.


Installing (Users)

  Copy VROBJEX.DLL to any directory on your LIBPATH.  If you have a previous
  version installed, close all VX-REXX applications before replacing the old
  copy.  Also make sure that any other old versions of VROBJEX.DLL are removed
  from your system.

  You can safely ignore the remaining files from this package unless you plan
  to develop REXX programs using this library.


Installing (Developers)

  If you have been using any functions from a previous version of this library,
  make sure you call VRXDropFuncs() from a REXX program before upgrading.
  Close all VX-REXX applications before replacing the old DLL, and also make
  sure that no other copies of VROBJEX.DLL are present on your LIBPATH, or in
  the VXREXX directory.

  Copy VROBJEX.DLL to any directory on your LIBPATH.  

  Unzip the file DEVELOP.ZIP to your main VXREXX directory. This will place
  VROBJEX.VXO, VROBJEX.SYM and VROBJEX.INF in that directory, and the MTO and 
  macro files in the VXREXX\SYSTEM subdirectory.  (Note that VROBJEX.SYM is
  only needed if you want to analyze process dumps - if you don't know what
  that means then you can safely ignore it).

  Start VX-REXX and make sure that the new object classes appear on the object
  toolbar.  (If they don't, go into "Options" --> "Object libraries", and make
  sure that the "Search for and load all VXO files" checkbox is enabled, or
  else add VROBJEX.DLL to the "Loaded object libraries" list manually.)

  (If you installed the very first preview release, called VRTABDLG.DLL, then
  you should delete TABDLG.VXO from your VX-REXX directory if it exists.  You
  can also delete VRTABDLG.DLL if it is installed on your system.)


Using the TabbedDialog class

  TabbedDialog works much like a regular notebook.  In fact, it's implemented
  as a subclass of the normal Notebook class, so it has all the same methods
  and most of the same properties.  (A few properties, like "TabShape", have
  been removed because they don't apply to this type of control.)  See the
  programming reference for details.

  Consequently, it should be quite easy to replace your old notebook objects
  with this new one.  (In most cases, just deleting the old Notebook object
  and creating a new TabbedDialog object with the same name in its place should
  work fine -- although make sure you save any properties you have configured
  in the object settings, like "InitialPageList".)

  IMPORTANT: There is, however, one extra step that you MUST take.  In the
  "Init" section of EVERY page dialog which you are adding to the TabbedDialog
  notebook, you must edit the following code:

    if( \VRIsChildOf( window, "Notebook" ) ) then do
        call VRMethod window, "CenterWindow"
        call VRSet window, "Visible", 1
        call VRMethod window, "Activate"
    end

  Either delete this code entirely, or replace the string "Notebook" with
  "TabbedDialog".  Failure to do so will cause your pages to render improperly
  when the dialog is first populated.

  The above code is managed by VX-REXX itself, and not by the object class;
  therefore, there is unfortunately no way to automate this task.


Using the ToolTip class

  The ToolTip control actually consists of two PM windows which work in
  tandem.  The ToolTip object you create in the designer is a subclass of
  the descriptive text control (you are advised to set its Visible property
  to 0 as it has no interactive use).  This in turn creates a small secondary
  window which is used to display flyover help for any number of controls
  that you 'register' with the ToolTip object.  This secondary window is
  owned by the ToolTip control, but has the whole desktop as its parent; this
  arrangement allows it to extend outside the display area of the VX-REXX
  application.  The secondary window is automatically hidden, unhidden,
  resized, and updated with the correct text, as appropriate.

  Basically, you create one ToolTip object to manage all tooltips, then use
  its Register method to associate any number of other GUI controls with it
  in order to assign them tooltips.  The beauty of this is that works with any
  type of VX-REXX control (even the program window itself).  So you can add
  tooltips to buttons, dialogs, text fields, notebooks, sliders, containers...
  whatever.

  The only real restriction is that a ToolTip object must be on the same
  thread, and share the same message queue, as any other controls that it has
  registered.  (All controls in an application are normally on the same thread
  in any case, so this should not be an issue unless your program does some
  extremely unorthodox things.)

  All tooltips managed by a single ToolTip object will share the same font
  and colours.  If you want tooltips with different colours or fonts for
  certain controls, you will have to use separate ToolTip objects for them.


Known Problems/Limitations

  IconButton control:
   - When using an icon image in a button which is smaller than the icon device
     size, the icon may extend outside the button area.  This appears to be
     caused by the internal VX-REXX API used for rendering.  (This problem does
     not occur with bitmap images.)

  TabbedDialog control:
   - When a notebook page window has focus, key events are never passed up to
     the notebook control.  This prevents things like PageUp, PageDn, and tab
     focus switching from working properly.  This is a bug in VX-REXX's own
     dialog processing, and also occurs with the standard Notebook control.
     There does not appear to be any solution other than to manually handle
     the corresponding KeyPress events in each page dialog within your VX-REXX
     program and direct the notebook control to react accordingly.  (For
     example, you could intercept Tab and Backtab KeyPress events generated by
     the last/first controls on each page, respectively, and call the SetFocus
     method on the TabbedDialog in order to switch focus to the notebook tabs.)

  ToolTip control:
   - If a registered control is obscured by another control such as a menu, the
     tooltip may still appear when the mouse is over the obscured control's
     position.
   - Registering a control on one dialog window with a ToolTip control belonging
     to a different window SHOULD work (as long as both windows are open at the
     same time), but this has not been heavily tested.  In any case, doing this
     is not really recommended.  (If you MUST do this, you should Deregister any
     controls on a window whenever that window is closed, as trying to track
     controls which no longer exist will waste time and resources.)


History

  Version 1.3.2  (2018-04-14)
  - New utility function VRXSetMultiLineEditFormat.
  - Further cleanup to the variable pool and string return logic.


  Version 1.3.1  (2015-12-12)
  - Tooltips should no longer appear for invisible controls.
  - Fixed some minor memory-management issues when writing to the variable 
    pool. (Thanks to Steve Levine for pointing them out.)


  Version 1.3.0  (2014-11-05)
  - Added new Progress control (documentation and macros updated to match).


  Version 1.2.0  (2013-06-01)
  - Added new ToolTip control (documentation and macros updated to match).
  - Added multilingual support for the built-in dialogs (VRXDirectoryDialog
    and VRXColourDialog): they will now load the dialog template for the
    current LANG + codepage, if it exists in the DLL resources.  (Currently
    English, French, German, Dutch and Japanese are included.)
  - Some other minor code cleanup.
  - (TabbedDialog) Fixed problem with PageSelected event not being dispatched.


  Version 1.1.2  (2013-05-12)
  - (TabbedDialog) SetFocus method is now supported.
  - (TabbedDialog) When a new notebook page is selected, input focus should
    no longer sometimes get stuck on the previous page window.


  Version 1.1.1  (2012-02-08)
  - (IconButton) Fixed positioning and cropping of non-scaled bitmap images
    when the button is smaller than the image size.
  - (IconButton) Autosize property now properly takes both the image and
    text dimensions into account (where applicable).
  - (IconButton) Slightly increased the margin around non-rescaled images.


  Version 1.1.0  (2012-02-06)
  - Added new IconButton control.
  - Added new VRXDirectoryDialog function.
  - Removed ContextMenu from the list of events supported by TabbedDialog
    (since v1.0.1 it hasn't been triggered anyway).
  - Added some missing property information to TABBEDDI.MTO.
  - Fixed misreported version string from VRXVersion() and reworked logic to
    make sure it's always in sync with the BLDLEVEL string.
  - Corrected several minor errors in the help file.
  - Increased minimum required VX-REXX version to 2.1.


  Version 1.0.1  (2012-01-20)
  - Implemented workaround for PM exception when clicking on a TabbedDialog
    control with no pages.
  - TabbedDialog control now supports the page list (MB2 popup) menu.
  - Added BLDLEVEL information to DLL.


  Version 1.0.0  (2010-09-26)
  - Initial release.


Acknowledgements

  Much of the VRXColourDialog function is based on public domain code by Paul
  Ratcliffe.

  While I didn't use any of his actual code, the sources for Chris
  Wohlgemuth's DrDialog User Controls library were quite helpful to me in
  fine-tuning the VRXDirectoryDialog logic.

  While the progress-bar control is a clean implementation, its default style
  is inspired by the XWPHelpers progress bar control by Ulrich Moeller.

  I'd also like to thank Herwig Bauernfeind for providing testing and
  feedback.


Notices

  The VX-REXX Extras Library is (C) 2010-2015 Alex Taylor

  Redistribution and use in source and binary forms, with or without
  modification, are permitted provided that the following conditions are
  met:

  1. Redistributions of source code must retain the above copyright
     notice, this list of conditions and the following disclaimer.

  2. Redistributions in binary form must reproduce the above copyright
     notice, this list of conditions and the following disclaimer in the
     documentation and/or other materials provided with the distribution.

  3. The name of the author may not be used to endorse or promote products
     derived from this software without specific prior written permission.

  THIS SOFTWARE IS PROVIDED BY THE AUTHOR ''AS IS'' AND ANY EXPRESS OR
  IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
  WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT,
  INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
  (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
  SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
  STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
  ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  POSSIBILITY OF SUCH DAMAGE.

--
Alex Taylor - alex at altsan dot org
April 2018
