home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 18 REXX / 18-REXX.zip / vxdemo.zip / MACROS.TX$ / MACROS.TXT
Text File  |  1993-09-13  |  8KB  |  207 lines
  1. ---------------------------------------------------------------------
  2.  
  3.               VX-REXX Macro Installation & Design Guide
  4.  
  5.                   for use with VX-REXX version 1.01
  6.  
  7.                                                        September 1993
  8. ---------------------------------------------------------------------
  9.  
  10.  
  11. What is a macro?
  12. ----------------
  13.  
  14.     Besides stand-alone applications, REXX can also be used to write
  15. "macros" for use with REXX-aware applications.  A macro is simply a
  16. REXX program that is executed directly by an application.  The
  17. application defines its own external functions and/or subcommand
  18. handlers, and this allows the macro to call back into the application
  19. to perform complex operations, extract data, and so on.  And of course,
  20. you can develop these macros using VX-REXX.
  21.  
  22.     An example of a macro can be found in the SAMPLES\SCAN directory.
  23. It's a macro for use with the EPM editor.  See the readme for instructions
  24. on how to use it.
  25.  
  26.  
  27. VX-REXX macros
  28. --------------
  29.  
  30.     Macros can be written for use within the VX-REXX editing environment
  31. itself -- that is, VX-REXX is itself a REXX-aware application.  These
  32. macros can be used to extend the features of the design environment in
  33. many useful ways.
  34.  
  35.     The simplest example of a macro is the PROFILE.VRM file, located in
  36. the MACROS subdirectory.  Every time VX-REXX starts up, it executes
  37. the code in this file.  Its main purpose is to register the macros that
  38. are to be added to the VX-REXX popup menu.  VX-REXX includes a number of
  39. sample macros in the MACROS subdirectory.  Simply uncomment the appropriate
  40. lines in the default PROFILE.VRM file and run VX-REXX to try them out.
  41.  
  42.     Except for the PROFILE.VRM file, which must be located in the MACROS
  43. subdirectory, the following search order is used to find macro files:
  44.  
  45.         1. The directory where VX-REXX was installed (as returned by
  46.            the VREPath function).
  47.         2. The SYSTEM subdirectory.
  48.         3. The MACROS subdirectory.
  49.         4. The directories listed in the PATH environment variable.
  50.  
  51. The search order is not used if an absolute path (a path that starts at the
  52. root of a drive) is specified.  If no extension is given, the extension
  53. '.VRM' will be assumed.
  54.  
  55.     When creating your own macros, it is recommended that you place them
  56. in the MACROS subdirectory.  The SYSTEM subdirectory is reserved for
  57. use by VX-REXX.
  58.  
  59.  
  60. Installing VX-REXX macros
  61. -------------------------
  62.  
  63.     VX-REXX macros are added to the popup menu using the VREMacroAdd
  64. function:
  65.  
  66.         call VREMacroAdd title, filename, [object list]
  67.  
  68. When adding a macro, you specify the title to use on the popup menu
  69. and the name of the macro file to invoke.  You can also specify an
  70. optional list of object types for which the macro is valid.
  71.  
  72.     A couple of examples:
  73.  
  74.         call VREMacroAdd "Property editor...", "SetProps"
  75.         call VREMacroAdd "Match sizes", "Resize" 
  76.  
  77.     The following examples restrict the use of the macro to certain
  78. object types (in other words, they will only appear in the popup menu
  79. when you click on one of these object types):
  80.  
  81.         call VREMacroAdd "Tab editor...", "SetTabs", "Window"
  82.  
  83.         types = ';PushButton;RadioButton;CheckBox'
  84.         call VREMacroAdd 'Set button defaults', 'bdefault.vrm', types
  85.  
  86.     The space on the popup menu is limited, so if you have more macros
  87. than can comfortably fit on the menu, it may be simpler to write a single
  88. macro that lets you pick a macro from a listbox (don't forget to pass
  89. the correct arguments to the macro you are invoking).
  90.  
  91.  
  92. Editing the sample macros
  93. -------------------------
  94.  
  95.     The source for the sample macros are located in subdirectories of
  96. the MACROS directory.  To edit one of these macros, simply load the project
  97. as usual (i.e., from the Workplace Shell click on the .VRP file, or open
  98. the project from within VX-REXX).  After making any changes, save the
  99. project as usual.  Then select the "Make macro..." menu item from the
  100. "Project" menu to make a new macro (.VRM) file.  You should save the
  101. macro in the MACROS directory, not the project directory.
  102.  
  103.  
  104. Creating new macros
  105. -------------------
  106.  
  107.     To create new macros, just make a new project as you usually would
  108. and make the macro as described above.
  109.  
  110.     Please note that macros are not designed to be run using the Run
  111. menu item, as the macros depend directly on the VX-REXX editing environment.
  112. To test your macros you must add a call to VREMacroAdd to your PROFILE.VRM
  113. file.
  114.  
  115.  
  116. Arguments
  117. ---------
  118.  
  119.     When a macro is invoked, it is passed two object handles (internal
  120. object names) as arguments.  The first argument is the handle of the
  121. object on which the popup menu was invoked (i.e., where the user clicked)
  122. and the second argument is the handle of the window on which the object
  123. resides.
  124.  
  125.     The VRWindow() function works as usual within a macro.
  126.  
  127.  
  128. Available functions
  129. -------------------
  130.  
  131.     Because your macro is a VX-REXX macro, it has access to all the "VR"
  132. functions you normally use:  VRSet, VRGet, VRLoad, and so on.  But because
  133. you are running as a macro within the VX-REXX environment, a number of
  134. special functions with the "VRE" prefix are also available.  (Note: they
  135. are only available within the VX-REXX design environment.)
  136.  
  137.         VREPath()
  138.  
  139.         -- Returns the directory where VX-REXX is installed.
  140.  
  141.         VREMacroAdd( title, filename, [objlist] )
  142.  
  143.         -- Adds a macro to the popup menu.  Returns 1 (success) or 0.
  144.  
  145.         VREMacroDelete( title )
  146.  
  147.         -- Deletes a macro from the popup menu.  Returns 1 (success) or 0.
  148.  
  149.         VREMacroList( stemname, [option] )
  150.  
  151.         -- Fills a stem with the list of currently installed macros.  If
  152.            option is 'f', fills the stem with the macro filenames.  If
  153.            option is 't', fills the stem with the macro titles.  Default
  154.            is 'f'.  Returns 1 (success) or 0.
  155.  
  156.  
  157. New methods
  158. -----------
  159.  
  160.     The second argument passed to a macro is the handle of the window on
  161. which the object resides.  Besides all the normal methods available to
  162. the Window object, this object also has the following method available:
  163.  
  164.         call VRMethod window, 'GetSelectedRoots', stemname
  165.  
  166.         -- Fills the stem with the handles of the currently selected
  167.            objects on that window.
  168.  
  169.         call VRMethod window, 'NotebookOpen', object1, object2, ...
  170.  
  171.         -- Opens the property notebook(s) for the given object(s), if not
  172.            already open.
  173.  
  174.         call VRMethod window, 'NotebookUpdate', object1, object2, ...
  175.  
  176.         -- Forces the property notebook(s) for an object(s) to be updated
  177.            with the current property values.  Only needed in a few
  178.            situations.
  179.  
  180.         call VRMethod window, 'NotebookClose', object1, object2, ...
  181.  
  182.         -- Closes the property notebook(s) if open.
  183.  
  184.         call VRMethod window, 'SelectObject', stemname, [1 or 0]
  185.  
  186.         -- Selects or deselects objects on the window from a list of
  187.            objects in a stem.  If the last parameter is omitted, it
  188.            defaults to 1.  For example, to make sure an object is
  189.            selected:
  190.  
  191.                  sel.0 = 1
  192.                  sel.1 = object_handle
  193.                  call VRMethod window, 'SelectObject', 'sel.', 1
  194.  
  195.            or to deselect two objects:
  196.  
  197.                  sel.0 = 2
  198.                  sel.1 = ......
  199.                  sel.2 = ......
  200.                  call VRMethod window, 'SelectObject', 'sel.', 0
  201.  
  202.            To deselect all object use this shortcut:
  203.  
  204.                  sel.0 = 0
  205.                  call VRMethod window, 'SelectObject', 'sel.', 0
  206.  
  207.