============================================================================
 VX-REXX Tech Note #8:
                 
                              Extending VX-REXX's drag-and-drop programming

                                                            October 7, 1994

                               Applies to VX-REXX versions 1.01 and greater
                     
----------------------------------------------------------------------------

                                                       Eric Giguere
                                                       giguere@watcom.on.ca
                                                       Watcom International

============================================================================


Abstract
--------

You can use drag-and-drop programming within the VX-REXX development
environment to automatically insert code into your program.  This technical
note shows you how to customize these features.


How it works
------------

When the VX-REXX design environment starts up, it looks in the VXREXX\SYSTEM
directory for files ending in the extensions MTO and MTC.  The MTO files
describe the properties and methods that each object supports.  The MTC
files describe the REXX and VX-REXX functions that are available.  VX-REXX
reads the contents of these files and then when the user drags an
object onto a section editor window (or chooses "Insert code..." in the
section editor popup menu) a dialog appears listing the options that
are available, as described in the appropriate MTO or MTC file.  If the
user selects one of the options in the list, a macro file is then
invoked.  The macro file typically displays a second dialog asking for
values for various parameters and then forms the string to be inserted
at the current cursor location.

By creating your own MTC or MTO files and the appropriate macro files
to accompany them you can extend VX-REXX.


MTC Files -- Functions
----------------------

An MTC file describes a set of functions.  The first line describes
the contents of the file and is ignored, for example "Additional functions".
The remaining lines in the file describe the functions themselves.
Here is a simple example:

        My own functions
        Useful functions;Beep a lot;dummy;mybeep
        Useful functions;Shake the screen horizontally;horiz;shake
        Useful functions;Shake the screen vertically;vert;shake
        Not-so-useful functions;Burp;1;burp
        Not-so-useful functions;Burp twice;2;burp

As you can see, each line consists of semicolon-delimited fields.
The first field is the section heading and the second field is
the title to use for the function.  So in the container the user
would see the following:

        Not-so-useful functions
            Burp
            Burp twice
        Useful functions
            Beep a lot
            Shake the screen horizontally
            Shake the screen vertically

The third and fourth fields are only used if the user selects
a particular item.  The third field is an argument string to pass
to a macro, and the fourth field is the name of a macro to invoke.
The macro must exist either in the VXREXX\SYSTEM directory or in
the VXREXX\MACROS directory (most of the VX-REXX macros are built
into the MACROS.DLL file, however).

See below for a discussion of how to build the macro files.


MTO Files -- Objects
--------------------

MTO files are similar to MTC files but describe the properties
and methods of an object.  These files should be provided by
the developer of a VX-REXX object.  They look like MTC files:

          Methods;Invoke help;InvokeHelp;NoParms
          Methods;List methods;ListMethods;ListMeth
          Get property;AllowDrag;AllowDrag;GetVal
          Get property;Visible;Visible;GetVal
          Set property;AllowDrag;AllowDrag;TFProps
          Set property;Visible;Visible;TFProps

Again, the first field is the section heading, the second field
is the item title, the third field is the argument to pass to
a macro, the fourth field is the macro to invoke.


Macros
------

Macros are simply VX-REXX programs that have been saved using
the "Make macro..." menu item.  Several predefined macros are
also available, collected into the MACROS.DLL file.  Here are
the names of the predefined macros and what they do:

      GetVal -- Does not display a window, simply returns
                a string of the form "value = VRGet( object, property )",
                where property is replaced with the argument that
                was passed to the macro and object is replaced with
                the name of the object in question.

      NoParms -- Does not display a window, simply returns
                 a string of the form "ok = VRMethod( object, method )",
                 where method is replaced with the argument that was
                 passed to the macro and object is replaced with the
                 name of the object in question.

      TFProps -- Displays a dialog with a checkbox.  Returns a
                 string of the form "ok = VRSet( object, property, val )",
                 where val = 0 or 1 depending on what the user chose.

      EnumProp -- Displays a dialog with a dropdown combo box allowing
                  the user to choose between several choices for a
                  property setting.  The name of the property and the
                  choices are passed as the parameter, for example:

                  Set property;DragTarget;DragTarget_All_Files_None;EnumProp

                  The '_' character is used to delimit the various parts
                  of the list.  Returns a string of the form
                  "ok = VRSet( object, property, val )".

      NumProps -- Like TFProps, but allows user to type in a number.

      StrProps -- Like TFProps, but allows user to type in a string.

If one of these predefined macros does not suit your needs, simply
create a new macro that follows these rules:

     -- One argument will be passed to a macro invoked from an MTC
        file, accessible as InitArgs.2.  The argument is the argument
        string from the MTC file. (InitArgs.1 will be a null string.)

     -- Two arguments will be passed to a macro invoked from an MTO
        file, accessible as InitArgs.1 and InitArgs.2.  The first
        argument is the name of the object, the second is the
        argument string from the line in the MTO file.

     -- Your macro should display a dialog if user input is required.

     -- When done, the macro must return either a null string (indicating
        that the macro was cancelled and nothing is to be inserted)
        or a string.  The string will be inserted into the editor at
        the current cursor location and should be a valid REXX statement.

The macro must be installed in the VXREXX\SYSTEM or VXREXX\MACROS
directory.  (The SYSTEM directory is used for VX-REXX supplied macros,
so it is recommended that you use the MACROS directory.)


Examples
--------

Included with this tech note is a sample MTC file, SAMPLE.MTC, and
the sample macro file SAMPLE1, which demonstrate the concepts presented
here.  You can use them as patterns for building your own files.  To
try them out, simply copy the files into your VXREXX\SYSTEM directory,
start VX-REXX, open the Init section, then select "Insert code..."
from the popup menu.


