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

              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

