home *** CD-ROM | disk | FTP | other *** search
/ Magazyn Exec 5 / CD_Magazyn_EXEC_nr_5.iso / Programy / OS3.5+ / BoingBag39-1.lha / BoingBag3.9-1 / Manuals / English / Workbench-ARexx.doc < prev    next >
Text File  |  2001-02-21  |  53KB  |  2,060 lines
  1. The Workbench ARexx interface
  2. =============================
  3.  
  4. Workbench acts as an ARexx host under the name of "WORKBENCH". It supports
  5. a number of commands as will be described below. Note that for the ARexx
  6. interface to work, rexxsyslib.library must be installed (this library is
  7. part of a regular Workbench installation) and the RexxMast program must
  8. have been started.
  9.  
  10.  
  11. 1. ACTIVATEWINDOW command
  12.  
  13. Purpose:
  14.  
  15.     This command will attempt to make a window the active one.
  16.  
  17. Format:
  18.  
  19.     ACTIVATEWINDOW [WINDOW] <ROOT|Drawer name>
  20.  
  21. Template:
  22.  
  23.     ACTIVATEWINDOW WINDOW
  24.  
  25. Parameters:
  26.  
  27.     WINDOW
  28.  
  29.         Either "ROOT" to activate the Workbench root window (where volume
  30.         icons and AppIcons live) or the fully qualified name of a drawer
  31.         window to activate. Note that the drawer window must already be open.
  32.  
  33.         If no WINDOW parameter is specified, this command will try to operate
  34.         on the currently active Workbench window.
  35.  
  36. Errors:
  37.  
  38.     10 - If the named window cannot be activated. The error code will be
  39.          placed in the WORKBENCH.LASTERROR variable.
  40.  
  41. Result:
  42.  
  43. -
  44.  
  45. Notes:
  46.  
  47.     If you choose to have a window activated that is not the root window you
  48.     must make sure that the window name is given as a fully qualified path
  49.     name. For example "Work:" is a fully qualified name, and so is
  50.     "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A
  51.     fully qualified name always contains the name of an assignment, a volume
  52.     or a device.
  53.  
  54. Example:
  55.  
  56.     /* Activate the root window. */
  57.     ADDRESS workbench
  58.  
  59.     ACTIVATEWINDOW root
  60.  
  61.     /* Activate the "Work:" partition's window. */
  62.     ACTIVATEWINDOW 'Work:'
  63.  
  64.  
  65. 2. CHANGEWINDOW command
  66.  
  67. Purpose:
  68.  
  69.     This command will attempt to change the size and the position of a window.
  70.  
  71. Format:
  72.  
  73.     CHANGEWINDOW [WINDOW] <ROOT|ACTIVE|LASTACTIVE|Drawer name>
  74.                  [LEFTEDGE <new left edge position>]
  75.                  [TOPEDGE <new top edge position>]
  76.                  [WIDTH <new window width>]
  77.                  [HEIGHT <new window height>]
  78.  
  79. Template:
  80.  
  81.     CHANGEWINDOW WINDOW,LEFTEDGE/N,TOPEDGE/N,WIDTH/N,HEIGHT/N
  82.  
  83. Parameters:
  84.  
  85.     WINDOW
  86.  
  87.         Either "ROOT" to resize/move the Workbench root window (where volume
  88.         icons and AppIcons live), "ACTIVE" to change the currently active
  89.         Workbench window or the fully qualified name of a drawer window to
  90.         change. Note that the drawer window must already be open.
  91.  
  92.         If no WINDOW parameter is specified, this command will try to operate
  93.         on the currently active Workbench window.
  94.  
  95.     LEFTEDGE
  96.  
  97.         New left edge window position.
  98.  
  99.     TOPEDGE
  100.  
  101.         New top edge window position.
  102.  
  103.     WIDTH
  104.  
  105.        New window width.
  106.  
  107.     HEIGHT
  108.  
  109.        New window height.
  110.  
  111. Errors:
  112.  
  113.     10 - If the named window cannot be changed; this can also happen if you
  114.          specified "ACTIVE" as the window name and none of the Workbench
  115.          windows is currently active. The error code will be placed in the
  116.          WORKBENCH.LASTERROR variable.
  117.  
  118. Result:
  119.  
  120.     -
  121.  
  122. Notes:
  123.  
  124.     If you choose to have a window changed that is neither the root nor the
  125.     active window you must make sure that the window name is given as a fully
  126.     qualified path name. For example "Work:" is a fully qualified name, and so
  127.     is "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A
  128.     fully qualified name always contains the name of an assignment, a volume
  129.     or a device.
  130.  
  131. Example:
  132.  
  133.     /* Change the root window; move it to position 10,30.
  134.      * and change its size to 200×100 pixels.
  135.      */
  136.     ADDRESS workbench
  137.  
  138.     CHANGEWINDOW root LEFTEDGE 10 TOPEDGE 30 WIDTH 200 HEIGHT 100
  139.  
  140.     /* Change the currently active window. */
  141.     CHANGEWINDOW active 20 40 200 100
  142.  
  143.  
  144. 3. DELETE command
  145.  
  146. Purpose:
  147.  
  148.     This command is for deleting files and drawers (and their contents).
  149.  
  150. Format:
  151.  
  152.     DELETE [NAME] <File or drawer name> [ALL]
  153.  
  154. Template:
  155.  
  156.     DELETE NAME/A,ALL/S
  157.  
  158. Parameters:
  159.  
  160.     NAME
  161.  
  162.         Name of the file or drawer or volume to delete.
  163.  
  164.     ALL
  165.  
  166.         If the object in question is a drawer, attempt to delete
  167.         the contents of the drawer as well as the drawer itself.
  168.         If this option is not specified, the DELETE command will
  169.         only attempt to delete the drawer itself, which may fail
  170.         if the drawer is not yet empty.
  171.  
  172. Errors:
  173.  
  174.     10 - If the named file, drawer or volume could not be found or
  175.          could not be deleted.
  176.  
  177. Result:
  178.  
  179.     -
  180.  
  181. Notes:
  182.  
  183.     The file name given must be an absolute path, such as in
  184.     "RAM:Empty". A relative path, such as "/fred/barney" will
  185.     not work.
  186.  
  187. Example:
  188.  
  189.     /* Delete the contents of the drawer "RAM:Empty". */
  190.     ADDRESS workbench
  191.  
  192.     DELETE 'RAM:Empty' ALL
  193.  
  194.  
  195. 4. FAULT command
  196.  
  197. Purpose:
  198.  
  199.     This command will return a human readable explanation corresponding
  200.     to an error code.
  201.  
  202. Format:
  203.  
  204.     FAULT [CODE] <Error code>
  205.  
  206. Template:
  207.  
  208.     FAULT CODE/A/N
  209.  
  210. Parameters:
  211.  
  212.     CODE
  213.  
  214.         Error code to return a human readable explanation for.
  215.  
  216. Errors:
  217.  
  218.     -
  219.  
  220. Result:
  221.  
  222.     -
  223.  
  224. Example:
  225.  
  226.     /* Query the error message corresponding to error code #205. */
  227.     ADDRESS workbench
  228.     OPTIONS RESULTS
  229.  
  230.     FAULT 205
  231.     SAY result
  232.  
  233.  
  234. 5. GETATTR command
  235.  
  236. Purpose:
  237.  
  238.     This command will retrieve information from the Workbench database, such
  239.     the names of the drawers currently open and the icons currently selected.
  240.  
  241. Format:
  242.  
  243.     GETATTR [OBJECT] <Object name> [NAME <Item name>]
  244.             [STEM <Name of stem variable>] [VAR <Variable name>]
  245.  
  246. Template:
  247.  
  248.     GETATTR OBJECT/A,NAME/K,STEM/K,VAR/K
  249.  
  250. Parameters:
  251.  
  252.     OBJECT
  253.  
  254.         Name of the database entry to retrieve. For a list of valid
  255.         entries see below.
  256.  
  257.     NAME
  258.  
  259.         For some datatabase entries further information is required
  260.         to identify the data to retrieve. This is when you will need
  261.         to provide a name.
  262.  
  263.     STEM
  264.  
  265.         If you request more than one database entry you will need to
  266.         provide a variable to store the information in. For an example
  267.         of its use, see below.
  268.  
  269.     VAR
  270.  
  271.         If you want the queried information to be stored in a specific
  272.         variable (other than the RESULT variable), this is where you
  273.         provive its name.
  274.  
  275. Attributes:
  276.  
  277.     You can obtain information on the following attributes:
  278.  
  279.     APPLICATION.VERSION
  280.  
  281.         Version number of "workbench.library".
  282.  
  283.     APPLICATION.SCREEN
  284.  
  285.         Name of the public screen Workbench uses.
  286.  
  287.     APPLICATION.AREXX
  288.  
  289.         Name of the Workbench ARexx port.
  290.  
  291.     APPLICATION.LASTERROR
  292.  
  293.         Number of the last error caused by the ARexx interface.
  294.  
  295.     APPLICATION.ICONBORDER
  296.  
  297.         Sizes of the icon borders, returned as four numbers separated
  298.         by blank spaces, e.g. "4 3 4 3". The four numbers represent
  299.         the left border width, the top border height, the right border
  300.         width and the bottom border height (in exactly that order).
  301.  
  302.     APPLICATION.FONT.SCREEN.NAME
  303.  
  304.         Name of the Workbench screen font.
  305.  
  306.     APPLICATION.FONT.SCREEN.WIDTH
  307.     APPLICATION.FONT.SCREEN.HEIGHT
  308.  
  309.         Size of a single character of the Workbench screen font. Please
  310.         note that since the font in question may be proportional spaced
  311.         the width information may be of little value. To measure the
  312.         accurate pixel width of a text in reference to the font, use
  313.         the .SIZE attribute.
  314.  
  315.     APPLICATION.FONT.SCREEN.SIZE
  316.  
  317.         Size of a text, measured in pixels, in reference to the screen
  318.         font. The text to measure must be provided with the NAME
  319.         parameter of the GETATTR command.
  320.  
  321.     APPLICATION.FONT.ICON.NAME
  322.  
  323.         Name of the Workbench icon font.
  324.  
  325.     APPLICATION.FONT.ICON.WIDTH
  326.     APPLICATION.FONT.ICON.HEIGHT
  327.  
  328.         Size of a single character of the Workbench icon font. Please
  329.         note that since the font in question may be proportional spaced
  330.         the width information may be of little value. To measure the
  331.         accurate pixel width of a text in reference to the font, use
  332.         the .SIZE attribute.
  333.  
  334.     APPLICATION.FONT.ICON.SIZE
  335.  
  336.         Size of a text, measured in pixels, in reference to the icon
  337.         font. The text to measure must be provided with the NAME
  338.         parameter of the GETATTR command.
  339.  
  340.     APPLICATION.FONT.SYSTEM.NAME
  341.  
  342.         Name of the system font.
  343.  
  344.     APPLICATION.FONT.SYSTEM.WIDTH
  345.     APPLICATION.FONT.SYSTEM.HEIGHT
  346.  
  347.         Size of a single character of the system font.
  348.  
  349.     APPLICATION.FONT.SYSTEM.SIZE
  350.  
  351.         Size of a text, measured in pixels, in reference to the
  352.         system font. The text to measure must be provided with the
  353.         NAME parameter of the GETATTR command.
  354.  
  355.  
  356.     WINDOWS.COUNT
  357.  
  358.         Number of the drawer windows currently open. This can be 0.
  359.  
  360.     WINDOWS.0 .. WINDOWS.N
  361.  
  362.         Names of the windows currently open.
  363.  
  364.     WINDOWS.ACTIVE
  365.  
  366.         Name of the currently active Workbench window; this will
  367.         be "" if none of Workbench's windows is currently active.
  368.  
  369.     WINDOWS.LASTACTIVE
  370.  
  371.         Name of the previously active Workbench window; this will
  372.         be "" if there is no previously active Workbench window
  373.         or if the previously active Workbench window has already
  374.         been closed. This attribute is available for querying
  375.         starting with Workbench version 45.
  376.  
  377.  
  378.     KEYCOMMANDS.COUNT
  379.  
  380.         Number of keyboard commands assigned. This can be 0.
  381.  
  382.     KEYCOMMANDS.0 .. KEYCOMMANDS.N
  383.  
  384.         Information on all the keyboard commands assigned.
  385.  
  386.         KEYCOMMANDS.<n>.NAME
  387.  
  388.             Name of the keyboard command.
  389.  
  390.         KEYCOMMANDS.<n>.KEY
  391.  
  392.             The key combination assigned to this keyboard
  393.             command.
  394.  
  395.         KEYCOMMANDS.<n>.COMMAND
  396.  
  397.             The ARexx command assigned to this key combination.
  398.  
  399.  
  400.     MENUCOMMANDS.COUNT
  401.  
  402.         Number of menu commands assigned (through the "MENU ADD .."
  403.         command). This can be 0.
  404.  
  405.     MENUCOMMANDS.0 .. MENUCOMMANDS.N
  406.  
  407.         Information on all the menu commands assigned.
  408.  
  409.         MENUCOMMANDS.<n>.NAME
  410.  
  411.             Name of this menu item.
  412.  
  413.         MENUCOMMANDS.<n>.TITLE
  414.  
  415.             Title of this menu item.
  416.  
  417.         MENUCOMMANDS.<n>.SHORTCUT
  418.  
  419.             The keyboard shortcut assigned to this menu item.
  420.  
  421.         MENUCOMMANDS.<n>.COMMAND
  422.  
  423.             The ARexx command assigned to this menu item.
  424.  
  425.  
  426.     The following attributes require that the name of the window to obtain
  427.     information on is provided.
  428.  
  429.     WINDOW.LEFT
  430.  
  431.         Left edge of the window.
  432.  
  433.     WINDOW.TOP
  434.  
  435.         Top edge of the window.
  436.  
  437.     WINDOW.WIDTH
  438.  
  439.         Width of the window.
  440.  
  441.     WINDOW.HEIGHT
  442.  
  443.         Height of the window.
  444.  
  445.     WINDOW.MIN.WIDTH
  446.  
  447.         Minimum width of the window.
  448.  
  449.     WINDOW.MIN.HEIGHT
  450.  
  451.         Minimum height of the window.
  452.  
  453.     WINDOW.MAX.WIDTH
  454.  
  455.         Maximum width of the window.
  456.  
  457.     WINDOW.MAX.HEIGHT
  458.  
  459.         Maximum height of the window.
  460.  
  461.     WINDOW.VIEW.LEFT
  462.  
  463.         Horizontal offset of the drawer contents; this value corresponds
  464.         to the horizontal window scroller position.
  465.  
  466.     WINDOW.VIEW.TOP
  467.  
  468.         Vertical offset of the drawer contents; this value corresponds
  469.         to the vertical window scroller position.
  470.  
  471.     WINDOW.SCREEN.NAME
  472.  
  473.         Name of the public screen the window was opened on.
  474.  
  475.     WINDOW.SCREEN.WIDTH
  476.     WINDOW.SCREEN.HEIGHT
  477.  
  478.         Size of the public screen the window was opened on.
  479.  
  480.     WINDOW.ICONS.ALL.COUNT
  481.  
  482.         Number of the icons displayed in the window. This can be 0.
  483.  
  484.     WINDOW.ICONS.ALL.0 .. WINDOW.ICONS.ALL.N
  485.  
  486.         Information on all the icons displayed in the window:
  487.  
  488.         WINDOW.ICONS.ALL.<n>.NAME
  489.  
  490.             Name of the icon in question.
  491.  
  492.         WINDOW.ICONS.ALL.<n>.LEFT
  493.         WINDOW.ICONS.ALL.<n>.TOP
  494.  
  495.             Position of the icon in question.
  496.  
  497.         WINDOW.ICONS.ALL.<n>.WIDTH
  498.         WINDOW.ICONS.ALL.<n>.HEIGHT
  499.  
  500.             Size of the icon in question.
  501.  
  502.         WINDOW.ICONS.ALL.<n>.TYPE
  503.  
  504.             Type of the icon; one of DISK, DRAWER, TOOL, PROJECT,
  505.             GARBAGE, DEVICE, KICK or APPICON.
  506.  
  507.         WINDOW.ICONS.ALL.<n>.STATUS
  508.  
  509.             Whether the icon is selected and (if the icon is a drawer-like
  510.             object, such as a disk, drawer or trashcan icon) whether the
  511.             corresponding drawer is currently open or closed. This attribute
  512.             is returned in the form of a string, such as "SELECTED OPEN"
  513.             which means that the icon is selected and the corresponding drawer
  514.             is currently open. The other options include "UNSELECTED" and
  515.             "CLOSED".
  516.  
  517.     WINDOW.ICONS.SELECTED.COUNT
  518.  
  519.         Number of the selected icons displayed in the window. This can be 0.
  520.  
  521.     WINDOW.ICONS.SELECTED.0 .. WINDOW.ICONS.SELECTED.N
  522.  
  523.         Information on all selected the icons in the window:
  524.  
  525.         WINDOW.ICONS.SELECTED.<n>.NAME
  526.  
  527.             Name of the icon in question.
  528.  
  529.         WINDOW.ICONS.SELECTED.<n>.LEFT
  530.         WINDOW.ICONS.SELECTED.<n>.TOP
  531.  
  532.             Position of the icon in question.
  533.  
  534.         WINDOW.ICONS.SELECTED.<n>.WIDTH
  535.         WINDOW.ICONS.SELECTED.<n>.HEIGHT
  536.  
  537.             Size of the icon in question.
  538.  
  539.         WINDOW.ICONS.SELECTED.<n>.TYPE
  540.  
  541.             Type of the icon; one of DISK, DRAWER, TOOL, PROJECT,
  542.             GARBAGE, DEVICE, KICK or APPICON.
  543.  
  544.         WINDOW.ICONS.SELECTED.<n>.STATUS
  545.  
  546.             Whether the icon is selected and (if the icon is a drawer-like
  547.             object, such as a disk, drawer or trashcan icon) whether the
  548.             corresponding drawer is currently open or closed. This attribute
  549.             is returned in the form of a string, such as "SELECTED OPEN"
  550.             which means that the icon is selected and the corresponding drawer
  551.             is currently open. The other options include "UNSELECTED" and
  552.             "CLOSED". Of course, for the WINDOW.ICONS.SELECTED stem the
  553.             icon status will always be reported as "SELECTED".
  554.  
  555.     WINDOW.ICONS.UNSELECTED.COUNT
  556.  
  557.         Number of the unselected icons displayed in the window. This can be 0.
  558.  
  559.     WINDOW.ICONS.UNSELECTED.0 .. WINDOW.ICONS.UNSELECTED.N
  560.  
  561.         Information on all selected the icons in the window:
  562.  
  563.         WINDOW.ICONS.UNSELECTED.<n>.NAME
  564.  
  565.             Name of the icon in question.
  566.  
  567.         WINDOW.ICONS.UNSELECTED.<n>.LEFT
  568.         WINDOW.ICONS.UNSELECTED.<n>.TOP
  569.  
  570.             Position of the icon in question.
  571.  
  572.         WINDOW.ICONS.UNSELECTED.<n>.WIDTH
  573.         WINDOW.ICONS.UNSELECTED.<n>.HEIGHT
  574.  
  575.             Size of the icon in question.
  576.  
  577.         WINDOW.ICONS.UNSELECTED.<n>.TYPE
  578.  
  579.             Type of the icon; one of DISK, DRAWER, TOOL, PROJECT,
  580.             GARBAGE, DEVICE, KICK or APPICON.
  581.  
  582.         WINDOW.ICONS.UNSELECTED.<n>.STATUS
  583.  
  584.             Whether the icon is selected and (if the icon is a drawer-like
  585.             object, such as a disk, drawer or trashcan icon) whether the
  586.             corresponding drawer is currently open or closed. This attribute
  587.             is returned in the form of a string, such as "UNSELECTED OPEN"
  588.             which means that the icon is selected and the corresponding drawer
  589.             is currently open. The other options include "SELECTED" and
  590.             "CLOSED". Of course, for the WINDOW.ICONS.UNSELECTED stem the
  591.             icon status will always be reported as "UNSELECTED".
  592.  
  593. Errors:
  594.  
  595.     10 - If the requester information could not be retrieved, you requested
  596.          more than one database entry and did not provide a stem variable
  597.          or if you provided a stem variable but did not request more than
  598.          one database entry. The error code will be placed in the
  599.          WORKBENCH.LASTERROR variable.
  600.  
  601. Result:
  602.  
  603.     RESULT - The information retrieved from the database.
  604.  
  605. Example:
  606.  
  607.     /* Query the Workbench version. */
  608.     ADDRESS workbench
  609.     OPTIONS RESULTS
  610.  
  611.     GETATTR application.version
  612.     SAY result
  613.  
  614.     /* Query the Workbench version and store it in the
  615.      * variable `version_number'.
  616.      */
  617.     GETATTR application.version VAR version_number
  618.     SAY version_number
  619.  
  620.     /* Query the names of all currently open windows,
  621.      * then print them.
  622.      */
  623.     GETATTR windows STEM window_list
  624.  
  625.     DO i = 0 TO window_list.count-1
  626.         SAY window_list.i;
  627.     END;
  628.  
  629.     /* Query name, position and size of the first icon
  630.      * shown in the root window.
  631.      */
  632.     GETATTR window.icons.all.0 NAME root STEM root
  633.  
  634.     SAY root.name
  635.     SAY root.left
  636.     SAY root.top
  637.     SAY root.width
  638.     SAY root.height
  639.     SAY root.type
  640.  
  641.     /* Query the width and height of the root window. */
  642.     GETATTR window.width NAME root
  643.     SAY result
  644.  
  645.     GETATTR window.height NAME root
  646.     SAY result
  647.  
  648.     /* Query the length of a text (in pixels) with reference
  649.      * to the icon font.
  650.      */
  651.     GETATTR application.font.icon.size NAME 'Text to measure'
  652.     SAY result
  653.  
  654.  
  655. 6. HELP command
  656.  
  657. Purpose:
  658.  
  659.     This command can be used to open the online help and to obtain information
  660.     on the supported menus, commands and command parameters.
  661.  
  662. Format:
  663.  
  664.     HELP [COMMAND <Command name>] [MENUS] [PROMPT]
  665.  
  666. Template:
  667.  
  668.     HELP COMMAND/K,MENUS/S,PROMPT/S
  669.  
  670. Parameters:
  671.  
  672.     COMMAND
  673.  
  674.         Name of the command whose command template should be retrieved.
  675.  
  676.     MENUS
  677.  
  678.         Specify this parameter to retrieve a list of menu items
  679.         currently available.
  680.  
  681.     PROMPT
  682.  
  683.         Specify this parameter to invoke the online help system.
  684.  
  685.  
  686.     If no parameter is provided, a list of supported commands will be
  687.     returned.
  688.  
  689. Errors:
  690.  
  691.     10 - If the named command is not supported by the ARexx interface.
  692.          The error code will be placed in the WORKBENCH.LASTERROR variable.
  693.  
  694. Result:
  695.  
  696.     RESULT
  697.  
  698.         The command template, list of menu items or commands, as
  699.         specified in the command parameters.
  700.  
  701. Example:
  702.  
  703.     /* Retrieve the list of supported commands. */
  704.     ADDRESS workbench
  705.     OPTIONS results
  706.  
  707.     HELP
  708.     SAY result
  709.  
  710.     /* Retrieve the command template of the `GETATTR' command. */
  711.     HELP COMMAND getattr
  712.     SAY result
  713.  
  714.     /* Retrieve the list of available menu items. */
  715.     HELP MENUS
  716.     SAY result
  717.  
  718.  
  719. 7. ICON command
  720.  
  721. Purpose:
  722.  
  723.     This command is for manipulating the icons displayed in a window.
  724.  
  725. Format:
  726.  
  727.     ICON [WINDOW] <Window name> <Icon name> .. <Icon name>
  728.          [OPEN] [MAKEVISIBLE] [SELECT] [UNSELECT]
  729.          [UP <Pixels>] [DOWN <Pixels>] [LEFT <Pixels>] [RIGHT <Pixels>]
  730.          [X <Horizontal position>] [Y <Vertical position>]
  731.          [ACTIVATE UP|DOWN|LEFT|RIGHT] [CYCLE PREVIOUS|NEXT]
  732.          [MOVE IN|OUT]
  733.  
  734. Template:
  735.  
  736.     ICON WINDOW,NAMES/M,OPEN/S,MAKEVISIBLE/S,SELECT/S,UNSELECT/S,
  737.          UP/N,DOWN/N,LEFT/N,RIGHT/N,X/N,Y/N,ACTIVATE/K,CYCLE/K,
  738.          MOVE/K
  739.  
  740. Parameters:
  741.  
  742.     WINDOW
  743.  
  744.         Name of the window whose icons should be manipulated. This can be
  745.         "ROOT" to work on the Workbench root window (where volume icons and
  746.         AppIcons live), "ACTIVE" to work on the currently active Workbench
  747.         window or the fully qualified name of a drawer window. Note that the
  748.         drawer window must already be open.
  749.  
  750.         If no WINDOW parameter is specified, this command will try to operate
  751.         on the currently active Workbench window.
  752.  
  753.     NAMES
  754.  
  755.         Names of the icons to manipulate.
  756.  
  757.     OPEN
  758.  
  759.         Specifies that the named icons should be opened.
  760.  
  761.     MAKEVISIBLE
  762.  
  763.         Specifies that the named icons should be made
  764.         visible. This generally works well for the first icon
  765.         in a list but does not always work for a whole list.
  766.  
  767.     SELECT
  768.  
  769.         Select the named icons.
  770.  
  771.     UNSELECT
  772.  
  773.         Unselect the named icons.
  774.  
  775.     UP, DOWN, LEFT, RIGHT
  776.  
  777.         Move the named icons by the specified number of pixels.
  778.  
  779.     X, Y
  780.  
  781.         Move the named icons to the specified position.
  782.  
  783.     ACTIVATE
  784.  
  785.         This command is for activating the icon closest to the
  786.         currently selected icon in the window. "Activating" in
  787.         this context means "selecting an icon, whilst at the same
  788.         time unselecting all others". Thus, the "active" icon
  789.         is the only selected icon in the window.
  790.  
  791.         You can indicate which direction the next icon to be
  792.         activated should be searched for, relative to the currently
  793.         active icon. "UP" searches upwards, "DOWN" searches
  794.         downwards, "LEFT" searches to the left and "RIGHT"
  795.         searches to the right.
  796.  
  797.     CYCLE
  798.  
  799.         This command is for cycling through all icons in a window,
  800.         making each one the active one in turn (for a description
  801.         of what "active" means in this context, see the "ACTIVATE"
  802.         description above). You must indicate in which direction
  803.         you want to cycle through the icons: you can either
  804.         specify "PREVIOUS" or "NEXT".
  805.  
  806.     MOVE
  807.  
  808.         This command is not for moving icons but for moving through
  809.         a file system hierarchy. Thus, moving "in" will open a drawer
  810.         and moving "out" will open the drawer's parent directory.
  811.         The "IN" parameter will cause the drawer represented by the
  812.         active icon to be opened. Please note that an icon must be
  813.         selected and it must be a drawer. The "OUT" parameter will
  814.         open the drawer's parent directory, and it also requires that
  815.         in the drawer there is an icon selected. This may sound
  816.         strange, but this feature is not meant as a replacement for
  817.         the "Open Parent" menu item.
  818.  
  819. Errors:
  820.  
  821.     10 - If the named window cannot be found, none of the Workbench
  822.          windows are currently active and the command was set to
  823.          work on the currently active Workbench window. The error code
  824.          will be placed in the WORKBENCH.LASTERROR variable.
  825.  
  826. Result:
  827.  
  828.     -
  829.  
  830. Example:
  831.  
  832.     /* Select the icons of the "Workbench" and "Work" volumes
  833.      * displayed in the root window.
  834.      */
  835.     ADDRESS workbench
  836.  
  837.     ICON WINDOW root NAMES Workbench Work SELECT
  838.  
  839.     /* Open the "Workbench" volume icon displayed in the root
  840.      * window.
  841.      */
  842.     ICON WINDOW root NAMES Workbench OPEN
  843.  
  844.  
  845. 8. INFO command
  846.  
  847. Purpose:
  848.  
  849.     This command is for opening the Workbench icon information
  850.     requester.
  851.  
  852. Format:
  853.  
  854.     INFO [NAME] <File, drawer or volume name>
  855.  
  856. Template:
  857.  
  858.     INFO NAME/A
  859.  
  860. Parameters:
  861.  
  862.     NAME
  863.  
  864.         Name of the file, drawer or volume to open the information
  865.         window for.
  866.  
  867. Errors:
  868.  
  869.     10 - If the named file, drawer or volume could not be found. The
  870.          error code will be placed in the WORKBENCH.LASTERROR variable.
  871.  
  872. Result:
  873.  
  874.     -
  875.  
  876. Example:
  877.  
  878.     /* Open the information window for "SYS:". */
  879.     ADDRESS workbench
  880.  
  881.     INFO NAME 'SYS:'
  882.  
  883.  
  884. 9. KEYBOARD command
  885.  
  886. Purpose:
  887.  
  888.     This command can be used to bind ARexx commands to key combinations.
  889.  
  890. Format:
  891.  
  892.     KEYBOARD [NAME] <Name of key combination> ADD|REMOVE
  893.              [KEY <Key combination>] [CMD <ARexx command>]
  894.  
  895. Template:
  896.  
  897.     KEYBOARD NAME/A,ADD/S,REMOVE/S,KEY,CMD/F
  898.  
  899. Parameters:
  900.  
  901.     NAME
  902.  
  903.         Name of the key combination to add or remove. Each key combination
  904.         must have a name with which it is associated. The name must be
  905.         unique.
  906.  
  907.     ADD
  908.  
  909.         This tells the KEYBOARD command to add a new keyboard combination.
  910.         You will also need to specify the KEY and CMD parameters.
  911.  
  912.     REMOVE
  913.  
  914.         This tells the KEYBOARD command to remove an existing keyboard
  915.         combination.
  916.  
  917.     KEY
  918.  
  919.         The keyboard combination to add; this must be in the same format
  920.         as used by the Commodities programs.
  921.  
  922.     CMD
  923.  
  924.         This is the ARexx command to bind to the keyboard combination.
  925.         The command can either be the name of an ARexx script to execute
  926.         or a short ARexx program in a single line.
  927.  
  928. Errors:
  929.  
  930.     10 - The command will fail if you tried to add a duplicate of an
  931.          existing key combination or if the key combination to remove
  932.          does not exist. The error code will be placed in the
  933.          WORKBENCH.LASTERROR variable.
  934.  
  935. Result:
  936.  
  937.     -
  938.  
  939. Example:
  940.  
  941.     /* Bind an ARexx script to the [Control]+A key combination.
  942.      * When pressed, this will cause the ARexx script by the name
  943.      * "test.wb" to be executed. ARexx will search for that program
  944.      * in the "REXX:" directory. If no "test.wb" file can
  945.      * be found, ARexx will attempt to execute a script
  946.      * by the name of "test.rexx".
  947.      */
  948.     ADDRESS workbench
  949.  
  950.     KEYBOARD ADD NAME test1 KEY '"ctrl a"' CMD 'test'
  951.  
  952.     /* Bind an ARexx script to the [Alt]+[F1] key combination.
  953.      * When pressed, this will cause a short inline program to be
  954.      * executed.
  955.      */
  956.     KEYBOARD ADD NAME test2 KEY '"alt f1"' CMD "'say 42"
  957.  
  958.     /* Bind an ARexx script to the [Shift]+[Help] key combination.
  959.      * When pressed, this will cause the Workbench "About" menu item
  960.      * to be invoked.
  961.      */
  962.     KEYBOARD ADD NAME test3 KEY '"shift help"' CMD "'MENU INVOKE WORKBENCH.ABOUT"
  963.  
  964.     /* Remove the first key combination we added above. */
  965.     KEYBOARD REMOVE NAME test1
  966.  
  967.  
  968. 10. LOCKGUI command
  969.  
  970. Purpose:
  971.  
  972.     This command will block access to all Workbench drawer windows.
  973.  
  974. Format:
  975.  
  976.     LOCKGUI
  977.  
  978. Template:
  979.  
  980.     LOCKGUI
  981.  
  982. Parameters:
  983.  
  984.     -
  985.  
  986. Errors:
  987.  
  988.     -
  989.  
  990. Result:
  991.  
  992.     -
  993.  
  994. Notes:
  995.  
  996.     It takes as many UNLOCKGUI commands as there were LOCKGUI commands
  997.     to make the Workbench drawer windows usable again. In other words,
  998.     the LOCKGUI command "nests".
  999.  
  1000. Example:
  1001.  
  1002.     /* Block access to all Workbench drawer windows. */
  1003.     ADDRESS workbench
  1004.  
  1005.     LOCKGUI
  1006.  
  1007.  
  1008. 11. MENU command
  1009.  
  1010. Purpose:
  1011.  
  1012.     This command is for invoking items of the Workbench menu, as if the user
  1013.     had selected them with the mouse and for adding/removing user menus.
  1014.  
  1015. Format:
  1016.  
  1017.     MENU [WINDOW <Window name>] [INVOKE] <Menu name>
  1018.          [NAME <Menu name>] [TITLE <Menu title>]
  1019.          [SHORTCUT <Menu shortcut>] [ADD|REMOVE]
  1020.          [CMD <ARexx command>]
  1021.  
  1022. Template:
  1023.  
  1024.     MENU WINDOW/K,INVOKE,NAME/K,TITLE/K,SHORTCUT/K,ADD/S,REMOVE/S,CMD/K/F
  1025.  
  1026. Parameters:
  1027.  
  1028.     The following set of parameters can be used solely for invoking
  1029.     menu items.
  1030.  
  1031.     WINDOW
  1032.  
  1033.         Name of the window whose menu should be invoked. This can be "ROOT"
  1034.         to work on the Workbench root window (where volume icons and AppIcons
  1035.         live), "ACTIVE" to work on the currently active Workbench window or
  1036.         the fully qualified name of a drawer window. Note that the drawer
  1037.         window must already be open.
  1038.  
  1039.         If no WINDOW parameter is specified, this command will try to operate
  1040.         on the currently active Workbench window.
  1041.  
  1042.     INVOKE
  1043.  
  1044.         Name of the menu to invoke. See below for a list of
  1045.         available menu items.
  1046.  
  1047.     The following set of parameters are for adding and removing menu items.
  1048.  
  1049.     NAME
  1050.  
  1051.         Name of the menu item to add or remove. Each menu item must have
  1052.         a name with which it is associated. The name must be unique and
  1053.         has nothing to do with the title of the item, as shown in the
  1054.         "Tools" menu.
  1055.  
  1056.     TITLE
  1057.  
  1058.         This is the text that will be used as the menu item title,
  1059.         as it will appear in the "Tools" menu. This parameter is
  1060.         required if you ADD a new menu item.
  1061.  
  1062.         Starting with workbench.library 44.1511 you can add sub menu
  1063.         items by specifying the name of the menu item to add to
  1064.         and the name of the sub menu item as the title. The two
  1065.         must be separated by a backslash character ("\"), as in
  1066.         "Menu title\Sub menu title".
  1067.  
  1068.     SHORTCUT
  1069.  
  1070.         When adding a new menu item, this will be the menu shortcut
  1071.         associated with the item. Please note that the shortcut cannot
  1072.         be longer than a single character and that it will be ignored
  1073.         if there already is an item in any of the menus which uses
  1074.         this shortcut. This parameter is optional.
  1075.  
  1076.     ADD
  1077.  
  1078.         This tells the MENU command to add a new item to the "Tools"
  1079.         menu. When adding a menu item you will also need to specify
  1080.         the NAME, TITLE and CMD parameters.
  1081.  
  1082.         Starting with V45 you can also add new menu titles beyond
  1083.         the "Tools" menu. For such menu titles, the first letter of
  1084.         the TITLE parameter must indicate the name of the title
  1085.         to add. This means for example that a title like
  1086.         "\menu title\menu item\submenu item" will a new menu title
  1087.         by the name of "menu title", and below that add a menu item
  1088.         labeled "menu item" and below that a submenu item by the
  1089.         name of "submenu item".
  1090.  
  1091.         Before the respective menu titles, items and subitems are
  1092.         added, all backslashes are removed from their labels; if
  1093.         you want to retain a single backslash, use two \\ in place
  1094.         of one; the cleanup code will only remove the first one.
  1095.  
  1096.     REMOVE
  1097.  
  1098.         This tells the MENU command to remove a menu item previously
  1099.         added via the ARexx interface. When removing a menu item you
  1100.         will also need to specify the NAME parameter.
  1101.  
  1102.     CMD
  1103.  
  1104.         This is the ARexx command to bind to the new menu item. The
  1105.         command can either be the name of an ARexx script to execute
  1106.         or a short ARexx program in a single line.
  1107.  
  1108. Menu items:
  1109.  
  1110.     WORKBENCH.BACKDROP
  1111.  
  1112.         Toggles the Workbench "Backdrop" window switch.
  1113.  
  1114.     WORKBENCH.EXECUTE
  1115.  
  1116.         Invokes the Workbench "Execute Command" requester. The user will
  1117.         be prompted to enter the command to be executed.
  1118.  
  1119.     WORKBENCH.REDRAWALL
  1120.  
  1121.         Invokes the Workbench "Redraw All" function.
  1122.  
  1123.     WORKBENCH.UPDATEALL
  1124.  
  1125.         Invokes the Workbench "Update All" function.
  1126.  
  1127.     WORKBENCH.LASTMESSAGE
  1128.  
  1129.         Redisplays the last Workbench error message.
  1130.  
  1131.     WORKBENCH.ABOUT
  1132.  
  1133.         Displays the Workbench "About..." requester.
  1134.  
  1135.     WORKBENCH.QUIT
  1136.  
  1137.         Attempts to close Workbench; this may bring up a requester the
  1138.         user will have to answer.
  1139.  
  1140.     WINDOW.NEWDRAWER
  1141.  
  1142.         Prompts the user to enter the name of a new drawer to be
  1143.         created.
  1144.  
  1145.     WINDOW.OPENPARENT
  1146.  
  1147.         If possible, this will open the parent directory of the drawer
  1148.         the command operates on.
  1149.  
  1150.     WINDOW.CLOSE
  1151.  
  1152.         If possible, this will close the drawer the command operates on.
  1153.  
  1154.     WINDOW.UPDATE
  1155.  
  1156.         This will update the drawer the command operates on, i.e. the
  1157.         contents will be reread.
  1158.  
  1159.     WINDOW.SELECTCONTENTS
  1160.  
  1161.         This will select the contents of the drawer the command operates on.
  1162.  
  1163.     WINDOW.CLEARSELECTION
  1164.  
  1165.         This unselects all icons selected in the drawer the command
  1166.         operates on.
  1167.  
  1168.     WINDOW.CLEANUPBY.COLUMN
  1169.  
  1170.         This will sort the contents of the drawer and place the icons
  1171.         in columns.
  1172.  
  1173.     WINDOW.CLEANUPBY.NAME
  1174.  
  1175.         This will sort the contents of the drawer by name and place
  1176.         the icons in rows.
  1177.  
  1178.     WINDOW.CLEANUPBY.DATE
  1179.  
  1180.         This will sort the contents of the drawer by date and place
  1181.         the icons in rows.
  1182.  
  1183.     WINDOW.CLEANUPBY.SIZE
  1184.  
  1185.         This will sort the contents of the drawer by size and place
  1186.         the icons in rows.
  1187.  
  1188.     WINDOW.CLEANUPBY.TYPE
  1189.  
  1190.         This will sort the contents of the drawer by type and place
  1191.         the icons in rows.
  1192.  
  1193.     WINDOW.RESIZETOFIT
  1194.  
  1195.         This will resize the drawer window, trying to make it just as
  1196.         large as to allow all its icons to fit.
  1197.  
  1198.     WINDOW.SNAPSHOT.WINDOW
  1199.  
  1200.         This will snapshot the drawer window, but none of its contents.
  1201.  
  1202.     WINDOW.SNAPSHOT.ALL
  1203.  
  1204.         This will snapshot the drawer window and its contents.
  1205.  
  1206.     WINDOW.SHOW.ONLYICONS
  1207.  
  1208.         This will change the display mode of the drawer to show only
  1209.         files and drawers which have icons attached.
  1210.  
  1211.     WINDOW.SHOW.ALLFILES
  1212.  
  1213.         This will change the display mode of the drawer to show all
  1214.         files and drawers, regardless of whether they have icons
  1215.         attached or not.
  1216.  
  1217.     WINDOW.VIEWBY.ICON
  1218.  
  1219.         This will change the display mode of the drawer to show
  1220.         its contents as icons.
  1221.  
  1222.     WINDOW.VIEWBY.NAME
  1223.  
  1224.         This will change the display mode of the drawer to show
  1225.         its contents in textual format, sorted by name.
  1226.  
  1227.     WINDOW.VIEWBY.DATE
  1228.  
  1229.         This will change the display mode of the drawer to show
  1230.         its contents in textual format, sorted by date.
  1231.  
  1232.     WINDOW.VIEWBY.SIZE
  1233.  
  1234.         This will change the display mode of the drawer to show
  1235.         its contents in textual format, sorted by size.
  1236.  
  1237.     WINDOW.VIEWBY.TYPE
  1238.  
  1239.         This will change the display mode of the drawer to show
  1240.         its contents in textual format, sorted by type.
  1241.  
  1242.     ICONS.OPEN
  1243.  
  1244.         This will open the currently selected icons. Workbench
  1245.         may bring up a requester in case project icons are found
  1246.         which lack a default tool.
  1247.  
  1248.     ICONS.COPY
  1249.  
  1250.         This will duplicate the currently selected icons.
  1251.  
  1252.     ICONS.RENAME
  1253.  
  1254.         This will prompt the user to choose a new name for each
  1255.         currently selected icon.
  1256.  
  1257.     ICONS.INFORMATION
  1258.  
  1259.         This will open the information window for every currently
  1260.         selected icon.
  1261.  
  1262.     ICONS.SNAPSHOT
  1263.  
  1264.         This will lock the position of every currently selected icon.
  1265.  
  1266.     ICONS.UNSNAPSHOT
  1267.  
  1268.         This will unlock the position of every currently selected icon.
  1269.  
  1270.     ICONS.LEAVEOUT
  1271.  
  1272.         This will permanently put all currently selected icons on the
  1273.         Workbench root window.
  1274.  
  1275.     ICONS.PUTAWAY
  1276.  
  1277.         This will move all currently selected icons out of the root
  1278.         window and put them back into the drawers they belong.
  1279.  
  1280.     ICONS.DELETE
  1281.  
  1282.         This will cause all currently selected files to be deleted,
  1283.         provided the user confirms this action first.
  1284.  
  1285.     ICONS.FORMATDISK
  1286.  
  1287.         This will invoke the "Format" command on every currently selected
  1288.         disk icon. This will not format the disks immediately. The user
  1289.         will have to confirm this action first.
  1290.  
  1291.     ICONS.EMPTYTRASH
  1292.  
  1293.         With a trashcan icon selected, this will empty it.
  1294.  
  1295.     TOOLS.RESETWB
  1296.  
  1297.         This will close and reopen all Workbench windows.
  1298.  
  1299.     The HELP command will provide a complete list of menu items that can be
  1300.     invoked. Depending on the state of each menu item (e.g. the "Open" menu
  1301.     item will be disabled if no icon is currently selected) the MENU command
  1302.     can silently fail to invoke the item you had in mind.
  1303.  
  1304. Errors:
  1305.  
  1306.     10 - If the named window cannot be found, none of the Workbench
  1307.          windows are currently active and the command was set to
  1308.          work on the currently active Workbench window. The command can
  1309.          also fail if you tried to add a duplicate of an existing
  1310.          menu item or if the menu item to remove does not exist.
  1311.          The error code will be placed in the WORKBENCH.LASTERROR
  1312.          variable.
  1313.  
  1314. Result:
  1315.  
  1316.     -
  1317.  
  1318. Example:
  1319.  
  1320.     /* Invoke the "About" menu. */
  1321.     ADDRESS workbench
  1322.     OPTIONS RESULTS
  1323.  
  1324.     MENU WINDOW root INVOKE WORKBENCH.ABOUT
  1325.  
  1326.     /* Add an item to the "Tools" menu; selecting it
  1327.      * will cause the ARexx script by the name "test.wb"
  1328.      * to be executed. ARexx will search for that program
  1329.      * in the "REXX:" directory.
  1330.      */
  1331.     MENU ADD NAME test1 TITLE '"Execute a script"' SHORTCUT '!' CMD 'test'
  1332.  
  1333.     /* Add an item to the "Tools" menu; selecting it
  1334.      * will cause a short inline program to be executed.
  1335.      */
  1336.     MENU ADD NAME test2 TITLE '"Short inline program"' CMD "'say 42"
  1337.  
  1338.     /* Add an item to the "Tools" menu; selecting it
  1339.      * will cause the Workbench "About" menu item to be invoked.
  1340.      */
  1341.     MENU ADD NAME test3 TITLE '"About..."' CMD "'MENU INVOKE WORKBENCH.ABOUT"
  1342.  
  1343.     /* Add a new item to the "Tools" menu, then add two sub items
  1344.      * to the new item. Note that this feature requires workbench.library
  1345.      * 44.1511 or higher to work.
  1346.      */
  1347.     GETATTR APPLICATION.VERSION
  1348.     PARSE VAR RESULT ver '.' rev
  1349.     IF ((ver > 44) | ((ver == 44) & (rev >= 1511))) THEN DO
  1350.        MENU ADD NAME test4 TITLE '"Say something\Hello"' CMD "'say hello";
  1351.        MENU ADD NAME test5 TITLE '"Say something\World"' CMD "'say world";
  1352.     END;
  1353.  
  1354.     /* Add a new menu title, and to that title add one single item. Note
  1355.      * that this feature requires workbench.library V45 or higher to work.
  1356.      */
  1357.     GETATTR APPLICATION.VERSION
  1358.     PARSE VAR RESULT ver '.' .
  1359.     IF (ver >= 45) THEN DO
  1360.        MENU ADD NAME test6 TITLE '"\New title\Say something\Hello"' CMD "'say hello";
  1361.     END;
  1362.  
  1363.     /* Remove the first menu item we added above. */
  1364.     MENU REMOVE NAME test1
  1365.  
  1366.  
  1367. 12. MOVEWINDOW command
  1368.  
  1369. Purpose:
  1370.  
  1371.     This command will attempt to change the position of a window.
  1372.  
  1373. Format:
  1374.  
  1375.     MOVEWINDOW [WINDOW] <ROOT|ACTIVE|LASTACTIVE|Drawer name>
  1376.                [[LEFTEDGE] <new left edge position>]
  1377.                [[TOPEDGE] <new top edge position>]
  1378.  
  1379. Template:
  1380.  
  1381.     MOVEWINDOW WINDOW,LEFTEDGE/N,TOPEDGE/N
  1382.  
  1383. Parameters:
  1384.  
  1385.     WINDOW
  1386.  
  1387.         Either "ROOT" to move the Workbench root window (where volume icons
  1388.         and AppIcons live), "ACTIVE" to move the currently active Workbench
  1389.         window or the fully qualified name of a drawer window to change. Note
  1390.         that the drawer window must already be open.
  1391.  
  1392.         If no WINDOW parameter is specified, this command will try to operate
  1393.         on the currently active Workbench window.
  1394.  
  1395.     LEFTEDGE
  1396.  
  1397.         New left edge window position.
  1398.  
  1399.     TOPEDGE
  1400.  
  1401.         New top edge window position.
  1402.  
  1403. Errors:
  1404.  
  1405.     10 - If the named window cannot be moved; this can also happen if you
  1406.          specified "ACTIVE" as the window name and none of the Workbench
  1407.          windows is currently active. The error code will be placed in the
  1408.          WORKBENCH.LASTERROR variable.
  1409.  
  1410. Result:
  1411.  
  1412.     -
  1413.  
  1414. Notes:
  1415.  
  1416.     If you choose to have a window moved that is neither the root nor the
  1417.     active window you must make sure that the window name is given as a fully
  1418.     qualified path name. For example "Work:" is a fully qualified name, and so
  1419.     is "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A
  1420.     fully qualified name always contains the name of an assignment, a volume
  1421.     or a device.
  1422.  
  1423. Example:
  1424.  
  1425.     /* Move the root window to position 10,30. */
  1426.     ADDRESS workbench
  1427.  
  1428.     MOVEWINDOW root LEFTEDGE 10 TOPEDGE 30
  1429.  
  1430.     /* Move the currently active window. */
  1431.     MOVEWINDOW active 20 40
  1432.  
  1433.  
  1434. 13. NEWDRAWER command
  1435.  
  1436. Purpose:
  1437.  
  1438.     This command is for creating new drawers.
  1439.  
  1440. Format:
  1441.  
  1442.     NEWDRAWER [NAME] <Name of drawer to create>
  1443.  
  1444. Template:
  1445.  
  1446.     NEWDRAWER NAME/A
  1447.  
  1448. Parameters:
  1449.  
  1450.     NAME
  1451.  
  1452.         Name of the drawer to be created.
  1453.  
  1454. Errors:
  1455.  
  1456.     10 - If the named drawer could not be created.
  1457.  
  1458. Result:
  1459.  
  1460.     -
  1461.  
  1462. Notes:
  1463.  
  1464.     The drawer name given must be an absolute path, such as in
  1465.     "RAM:Empty". A relative path, such as "/fred/barney" will
  1466.     not work.
  1467.  
  1468. Example:
  1469.  
  1470.     /* Create a drawer by the name of "Empty" in the RAM disk. */
  1471.     ADDRESS workbench
  1472.  
  1473.     NEWDRAWER 'RAM:Empty'
  1474.  
  1475.  
  1476. 14. RENAME command
  1477.  
  1478. Purpose:
  1479.  
  1480.     This command is for renaming files, drawers and volumes.
  1481.  
  1482. Format:
  1483.  
  1484.     RENAME [OLDNAME] <Name of file/drawer/volume to rename>
  1485.            [NEWNAME] <New name of the file/drawer/volume>
  1486.  
  1487. Template:
  1488.  
  1489.     RENAME OLDNAME/A,NEWNAME/A
  1490.  
  1491. Parameters:
  1492.  
  1493.     OLDNAME
  1494.  
  1495.         Name of the file/drawer/volume to be renamed. This must
  1496.         be an absolute path, such as in "RAM:Empty". A relative
  1497.         path, such as "/fred/barney", will not work.
  1498.  
  1499.     NEWNAME
  1500.  
  1501.         The new name to assign to the file/drawer/volume. This
  1502.         must not be an absolute or relative path. For example,
  1503.         "wilma" is valid new name, "/wilma" or "wilma:" would
  1504.         be invalid names.
  1505.  
  1506. Errors:
  1507.  
  1508.     10 - If the object cannot be renamed.
  1509.  
  1510. Result:
  1511.  
  1512.     -
  1513.  
  1514. Notes:
  1515.  
  1516.     The RENAME command does not work like for example the AmigaDOS
  1517.     "Rename" command. For example, "RENAME 'ram:empty' 'newname'"
  1518.     will rename the file 'RAM:empty' to 'RAM:newname'.
  1519.  
  1520. Example:
  1521.  
  1522.     /* Rename a drawer by the name of "Old" in the RAM disk to "New". */
  1523.     ADDRESS workbench
  1524.  
  1525.     RENAME 'RAM:Old' 'New'
  1526.  
  1527.  
  1528. 15. RX command
  1529.  
  1530. Purpose:
  1531.  
  1532.     This command is for executing ARexx scripts and commands.
  1533.  
  1534. Format:
  1535.  
  1536.     RX [CONSOLE] [ASYNC] [CMD] <Command to execute>
  1537.  
  1538. Template:
  1539.  
  1540.     RX CONSOLE/S,ASYNC/S,CMD/A/F
  1541.  
  1542. Parameters:
  1543.  
  1544.     CONSOLE
  1545.  
  1546.         This switch indicates that a console (for default I/O)
  1547.         is needed.
  1548.  
  1549.     ASYNC
  1550.  
  1551.         This switch indicates that the command should be run
  1552.         asynchronously, i.e. the "RX" command will return as
  1553.         soon as ARexx has been instructed to run the command
  1554.         you specified. Otherwise, the "RX" command will wait
  1555.         for the specified ARexx command to complete execution.
  1556.  
  1557.     COMMAND
  1558.  
  1559.         This is the name of the ARexx program to execute.
  1560.  
  1561. Errors:
  1562.  
  1563.     10 - If the given ARexx program could not be executed.
  1564.  
  1565. Result:
  1566.  
  1567.     -
  1568.  
  1569. Example:
  1570.  
  1571.     /* Execute an ARexx program by the name of 'test.wb';
  1572.      * its output should be sent to a console window.
  1573.      */
  1574.     ADDRESS workbench
  1575.  
  1576.     RX CONSOLE CMD 'test.wb'
  1577.  
  1578.  
  1579. 16. SIZEWINDOW command
  1580.  
  1581. Purpose:
  1582.  
  1583.     This command will attempt to change the size of a window.
  1584.  
  1585. Format:
  1586.  
  1587.     SIZEWINDOW [WINDOW] <ROOT|ACTIVE|LASTACTIVE|Drawer name>
  1588.                [[WIDTH] <new window width>]
  1589.                [[HEIGHT] <new window height>]
  1590.  
  1591. Template:
  1592.  
  1593.     SIZEWINDOW WINDOW,WIDTH/N,HEIGHT/N
  1594.  
  1595. Parameters:
  1596.  
  1597.     WINDOW
  1598.  
  1599.         Either "ROOT" to resize the Workbench root window (where volume icons
  1600.         and AppIcons live), "ACTIVE" to resize the currently active Workbench
  1601.         window or the fully qualified name of a drawer window to change. Note
  1602.         that the drawer window must already be open.
  1603.  
  1604.         If no WINDOW parameter is specified, this command will try to operate
  1605.         on the currently active Workbench window.
  1606.  
  1607.     WIDTH
  1608.  
  1609.         New window width.
  1610.  
  1611.     HEIGHT
  1612.  
  1613.         New window height.
  1614.  
  1615. Errors:
  1616.  
  1617.     10 - If the named window cannot be resized; this can also happen if you
  1618.          specified "ACTIVE" as the window name and none of the Workbench
  1619.          windows is currently active. The error code will be placed in the
  1620.          WORKBENCH.LASTERROR variable.
  1621.  
  1622. Result:
  1623.  
  1624.     -
  1625.  
  1626. Notes:
  1627.  
  1628.     If you choose to have a window resized that is neither the root nor the
  1629.     active window you must make sure that the window name is given as a fully
  1630.     qualified path name. For example "Work:" is a fully qualified name, and so
  1631.     is "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A
  1632.     fully qualified name always contains the name of an assignment, a volume
  1633.     or a device.
  1634.  
  1635. Example:
  1636.  
  1637.     /* Change the root window size to 200×100 pixels. */
  1638.     ADDRESS workbench
  1639.  
  1640.     SIZEWINDOW root 30 WIDTH 200 HEIGHT 100
  1641.  
  1642.     /* Resize the currently active window. */
  1643.     SIZEWINDOW active 200 100
  1644.  
  1645.  
  1646. 17. UNLOCKGUI command
  1647.  
  1648. Purpose:
  1649.  
  1650.     This command will allow access to all Workbench drawer windows locked
  1651.     with the LOCKGUI command.
  1652.  
  1653. Format:
  1654.  
  1655.     UNLOCKGUI
  1656.  
  1657. Template:
  1658.  
  1659.     UNLOCKGUI
  1660.  
  1661. Parameters:
  1662.  
  1663.     -
  1664.  
  1665. Errors:
  1666.  
  1667.     -
  1668.  
  1669. Result:
  1670.  
  1671.     -
  1672.  
  1673. Notes:
  1674.  
  1675.     It takes as many UNLOCKGUI commands as there were LOCKGUI commands
  1676.     to make the Workbench drawer windows usable again. In other words,
  1677.     the LOCKGUI command "nests".
  1678.  
  1679. Example:
  1680.  
  1681.     /* Reallow access to all Workbench drawer windows. */
  1682.     ADDRESS workbench
  1683.  
  1684.     UNLOCKGUI
  1685.  
  1686.  
  1687. 18. UNZOOMWINDOW command
  1688.  
  1689. Purpose:
  1690.  
  1691.     This command will attempt return a window to its original position and
  1692.     dimensions.
  1693.  
  1694. Format:
  1695.  
  1696.     UNZOOMWINDOW [WINDOW] <ROOT|ACTIVE|LASTACTIVE|Drawer name>
  1697.  
  1698. Template:
  1699.  
  1700.     UNZOOMWINDOW WINDOW
  1701.  
  1702. Parameters:
  1703.  
  1704.     WINDOW
  1705.  
  1706.         Name of the window to operate on. "ROOT" will use the Workbench root
  1707.         window (where volume icons and AppIcons live), "ACTIVE" will use
  1708.         the currently active Workbench window. Any other fully qualified
  1709.         path name will use the drawer window corresponding to the path.
  1710.         If no WINDOW parameter is specified, this command will try to operate
  1711.         on the currently active Workbench window.
  1712.  
  1713. Errors:
  1714.  
  1715.     10 - If the named window cannot be found. The error code will be
  1716.          placed in the WORKBENCH.LASTERROR variable.
  1717.  
  1718. Result:
  1719.  
  1720.     -
  1721.  
  1722. Example:
  1723.  
  1724.     /* Change the root window. */
  1725.     ADDRESS workbench
  1726.  
  1727.     UNZOOMWINDOW root
  1728.  
  1729.  
  1730. 19. VIEW command
  1731.  
  1732. Purpose:
  1733.  
  1734.     This command will change the position of the viewable display area of a
  1735.     window.
  1736.  
  1737. Format:
  1738.  
  1739.     VIEW [WINDOW] <ROOT|ACTIVE|LASTACTIVE|Drawer name>
  1740.          [PAGE|PIXEL] [UP|DOWN|LEFT|RIGHT]
  1741.  
  1742. Template:
  1743.  
  1744.     VIEW WINDOW,PAGE/S,PIXEL/S,UP/S,DOWN/S,LEFT/S,RIGHT/S
  1745.  
  1746. Parameters:
  1747.  
  1748.     WINDOW
  1749.  
  1750.         Either "ROOT" to change the Workbench root window view (where volume
  1751.         icons and AppIcons live), "ACTIVE" to change the currently active
  1752.         Workbench window view or the fully qualified name of a drawer window
  1753.         to change. Note that the drawer window must already be open.
  1754.  
  1755.         If no WINDOW parameter is specified, this command will try to operate
  1756.         on the currently active Workbench window.
  1757.  
  1758.     UP
  1759.  
  1760.         Move the view up by about 1/8 of the window height. If PAGE is
  1761.         specified, moves the view up by a whole page. If PIXEL is specified,
  1762.         moves the view up by a single pixel.
  1763.  
  1764.     DOWN
  1765.  
  1766.         Move the view down by about 1/8 of the window height. If PAGE is
  1767.         specified, moves the view down by a whole page. If PIXEL is
  1768.         specified, moves the view down by a single pixel.
  1769.  
  1770.     LEFT
  1771.  
  1772.         Move the view left by about 1/8 of the window height. If PAGE is
  1773.         specified, moves the view left by a whole page. If PIXEL is
  1774.         specified, moves the view left by a single pixel.
  1775.  
  1776.     RIGHT
  1777.  
  1778.         Move the view right by about 1/8 of the window height. If PAGE is
  1779.         specified, moves the view right by a whole page. If PIXEL is
  1780.         specified, moves the view right by a single pixel.
  1781.  
  1782. Errors:
  1783.  
  1784.     10 - If the named window view cannot be changed; this can also happen if you
  1785.          specified "ACTIVE" as the window name and none of the Workbench
  1786.          windows is currently active. The error code will be placed in the
  1787.          WORKBENCH.LASTERROR variable.
  1788.  
  1789. Result:
  1790.  
  1791.     -
  1792.  
  1793. Notes:
  1794.  
  1795.     If you choose to have a window view changed that is neither the root nor
  1796.     the active window you must make sure that the window name is given as a
  1797.     fully qualified path name. For example "Work:" is a fully qualified name,
  1798.     and so is "SYS:Utilities". "Devs/Printers" would not be a fully qualified
  1799.     name. A fully qualified name always contains the name of an assignment, a
  1800.     volume or a device.
  1801.  
  1802.     To find out about a window's current view position, use the GETATTR
  1803.     command and query the window's WINDOW.VIEW.LEFT and WINDOW.VIEW.TOP
  1804.     attributes.
  1805.  
  1806. Example:
  1807.  
  1808.     /* Change the root window view; move it up by a whole page. */
  1809.     ADDRESS workbench
  1810.  
  1811.     VIEW root PAGE UP
  1812.  
  1813.  
  1814. 20. WINDOW command
  1815.  
  1816. Purpose:
  1817.  
  1818.     This command will change, open, close or snapshot windows.
  1819.  
  1820. Format:
  1821.  
  1822.     WINDOW [WINDOWS] <Window name> .. <Window name>
  1823.            [OPEN|CLOSE] [SNAPSHOT] [ACTIVATE] [MIN|MAX]
  1824.            [FRONT|BACK] [CYCLE PREVIOUS|NEXT]
  1825.  
  1826. Template:
  1827.  
  1828.     WINDOW WINDOWS/M/A,OPEN/S,CLOSE/S,SNAPSHOT/S,ACTIVATE/S,MIN/S,MAX/S,
  1829.            FRONT/S,BACK/S,CYCLE/K
  1830.  
  1831. Parameters:
  1832.  
  1833.     WINDOWS
  1834.  
  1835.         Names of the windows to operate on. This can be "ROOT" to for the
  1836.         Workbench root window (where volume icons and AppIcons live),
  1837.         "ACTIVE" for the currently active Workbench window or the fully
  1838.         qualified name of a drawer window.
  1839.  
  1840.     OPEN
  1841.  
  1842.         Attempt to open the specified windows.
  1843.  
  1844.     CLOSE
  1845.  
  1846.         Close the specified windows. Note that if a window is closed no
  1847.         further operations (such as SNAPSHOT, ACTIVATE, etc.) can be
  1848.         performed on it.
  1849.  
  1850.     SNAPSHOT
  1851.  
  1852.         Snapshot the sizes and positions of the specified windows.
  1853.  
  1854.     ACTIVATE
  1855.  
  1856.         Activate the specified windows. With multiple windows to activate,
  1857.         only one window will wind up as the active one. Commonly, this will
  1858.         be the last window in the list.
  1859.  
  1860.     MIN
  1861.  
  1862.         Resize the windows to their minimum dimensions.
  1863.  
  1864.     MAX
  1865.  
  1866.         Resize the windows to their maximum dimensions.
  1867.  
  1868.     FRONT
  1869.  
  1870.         Move the windows into the foreground.
  1871.  
  1872.     BACK
  1873.  
  1874.         Move the windows into the background.
  1875.  
  1876.     CYCLE
  1877.  
  1878.         This command operates on the currently active drawer window.
  1879.         You can specify either "PREVIOUS", to activate the previous
  1880.         drawer window in the list, or "NEXT", to activate the next
  1881.         following drawer window in the list.
  1882.  
  1883. Errors:
  1884.  
  1885.     10 - If the named windows cannot be opened or operated on; this can
  1886.          also happen if you specified "ACTIVE" as a window name and none
  1887.          of the Workbench windows is currently active. The error code will
  1888.          be placed in the WORKBENCH.LASTERROR variable.
  1889.  
  1890. Result:
  1891.  
  1892.     -
  1893.  
  1894. Notes:
  1895.  
  1896.     If you choose to have a window operated on that is neither the root nor
  1897.     the active window you must make sure that the window name is given as a
  1898.     fully qualified path name. For example "Work:" is a fully qualified name,
  1899.     and so is "SYS:Utilities". "Devs/Printers" would not be a fully qualified
  1900.     name. A fully qualified name always contains the name of an assignment, a
  1901.     volume or a device.
  1902.  
  1903. Example:
  1904.  
  1905.     /* Open the "Work:" drawer. */
  1906.     ADDRESS workbench
  1907.  
  1908.     WINDOW 'Work:' OPEN
  1909.  
  1910.     /* Activate the root window. */
  1911.     WINDOW root ACTIVATE
  1912.  
  1913.  
  1914. 21. WINDOWTOBACK command
  1915.  
  1916. Purpose:
  1917.  
  1918.     This command will push a window into the background.
  1919.  
  1920. Format:
  1921.  
  1922.     WINDOWTOBACK [WINDOW] <ROOT|ACTIVE|LASTACTIVE|Drawer name>
  1923.  
  1924. Template:
  1925.  
  1926.     WINDOWTOBACK WINDOW
  1927.  
  1928. Parameters:
  1929.  
  1930.     WINDOW
  1931.  
  1932.         "ROOT" to push the the Workbench root window (where volume icons and
  1933.         AppIcons live) into to the background, "ACTIVE" to push the currently
  1934.         active Workbench window into the background or the fully qualified
  1935.         name of a drawer window. Note that the drawer window must already be
  1936.         open.
  1937.  
  1938.         If no WINDOW parameter is specified, this command will try to operate
  1939.         on the currently active Workbench window.
  1940.  
  1941. Errors:
  1942.  
  1943.     10 - If the named window cannot be found. The error code will be
  1944.          placed in the WORKBENCH.LASTERROR variable.
  1945.  
  1946. Result:
  1947.  
  1948.     -
  1949.  
  1950. Notes:
  1951.  
  1952.     If you choose to have a window pushed into the background that is not the
  1953.     root window or the currently active window you must make sure that the
  1954.     window name is given as a fully qualified path name. For example "Work:"
  1955.     is a fully qualified name, and so is "SYS:Utilities". "Devs/Printers"
  1956.     would not be a fully qualified name. A fully qualified name always
  1957.     contains the name of an assignment, a volume or a device.
  1958.  
  1959. Example:
  1960.  
  1961.     /* Push the root window into the background. */
  1962.     ADDRESS workbench
  1963.  
  1964.     WINDOWTOBACK root
  1965.  
  1966.  
  1967. 22. WINDOWTOFRONT command
  1968.  
  1969. Purpose:
  1970.  
  1971.     This command will bring a window to the foreground.
  1972.  
  1973. Format:
  1974.  
  1975.     WINDOWTOFRONT [WINDOW] <ROOT|ACTIVE|LASTACTIVE|Drawer name>
  1976.  
  1977. Template:
  1978.  
  1979.     WINDOWTOFRONT WINDOW
  1980.  
  1981. Parameters:
  1982.  
  1983.     WINDOW
  1984.  
  1985.         "ROOT" to bring the the Workbench root window (where volume icons and
  1986.         AppIcons live) to the foreground, "ACTIVE" to bring the currently
  1987.         active Workbench window to the foreground or the fully qualified name
  1988.         of a drawer window. Note that the drawer window must already be open.
  1989.  
  1990.         If no WINDOW parameter is specified, this command will try to operate
  1991.         on the currently active Workbench window.
  1992.  
  1993. Errors:
  1994.  
  1995.     10 - If the named window cannot be found. The error code will be
  1996.          placed in the WORKBENCH.LASTERROR variable.
  1997.  
  1998. Result:
  1999.  
  2000.     -
  2001.  
  2002. Notes:
  2003.  
  2004.     If you choose to have a window brought to the foreground that is not the
  2005.     root window or the currently active window you must make sure that the
  2006.     window name is given as a fully qualified path name. For example "Work:"
  2007.     is a fully qualified name, and so is "SYS:Utilities". "Devs/Printers"
  2008.     would not be a fully qualified name. A fully qualified name always
  2009.     contains the name of an assignment, a volume or a device.
  2010.  
  2011. Example:
  2012.  
  2013.     /* Bring the root window to the foreground. */
  2014.     ADDRESS workbench
  2015.  
  2016.     WINDOWTOFRONT root
  2017.  
  2018.  
  2019. 23. ZOOMWINDOW command
  2020.  
  2021. Purpose:
  2022.  
  2023.     This command will change a window to alternate position and
  2024.     dimensions.
  2025.  
  2026. Format:
  2027.  
  2028.     ZOOMWINDOW [WINDOW] <ROOT|ACTIVE|LASTACTIVE|Drawer name>
  2029.  
  2030. Template:
  2031.  
  2032.     ZOOMWINDOW WINDOW
  2033.  
  2034. Parameters:
  2035.  
  2036.     WINDOW
  2037.  
  2038.         Name of the window to operate on. "ROOT" will use the Workbench root
  2039.         window (where volume icons and AppIcons live), "ACTIVE" will use
  2040.         the currently active Workbench window. Any other fully qualified
  2041.         path name will use the drawer window corresponding to the path.
  2042.         If no WINDOW parameter is specified, this command will try to operate
  2043.         on the currently active Workbench window.
  2044.  
  2045. Errors:
  2046.  
  2047.     10 - If the named window cannot be found. The error code will be
  2048.          placed in the WORKBENCH.LASTERROR variable.
  2049.  
  2050. Result:
  2051.  
  2052.     -
  2053.  
  2054. Example:
  2055.  
  2056.     /* Change the root window. */
  2057.     ADDRESS workbench
  2058.  
  2059.     ZOOMWINDOW root
  2060.