--------------------------------------------------------------------- VX-REXX Macro Installation & Design Guide for use with VX-REXX version 1.01 September 1993 --------------------------------------------------------------------- What is a macro? ---------------- Besides stand-alone applications, REXX can also be used to write "macros" for use with REXX-aware applications. A macro is simply a REXX program that is executed directly by an application. The application defines its own external functions and/or subcommand handlers, and this allows the macro to call back into the application to perform complex operations, extract data, and so on. And of course, you can develop these macros using VX-REXX. An example of a macro can be found in the SAMPLES\SCAN directory. It's a macro for use with the EPM editor. See the readme for instructions on how to use it. VX-REXX macros -------------- Macros can be written for use within the VX-REXX editing environment itself -- that is, VX-REXX is itself a REXX-aware application. These macros can be used to extend the features of the design environment in many useful ways. The simplest example of a macro is the PROFILE.VRM file, located in the MACROS subdirectory. Every time VX-REXX starts up, it executes the code in this file. Its main purpose is to register the macros that are to be added to the VX-REXX popup menu. VX-REXX includes a number of sample macros in the MACROS subdirectory. Simply uncomment the appropriate lines in the default PROFILE.VRM file and run VX-REXX to try them out. Except for the PROFILE.VRM file, which must be located in the MACROS subdirectory, the following search order is used to find macro files: 1. The directory where VX-REXX was installed (as returned by the VREPath function). 2. The SYSTEM subdirectory. 3. The MACROS subdirectory. 4. The directories listed in the PATH environment variable. The search order is not used if an absolute path (a path that starts at the root of a drive) is specified. If no extension is given, the extension '.VRM' will be assumed. When creating your own macros, it is recommended that you place them in the MACROS subdirectory. The SYSTEM subdirectory is reserved for use by VX-REXX. Installing VX-REXX macros ------------------------- VX-REXX macros are added to the popup menu using the VREMacroAdd function: call VREMacroAdd title, filename, [object list] When adding a macro, you specify the title to use on the popup menu and the name of the macro file to invoke. You can also specify an optional list of object types for which the macro is valid. A couple of examples: call VREMacroAdd "Property editor...", "SetProps" call VREMacroAdd "Match sizes", "Resize" The following examples restrict the use of the macro to certain object types (in other words, they will only appear in the popup menu when you click on one of these object types): call VREMacroAdd "Tab editor...", "SetTabs", "Window" types = ';PushButton;RadioButton;CheckBox' call VREMacroAdd 'Set button defaults', 'bdefault.vrm', types The space on the popup menu is limited, so if you have more macros than can comfortably fit on the menu, it may be simpler to write a single macro that lets you pick a macro from a listbox (don't forget to pass the correct arguments to the macro you are invoking). Editing the sample macros ------------------------- The source for the sample macros are located in subdirectories of the MACROS directory. To edit one of these macros, simply load the project as usual (i.e., from the Workplace Shell click on the .VRP file, or open the project from within VX-REXX). After making any changes, save the project as usual. Then select the "Make macro..." menu item from the "Project" menu to make a new macro (.VRM) file. You should save the macro in the MACROS directory, not the project directory. Creating new macros ------------------- To create new macros, just make a new project as you usually would and make the macro as described above. Please note that macros are not designed to be run using the Run menu item, as the macros depend directly on the VX-REXX editing environment. To test your macros you must add a call to VREMacroAdd to your PROFILE.VRM file. Arguments --------- When a macro is invoked, it is passed two object handles (internal object names) as arguments. The first argument is the handle of the object on which the popup menu was invoked (i.e., where the user clicked) and the second argument is the handle of the window on which the object resides. The VRWindow() function works as usual within a macro. Available functions ------------------- Because your macro is a VX-REXX macro, it has access to all the "VR" functions you normally use: VRSet, VRGet, VRLoad, and so on. But because you are running as a macro within the VX-REXX environment, a number of special functions with the "VRE" prefix are also available. (Note: they are only available within the VX-REXX design environment.) VREPath() -- Returns the directory where VX-REXX is installed. VREMacroAdd( title, filename, [objlist] ) -- Adds a macro to the popup menu. Returns 1 (success) or 0. VREMacroDelete( title ) -- Deletes a macro from the popup menu. Returns 1 (success) or 0. VREMacroList( stemname, [option] ) -- Fills a stem with the list of currently installed macros. If option is 'f', fills the stem with the macro filenames. If option is 't', fills the stem with the macro titles. Default is 'f'. Returns 1 (success) or 0. New methods ----------- The second argument passed to a macro is the handle of the window on which the object resides. Besides all the normal methods available to the Window object, this object also has the following method available: call VRMethod window, 'GetSelectedRoots', stemname -- Fills the stem with the handles of the currently selected objects on that window. call VRMethod window, 'NotebookOpen', object1, object2, ... -- Opens the property notebook(s) for the given object(s), if not already open. call VRMethod window, 'NotebookUpdate', object1, object2, ... -- Forces the property notebook(s) for an object(s) to be updated with the current property values. Only needed in a few situations. call VRMethod window, 'NotebookClose', object1, object2, ... -- Closes the property notebook(s) if open. call VRMethod window, 'SelectObject', stemname, [1 or 0] -- Selects or deselects objects on the window from a list of objects in a stem. If the last parameter is omitted, it defaults to 1. For example, to make sure an object is selected: sel.0 = 1 sel.1 = object_handle call VRMethod window, 'SelectObject', 'sel.', 1 or to deselect two objects: sel.0 = 2 sel.1 = ...... sel.2 = ...... call VRMethod window, 'SelectObject', 'sel.', 0 To deselect all object use this shortcut: sel.0 = 0 call VRMethod window, 'SelectObject', 'sel.', 0