Watcom VX-REXX

═══ 1. Using online information ═══ The most up-to-date information on VX-REXX is available online in the VX¨REXX Programmer's Guide and and the VX¨REXX Reference. The Errata section of this document lists the differences between the online documentation and the printed manual. In addition to online books, full context sensitive help is available within the VX-REXX development environment. Simply activate the VX-REXX window by clicking on it, and press the F1 key. A help window will appear, with general information about the VX-REXX development environment. You can also access help for VX-REXX from its Help menu. For more specific help on any of VX-REXX's menu choices use the cursor keys to choose a menu item, or hold down mouse button 1 on the menu item, and press F1. The context help is linked to the full text of the VX¨REXX Programmer's Guide and VX¨REXX Reference. To access help on an object, for example, click on the object in the tool palette and press F1. A help window will open with a short description of the object. Within the description the object name will appear with special highlighting. Double click on this field to see the complete reference entry for that object. ═══ 2. Workplace Shell Integration ═══ Workplace Shell (WPS) Integration o Create new projects by dragging and dropping o Edit VX-REXX objects using WPS techniques o Drag and drop programming o Assigning icons to your progrmas o Providing help for your programs o Multi-threaded programs o Shutdown and Window List messages o Presentation Manager windows ═══ Create new projects by dragging and dropping a project template ═══ The Projects folder in the Watcom VX-REXX folder contains a VX-REXX Project template. Drag and drop this template to create a new project folder. Open the folder and double click on the Project.VRP icon to edit the project. You can also open projects by dropping the project (VRP) file on the VX-REXX icon contained in the Watcom VX-REXX folder. For information on developing VX-REXX projects, see Creating and running projects in the Programmer's Guide. ═══ Edit VX-REXX objects using Workplace Shell techniques ═══ o Use mouse button 1 to select and resize objects. Both marquee and swipe selection are supported. o Use mouse button 2 to move objects and to open their pop-up menus. o Directly edit text objects by clicking mouse button 1 while pressing the Alt key. o Directly modify objects using their property notebooks. You can open a property notebook either by using an object's pop-up menu or by double clicking on the object. o Drag and drop fonts and colors from the Workplace Shell font and color palettes. You can drag fonts and colors from these palettes onto VX-REXX objects to set their font and color properties. Note that to set the foreground color on an object, press and hold the Ctrl key while dragging and dropping the color, otherwise the background color will be set. For more information, please see Adding objects to a window and Changing object properties in the Programmer's Guide. ═══ Write code using drag and drop programming ═══ Using the VX-REXX drag and drop programming feature entire programs can be written without typing a line of code. For example, to create code to get the value of an entry field you simply drag the entry field and drop it on the editor where the code is to be inserted. Then you select the Value property from a list, click OK, and the code is inserted, complete with the name of the entry field. You can also insert code directly using the Insert code item in the section editor's Edit menu, and you can configure VX-REXX to copy the generated code to the OS/2 clipboard so you can use this feature with external editors. The A simple program chapter of the Programmer's Guide shows how to use the drag and drop programming feature. ═══ Assign icons to your programs ═══ Icons can be assigned to VX-REXX executables (EXE) programs using the General page of the program's Settings notebook. You can also set the icon by placing an icon (ICO) file with the same name as the program in the same directory as the program. Once assigned, a program's icon is used within the Workplace Shell to represent the program. It is also used when the program is running as the title bar icon, and as the icon used to represent a minimized window. ═══ Provide context sensitive help and status information ═══ VX-REXX objects include properties that you can use to provide help and status information (hints) to your users. The help, either a simple text window or an OS/2 Information Presentation Facility help panel, is automatically displayed when your user presses F1. Hints are automatically displayed in the status area whenever an object has the focus or the pointer is moved over an object. For more information, please see Adding help to a program in the Programmer's Guide. ═══ Create programs with multiple threads ═══ Every VX-REXX program contains multiple threads. This means your program will not freeze the system while it performs long calculations. You can also create and control threads within your own program so you can optimize your use of the computer. For more information, please see the StartThread method in the Reference. ═══ Respond to Window List and shutdown messages ═══ Your users can halt your programs using the OS/2 Window List or by shutting down OS/2 -- even when your program is performing long calculations. You can provide code to ensure your application shuts down gracefully when interrupted, so for example, you can give your users a chance to save or discard their data when OS/2 is shut down. For more information, please see the Halt routine in the Reference. ═══ List, control, and send keys to PM windows ═══ You can write programs that list and control windows on the OS/2 desktop. You can get and set their caption, position and size, and z-order, as well as enable, disable, minimize, maximize, and restore them. For more information, please see the Working with other programs chapter in the Reference. ═══ 3. Commonly Asked Questions ═══ General o Known limits and problems o Recovering from system crashes o Running programs from VX-REXX o Modal vs. modeless windows o Common mistakes o Tab order o Using OS/2 file types o Making VX-REXX programs that do not require Presentation Manager Objects o The VX-REXX console o Using the ComboBox and DropDownComboBox objects o Using the GroupBox object o Object naming o Overlapping objects REXX questions o Common REXX coding errors o Opening and closing files o Reading and writing files o Returning multiple values Compatibility issues o Issues with the SOMObjects Toolkit o Issues with OS/2 2.0, Microsoft LAN Manager o Issues with Quercus System's Personal REXX ═══ Known limits and problems ═══ Presentation Manager restrictions: o ListBox, ComboBox and DropDownComboBox objects can only hold a certain amount of data. The exact number of lines depends on the length of the lines, but is commonly between 1500 and 2000 lines. o Placing several hundred objects on a Window can exhaust the Presentation Manager memory area, and you will not be able to create any more objects unless you delete some first. There is usually no valid reason for having so many objects and you should consider splitting your window into two or more windows. Video driver problems: o Early versions of the Compaq QVision video driver caused problems with VX-REXX and other applications. Contact Compaq for an updated driver if problems occur. o Problems with VX-REXX have been reported on machines running OS/2 2.11 and ATI video cards based on the MACH-32 chip. These problems are under investigation. Property notebook updating: o Open property notebooks are not updated while open to show the results of drag and drop fonts and colors. To refresh the values on a page, turn to another page, then turn back to the first page. Closing and reopening a notebook also refreshes the values. Loading files saved as text: o Not all syntax errors in text-format (VRT) window files are reported. In these cases the file will load successfully, but the window will not appear. If this happens, fix the syntax errors in the text file and reload it. Debugger restrictions: o Because of the way the debugger handles breakpoints, it is impossible to break a program on the first instruction in a file. o The current version of the interactive debugger supports only the main thread of a program. Use the standard REXX trace instruction with the VX-REXX console to debug multithreaded projects. ═══ Recovering from system crashes ═══ If your OS/2 system crashes or locks up while you are editing a VX-REXX project, it may be possible for you to recover the project. The program RECOVER.EXE has been provided to help in this task. Temporary directories VX-REXX creates temporary directories where it saves all files in an open project. The directory names have the form __TMP<n> where <n> is a number between one and nine. Attempts are made to create temporary directories under the following directories, in the order listed: 1. The directory specified in the TMP environment variable, if it is defined. 2. The root of the current drive. 3. The root of the drive containing VX-REXX. A temporary directory contains the macro version of a project. There are files with extensions of VRM and VRW which correspond to project files of the same name but with extensions of VRX and VRY, respectively. A temporary directory also contains files with an extension of CMD. These files contain individual sections of a project. All sections can be found in the CMD files. However, the section names and the project files from which the sections were taken are not saved in the temporary directory. The RECOVER utility rebuilds a project from the VRM and VRW files in a temporary directory. It does not consider the CMD files. This utility may be able to recover changes to a project which have been lost due to a system crash. Using RECOVER This program lists temporary directories from which VX-REXX projects can be recovered. The search for these directories is carried out in the locations stated above. Note that the roots of all drives will be searched for temporary directories. If a project needs to be recovered from a network drive or a floppy disk, ensure that the appropriate disk is accessible before running RECOVER. Also, make sure that you do not delete directories that are currently in use by a VX-REXX session. If you are unsure which directories are being used, simply close all VX-REXX sessions before recovering or deleting a directory. P.To determine which temporary directory contains a particular project, select a directory from the directory listing. The window and code files contained in the directory will be listed. Select a file and then press the View File button in order to view the file. Browse through the directory listing and view files until the project to recover has been found. Note that more than one temporary directory may contain a given project. In this case, use the dates of the directories to determine which version of the project needs to be recovered. When the directory containing the project to recover has been found, press the RECOVER button. First the name and path of the project file will be requested followed by prompts for new names of the code and window files. Pressing Cancel during any of these prompts will cancel the recovery from the selected directory. It is strongly recommended that new directories be created in which to place the recovered projects as there is no guarantee that the recovered project will work properly. Recovering the project on top of an old copy of the project can be risky. After the names of all files in a project have been specified, the project will be recovered and the temporary directory containing the project may be deleted. Usually, this directory is deleted to prevent the accumulation of temporary directories. However, it may be retained if its CMD files need to be examined or recovered, since this utility does not recover these files. In addition, there is a Delete button which allows you to delete VX-REXX temporary directories without recovering the projects they contain. You may wish to do this if all available temporary directory names are already in use, which prevents VX-REXX from running. You may also do this if the project in a directory has already been recovered, and so the contents of the directory are no longer needed. ═══ Making VX-REXX programs that do not require Presentation Manager ═══ You may use VX-REXX to create applications that run in OS/2 full-screen or windowed sessions providing the following restrictions are met: 1. The VX-REXX project has no window files. 2. The project does not use VRGet, VRSet, VRMethod, VRFileDialog, VRFontDialog, VRMessage, VRMessageStem, VRPrompt, VRWindow, or any other function that can only be run in a Presentation Manager session. 3. The executable is marked as a non-PM executable. To mark an executable as a non-PM executable, use the exehdr program, which is part of the OS/2 Toolkit and also included with VX-REXX. For example, to mark test.exe as an executable for use in OS/2 windowed or full-screen sessions, use: exehdr /pmtype:windowcompat test.exe ═══ Using the ComboBox and DropDownComboBox objects ═══ ComboBox and DropDownComboBox behaviour with respect to the Click event changed in version 2.0 of VX-REXX. Here are the important points to remember: o The Click event occurs when a new item in the list is selected, not for each mouse click. o When responding to a Click event, use the Selected property or SelectedString property to determine which item in the list was selected. The Value property is not necessarily accurate at that point in time. o When responding to a Change event, use the Value property to determine the new value. In addition, note that the Height of a DropDownComboBox object is the height of the visible area plus the height of the drop-down list. If the height is too small, the drop-down list will not be accessible by the user. ═══ Using the GroupBox object ═══ In VX-REXX, the GroupBox object contains the objects that are placed inside it. Objects in a group box cannot be moved outside the group box except by cutting and pasting them. ═══ The VX-REXX console ═══ VX-REXX provides a simple console window that is used to display messages that would normally be displayed in an OS/2 window or OS/2 full-screen session. Output from the REXX SAY statement (usually called the standard output stream) is printed on the console. User input for the REXX PULL statement (usually called the standard input stream) occurs from the console. Here are a few tips to using the console: o To shut off the console or log it to a file, use the VRRedirectStdIO function. o The console can be show, hidden, moved or resized under program controls. See the Using objects chapter in the Programmer's Guide and the Console object in the Reference. o The console may not always work when running a VX-REXX program as a macro within another application because that application may be intercepting the standard input and output streams. Refer to that application's documentation. ═══ Running programs from VX-REXX ═══ General Programs are run from within a VX-REXX project by using the facilities provided by the OS/2 command interpreter, CMD.EXE, and the ADDRESS statement. To run a program FOO.EXE and suspend the VX-REXX project until the program has finished, use this syntax: address cmd 'foo' You may use the usual redirection operators, as in: address cmd 'dir >out.lst' To run a program FOO.EXE without waiting for it to finish, use the OS/2 START command: address cmd 'start foo' To get help for the START command, type help start from and OS/2 window. VIO support Certain types of OS/2 programs require direct access to the OS/2 console. This direct access is provided by a system facility called "VIO support". Presentation Manager programs such as VX-REXX cannot directly run programs requiring VIO support. If you run such a program, you will get the following error: SYS0436: An invalid VIO handle was found The OS/2 PSTAT command, for example, requires VIO support. To run such a program from VX-REXX, you must use the START command to run the program in its own OS/2 window: address cmd 'start /win pstat <con >con 2>&1' Redirecting the standard input, output and error streams By default, VX-REXX redirects the standard input, output and error streams to its own console window. If you start a program or an OS/2 command, its output is sent to the console and its input is taken from the console. For example, the following instruction sends a directory listing to the console: address cmd 'dir' When you run non-PM programs, the output is sent to the console unless you explicitly redirect it to a file using the > operator: address cmd 'dir >out.lst' Use the < operator to redirect input. Use the 2> operator to redirect standard error. Standard error and standard output may be merged by using the syntax 2>&1. To redirect to the console instead of a file, use con as the filename: address cmd 'start /win pstat <con >con 2>con' ═══ Modal vs. modeless windows ═══ A modal window disables its parent window, but a modeless window does not. Modal windows must be dimissed before processing can continue in the parent window. Modal windows are most often created as the primary window in another window file, and that window file is called whenever the modal window is to be displayed, passing the value of VRWindow as the first parameter. A modal window may also be created as a secondary window, however, and should be loaded using the wait option of VRLoadSecondary. Modal and modeless windows always stay on top of their parent window. If you want a modeless window to act like the main window of your application, you must load it using VRLoad instead of VRLoadSecondary, passing a null string as the parent window. For more discussion on modal and modeless windows, see the Creating custom dialogs, Secondary windows, and Multiple file projects chapters in the Programmer's Guide. ═══ Common mistakes ═══ Referencing a window before it is loaded The primary window in a window file is automatically loaded by VX-REXX, but any secondary windows must be explicitly loaded by calling VRLoadSecondary. If a window is not loaded and you try to set or get any of its properties, a syntax error will occur. You can use the VRIsValidObject function to determine if a window or other object is available. ═══ Object naming ═══ Two new forms of object naming, parent-child naming and context-sensitive naming, simplify the building of complex projects. o Parent-child naming o Context-sensitive naming ═══ Tab order ═══ When creating new objects, those objects are placed at the end of the tab order. Objects pasted into a window, however, are not placed at the end of the tab order. They keep their current tab index and the tab indices of other objects on the window are adjusted accordingly. You should create and edit your windows without regard to the tab order, then set the tab order in the final version. To set the tab order, you can either set the TabIndex property on objects in a window, or you can use the tab editor which is described elsewhere in this document. ═══ Issues with the SOMObjects Toolkit ═══ The initial release of SOM version 2 was not compatible with certain SOM-based applications, including VX-REXX. IBM has released a corrective service disk for SOM-2. Ask your IBM service representative for the SOM-2 CSD 2.02 or higher. ═══ Issues with OS/2 2.0, Microsoft LAN Manager ═══ IBM OS/2 2.0 Service Pak required IBM OS/2 version 2.0 with the OS/2 Service Pak or higher must be installed prior to installing VX-REXX. If you are running OS/2 2.0 without the OS/2 Service Pak, you must obtain it from IBM and install it to make sure that all features of VX-REXX work correctly. The Service Pak can be number XR06055 or XR06100. You can obtain the Service Pak from the IBM OS/2 BBS, from CompuServe, or directly from IBM. Contact your IBM representative for more information. IBM OS/2 2.1 and Microsoft Lan Server The released version of OS/2 2.1 does not support Microsoft Lan Server public applications properly. Public applications will work under OS/2 2.1 if an IBM patch for OS/2 2.1 is applied. Contact IBM support and ask for the fix for APAR PJ08829. Note that the VROBJ.DLL file must be in the same directory as the VX-REXX executable (EXE) file that uses it, or in some directory listed in your LIBPATH. Your LIBPATH is set in the CONFIG.SYS file in the root of your OS/2 volume. ═══ Issues with Quercus System's Personal REXX ═══ Syntax errors with Quercus System's Personal REXX When running under Quercus System's Personal REXX version 3.0a syntax errors are either reported only within the VX-REXX console or both within the VX-REXX console and the standard VX-REXX error dialog. Multithreading problems with Quercus System's Personal REXX When running under Personal REXX version 3.0a multithreading problems can occur. Users are encouraged to contact Quercus Systems. Contacting Quercus Systems For more information on Personal REXX, please contact Quercus Systems at the following address: Quercus Systems P.O. Box 2157 Saratoga, CA 95070 USA (408) 867-7399 (408) 867-7489 (FAX) ═══ Overlapping objects ═══ Overlapping objects may not be displayed correctly unless the ClipSiblings property is set for every object that intersects another object. See the section on moving objects to the front and back in Adding objects to a window for more details. ═══ Common REXX coding errors ═══ Blank space where it does not belong In REXX expressions, blank space is interpreted as an implicit concatenation operator (the terms are concatenated with a blank in between). As a result, REXX will interpret many mistyped statements as an expression involving the blank concatenation operator. For example, inserting a blank after a function name in a function call changes the meaning of the expression: textUpper = translate ( text ) to: textUpper = "TRANSLATE" || " " || text Blank space also plays a special role in the parse instruction. Compare the following: parse arg a b c parse arg a, b, c The first line parses the first argument passed to the routine into three parts, the second line sets the three variables to the value of the first three arguments passed to the routine. Function calls versus the CALL statement When you call a routine that returns a result, you must enclose the parameters in parentheses: text = VRGet( "EF_1", "Value" ) If you are calling a routine that does not return a value, you should use the call instruction: call VRSet "EF_1", "BackColor", "Blue" Note that there is no comma between the name of the routine and the first parameter. Ignoring return values of functions When using a function as a procedure, you must not ignore the return value. If the return value is not handled it will be passed to the default host environment as a command. This will normally result in a failure trace message. Either assign the returned value to a variable or use the call instruction to call the function as a procedure. Line continuation In REXX, the comma is the line continuation character. It is required when extending one clause over several lines. For example, call foo a, b, c can also be written as call foo a, , b, , c It is easy to forget the second comma if you are breaking a line in the middle of a parameter list. Omitted arguments REXX allows arguments to be omitted. Be careful not to omit arguments by accident. The following calls foo with four arguments (the first one is omitted). call foo, a, b, c Undefined variables It is not a syntax error to use undefined variables in REXX. Undefined variables are defined to have their own name translated to uppercase as their value. As a result it is often difficult to find programming errors that are a result of using undefined variables. o Add a "SIGNAL ON NOVALUE" statement to the main section of your programs. This will cause the system to issue a syntax error if you use an undefined variable. o Be careful to include the period when referring to stems. The variables A and A. are unrelated. o Misspelled commands will often be interpreted as undefined variables. The line sy 'hello' (which should be "say 'hello'") will be interpreted as "SY" || " " || 'hello' Thus the string "SY hello" will be sent to OS/2 for execution, resulting in a command failure error. Using expressions in the tail of a compound symbol The tail of a compound symbol can only be a simple variable, as in: ok = A.I Literals are not allowed. For example, the following is interpreted as a concatenation between A. and "name" bad = A."name" Expressions are not allowed. The following is interpreted as "bad = (A.I) - 1". bad = A.I-1 A way around this is to assign the literal or expression to a simple variable and use that to form the compound variable. For example: J = I - 1 ok = A.J ═══ Opening and closing files ═══ Explicit open and close commands are not required to read and write files using REXX, but you must be aware that once you access a file it is left open unless you explicitly close it. You cannot delete files that are open and you may be unable to open new files if all available file handles have been used. To avoid such problems, be sure your REXX program closes any files it opens as soon as it is done with them. For example, the following code opens a file called baker, writes to it, and closes it: call stream "baker", "c", "open write" call lineout "baker", "Skip to the loo" call stream "baker", "c", "close" For more information about the stream instruction, see the online REXX Information. ═══ Reading and writing files ═══ Data is read from a file using the LINEIN and CHARIN functions. Data is written to a file using the LINEOUT and CHAROUT functions. These functions can also be used to read and write from serial ports, however there also exist REXX function libraries geared specifically towards this task. ═══ Returning multiple values ═══ Multiple values can be returned from a function by concatenating them into a single string, returning the string, then using parse to break the return string into separate values. Another way to return multiple values is to use the PutVar and GetVar methods. ═══ Using OS/2 file types ═══ OS/2 files have the concept of a file type which may be associated with every file. The file type is a text string which describes the contents of the file. Not all files have a file type (ie. the file type is the null string). The following file types are predefined by OS/2: Assembler Code Binary Data Bitmap C Code DOS Command File Dynamic Link Library Executable FORTRAN Code Icon Library Metafile Object Code OS/2 Command File Pascal Code Plain Text Resource File You can get a list of all file types defined on your computer by using the VRListFileTypes function. To set the file type for a file, use the VRSetFileType function. The VRGetFileType function returns the file type for a given file. You can pass file types to the VRFileDialog function to display files that have a certain file type. ═══ 4. Errata ═══ Errata: August 1994 printing Manual Omissions Corrections and Additions ═══ Omissions from the printed manual ═══ The following functions and methods are described only in the online version of the Reference: (none) ═══ Corrections and additions ═══ The following table lists corrections and additions to the August 1994 printing of WATCOM VX-REXX Programmer's Guide and Reference. The number in the left column is the page number, and the right column describes the necessary change. 86 In the "Renaming an object" section, the second label in both event routines should be PB_Start_ClickEnd:. 125 A new section called "Selecting records" has been added. See the online version of the Programmer's Guide. ═══ 5. New since 2.0 ═══ ═══ 5.1. New in version 2.1 ═══ What's new in version 2.1: Design environment General Code sharing Object renaming New options Menu editor Section editor Code generation macros Property notebook Runtime environment General Parent-child naming Context-sensitive naming Drag-drop support Functions Methods Properties and events Objects Window manipulation Sample programs Bounce CUA 91 ═══ Property notebook changes ═══ o The property notebook now uses a 10 point "Helv" font. o Context-sensitive help is available for any property or event by pressing F1. o New property notebooks open to the last page that was turned to in an already open property notebook. This makes it easier to change the same property on different objects. ═══ Parent-child object naming ═══ Version 2.0 introduced parent-child object naming, where if you had two objects with the same name (on two different secondary windows, for example) you could distinguish between them by including the name of the parent object, as in: call VRSet 'SW_1.PB_1', 'Caption', 'First' call VRSet 'SW_2.PB_1', 'Caption', 'Second' If an object was contained inside a group box, you could extend the notation: call VRSet 'SW_1.GB_2.PB_1', 'Caption', 'In the box' This notational convenience has been extended so that you do not have to specify every parent object. If MyButton is a push button inside the group box MyGroup located on the window MyWindow, the following notations all work: call VRSet 'MyWindow.MyGroup.MyButton', 'Caption', 'A' call VRSet 'MyWindow.MyButton', 'Caption', 'B' call VRSet 'MyGroup.MyButton', 'Caption', 'C' call VRSet 'MyButton', 'Caption', 'D' (If there are two group boxes called MyGroup on different windows, only the first two forms uniquely identify the object.) The internal handle of an object, obtained using: handle = VRGet( 'MyWindow', 'Self' ) or inside an event routine using: object = VRInfo( 'Object' ) can be substituted for a symbolic name at any point: handle = VRGet( 'MyWindow', 'Self' ) call VRSet handle || '.PB_2', 'Caption', 'foo' ═══ Context-sensitive object naming ═══ If an object name is passed to VRGet, VRSet or VRMethod, the Window where the last event was generated is searched first. In other words, if inside the Click event for PB_1 you say: call VRSet 'PB_1', 'Caption', 'Foo' the new behaviour is equivalent to: window = VRInfo( "Window" ) if( VRIsValidObject( window || '.PB_1' ) )then call VRSet window || '.PB_1', 'Caption', foo else call VRSet 'PB_1', 'Caption', foo The name of the Window on which the object is located is implicitly added to the front of the object name. This behaviour only applies to programs generated using VX-REXX 2.1. You can explicitly turn it off using: call VROptions 'NoImplicitNames' or turn it on using: call VROptions 'ImplicitNames' Unless explicitly changed, programs created with earlier versions of VX-REXX do not exhibit the new behaviour. ═══ Code sharing ═══ Shared routines (sections) can be added to a file using the Section List window and the Add menu item. You will be prompted for the name of a file. The contents of the file will be appended to the current code or window file when the project is compiled into an executable or a macro. You may edit a shared section by double clicking on the entry in the section list. If a relative path name is given, the file will be searched for in the following order: relative to the project directory, then relative to the directories in the VXINCLUDE environment variable, then relative to the directory in the VXREXX environment variable. ═══ General ═══ o Objects can be dragged from the tool palette and dropped onto a window. o The design environment prompts you for a window name when creating new primary or secondary windows. o The menus the Window, Section and File lists are now accessible as popup menus as well. o The system menu for primary and secondary windows is now active in design mode. This means that you can close a window in the design environment by double clicking on its system menu. o The menu editor has been moved to the Open menu item on the pop-up menu for the Window object. o A Tab Editor can be used to set the tab order of objects on a window. It is accessed by selecting the Tab editor... item from the Open... menu on the Window object's pop-up menu. o A new Close window menu item has been added to the Window pop-up menu. You may use this for closing a Window with no system menu. o When a secondary window is created, new Init and Fini routines for that window are created. The Create and Close events automatically call the Init and Fini routines. o The UserData property is now encoded when a file is saved as a text file. o Sections can be renamed. o Hints are now displayed at design time. ═══ Object renaming ═══ The design environment includes some enhancements to object renaming: o Clicking on an object while holding the Alt and Shift keys down can be used to change the name of the object. o When an object is renamed, the design environment updates references to that object in the REXX code. The references that are changed all have the format name_suffix, where name is the old name of the object and suffix is any string without underscores. To be changed, name must be a string starting with a series of alphabetic characters followed by an underscore and any sequence of alphanumeric characters. Only the following references are changed in the REXX code: - Literal strings - Labels - call and signal instructions For example, if the object PB_1 is renamed to PB_Open, the following code: PB_1_Click: if( VRGet( "PB_1", "Caption" \= "" ) then signal PB_1_ClickEnd call VRSet "PB_1", "Caption", "Clicked" PB_1_ClickEnd: return is updated to: PB_Open_Click: if( VRGet( "PB_Open", "Caption" \= "" ) then signal PB_Open_ClickEnd call VRSet "PB_Open", "Caption", "Clicked" PB_Open_ClickEnd: return But note that if PB_1 had been renamed to Foo, then renaming Foo to another name would only rename the sections that belong to Foo, and not any references in the REXX code. ═══ New options ═══ The Options menu has been reorganized: o Run options has been moved from the Options menu to the Run menu. o The new Autosave item can be used to set timed reminder messages for saving your project. An option is also available to automatically save the project before running or debugging it. o The new Messages item lets you control the verbosity of the design environment. o The new Object libraries item lets you automatically load object libraries. This item replaces the Add object library and Remove object library items in previous versions of VX-REXX. o The Editor item now allows you to specify a default header for new sections, and to use the VX-REXX section editor instead of an external editor when editing files. o The new Advanced item controls whether or not executables made with VX-REXX are compressed (the default) or simply encoded. ═══ Menu editor ═══ o The menu editor is now accessed from the Open... item of the pop-up menu or by double-clicking on the window menubar. o A bug in the menu editor has been fixed allowing the editing of menu items with the same caption. o A Clear button has been added to the menu editor, which clears the current values in preparation for inserting a new menu or menu item. o After editing, menus can be viewed at design time. Simply select the menu sa you normally would. You may also double click on a menu or menu item to bring up its property notebook. ═══ Section editor ═══ o Fixed the bug that could cause a crash when selecting large amounts of text. o Fonts and colors dragged from the OS/2 font and color palettes are now supported. Fonts and colors may also be changed using the items under the Settings menu. o Font, color and window size settings can be saved. o Menu items and accelerators have been added to run the project and to switch to various windows. o Case-sensitive search and replace can now be done. o Easier access to online help. o Characters are no longer missing when exporting selected text to a file. ═══ Code generation macros ═══ o The "Add records from a directory" container method (FillFromDir) now generates correct code. ═══ General ═══ o The VX-REXX run time libraries are now built with Pentium optimizations. o Events can be added dynamically at run time using the DefineEvent method. o Picture references are now cached, resulting in better performance, especially with container icon references. ═══ Drag and drop ═══ All objects can now act both as drag sources and drag targets, as controlled by the following events and properties: AllowDrag, DragDrop, DragIcon, DragStart, DragTarget, StartDrag. Drag targets To act as a drag target, the DragTarget property must be set to a value other than "None" AND the DragDrop event must be defined. The special value "Parent" may be used to let the parent object act as the drag target instead of the object itself. Otherwise, valid drag targets are "Record", "Files=", "Filetypes=", "Objects", "Formats=". The first three work as described for the Container's DragTarget property. If "Objects" is specified, VX-REXX objects from the same application can be dropped onto the application. "Formats=" allows you to specify in detail the exact rendering formats the object will accept as a drag target. The DragTarget property can also specify the default operation and the supported operations. For example, to define an object that allows *.TXT files to be dropped on it, with a default Copy operation and only allows Link and Copy: Files="*.TXT";Default=Copy;Operations=Link,Copy When an acceptable object is dropped on a VX-REXX object, a DragDrop event is defined and information is made available about the dropped object. The following items can be accessed using VRInfo with the DragDrop event: SourceObject The internal name of the VX-REXX object that is the drag source. This will be null if the source object is not an object in your program. TargetObject The internal name of the VX-REXX object that is the drag target. SourceRecord If the source object is a container, this is the record handle of the record being dragged. TargetRecord If the target object is a container, this is the record handle of the record where the drop occurred. SourceIndex If the source object is a listbox, value set or combo box, this is the numeric index (starting at 1) of the item in the object where the drag started, or 0 if the drag did not start on an item. TargetIndex Like SourceIndex, but identifies which item the drop occurred on. SourceName, TargetName, ContainerName Strings that identify the file or object. SourceFile The concatenation of ContainerName and SourceName. Format The complete OS/2 rendering format of the object. NativeFormat The native format, a subset of the Format. Left, Top, Bottom Where the object was dropped. Operation The drag operation. No actions occur in response to a drop -- the program must analyse the drop and decide on an appropriate course of action. Drag sources To act as a drag source, an object must have the AllowDrag property set. If a DragStart event is defined, the program must call the StartDrag method to start the actual dragging operation. For all objects except the Container, the syntax for StartDrag is as follows: call VRMethod object, 'StartDrag', default, dragimage,, format, type, cname, sname, tname, index The arguments are: default The default operation dragging operation, one of "Default", "Copy", "Link" or "Move". If omitted, "Default" is the default. dragimage The path of the icon or bitmap to use for the dragging operation. If omitted, the value of the DragIcon property is used. If DragIcon is not defined and the object supports a PicturePath property, the latter is used instead. format The OS/2 drag and drop rendering format string. If omitted, the format <DRM_VXREXX_OBJECT,DRF_UNKNOWN> is used. type The OS/2 drag and drop type string. If omitted, the type "VX-REXX Object" is used. cname The "container name", which has nothing to do with the Container object, but is rather the a string which describes the object that "contains" the object being dragged. If omitted, the internal name of the parent object is used. sname The "source name". If omitted, the internal name of the source object is used. tname The "target name". If omitted, the internal name of the source object is used. index The numeric value to use when setting the "SourceIndex" VRInfo parameter when the object is dropped on another VX-REXX object. If a DragStart event is NOT defined, the drag action occurs automatically as if StartDrag had been called as follows: ═══ Functions ═══ o VRFlush function The VRFlush function is used to remove unwanted events from the event queue, based either on the event type or the object that generated them, or both. o VRFileDialog function The VRFileDialog function now supports multiple file selection. o VRFontDialog function Use the VRFontDialog function to present a standard font dialog to the user. The syntax is: newFont = VRFontDialog( [parent], [initialFont], [title] ) parent The dialog's parent window. If omitted, the desktop is used instead. initialFont The font that is initially selected in the dialog. title The font dialog title. The font strings have the form <size>.<facename>[modifier1][modifier2]... modifiers are: Bold Italic Underline Strikeout o VRGetFileType function The VRGetFileType function no longer strips off the last character on files types that were not set using VRSetFileType. o VRInfo function The VRInfo function has been extended in several ways: - The following new information is available for all events: o Left o Top o AltPressed o CtrlPressed o ShiftPressed o Button1Pressed o Button2Pressed o FocusObject o FocusWindow - The name of a stem variable can be passed to VRInfo. o VRIsChildOf function The new VRIsChildOf function checks if a given object's type is a child of some other object type. You can use this function, for example, to see if the parent of a window is a notebook. o VROptions function VROptions has two new options: ImplicitNames and NoImplicitNames, used to turn implicit (context-sensitive) naming on or off. o VRSetFileType function VRSetFileType now accepts the null string as a valid type. ═══ Methods ═══ o Clear method The Clear method has been added to the Console object. o CharFromLine method The CharFromLine method returns the insertion point that corresponds to the start of the given line in an MLE. o ColorIndex method Use this Screen object method to convert color indices to strings and back. o DefineEvent method The DefineEvent method has been added to all objects and can be used to add a new event to an object that is triggered when a specified Presentation Manager message is sent to an object. o DisableRefresh method The DisableRefresh method disables updating of an MLE while changes are being made and also changes the mouse pointer. o EnableRefresh method The EnableRefresh method enables the updating of an MLE and restores the mouse pointer. o GetFieldAttr method The GetFieldAttr method now accepts the new Width attribute. This returns the width of the field in twips. If the width is 0, the container automatically resizes the field to accommodate the widest data in that field. The default width is 0. The Name of the field can also be retrieved using this method. o GetFieldData method The container GetFieldData method now also accepts the name of a stem variable in place of a field handle (or name). Passing a stem indicates you want data on all the fields in the given record. On return, stem.0 is the number of fields, stem.1 is the first data value, stem.2 is the second value and so on. If a field has a symbolic name, the method also sets the variable with the form stem.!fieldName. o GetFieldList method The new container GetFieldList method returns a list of field handles in a REXX stem variable. o GetPageNumber method The notebook GetPageNumber method now returns the correct value. o GetRecordAttr method The container GetRecordAttr method supports two new record attributes: - UserData, used to store arbitrary application data. - Source, used to indicate which records are to be included in a drag or pop-up menu operation. o LineFromChar method The LineFromChar method returns the line number that corresponds to the given insertion point in the MLE. o ListPrinters method The ListPrinters method now also returns the default printer. o PostEvent method The PostEvent method has been added to all objects. It allows an object to "trigger" one if its own events. o PostQueue method The "object" and "event" values returned by VRInfo can now be set when calling the PostQueue method. If "object" is set, the "window" value is also implicitly set. o Popup method When activated using the Popup method, menus now pop up on the currently active window, not the window they are defined in. o QueryChanged method The QueryChanged method returns the MLE changed flag status. o QueryFirstChar method The QueryFirstChar method returns the insertion point of the first visible character of an MLE. o QueryFormatLineLength method The QueryFormatLineLength method returns the number of bytes in an MLE line after formatting has been applied. o QueryFormatTextLength method The QueryFormatTextLength method returns the length of the specified MLE text after formatting is applied. o QueryLineCount method The QueryLineCount method returns the number of lines in an MLE. o QueryLineLength method The QueryLineLength method returns the length of an MLE line starting at the given insertion point. o QuerySel The QuerySel method returns the insertion point of the anchor point or cursor point in an MLE. o QueryTabStop method The QueryTabStop method returns the size (in pixels) of the MLE tab stop. o Search method The Search method searches for text in an MLE. o SetChanged method The SetChanged method sets the changed status of an MLE. o SetFieldAttr method The SetFieldAttr method now accepts the new Width attribute. Set the width to the field width in twips. If the width is set to 0, the container automatically resizes the field to accommodate the widest data in that field. The default width is 0. o SetFieldData method The SetFieldData method now raises a REXX syntax error if passed the name of an invalid field attribute. Previously, it would just return 0 without causing an syntax error. o SetFirstChar method The SetFirstChar method sets the first visible character in an MLE. o SetRecordAttr method The SetRecordAttr method supports the new record attributes, Source and UserData. o SetSel method The SetSel method sets the cursor and anchor points of an MLE. o SetTabStop method The SetTabStop method sets the length of the tab stop (in pixels) of an MLE. o StartDrag method The StartDrag method now applies to all objects, but with an extended syntax allowing the program to specify in detail how the dragging operation should occur. o StartThread method When starting a window file, code file or external file as a new thread using the StartThread method, either of the words "command", "function" or "subroutine" may be added before the name of the file. The file will then be started as either a command file, a function, or a subroutine. For example, to start a window file as a subroutine: call VRMethod 'Application', 'StartThread', 'subroutine window2' If not specified, the default is "command". o UpdateLayout method When dynamically adding or removing children from a window or group box whose LayoutStyle property is set, the UpdateLayout method can be used to force an update of the layout. ═══ Objects ═══ o Application object The Program property is now set to a null string if the program is being run from within the design environment. o CheckBox. object The NoPointerFocus property has been added. o ComboBox object - You can now store per-string user data for combo boxes list items. See the on-line documentation for the GetItemData, SetItemData, GetItemDataList, and SetItemDataList methods. - System response has been improved when passing large stem arrays to AddStringList. o Console object - The Clear method is now supported on the Console object. o Container object - New AutoEdit property. - Enhanced GetFieldAttr method. - Enhanced GetFieldData method. - New GetFieldList method. - New Guard event. - New GuardRecords property. - New GuardScroll method. - New KeptRecords property that sets an upper limit on the number of records in a container. - Enhanced SetFieldAttr method. - New TreeCount property. - Enhanced GetRecordAttr and SetRecordAttr methods. - New UserData record attribute. - New Width and UserData field attributes. - Certain painting problems were fixed. - System response has been improved when passing large stem arrays to AddRecordList and SetRecordAttr. - Previously, the in-use emphasis would be drawn in detail view only if the first column was an icon field. Now the in-use emphasis is drawn on the leftmost icon field, even if it isn't the first field. - Passing an invalid value to SetFieldData to set a ULONG field now returns 0. - Setting the field data for an icon field to the null string removes the icon. - Asking for SourceOrSelected returns the empty list if the container itself has the source emphasis. - Records that were initially created as invisible are now redrawn correctly when they are made visible. o DropDownComboBox (DDCB) object - You can now store per-string user data for DDCB list items. See the on-line documentation for the GetItemData, SetItemData, GetItemDataList, and SetItemDataList methods. - System response has been improved when passing large stem arrays to AddStringList. o GroupBox object - New properties: BorderType and LayoutStyle. - New method: UpdateLayout. o ImagePushButton and ImageRadioButton objects - These objects paint themselves correctly when they are disabled. - Both objects now support the ForeColor property and the NoPointerFocus property. - The ImageRadioButton has a new ToggleMode property. o ListBox object - System response has been improved when passing large stem arrays to AddStringList. o MultiLineEntryField object The MLE had difficulty retrieving text more than 64K in size. This has been fixed. The MLE supports these new methods: - CharFromLine - LineFromChar - QueryLineLength - SetFirstChar - SetTabStop - SetChanged - QueryFormatLineLength - DisableRefresh - EnableRefresh - QueryChanged - QueryFirstChar - QueryLineCount - QueryTabStop - QueryFormatTextLength - QuerySel - SetSel - Search o Notebook object - In a PageSelected event, the internal name of the old page window is available using VRInfo: oldPageWindow = VRInfo( "OldPageWindow" ) - Previously calling VRInfo("OldPage") in a PageSelected event returned the internal name of the notebook, not the page number (as advertised). This bug has been fixed. - Notebooks were behaving like GroupBox objects and "swallowing" objects they were laid on top of. This has been fixed. - Keyboard navigation between notebook pages is now properly supported. - The GetPageNumber method now returns the correct page number. - Fixed the bug that prevented PageLoad events from occurring when pages were added using InsertBlankPage after calling DeletePage. o PushButton object The NoPointerFocus property has been added. o RadioButton object The NoPointerFocus property has been added. o Screen object The Screen object supports the following new methods and properties: - ColorIndex Converts a color index to a string and back. - FindWindow Allows you to find a window handle by name. - PixelsToTwips Convert pixels into twips. - PointerVisible Controls the pointer visibility. - TwipsToPixels Convert twips into pixels. The GetActiveWindow and GetFocusWindow methods will now optionally return the internal name of the VX-REXX object that is active or has the input focus. Previously, these two methods would only return a Presentation Manager window handle. o Slider object The slider object would sometimes shrink in size. This has been fixed. o Window object The Window object supports the following new events, methods and properties: - Help event Occurs when the user presses F1. - UpdateLayout method Used to force an update of the window layout if LayoutStyle is set. ═══ Properties and events ═══ o AllowDrag property All objects in the tool palette support the AllowDrag property. If on, the object can act as a drag source. See the DragStart property. o AutoEdit property When this property is set to 1, pressing TAB (or BACKTAB) while editing a detail view field will automatically move to the next (or previous field). If there are no more fields in the record, the next record is opened for editing. If there are no more records to edit, the input focus is moved to the next object in the tab order. Read-only fields are skipped. o Autosize property The Autosize property takes mnemonics into account when calculating the size of the object. It does not leave extra space around the radio button and check box objects either. o AutoTab property Entry fields now handle overstrike mode correctly when AutoTab is on. o BeginEdit event The handle of the field being edited can be had using VRInfo. o BorderType property The GroupBox object has several new border styles that are set using the BorderType property. o ClipSiblings property A new property on most objects, it controls how objects are painted if they overlap. Turn it on to ensure that the objects paint themselves according to their SiblingOrder. o ContextMenu event When a ContextMenu event is generated on a ListBox, ComboBox or DropDownComboBox object, VRInfo("Index") can be used to retrieve the index of the item that was clicked on. The value will be zero if the click did not occur on a list item. The value is also available from the menu Click event if a menu invoked using the Popup method inside the ContextMenu event code. o DragIcon property This is the icon or bitmap to use when dragging the object. It uses the same syntax as PicturePath. o DragDrop event and DragTarget property All objects now support the DragTarget property and the DragDrop event. o DragStart event All objects support this event. As with the container, if AllowDrag is on and DragStart is NOT defined, a default dragging action occurs. Otherwise it is up to the program to call the StartDrag method from within the DragStart event to start the dragging. o EndEdit event The handle of the field being edited can be had using VRInfo. o ForeColor property The ForeColor property has been added to the ImagePushButton, ImageRadioButton and PictureBox. This property is used along with BackColor when displaying monochrome bitmaps. o Help event The Help event occurs when the user presses F1 on a window. See also Adding help to a program for more information. o LayoutStyle property The LayoutStyle property has been added to the GroupBox object. o NoPointerFocus property The NoPointerFocus property has been added to the PushButton, RadioButton, CheckBox, ImagePushButton and ImageRadioButton objects. If set, the user can click on the object but the focus will not move to the object. o PointerVisible property The PointerVisible property on the Screen object controls whether or not the mouse pointer is visible. o Program property The Program property is now set to a null string when the program is being run or debugged from within the design environment. o StatusFont property Sets the font used in the status area of a window. o ToggleMode property The new ToggleMode property can be used to make an ImageRadioButton object act as a toggle. o TreeCount property (containers) The new TreeCount property returns the total number of records in a container, including child records. It is different from the Count property in that the Count property only includes top level records. o Verify event A new event that can be used to validate data entered in entry fields, MLEs, combo boxes, DDCBs and spin buttons. o WindowListTitle property Sets (or removes) the name of a window in the WindowList. ═══ Window manipulation ═══ The following features aid in the manipulation of Presentation Manager windows from within a VX-REXX program: o The Working with other programs chapter has a section describing how to obtain and work with Presentation Manager window handles. o The FindWindow method has been added to the Screen object. o The following properties can be set using VRSet or retrieved using VRGet: - Left - Top - Width - Height - Caption - Visible - Enabled - Parent - SiblingOrder - WindowState o The following additional properties can be used with VRGet only: - ClassName - ProcessID - ThreadID - ID - Parent - Sibling - FirstChild - Owner - Self - Hwnd - Object o The following methods can be invoked using VRMethod: - SetFocus - Maximize - Minimize - Restore ═══ Bounce ═══ The Bounce sample has been improved by the addition of gravity. ═══ CUA 91 ═══ The CUA91 sample demonstrates several VX-REXX features and programming techniques relevant to developing CUA'91 compliant applications. It also demonstrates how to use subroutines contained in OBJECT.VRS to simplify the process. ═══ 5.2. New in version 2.0a ═══ What's new in version 2.0a: Design environment Miscellaneous Changes Runtime environment Containers Container and Workplace Shell interaction Named field support for containers Popup Menus I/O Console Bitmap Support Picturebox Object DDE Support Accelerators Font Support DBCS Support Other Changes VX-REXX Features Properties, methods, and functions Sample programs New or improved samples ═══ Miscellaneous Changes ═══ The following sections list significant changes to the design environment. o The design environment's initialization file (VRXEDIT.INI) is now stored in the OS2 directory. Previously, it was stored in the VXREXX directory. o Drag and drop code generation macros The code generation macros are now faster. The macro for VRDestroy was missing and has been added. The macro for SetRecordAttr has been corrected. o Menu editor The menu editor has been sped up. It also asks the user if changes have been made to a menu or menu item and the Change button was not clicked. o The property notebook for containers has been rearranged. - The AutoPosition property has been moved from the "Style" page to the "Views" page. - The ExtendSelect and MultiSelect properties have been moved from the "Style" page to the "List" page. o The SetProp macro used to cause unpredictable results if you selected all objects. o The Help menu now contains items to directly access the VX-REXX Reference, VX-REXX Programmer's Guide and REXX Reference online documents. o Section editor The built-in section editor has been improved in several ways: - Previously, the "Insert code" feature would stop working after a certain number of times due to a bug in the C run-time library. This has been corrected. - Double-byte character set (DBCS) support has been added, including a DBCS conversion bar. The conversion bar only appears in DBCS versions of OS/2. - The font used by the section editor can be changed using a new menu item in the Settings menu. When you pick a new font, it is propagated to all open section editor windows. - In previous versions of the VX-REXX design environment, it was not possible to save window files that were greater than 64k bytes long. This restriction has been removed. - Closing a section editor window from the Task List will only close the window, not the complete project. - Restoring a section editor window from the Task List will also restore the complete project if the project was also minimized. - The online reference manuals can be accessed from the Help menu. - When text is selected in a section editor window, a new 'Lookup' item appears in the popup menu allowing you to lookup the currently selected word in the online references. You can also use Ctrl+DoubleClick to select a word and automatically look it up. o File limits Windows with more than 64K of data in them are now saved correctly. o Font editing The font dialog in the property notebooks now supports the Strikeout, Underscore and Outline attributes. The appear in the font name as ".Strikeout", ".Underscore" and ".Outline", in any order. o Direct editing Direct text editing with alt-Click no longer sounds a beep. o Bitmaps and icons A new Show pictures menu item has been added to the Options menu. If set, all PictureBox, ImagePushButton and ImageRadioButton objects will display their pictures in the design environment. Previously, they would only do so at run-time. If this option is not set, these objects will be hatched if a value has been assigned to their PicturePath properties and blank otherwise. ═══ Containers ═══ o You now have greater control over the drag/drop operation. You can specify the default operation type using the DragStart method. You can change the set of dragged records when the operation begins by changing the Source attributes while in the new StartDrag event. o You can now fill a container based on the contents of a directory using the new FillFromDir method. o You can now refer to detail view fields using a symbolic name. See the enhanced AddField method. o The appearance of minitature icons has been improved. o The amount of screen flicker has been reduced when invoking the SetRecordAttr and SetFieldData methods. o The source emphasis is now drawn more consistently around records. o Setting the Expanded and Collapsed record attributes now expands or collapses the record tree. ═══ Container and Workplace Shell interaction ═══ You can now drag records onto Workplace Shell objects other than the Shredder and printer objects. See the new DragFile event and the expanded SetRecordAttr method. ═══ Named field suppport for containers ═══ You can now assign symbolic names to container fields using the AddField method. Any method that takes a field handle will now accept a symbolic field name. For example, the following code sample creates two named fields called "NameField" and "PriceField". A record is then added, and its field information is set. f1 = VRMethod( "CN_1", "AddField", "String", "Name", "NameField" ) f2 = VRMethod( "CN_1", "AddField", "ULong", "Price", "PriceField" ) record = VRMethod( "CN_1", "AddRecord",,, "Car wax", "Information" ) call VRMethod "CN_1", "SetFieldData", record,, "NameField", "Car wax",, "PriceField", "19.95" Notice that the field names "NameField" and "PriceField" are passed to the SetFieldData method. You could also invoke the method with the following line for the same result: call VRMethod "CN_1", "SetFieldData", record,, f1, "Car wax",, f2, "19.95" ═══ Popup menus ═══ o The internal name of the object for which a context menu was requested is now available in the Click event of popup menu items. In the Click event you can retrieve the source object name by using the VRInfo function. The Popup sample program shows how you can use VRInfo to get the name of the object to which the context menu applies. The Click event for one of the popup menu items is shown below: MI_BackRed_Click: call SetColor "Red" return SetColor: procedure parse arg color source = VRInfo( "Source" ) call VRSet source, "BackColor", color return o Closing a cascaded portion of a popup menu no longer closes the whole menu. ═══ I/O console ═══ The I/O console no longer converts carriage return characters to newline characters on input, and also makes sure that all input lines are terminated with a CR-LF pair. The OS/2 BACKUP command will now work properly with the I/O console. You can use the name 'Console' to refer to the console's frame window and use VRGet, VRSet and VRMethod to manipulate the console as you would any other Presentation Manager window. For example: /* Hide the console */ call VRSet 'Console', 'Visible', 0 /* Get the width */ width = VRGet( 'Console', 'Width' ) See the entry for HWnd for more information on how to manipulate window handles. The Window Controller sample is also a good place to look. ═══ Bitmap support ═══ When loading a bitmap from a file which contains several bitmaps (a bitmap array, each bitmap specific to a particular display resolution and/or number of colors), VX-REXX used to pick the bitmap with exactly the same number of colors as the current display, or the first bitmap in the file. Now it picks the closest bitmap, where "closest" means the bitmap with the greatest number of colors less than or equal to the maximum number of displayable colors for your system. (Only the standard system color palette is supported, however.) ═══ PictureBox object ═══ The PictureBox object now correctly draws its border when displaying a picture. Pictures are also clipped to the correct area if ResizePicture is not set. ═══ DDE support ═══ DDE conversations were not being properly terminated in some cases. This has been fixed. If the DDE client is in the middle of a conversation with a DDE server and the server terminates or hangs abruptly without notifying the client, your application can be interrupted cleanly by closing it from the Task List. ═══ Accelerators ═══ Menu accelerators now accept mixed-case alphabetic characters by default. Previously, they only accepted the lowercase version of an alphabetic character. You can now add the keyword case to the end of the accelerator string to force the accelerator to be case-sensitive. ═══ Font support ═══ All objects that have a Font property now support strikeout, underscore, and outline attributes. For example, setting Font to 10.System Proportional.Underscore causes the object to underline displayed text. See the Font section of the online Reference for more information. ═══ DBCS support ═══ The following features have been added to support DBCS (double byte character set) environments: o VX-REXX objects now support DBCS fonts. o Window objects can have an options DBCS-SBCS conversion bar at the bottom of the window. ═══ Other changes ═══ o Previously, running executables generated with VX-REXX would sometimes report problems if multiple copies of VROBJ.DLL were in the LIBPATH and the directory where the executable was located. This problem has been fixed. o The size of the stack used by VX-REXX run time library (VROBJ.DLL) can be increased by setting the VXREXXSTACK environment variable to desired stack size in bytes before running the program. The default stack size for VROBJ is 32K. You may need to increase the stack size if you are developing new VX-REXX objects that demand a larger stack. o In version 2.0, a syntax error would occur if you tried to use VRSet, VRGet or VRMethod with a Presentation Manager window handle that was no longer valid (if, for example, the window has been destroyed). In 2.0a this no longer occurs. Instead, the function call is simply ignored and has no effect. (This is only true for window handles, not VX-REXX objects.) ═══ New or improved properties, methods, and functions ═══ The following sections list new or improved properties, methods, and functions for version 2.0a. Accelerator property Accelerators are now mixed-case by default. Use the new keyword Case to define case-sensitive accelerators. See the Accelerator property in the online Reference for details. Acknowledge event The Acknowledge event was inadvertently missing from the documentation, although it existed in version 2.0. AddField method The AddField method takes a new name parameter which lets you assign a symbolic name to a field. AddRecordList method The AddRecordList method now inserts records in the given order when adding to the front of the list. CenterWindow method The relative parameter is now case insensitive. DBCSConversionBar property Window objects can now optionally include a DBCS-SBCS conversion bar at the bottom of the window. See the DBCSConversionBar section in the online Reference for details. Delay property The Delay property of Timer objects now works for values greater than 65,535. Destroy event Previously the Destroy event was not being generated. This has been fixed. See the revised Destroy section in the online Reference for tips on using the Destroy event. DragFile event The DragFile event occurs when records are dropped onto Workplace Shell objects other than the printer or the OS/2 Shredder. DragStart event The DragStart event occurs whenever the user starts dragging container records. FillFromDir method The FillFromDir method fills a container with records based on the contents of a directory. The result is a container that acts like a Workplace Shell folder. See the FillFromDir method for more information. GetClipboard method The GetClipboard method no longer causes a syntax error if the clipboard is empty or contains something other than text. Instead, an empty string is returned. GetFieldData method The GetFieldData method now raises a REXX syntax error if passed an invalid field handle/name. GetRecordAttr method The GetRecordAttr method now supports a new record attribute called "Filename". GetRecordList method o You can now use the GetRecordList method to list records that have the Source attribute set to 1. o The method now supports the keyword SourceOrSelected for the emphasis parameter. The method will return records with the source emphasis or, if there are none, records with the selected emphasis. This keyword is useful when writing menu item click events in menus that are used both as pull-down and popup menus. HelpTag property Help file contents can now be accessed by setting the HelpTag property to contents or help contents. HelpTag also supports index (or help index) and using (or help using) as well. Menu objects Menu objects can now be destroyed using VRDestroy. MenuItem objects Disabled menu items in popup menus are now displayed as dimmed text. Menu items can also now be destroyed using VRDestroy. Popup method The Popup method used to cause an access violation if the pos parameter was null. This has been fixed. SetFieldData method The amount of screen flicker that results from invoking the SetFieldData method has been reduced. SetRecordAttr method o The SetRecordAttr method now supports a new record attribute called "Filename". o The method now supports the keyword All in place of a record handle. o The amount of screen flicker that results from invoking this method has been reduced. o Setting the Expanded or Collapsed record attributes now expands and closes the record tree. Source property Containers now have a Source property. Setting this property causes the container to be drawn with the source emphasis. StartDrag method The StartDrag method initiates a drag operation. VRCreate function You can now use the VRCreate function to create objects on windows that were created from different REXX files. VRFileData function The VRFileDate function now sets the seconds part of the file time correctly. VRIniDir property The new VRIniDir function returns the directory where the OS/2 initialization files are stored. VRParseFilePath function Previously, the VRParseFilePath function would cause a system error if passed an empty string. Now it returns an empty string. VRSortStem function Previously, the VRSortStem function would fail for large arrays. It can now handle arrays with millions of items. ═══ New or improved sample programs ═══ The following sections new sample programs have been updated for version 2.0a: File browser shows how to display a list of files using a container These samples are described in the Samples section of this document. ═══ 6. Previous versions ═══ ═══ 6.1. New in version 2.0 ═══ What's new in version 2.0: New Features New Objects Direct Object Editing Design Environment Tab Editor OS/2 File Type Support File Functions Object Naming Error Detection Improved List Boxes Improved MLEs Improved Windows Picture Boxes Properties, events, methods Improved Documentation Q+E interface functions VXQE Runtime library VXQE Function Prototypes Sample Programs Known Problems Contacting Q+E Fixed Bugs Design Environment Runtime Environment Properties, events, methds ═══ New Objects ═══ o Container A container shows a view of a set of records. The view may consist of icons, text, or a combination of both. - Provides icon, name, text, detail and tree views - User definable columns for detail view - Supports drag and drop interactions with other containers and with Workplace Shell objects - Supports sorting and searching records - Allows records to be shared between containers For more information, see the Using objects chapter in the VX¨REXX Programmer's Guide or the Container section in the VX¨REXX Reference. o Notebook Notebooks present a group of windows to the user using a book metaphor. The notebook shows each window as page. Pages have tabs that the user can click on to display the page. Some features of notebooks include: - Full control over the positioning of the binding and the page tabs - Supports pages with major, minor, or no tabs - Pages can be added or removed dynamically at run time - Pages are loaded only as required to improve performance - Any VX-REXX window can be shown in a notebook For more information, see the Using objects chapter in the VX¨REXX Programmer's Guide or the Notebook section in the VX¨REXX Reference. o Popup menus Any Menu object can now be displayed as a pop-up menu. For more information, see the Creating a pop-up menu chapter in the VX¨REXX Programmer's Guide and the Popup method section of the VX¨REXX Reference. o Conditional cascaded menus Any Menu object can now be displayed as a conditional cascaded menu. For more information, see the Creating a conditional cascaded menu chapter in the PrGuide. and the DefaultItem property section in the VX¨REXX Reference. o Slider Sliders let the user select a value from a range of values. They can also be used as a status bar or "thermometer" to indicate progress in a long operation. For more information, see the Using objects chapter in the VX¨REXX Programmer's Guide and the Slider object section in the VX¨REXX Reference. o Timer You can use timers to respond to the passing of time. Timers wait for some configurable interval, then post an event. For more information, see the Using objects chapter in the VX¨REXX Programmer's Guide and the Timer object section in the VX¨REXX Reference. o DDE Client With a DDE client object, your programs can communicate with DDE servers that are part of other applications running on your computer. Some features of the DDE client include: - Supports cold, warm, and hot links - Allows communication with OS/2 and Windows DDE servers For more information, see the Using objects chapter in the VX¨REXX Programmer's Guide and the DDEClient section in the VX¨REXX Reference. o ValueSet Value sets presents the user with a set of choices, one of which is selected at all timers. The items in the ValueSet are arranged in a grid. The items can display bitmaps, colors, icons, or text. For more information, see the Using objects chapter in the VX¨REXX Programmer's Guide and the ValueSet section in the VX¨REXX Reference. ═══ Direct editing of objects at design time ═══ You can now use direct editing techniques to change the Value or Caption properties of the following objects at design time: o check boxes o DDE clients o descriptive text o entry fields o multiline entry fields o push buttons o radio buttons o timers o windows For example, to change the caption on a push button, follow these steps: 1. While holding the Alt key, click mouse button 1 on the push button. 2. Type the new text for the button. 3. Click mouse button 1 anywhere not on the button. ═══ Easier to use design environment ═══ o Accelerator keys have been added to many menu items in the design environment. o All windows in the design environment are positioned so that part of the title bar is visible. o In property notebooks, you can now change the Font property by typing in the entry field. You can still press the Edit button to invoke the font dialog. o In the menu editor, double clicking on a menu caption in the list box is equivalent to pressing the "Edit event" button. o The "OK" button in the menu editor has been renamed "Close". o The pop-up menu for objects now uses check marks to show which events have routines defined. o You can now position windows by clicking mouse button 2 and dragging the window, the same as for all other objects. o You can now resize windows with Thin or Dialog borders the same way as windows with Sizeable borders. o VX-REXX now indicates when it is saving or loading a project by displaying the appropriate text on the status bar. ═══ New tab editor ═══ The tab editor is now installed automatically in the design environment's pop-up menu. Use the tab editor to visually set the tab order of objects on a window. Initially the tab editor displays all objects on the window that have the TabStop property set to 1. To move an object in the tab order, follow these steps: 1. Move the mouse over the object in the tab editor window. 2. Press mouse button 2 and drag the object to the desired position in the list. 3. Release mouse button 2 To set the tab order according to the CUA guidelines, press the Auto button. This automatically orders objects from left-to-right and from top-to-bottom in the window. Press the OK button to accept the changes you made in the tab editor window. To throw away the changes, press Cancel or close the window. ═══ New OS/2 file type support ═══ You can now get, set, and list OS/2 file types using the new VX-REXX functions VRGetFileType, VRSetFileType, and VRListFileTypes. ═══ Improved file functions ═══ The functions related to files and directories have the following improvements: o They accept HPFS file names for files on HPFS volumes o File names which contain more than one period are now supported. o LAN Server UNC names are now supported. o New file name parsing function: VRParseFilePath. ═══ Enhanced object naming ability ═══ VX-REXX now allows you to refer to objects using the name of the object's parent (and grand parent). To do this, prefix the name of the object with the name or internal name of its parent, followed by a period. For example, suppose you have a window (name is "Window1", internal name is "?VR0001"), with a group box (name is "GB_1", internal name is "?VR0002"), which contains a radio button (name is "RB_1", internal name is "?VR0003"). Any of the following expressions identify the radio button: RB_1 GB_1.RB_1 Window1.GB_1.RB_1 ?VR0003 ?VR0002.RB_1 ?VR0001.GB_1.RB_1 ?VR0001.?VR0002.RB1 ?VR0002.?VR0003 ?VR0001.?VR0002.?VR0003 The rules for forming a dotted name are as follows: o Dotted names are processed from left to right where the parent is listed to the left of its child. o Dotted names can start with either a name or an internal name. o If a dotted name starts with an internal name, then there must not be any internal names following the first (regular) name. o After the last internal name (if any), the remaining names must be regular names (ie. no internal names). o Dotted names cannot start or end with a dot. o No spaces are allowed before or after a dot. This feature is useful for referencing objects on a window that you load a number of times. For example, suppose you have a window with the name SW_1. On that window is a push button called PB_1. If you load the window twice (using VRLoad or VRLoadSecondary), the push buttons will have the same name. To refer to a specific button, prefix the button's name with the internal name of the window. The following code loads the SW_1 window twice, then sets the captions on the two buttons: w1 = VRLoadSecondary( "SW_1" ) w2 = VRLoadSecondary( "SW_1" ) call VRSet w1 || "." || "PB_1", "Caption", "Button1" call VRSet w2 || "." || "PB_1", "Caption", "Button2" ═══ Improved error detection at run time ═══ Calling VRSet, VRGet, or VRMethod with an invalid object name now causes a syntax error. To test whether an object name is still valid, use the new VRIsValidObject function. To disable this new error detection, use the new VROptions function. ═══ Improved list boxes ═══ You can now associate user data with strings in a list box. The AddString method now takes user data for a list item as a new optional parameter. Similarly, AddStringList now takes an optional stem variable with an array of user data for the list items. The following new list box methods are also provided to set and retrieve list item user data: SetItemData, GetItemData, SetItemDataList, and GetItemDataList. Note: These methods are documented in the online Reference only. ═══ Improved multiple line entry fields ═══ Multiple line entry fields (MLEs) can now hold more than 64k of data. MLEs also now support both raster and outline fonts. Previously, only raster fonts were supported. ═══ Improved windows ═══ If a window that is positioned off the screen is made visible, the window is automatically centered over its parent window. You can now create windows that do not have a title bar by setting the new TitleBar property to 0. ═══ Support for icons in picture objects ═══ You can now name icon resources and files using the PicturePath property. To reference an ICO file, set the PicturePath property to the complete file name of the ICO file including path. For an icon resource in a DLL, use the following syntax: $resourceID:DLLName where resourceID is the icon resource identifier. DLLName is the name of the DLL that contains the resource. You should not include any path information in the DLLName. ═══ New or improved properties, events, methods, and functions ═══ See the online Reference for more information. Autosize property Objects that have AutoSize set to 1 now resize themselves when they are loaded. This new behavior applies to descriptive text, DDE clients, timers, push buttons, radio buttons, check boxes, and entry fields. GetItemData method The GetItemData method retrieves user data for a list box item. GetItemDataList method The GetItemDataList method retrieves user data for a number of list box items. Popup method The Popup method displays a Menu object as a pop-up menu. SetItemData method The SetItemData method associates user data with a list box item. SetItemDataList method The SetItemDataList method associates user data with a number of list box items. TitleBar property The TitleBar property controls whether or not a window has a title bar. VRInfo function The VRInfo function now accepts the parameter Window for all events. It returns the internal name of the window which contains the object that caused the event. VRIsValidObject function The VRIsValidObject function returns 1 if a given object or PM window handle is still valid. VRParseFilePath function The VRParseFilePath function parses a file name without checking if the file exists. VRPrintFile function The VRPrintFile function prints a file. VRPintJobDialog function The VRPrintJobDialog function displays a print job dialog for a given printer. VRSortStem function The VRSortStem function sorts a REXX array. ═══ Improved documentation ═══ o Added chapter in the Programmer's Guide on writing programs with multiple threads. o Added chapter on writing custom modal dialogs. Bounce shows how to use a timer DDE Explorer shows how to find and communicate with DDE servers DragDrop shows how to add drag and drop to your programs File browser shows how to display a list of files using a container Notebook shows how to use a notebook Popup shows how to use a pop-up menu Printing shows how to print a file Q+E Text shows how to use VXQE and QELIB (from Q+E Software) RGB shows how to use sliders and value sets Update DB Sample shows how to use VXQE and QELIB or the DB2/2 SQL interface with DB2/2 These samples are described in the Samples section of this document. ═══ VXQE runtime library ═══ The file VXQE.DLL is the VXQE Library for Watcom VX-REXX. This library allows VX-REXX applications to access the Q+E Database Library, available from Q+E Software. You are allowed to redistribute the library royalty free under the restrictions described elsewhere in this document. ═══ Generating prototypes for VXQE functions ═══ To generate prototypes for VXQE functions, select the Insert Code item from the Edit menu in the VX-REXX section editor. The list of items in the dialog box which is displayed contains a section called VXQE Library. Descriptions for all the VXQE Library functions are listed in this section. Selecting any of these function descriptions will produce another dialog box which will prompt for parameter values and then automatically insert code for the selected function into the section editor. For a complete description of the automatic code generation feature, see the VX¨REXX Programmer's Guide. ═══ Sample programs ═══ There are two sample programs that demonstrate using the VXQE library: Q+E Text The Q+E Text program displays data for selected employees. It uses the VXQE library and the QELIB library (from Q+E Software) to access the EMP.TXT file supplied with QELIB. This sample application is the VX-REXX equivalent of the example provided with QELIB. Update DB Sample The Update DB Sample program uses the VXQE library and the QELIB (from Q+E Software), or the DB2/2 SQL interface to access IBM DB2/2. This sample is similar to the Sample Database sample, except it provides greater functionality, and allows the use of the Q+E interface. This application allows employee records from the STAFF table of the SAMPLE database to be viewed, modified, deleted and created. The sample database, called SAMPLE, supplied with Database Manager must be installed to run this sample. Also, to use the Q+E interface, any steps required to use a QELIB application with Database Manager must be performed. In particular, QLEE.DLL must be bound to the SAMPLE database. See the Q+E Database Library Documentation for complete details. ═══ Known problems ═══ A time stamp error may be reported by the IBM DB2/2 application. This error will probably be the result of an incorrect QLEE.BND file supplied with the Q+E Database Library. Contact Q+E Software to obtain a correct QLEE.BND file. ═══ Contacting Q+E Software ═══ For more information on the Q+E Database Library (QELIB), please contact Q+E Software at the following addresses: In North America: Q+E Software 5540 Centerview Drive Suite 324 Raleigh, NC 27606 USA (919) 859-2220 (Sales) (919) 851-1152 (Technical support) In Europe: Q+E Software Europe Marten Messweg 99 Rotterdam, The Netherlands (+31) 10 2202 022 ═══ Design environment ═══ o Previously, if you changed a section from a file that was not the current file, the changes would be ignored. This has been fixed. o Previously, if you quit the VX-REXX while the design environment was minimized, the design windows could be positioned in unpredictable locations the next time you ran VX-REXX. This bug has been fixed. o Previously, if you renamed an object that had event routines defined, the event sections might not have been renamed. The sections are now always renamed. o Previously, the debugger would not always show the last line of a section in a trace or source window. o Previously, pressing F1 when a user window was active would show the help text defined for the window rather than the VX-REXX help text. ═══ Run time environment ═══ o Menu items that are added to a menu bar are now displayed correctly. Previously, they were not always visible. o Previously, picture boxes were not painted properly if they overlapped the list area of a drop down combo box. They are now painted correctly. o Previously, in programs that were started without any command line arguments, the InitArgs.0 REXX variable was set to 1. It is now 0 (zero). ═══ Properties, methods, events, and functions ═══ Click event Setting the Selected property of a list box used to erroneously cause two Click events to be generated. Now a single event is generated. Enabled property Previously, if a window was created with Enabled set to 0, setting Enabled to 1 later on would have no effect. Now the window is enabled correctly. ForeColor property The ForeColor property has been removed from ImagePushButton and ImageRadioButton objects. PicturePath property Previously, if a window had a bitmap picture as the background, and the window was resized, the background would not always be drawn correctly. VRDir function o The function now validates its "search" parameter. Previously, the debugger may have behaved unpredictably when debugging a call to VRDir that passed an invalid search parameter. o VRDir no longer raises a syntax error if parameters were omitted. VRMessage function Fixed VRMessage to take into account the length of the title when setting size of dialog. Also made minimum width of dialog be 120 pixels. (Max width is 3/4 of screen width.) The function is now faster. VRParseFileName function Previously, the function would not correctly parse names ending in a backslash. VRRedirectStdio function This function now restores the original standard I/O streams when redirection is turned off. This fixes the problem of sometimes not being able to close streams after turning redirection off. File functions All file and directory related functions allow file names that contain more than one period. In previous versions of VX-REXX, these types of names were not allowed. ═══ 6.2. New in version 1.01 ═══ What's new in version 1.01: Development Environment Drag and Drop Macros Swipe Selection Status Line Tool Palette Event Routine Access Code Section Editor Default Editor New Runtime Features SpinButton Object Enhanced Keyboard Support Other Application Windows Clipboard support STDIO Redirection Source Code Encoding Error Handling Debugger Menus Personal REXX v3.0a Support Properties, Events, Methods AddStringList Method AdjustHeight Property Change Event ExtendedSelect Property HWnd Property Justification Property LayoutStyle Property ListChildren Method ListClasses Method Maximize Method Minimize Method MLE Object Painting Property Pointer Property PostQueue Method Restore Method StatusArea SupportsMethod Method SupportsProperty Method TabGroup Property VertJustification Property ═══ Drag and drop programming ═══ VX-REXX has a new facility to make programming faster and easier. All REXX functions, all of VX-REXX's built in functions, as well as all object methods and properties can be used without having to write a single line of code. All you have to do to start the process is drag an object onto a section editor window. Suppose you have a window with a list box and a push button. You want to add a string to the list every time the push button is clicked. 1. Open a VX-REXX section editor for the push button's Click event. 2. Position the insertion cursor in the section editor window at the point where you want the code to be inserted. 3. Drag the list box onto the section editor window. When the pointer is over an editor window, VX-REXX draws a line linking the object to the window to indicate that it will generate code, instead of moving the object. When you release the mouse button, VX-REXX displays a list of actions you can perform on the list box. 4. Select Add a string from the list VX-REXX will prompt you for the parameters to the AddString method. 5. Type the text you want to add to the list in the String entry field. 6. Click OK. VX-REXX will add a line at the insertion point similar to the following: position = VRMethod( "LB_1", "AddString", "Pressed" ) Inserting code without drag and drop You can also use this facility directly from the Insert code menu item in the section editor's Edit menu. This allows you to generate code for an object without dragging and dropping it, and to generate non-object specific code such as calls to standard REXX functions. To insert code in a section editor: 1. Open a section editor. 2. Position the insertion cursor in the section editor window at the point where you want the code to be inserted. 3. Select Insert code from either the Edit menu or the (new) pop-up menu (click on the section editor window with mouse button 2). VX-REXX will show a list of objects and tasks for which it can generate REXX code. 4. Pick an action, then fill in the dialog as described above to generate the code. Inserting code into external editors Drag and drop code generation does not work for editors other than the VX-REXX section editor. However you can configure VX-REXX so you can insert code into the OS/2 clipboard from where it can be pasted into any editor. The macros GenCodeO.VRM and GenCodeG.VRM in the Macros folder are used to enable this feature. Their use is explained in the Profile.VRM file, also contained in the Macro folder. It is also possible to directly invoke the insert code dialogs from a PM-hosted, REXX-aware editor. The files in the EPMProto directory in the Macros folder are provided to show how an insert code command can be added to the OS/2 Enhanced Editor (EPM). See the file EPMProto.TXT in the EPMProto directory for more information. ═══ Macros in the development environment ═══ You can now tailor the VX-REXX development environment by creating custom commands as VX-REXX macros. This allows you to add new features to VX-REXX! You create the macros using VX-REXX, just as you would for any other PM-hosted, REXX-aware application. You create a project, then choose Make macro from the Project menu. You add the macro to the development environment by adding a line to the Profile.VRM file located in the Macros folder. Macro commands added to VX-REXX appear as extra menu items in the VX-REXX pop-up menu -- either on all objects or only on selected objects. The following macros, along with their source projects, are included with VX-REXX: o Tab editor macro The tab editor macro provides a fast and easy way to set the tab order for all of the objects on a window. o Set properties macro The set properties macro can be used instead of property notebooks to view or set an object's properties. It makes it easier to edit all of the properties of a single object, or to set the same property on a number of objects. o Resize macro The resize macro forces a number of objects to the same size. A typical use is to force a number of push buttons to the same size. o Object list macro This macro lists all objects on a window. You can select objects from the list and open their property notebooks. This makes it possible to find objects that are behind other objects or beyond the border of the window. Details on how to create and install macros are provided in the Profile.VRM and the Macros.TXT files in the Macros directory. ═══ Swipe selection now supported ═══ If you press mouse button 1 while the pointer is not over an object, you get a marquee selection with a bounding rectangle. All selection in version 1.00 was done this way. If you press mouse button 1 while over an object, you start a swipe selection. As long as you hold mouse button 1 down, you will select any object the pointer passes over. ═══ New status line ═══ A status bar has been added to VX-REXX to give the name and class of the object that is currently under the pointer. You can disable the feature by unchecking the Show Hints menu item in the Options menu. ═══ Resizable tool palette ═══ You can now resize the tool palette. Its size and position is saved along with the size and position of the other VX-REXX windows when you save a project. ═══ Quicker access to event routines ═══ There is a new item in the VX-REXX object popup menu which lists all of the events for the object. This is a short cut for opening the object's property notebook, selecting the Events page, and clicking on the event. ═══ New popup menu in code section editor ═══ Clicking on a code section editor with mouse button 2 now displays a popup version of the Edit menu. This speeds up access to common commands such as cut, copy, and paste. ═══ Set the default editor to an external editor ═══ You can now configure VX-REXX to use an external editor as the default editor. To do this, set the check box in the external editor configuration dialog. ═══ New SpinButton object ═══ An additional object, the spin button, has been added. A spin button allows a user to enter a value or select a value from a list. Only a single value from the list is displayed; the user can change the displayed value by clicking on up and down buttons. You can set the list in a spin button either at design time or run time, and you can specify the list as either an enumerated set of values or as a range of values with a specified increment. See the Using objects section in the online Programmer's Guide and SpinButton object in the Reference for more information. ═══ Enhanced keyboard support ═══ o Accelerators VX-REXX menus can now have accelerator or short-cut keys. Accelerator keys allow your users to execute menu commands without opening a menu. See the online Reference under the Accelerator property or InstallAccelerator method for a full description. o Mnemonics Mnemonics are now supported for all options with captions. Mnemonics allow your users to activate objects without using a mouse. See the Caption property in the online Reference for more information. o Keystroke trapping Programs can now trap and modify keystrokes. This allows you to change the behavior of objects, for example convert text in an entry field to uppercase as it is entered. See the KeyPress event or KeyString property in the Reference documentation for a full description of this new feature. ═══ Manipulate windows belonging to other applications ═══ Using the new ListWindows method you can list all of the top level windows in the system. Then you can use the VRGet, VRSet, and VRMethod functions to interact with these windows. The windows appear to the program as VX-REXX objects which support a limited number of properties and methods. You can also post or send keystrokes to PM windows using the new PostKeyString and SendKeyString methods. See the ListWindows method, HWnd property, PostKeyString method, and SendKeyString method in the Reference for complete information. ═══ Clipboard support ═══ You can use two new methods on the Application object to read and write text from/to the OS/2 clipboard. See the PutClipboard and GetClipboard methods in the online documentation for more information. ═══ Improved control over STDIO redirection ═══ The VRRedirectSTDIO function now lets you enable and disable standard I/O redirection and logging under program control. ═══ Source code encoding in EXE files ═══ VX-REXX now encodes your REXX source code when it makes EXE files. This means that you can distribute your programs and keep your source secure. ═══ Improved error handling in VX-REXX generated macros ═══ When you make macros, VX-REXX now automatically generates code to trap syntax errors. The code displays an error message, then exits the macro. If you have your own syntax error handler, it will override the automatically generated one. ═══ File menu removed from the debugger ═══ The debugger section list window no longer contains a File menu with a single Quit item. It was removed to improve the conformance of VX-REXX to the CUA '91 object model. Now just close the section list window to quit the debugger and return to the design environment. ═══ Support for Personal REXX version 3.0a ═══ VX-REXX now works with Quercus System's Personal REXX version 3.0a. ═══ AddStringList method ═══ This method now disables list box repainting while adding strings to the list, speeding up the operation. ═══ AdjustHeight property ═══ This ListBox property forces the list box to adjust its height to an integral number of lines. ═══ Change event ═══ Objects containing an entry field now support a Change event which is triggered whenever the contents of the field have changed. ═══ ExtendedSelect property ═══ List boxes now support two styles of multiple selection, extended (items are selected in ranges) and non-extended (items are selected one at a time). ═══ HWnd property ═══ All visible objects now have an HWnd property which gives the value of the PM handle to the outer window of the object. ═══ Justification property ═══ DescriptiveText and EntryField objects have a new Justification property, which can be Left, Right, or Center. ═══ LayoutStyle property ═══ The layout style controls how a window arranges the objects it contains. You can use this property to make windows that automatically resize their children. ═══ ListChildren method ═══ This method lists the children of a given object. ═══ ListClasses method ═══ Use this method to list the classes of objects in a DLL or in the current program. ═══ Maximize method ═══ This new window method causes a window to be maximized. ═══ Minimize method ═══ This new window method minimizes a window. ═══ MultiLineEntryField object ═══ Multiline entry fields now support the DoubleClick event. ═══ Painting property ═══ This new property has been added to all visible objects and can be used to suppress painting of an object or group of objects during an update. ═══ Pointer property ═══ Use this property to set the pointer to an hourglass or other shape during long calculations. ═══ PostQueue method ═══ This method is the same as the Post method except that it allows you to specify which window queue (i.e. which primary window) should receive the posted event. This ensures that the event is not simply delivered to the currently active window. ═══ Restore method ═══ This window method restores a minimized or maximized window to its previous size and position. ═══ StatusArea ═══ The status area on windows now has a sporty 3D look. ═══ SupportsMethod method ═══ This method determines if a given method is available for a specified object or type of object. ═══ SupportsProperty methods ═══ This method determines if a given property is available for a specified object or type of object. ═══ TabGroup property ═══ This property has been added to all objects with the TabStop property. This property is used to group objects into tab groups without using group boxes. The user can move from object to object within a tab group by using either the tab or cursor keys, but can only switch between tab groups by using the tab key. ═══ VertJustification property ═══ DescriptiveText objects have a new VertJustification property, which can be Top, Bottom, or Center. You must set this property at design time; it is read only at run time. ═══ 7. Contacting Watcom ═══ How to Contact Watcom In North America (and all other non-European locations) Watcom International Corporation. 415 Phillip Street, Waterloo, Ontario, CANADA, N2L 3X2 General Inquiries Sales Technical Support tel: (519)886-3700 Upgrades, other product orders, hot-line: (519)886-3700 fax: (519)747-4971 and reseller inquiries/orders: fax: (519)747-4547 1-800-265-4555 (toll free in BBS: (519)884-2100 North America) Internet: tech@watcom.on.ca Compuserve: type GO WATCOM Watfax Technical support and product information is available 24 hours a day using our Watfax system. To reach Watfax, call 1-519-747-2693 from your touch-tone fax phone. In Europe Watcom Europe Limited. PO Box 64, Livingston, West Lothian, EH54 7AE, UNITED KINGDOM General Inquiries Sales Technical Support United Kingdom Upgrades, other product orders, United Kingdom tel: 0506 460112 and reseller inquiries/orders: tel: 0506 460112 fax: 0506 460115 fax: 0506 460115 United Kingdom Toll Free Other Locations tel: 0800 44 44 55 Other Locations tel: (44) 506 460112 fax: 0800 55 54 55 tel: (44) 506 460112 fax: (44) 506 460115 fax: (44) 506 460115 Germany Toll Free tel: 0130 81 88 62 BBS: (519)884-2100 fax: 0130 81 88 63 Internet: tech@watcom.on.ca Compuserve: type GO WATCOM France Toll Free tel: 05 90 81 35 fax: 05 90 81 36 All Other Locations tel: (44) 506 460112 fax: (44) 506 460115 ═══ 8. Notices ═══ Topics Copyright Disclaimer Trademarks ═══ Copyright ═══ Copyright 1993, 1994 by Watcom International Corporation All rights reserved. No part of this publication may be reproduced or used in any form or by any means -- graphic, electronic, or mechanical, including photocopying, recording, taping or information storage and retrieval systems -- without written permission of the Watcom International Corporation. ═══ Disclaimer ═══ Watcom (Watcom International Corporation and all of its subsidiaries) makes no representation or warranty with respect to the adequacy of this documentation or the programs which it describes for any particular purpose or with respect to its adequacy to produce any particular result. In no event shall Watcom, its employees, its contractors or the authors of this documentation be liable for special, direct, indirect or consequential damages, losses, costs, charges, claims, demands or claim for lost profits, fees or expenses of any nature or kind. ═══ Trademarks ═══ Watcom and VX-REXX are trademarks of Watcom International Corporation. IBM, OS/2, Extended Services, Extended Services for OS/2, Database 2, DB2/2, Multimedia Presentation Manager/2, and MMPM/2 are trademarks of the IBM Corporation. Q+E is a trademark of Q+E Software. ════════════════════════════════════════════════ Watcom VX-REXX v2.1 Registration Number: VXR2103724