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