The Workbench ARexx interface
=============================

Workbench acts as an ARexx host under the name of "WORKBENCH". It supports
a number of commands as will be described below. Note that for the ARexx
interface to work, rexxsyslib.library must be installed (this library is
part of a regular Workbench installation) and the RexxMast program must
have been started.


1. ACTIVATEWINDOW command

Purpose:

    This command will attempt to make a window the active one.

Format:

    ACTIVATEWINDOW [WINDOW] <ROOT|Drawer name>

Template:

    ACTIVATEWINDOW WINDOW

Parameters:

    WINDOW

        Either "ROOT" to activate the Workbench root window (where volume
        icons and AppIcons live) or the fully qualified name of a drawer
        window to activate. Note that the drawer window must already be open.

        If no WINDOW parameter is specified, this command will try to operate
        on the currently active Workbench window.

Errors:

    10 - If the named window cannot be activated. The error code will be
         placed in the WORKBENCH.LASTERROR variable.

Result:

-

Notes:

    If you choose to have a window activated that is not the root window you
    must make sure that the window name is given as a fully qualified path
    name. For example "Work:" is a fully qualified name, and so is
    "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A
    fully qualified name always contains the name of an assignment, a volume
    or a device.

Example:

    /* Activate the root window. */
    ADDRESS workbench

    ACTIVATEWINDOW root

    /* Activate the "Work:" partition's window. */
    ACTIVATEWINDOW 'Work:'


2. CHANGEWINDOW command

Purpose:

    This command will attempt to change the size and the position of a window.

Format:

    CHANGEWINDOW [WINDOW] <ROOT|ACTIVE|Drawer name>
                 [LEFTEDGE <new left edge position>]
                 [TOPEDGE <new top edge position>]
                 [WIDTH <new window width>]
                 [HEIGHT <new window height>]

Template:

    CHANGEWINDOW WINDOW,LEFTEDGE/N,TOPEDGE/N,WIDTH/N,HEIGHT/N

Parameters:

    WINDOW

        Either "ROOT" to resize/move the Workbench root window (where volume
        icons and AppIcons live), "ACTIVE" to change the currently active
        Workbench window or the fully qualified name of a drawer window to
        change. Note that the drawer window must already be open.

        If no WINDOW parameter is specified, this command will try to operate
        on the currently active Workbench window.

    LEFTEDGE

        New left edge window position.

    TOPEDGE

        New top edge window position.

    WIDTH

       New window width.

    HEIGHT

       New window height.

Errors:

    10 - If the named window cannot be changed; this can also happen if you
         specified "ACTIVE" as the window name and none of the Workbench
         windows is currently active. The error code will be placed in the
         WORKBENCH.LASTERROR variable.

Result:

    -

Notes:

    If you choose to have a window changed that is neither the root nor the
    active window you must make sure that the window name is given as a fully
    qualified path name. For example "Work:" is a fully qualified name, and so
    is "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A
    fully qualified name always contains the name of an assignment, a volume
    or a device.

Example:

    /* Change the root window; move it to position 10,30.
     * and change its size to 200100 pixels.
     */
    ADDRESS workbench

    CHANGEWINDOW root LEFTEDGE 10 TOPEDGE 30 WIDTH 200 HEIGHT 100

    /* Change the currently active window. */
    CHANGEWINDOW active 20 40 200 100


3. DELETE command

Purpose:

    This command is for deleting files and drawers (and their contents).

Format:

    DELETE [NAME] <File or drawer name> [ALL]

Template:

    DELETE NAME/A,ALL/S

Parameters:

    NAME

        Name of the file or drawer or volume to delete.

    ALL

        If the object in question is a drawer, attempt to delete
        the contents of the drawer as well as the drawer itself.
        If this option is not specified, the DELETE command will
        only attempt to delete the drawer itself, which may fail
        if the drawer is not yet empty.

Errors:

    10 - If the named file, drawer or volume could not be found or
         could not be deleted.

Result:

    -

Notes:

    The file name given must be an absolute path, such as in
    "RAM:Empty". A relative path, such as "/fred/barney" will
    not work.

Example:

    /* Delete the contents of the drawer "RAM:Empty". */
    ADDRESS workbench

    DELETE 'RAM:Empty' ALL


4. FAULT command

Purpose:

    This command will return a human readable explanation corresponding
    to an error code.

Format:

    FAULT [CODE] <Error code>

Template:

    FAULT CODE/A/N

Parameters:

    CODE

        Error code to return a human readable explanation for.

Errors:

    -

Result:

    -

Example:

    /* Query the error message corresponding to error code #205. */
    ADDRESS workbench
    OPTIONS RESULTS

    FAULT 205
    SAY result


5. GETATTR command

Purpose:

    This command will retrieve information from the Workbench database, such
    the names of the drawers currently open and the icons currently selected.

Format:

    GETATTR [OBJECT] <Object name> [NAME <Item name>]
            [STEM <Name of stem variable>] [VAR <Variable name>]

Template:

    GETATTR OBJECT/A,NAME/K,STEM/K,VAR/K

Parameters:

    OBJECT

        Name of the database entry to retrieve. For a list of valid
        entries see below.

    NAME

        For some datatabase entries further information is required
        to identify the data to retrieve. This is when you will need
        to provide a name.

    STEM

        If you request more than one database entry you will need to
        provide a variable to store the information in. For an example
        of its use, see below.

    VAR

        If you want the queried information to be stored in a specific
        variable (other than the RESULT variable), this is where you
        provive its name.

Attributes:

    You can obtain information on the following attributes:

    APPLICATION.VERSION

        Version number of "workbench.library".

    APPLICATION.SCREEN

        Name of the public screen Workbench uses.

    APPLICATION.AREXX

        Name of the Workbench ARexx port.

    APPLICATION.LASTERROR

        Number of the last error caused by the ARexx interface.

    APPLICATION.ICONBORDER

        Sizes of the icon borders, returned as four numbers separated
        by blank spaces, e.g. "4 3 4 3". The four numbers represent
        the left border width, the top border height, the right border
        width and the bottom border height (in exactly that order).

    APPLICATION.FONT.SCREEN.NAME

        Name of the Workbench screen font.

    APPLICATION.FONT.SCREEN.WIDTH
    APPLICATION.FONT.SCREEN.HEIGHT

        Size of a single character of the Workbench screen font. Please
        note that since the font in question may be proportional spaced
        the width information may be of little value. To measure the
        accurate pixel width of a text in reference to the font, use
        the .SIZE attribute.

    APPLICATION.FONT.SCREEN.SIZE

        Size of a text, measured in pixels, in reference to the screen
        font. The text to measure must be provided with the NAME
        parameter of the GETATTR command.

    APPLICATION.FONT.ICON.NAME

        Name of the Workbench icon font.

    APPLICATION.FONT.ICON.WIDTH
    APPLICATION.FONT.ICON.HEIGHT

        Size of a single character of the Workbench icon font. Please
        note that since the font in question may be proportional spaced
        the width information may be of little value. To measure the
        accurate pixel width of a text in reference to the font, use
        the .SIZE attribute.

    APPLICATION.FONT.ICON.SIZE

        Size of a text, measured in pixels, in reference to the icon
        font. The text to measure must be provided with the NAME
        parameter of the GETATTR command.

    APPLICATION.FONT.SYSTEM.NAME

        Name of the system font.

    APPLICATION.FONT.SYSTEM.WIDTH
    APPLICATION.FONT.SYSTEM.HEIGHT

        Size of a single character of the system font.

    APPLICATION.FONT.SYSTEM.SIZE

        Size of a text, measured in pixels, in reference to the
        system font. The text to measure must be provided with the
        NAME parameter of the GETATTR command.


    WINDOWS.COUNT

        Number of the drawer windows currently open. This can be 0.

    WINDOWS.0 .. WINDOWS.N

        Names of the windows currently open.

    WINDOWS.ACTIVE

        Name of the currently active Workbench window; this will
        be "" if none of Workbench's windows is currently active.


    KEYCOMMANDS.COUNT

        Number of keyboard commands assigned. This can be 0.

    KEYCOMMANDS.0 .. KEYCOMMANDS.N

        Information on all the keyboard commands assigned.

        KEYCOMMANDS.<n>.NAME

            Name of the keyboard command.

        KEYCOMMANDS.<n>.KEY

            The key combination assigned to this keyboard
            command.

        KEYCOMMANDS.<n>.COMMAND

            The ARexx command assigned to this key combination.


    MENUCOMMANDS.COUNT

        Number of menu commands assigned (through the "MENU ADD .."
        command). This can be 0.

    MENUCOMMANDS.0 .. MENUCOMMANDS.N

        Information on all the menu commands assigned.

        MENUCOMMANDS.<n>.NAME

            Name of this menu item.

        MENUCOMMANDS.<n>.TITLE

            Title of this menu item.

        MENUCOMMANDS.<n>.SHORTCUT

            The keyboard shortcut assigned to this menu item.

        MENUCOMMANDS.<n>.COMMAND

            The ARexx command assigned to this menu item.


    The following attributes require that the name of the window to obtain
    information on is provided.

    WINDOW.LEFT

        Left edge of the window.

    WINDOW.TOP

        Top edge of the window.

    WINDOW.WIDTH

        Width of the window.

    WINDOW.HEIGHT

        Height of the window.

    WINDOW.MIN.WIDTH

        Minimum width of the window.

    WINDOW.MIN.HEIGHT

        Minimum height of the window.

    WINDOW.MAX.WIDTH

        Maximum width of the window.

    WINDOW.MAX.HEIGHT

        Maximum height of the window.

    WINDOW.VIEW.LEFT

        Horizontal offset of the drawer contents; this value corresponds
        to the horizontal window scroller position.

    WINDOW.VIEW.TOP

        Vertical offset of the drawer contents; this value corresponds
        to the vertical window scroller position.

    WINDOW.SCREEN.NAME

        Name of the public screen the window was opened on.

    WINDOW.SCREEN.WIDTH
    WINDOW.SCREEN.HEIGHT

        Size of the public screen the window was opened on.

    WINDOW.ICONS.ALL.COUNT

        Number of the icons displayed in the window. This can be 0.

    WINDOW.ICONS.ALL.0 .. WINDOW.ICONS.ALL.N

        Information on all the icons displayed in the window:

        WINDOW.ICONS.ALL.<n>.NAME

            Name of the icon in question.

        WINDOW.ICONS.ALL.<n>.LEFT
        WINDOW.ICONS.ALL.<n>.TOP

            Position of the icon in question.

        WINDOW.ICONS.ALL.<n>.WIDTH
        WINDOW.ICONS.ALL.<n>.HEIGHT

            Size of the icon in question.

        WINDOW.ICONS.ALL.<n>.TYPE

            Type of the icon; one of DISK, DRAWER, TOOL, PROJECT,
            GARBAGE, DEVICE, KICK or APPICON.

        WINDOW.ICONS.ALL.<n>.STATUS

            Whether the icon is selected and (if the icon is a drawer-like
            object, such as a disk, drawer or trashcan icon) whether the
            corresponding drawer is currently open or closed. This attribute
            is returned in the form of a string, such as "SELECTED OPEN"
            which means that the icon is selected and the corresponding drawer
            is currently open. The other options include "UNSELECTED" and
            "CLOSED".

    WINDOW.ICONS.SELECTED.COUNT

        Number of the selected icons displayed in the window. This can be 0.

    WINDOW.ICONS.SELECTED.0 .. WINDOW.ICONS.SELECTED.N

        Information on all selected the icons in the window:

        WINDOW.ICONS.SELECTED.<n>.NAME

            Name of the icon in question.

        WINDOW.ICONS.SELECTED.<n>.LEFT
        WINDOW.ICONS.SELECTED.<n>.TOP

            Position of the icon in question.

        WINDOW.ICONS.SELECTED.<n>.WIDTH
        WINDOW.ICONS.SELECTED.<n>.HEIGHT

            Size of the icon in question.

        WINDOW.ICONS.SELECTED.<n>.TYPE

            Type of the icon; one of DISK, DRAWER, TOOL, PROJECT,
            GARBAGE, DEVICE, KICK or APPICON.

        WINDOW.ICONS.SELECTED.<n>.STATUS

            Whether the icon is selected and (if the icon is a drawer-like
            object, such as a disk, drawer or trashcan icon) whether the
            corresponding drawer is currently open or closed. This attribute
            is returned in the form of a string, such as "SELECTED OPEN"
            which means that the icon is selected and the corresponding drawer
            is currently open. The other options include "UNSELECTED" and
            "CLOSED". Of course, for the WINDOW.ICONS.SELECTED stem the
            icon status will always be reported as "SELECTED".

    WINDOW.ICONS.UNSELECTED.COUNT

        Number of the unselected icons displayed in the window. This can be 0.

    WINDOW.ICONS.UNSELECTED.0 .. WINDOW.ICONS.UNSELECTED.N

        Information on all selected the icons in the window:

        WINDOW.ICONS.UNSELECTED.<n>.NAME

            Name of the icon in question.

        WINDOW.ICONS.UNSELECTED.<n>.LEFT
        WINDOW.ICONS.UNSELECTED.<n>.TOP

            Position of the icon in question.

        WINDOW.ICONS.UNSELECTED.<n>.WIDTH
        WINDOW.ICONS.UNSELECTED.<n>.HEIGHT

            Size of the icon in question.

        WINDOW.ICONS.UNSELECTED.<n>.TYPE

            Type of the icon; one of DISK, DRAWER, TOOL, PROJECT,
            GARBAGE, DEVICE, KICK or APPICON.

        WINDOW.ICONS.UNSELECTED.<n>.STATUS

            Whether the icon is selected and (if the icon is a drawer-like
            object, such as a disk, drawer or trashcan icon) whether the
            corresponding drawer is currently open or closed. This attribute
            is returned in the form of a string, such as "UNSELECTED OPEN"
            which means that the icon is selected and the corresponding drawer
            is currently open. The other options include "SELECTED" and
            "CLOSED". Of course, for the WINDOW.ICONS.UNSELECTED stem the
            icon status will always be reported as "UNSELECTED".

Errors:

    10 - If the requester information could not be retrieved, you requested
         more than one database entry and did not provide a stem variable
         or if you provided a stem variable but did not request more than
         one database entry. The error code will be placed in the
         WORKBENCH.LASTERROR variable.

Result:

    RESULT - The information retrieved from the database.

Example:

    /* Query the Workbench version. */
    ADDRESS workbench
    OPTIONS RESULTS

    GETATTR application.version
    SAY result

    /* Query the Workbench version and store it in the
     * variable `version_number'.
     */
    GETATTR application.version VAR version_number
    SAY version_number

    /* Query the names of all currently open windows,
     * then print them.
     */
    GETATTR windows STEM window_list

    DO i = 0 TO window_list.count-1
    	SAY window_list.i;
    END;

    /* Query name, position and size of the first icon
     * shown in the root window.
     */
    GETATTR window.icons.all.0 NAME root STEM root

    SAY root.name
    SAY root.left
    SAY root.top
    SAY root.width
    SAY root.height
    SAY root.type

    /* Query the width and height of the root window. */
    GETATTR window.width NAME root
    SAY result

    GETATTR window.height NAME root
    SAY result

    /* Query the length of a text (in pixels) with reference
     * to the icon font.
     */
    GETATTR application.font.icon.size NAME 'Text to measure'
    SAY result


6. HELP command

Purpose:

    This command can be used to open the online help and to obtain information
    on the supported menus, commands and command parameters.

Format:

    HELP [COMMAND <Command name>] [MENUS] [PROMPT]

Template:

    HELP COMMAND/K,MENUS/S,PROMPT/S

Parameters:

    COMMAND

        Name of the command whose command template should be retrieved.

    MENUS

        Specify this parameter to retrieve a list of menu items
        currently available.

    PROMPT

        Specify this parameter to invoke the online help system.


    If no parameter is provided, a list of supported commands will be
    returned.

Errors:

    10 - If the named command is not supported by the ARexx interface.
         The error code will be placed in the WORKBENCH.LASTERROR variable.

Result:

    RESULT

        The command template, list of menu items or commands, as
        specified in the command parameters.

Example:

    /* Retrieve the list of supported commands. */
    ADDRESS workbench
    OPTIONS results

    HELP
    SAY result

    /* Retrieve the command template of the `GETATTR' command. */
    HELP COMMAND getattr
    SAY result

    /* Retrieve the list of available menu items. */
    HELP MENUS
    SAY result


7. ICON command

Purpose:

    This command is for manipulating the icons displayed in a window.

Format:

    ICON [WINDOW] <Window name> <Icon name> .. <Icon name>
         [OPEN] [MAKEVISIBLE] [SELECT] [UNSELECT]
         [UP <Pixels>] [DOWN <Pixels>] [LEFT <Pixels>] [RIGHT <Pixels>]
         [X <Horizontal position>] [Y <Vertical position>]
         [ACTIVATE UP|DOWN|LEFT|RIGHT] [CYCLE PREVIOUS|NEXT]
         [MOVE IN|OUT]

Template:

    ICON WINDOW,NAMES/M,OPEN/S,MAKEVISIBLE/S,SELECT/S,UNSELECT/S,
         UP/N,DOWN/N,LEFT/N,RIGHT/N,X/N,Y/N,ACTIVATE/K,CYCLE/K,
         MOVE/K

Parameters:

    WINDOW

        Name of the window whose icons should be manipulated. This can be
        "ROOT" to work on the Workbench root window (where volume icons and
        AppIcons live), "ACTIVE" to work on the currently active Workbench
        window or the fully qualified name of a drawer window. Note that the
        drawer window must already be open.

        If no WINDOW parameter is specified, this command will try to operate
        on the currently active Workbench window.

    NAMES

        Names of the icons to manipulate.

    OPEN

        Specifies that the named icons should be opened.

    MAKEVISIBLE

        Specifies that the named icons should be made
        visible. This generally works well for the first icon
        in a list but does not always work for a whole list.

    SELECT

        Select the named icons.

    UNSELECT

        Unselect the named icons.

    UP, DOWN, LEFT, RIGHT

        Move the named icons by the specified number of pixels.

    X, Y

        Move the named icons to the specified position.

    ACTIVATE

        This command is for activating the icon closest to the
        currently selected icon in the window. "Activating" in
        this context means "selecting an icon, whilst at the same
        time unselecting all others". Thus, the "active" icon
        is the only selected icon in the window.

        You can indicate which direction the next icon to be
        activated should be searched for, relative to the currently
        active icon. "UP" searches upwards, "DOWN" searches
        downwards, "LEFT" searches to the left and "RIGHT"
        searches to the right.

    CYCLE

        This command is for cycling through all icons in a window,
        making each one the active one in turn (for a description
        of what "active" means in this context, see the "ACTIVATE"
        description above). You must indicate in which direction
        you want to cycle through the icons: you can either
        specify "PREVIOUS" or "NEXT".

    MOVE

        This command is not for moving icons but for moving through
        a file system hierarchy. Thus, moving "in" will open a drawer
        and moving "out" will open the drawer's parent directory.
        The "IN" parameter will cause the drawer represented by the
        active icon to be opened. Please note that an icon must be
        selected and it must be a drawer. The "OUT" parameter will
        open the drawer's parent directory, and it also requires that
        in the drawer there is an icon selected. This may sound
        strange, but this feature is not meant as a replacement for
        the "Open Parent" menu item.

Errors:

    10 - If the named window cannot be found, none of the Workbench
         windows are currently active and the command was set to
         work on the currently active Workbench window. The error code
         will be placed in the WORKBENCH.LASTERROR variable.

Result:

    -

Example:

    /* Select the icons of the "Workbench" and "Work" volumes
     * displayed in the root window.
     */
    ADDRESS workbench

    ICON WINDOW root NAMES Workbench Work SELECT

    /* Open the "Workbench" volume icon displayed in the root
     * window.
     */
    ICON WINDOW root NAMES Workbench OPEN


8. INFO command

Purpose:

    This command is for opening the Workbench icon information
    requester.

Format:

    INFO [NAME] <File, drawer or volume name>

Template:

    INFO NAME/A

Parameters:

    NAME

        Name of the file, drawer or volume to open the information
        window for.

Errors:

    10 - If the named file, drawer or volume could not be found. The
         error code will be placed in the WORKBENCH.LASTERROR variable.

Result:

    -

Example:

    /* Open the information window for "SYS:". */
    ADDRESS workbench

    INFO NAME 'SYS:'


9. KEYBOARD command

Purpose:

    This command can be used to bind ARexx commands to key combinations.

Format:

    KEYBOARD [NAME] <Name of key combination> ADD|REMOVE
             [KEY <Key combination>] [CMD <ARexx command>]

Template:

    KEYBOARD NAME/A,ADD/S,REMOVE/S,KEY,CMD/F

Parameters:

    NAME

        Name of the key combination to add or remove. Each key combination
        must have a name with which it is associated. The name must be
        unique.

    ADD

        This tells the KEYBOARD command to add a new keyboard combination.
        You will also need to specify the KEY and CMD parameters.

    REMOVE

        This tells the KEYBOARD command to remove an existing keyboard
        combination.

    KEY

        The keyboard combination to add; this must be in the same format
        as used by the Commodities programs.

    CMD

        This is the ARexx command to bind to the keyboard combination.
        The command can either be the name of an ARexx script to execute
        or a short ARexx program in a single line.

Errors:

    10 - The command will fail if you tried to add a duplicate of an
         existing key combination or if the key combination to remove
         does not exist. The error code will be placed in the
         WORKBENCH.LASTERROR variable.

Result:

    -

Example:

    /* Bind an ARexx script to the [Control]+A key combination.
     * When pressed, this will cause the ARexx script by the name
     * "test.wb" to be executed. ARexx will search for that program
     * in the "REXX:" directory. If no "test.wb" file can
     * be found, ARexx will attempt to execute a script
     * by the name of "test.rexx".
     */
    ADDRESS workbench

    KEYBOARD ADD NAME test1 KEY '"ctrl a"' CMD 'test'

    /* Bind an ARexx script to the [Alt]+[F1] key combination.
     * When pressed, this will cause a short inline program to be
     * executed.
     */
    KEYBOARD ADD NAME test2 KEY '"alt f1"' CMD "'say 42"

    /* Bind an ARexx script to the [Shift]+[Help] key combination.
     * When pressed, this will cause the Workbench "About" menu item
     * to be invoked.
     */
    KEYBOARD ADD NAME test3 KEY '"shift help"' CMD "'MENU INVOKE WORKBENCH.ABOUT"

    /* Remove the first key combination we added above. */
    KEYBOARD REMOVE NAME test1


10. LOCKGUI command

Purpose:

    This command will block access to all Workbench drawer windows.

Format:

    LOCKGUI

Template:

    LOCKGUI

Parameters:

    -

Errors:

    -

Result:

    -

Notes:

    It takes as many UNLOCKGUI commands as there were LOCKGUI commands
    to make the Workbench drawer windows usable again. In other words,
    the LOCKGUI command "nests".

Example:

    /* Block access to all Workbench drawer windows. */
    ADDRESS workbench

    LOCKGUI


11. MENU command

Purpose:

    This command is for invoking items of the Workbench menu, as if the user
    had selected them with the mouse and for adding/removing user menus.

Format:

    MENU [WINDOW <Window name>] [INVOKE] <Menu name>
         [NAME <Menu name>] [TITLE <Menu title>]
         [SHORTCUT <Menu shortcut>] [ADD|REMOVE]
         [CMD <ARexx command>]

Template:

    MENU WINDOW/K,INVOKE,NAME/K,TITLE/K,SHORTCUT/K,ADD/S,REMOVE/S,CMD/K/F

Parameters:

    The following set of parameters can be used solely for invoking
    menu items.

    WINDOW

        Name of the window whose menu should be invoked. This can be "ROOT"
        to work on the Workbench root window (where volume icons and AppIcons
        live), "ACTIVE" to work on the currently active Workbench window or
        the fully qualified name of a drawer window. Note that the drawer
        window must already be open.

        If no WINDOW parameter is specified, this command will try to operate
        on the currently active Workbench window.

    INVOKE

        Name of the menu to invoke. See below for a list of
        available menu items.

    The following set of parameters are for adding and removing menu items.

    NAME

        Name of the menu item to add or remove. Each menu item must have
        a name with which it is associated. The name must be unique and
        has nothing to do with the title of the item, as shown in the
        "Tools" menu.

    TITLE

        This is the text that will be used as the menu item title,
        as it will appear in the "Tools" menu. This parameter is
        required if you ADD a new menu item.

        Starting with workbench.library 44.1511 you can add sub menu
        items by specifying the name of the menu item to add to
        and the name of the sub menu item as the title. The two
        must be separated by a backslash character ("\"), as in
        "Menu title\Sub menu title".

    SHORTCUT

        When adding a new menu item, this will be the menu shortcut
        associated with the item. Please note that the shortcut cannot
        be longer than a single character and that it will be ignored
        if there already is an item in any of the menus which uses
        this shortcut. This parameter is optional.

    ADD

        This tells the MENU command to add a new item to the "Tools"
        menu. When adding a menu item you will also need to specify
        the NAME, TITLE and CMD parameters.

    REMOVE

        This tells the MENU command to remove a menu item previously
        added via the ARexx interface. When removing a menu item you
        will also need to specify the NAME parameter.

    CMD

        This is the ARexx command to bind to the new menu item. The
        command can either be the name of an ARexx script to execute
        or a short ARexx program in a single line.

Menu items:

    WORKBENCH.BACKDROP

        Toggles the Workbench "Backdrop" window switch.

    WORKBENCH.EXECUTE

        Invokes the Workbench "Execute Command" requester. The user will
        be prompted to enter the command to be executed.

    WORKBENCH.REDRAWALL

        Invokes the Workbench "Redraw All" function.

    WORKBENCH.UPDATEALL

        Invokes the Workbench "Update All" function.

    WORKBENCH.LASTMESSAGE

        Redisplays the last Workbench error message.

    WORKBENCH.ABOUT

        Displays the Workbench "About..." requester.

    WORKBENCH.QUIT

        Attempts to close Workbench; this may bring up a requester the
        user will have to answer.

    WINDOW.NEWDRAWER

        Prompts the user to enter the name of a new drawer to be
        created.

    WINDOW.OPENPARENT

        If possible, this will open the parent directory of the drawer
        the command operates on.

    WINDOW.CLOSE

        If possible, this will close the drawer the command operates on.

    WINDOW.UPDATE

        This will update the drawer the command operates on, i.e. the
        contents will be reread.

    WINDOW.SELECTCONTENTS

        This will select the contents of the drawer the command operates on.

    WINDOW.CLEARSELECTION

        This unselects all icons selected in the drawer the command
        operates on.

    WINDOW.CLEANUPBY.COLUMN

        This will sort the contents of the drawer and place the icons
        in columns.

    WINDOW.CLEANUPBY.NAME

        This will sort the contents of the drawer by name and place
        the icons in rows.

    WINDOW.CLEANUPBY.DATE

        This will sort the contents of the drawer by date and place
        the icons in rows.

    WINDOW.CLEANUPBY.SIZE

        This will sort the contents of the drawer by size and place
        the icons in rows.

    WINDOW.CLEANUPBY.TYPE

        This will sort the contents of the drawer by type and place
        the icons in rows.

    WINDOW.RESIZETOFIT

        This will resize the drawer window, trying to make it just as
        large as to allow all its icons to fit.

    WINDOW.SNAPSHOT.WINDOW

        This will snapshot the drawer window, but none of its contents.

    WINDOW.SNAPSHOT.ALL

        This will snapshot the drawer window and its contents.

    WINDOW.SHOW.ONLYICONS

        This will change the display mode of the drawer to show only
        files and drawers which have icons attached.

    WINDOW.SHOW.ALLFILES

        This will change the display mode of the drawer to show all
        files and drawers, regardless of whether they have icons
        attached or not.

    WINDOW.VIEWBY.ICON

        This will change the display mode of the drawer to show
        its contents as icons.

    WINDOW.VIEWBY.NAME

        This will change the display mode of the drawer to show
        its contents in textual format, sorted by name.

    WINDOW.VIEWBY.DATE

        This will change the display mode of the drawer to show
        its contents in textual format, sorted by date.

    WINDOW.VIEWBY.SIZE

        This will change the display mode of the drawer to show
        its contents in textual format, sorted by size.

    WINDOW.VIEWBY.TYPE

        This will change the display mode of the drawer to show
        its contents in textual format, sorted by type.

    ICONS.OPEN

        This will open the currently selected icons. Workbench
        may bring up a requester in case project icons are found
        which lack a default tool.

    ICONS.COPY

        This will duplicate the currently selected icons.

    ICONS.RENAME

        This will prompt the user to choose a new name for each
        currently selected icon.

    ICONS.INFORMATION

        This will open the information window for every currently
        selected icon.

    ICONS.SNAPSHOT

        This will lock the position of every currently selected icon.

    ICONS.UNSNAPSHOT

        This will unlock the position of every currently selected icon.

    ICONS.LEAVEOUT

        This will permanently put all currently selected icons on the
        Workbench root window.

    ICONS.PUTAWAY

        This will move all currently selected icons out of the root
        window and put them back into the drawers they belong.

    ICONS.DELETE

        This will cause all currently selected files to be deleted,
        provided the user confirms this action first.

    ICONS.FORMATDISK

        This will invoke the "Format" command on every currently selected
        disk icon. This will not format the disks immediately. The user
        will have to confirm this action first.

    ICONS.EMPTYTRASH

        With a trashcan icon selected, this will empty it.

    TOOLS.RESETWB

        This will close and reopen all Workbench windows.

    The HELP command will provide a complete list of menu items that can be
    invoked. Depending on the state of each menu item (e.g. the "Open" menu
    item will be disabled if no icon is currently selected) the MENU command
    can silently fail to invoke the item you had in mind.

Errors:

    10 - If the named window cannot be found, none of the Workbench
         windows are currently active and the command was set to
         work on the currently active Workbench window. The command can
         also fail if you tried to add a duplicate of an existing
         menu item or if the menu item to remove does not exist.
         The error code will be placed in the WORKBENCH.LASTERROR
         variable.

Result:

    -

Example:

    /* Invoke the "About" menu. */
    ADDRESS workbench
    OPTIONS RESULTS

    MENU WINDOW root INVOKE WORKBENCH.ABOUT

    /* Add an item to the "Tools" menu; selecting it
     * will cause the ARexx script by the name "test.wb"
     * to be executed. ARexx will search for that program
     * in the "REXX:" directory. If no "test.wb" file can
     * be found, ARexx will attempt to execute a script
     * by the name of "test.rexx".
     */
    MENU ADD NAME test1 TITLE '"Execute a script"' SHORTCUT '!' CMD 'test'

    /* Add an item to the "Tools" menu; selecting it
     * will cause a short inline program to be executed.
     */
    MENU ADD NAME test2 TITLE '"Short inline program"' CMD "'say 42"

    /* Add an item to the "Tools" menu; selecting it
     * will cause the Workbench "About" menu item to be invoked.
     */
    MENU ADD NAME test3 TITLE '"About..."' CMD "'MENU INVOKE WORKBENCH.ABOUT"

    /* Add a new item to the "Tools" menu, then add two sub items
     * to the new item. Note that this feature requires workbench.library
     * 44.1511 or higher to work.
     */
    GETATTR APPLICATION.VERSION
    PARSE VAR RESULT ver '.' rev
    IF ((ver > 44) | ((ver == 44) & (rev >= 1511))) THEN DO
       MENU ADD NAME test4 TITLE '"Say something\Hello"' CMD "'say hello";
       MENU ADD NAME test5 TITLE '"Say something\World"' CMD "'say world";
    END;

    /* Remove the first menu item we added above. */
    MENU REMOVE NAME test1


12. MOVEWINDOW command

Purpose:

    This command will attempt to change the position of a window.

Format:

    MOVEWINDOW [WINDOW] <ROOT|ACTIVE|Drawer name>
               [[LEFTEDGE] <new left edge position>]
               [[TOPEDGE] <new top edge position>]

Template:

    MOVEWINDOW WINDOW,LEFTEDGE/N,TOPEDGE/N

Parameters:

    WINDOW

        Either "ROOT" to move the Workbench root window (where volume icons
        and AppIcons live), "ACTIVE" to move the currently active Workbench
        window or the fully qualified name of a drawer window to change. Note
        that the drawer window must already be open.

        If no WINDOW parameter is specified, this command will try to operate
        on the currently active Workbench window.

    LEFTEDGE

        New left edge window position.

    TOPEDGE

        New top edge window position.

Errors:

    10 - If the named window cannot be moved; this can also happen if you
         specified "ACTIVE" as the window name and none of the Workbench
         windows is currently active. The error code will be placed in the
         WORKBENCH.LASTERROR variable.

Result:

    -

Notes:

    If you choose to have a window moved that is neither the root nor the
    active window you must make sure that the window name is given as a fully
    qualified path name. For example "Work:" is a fully qualified name, and so
    is "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A
    fully qualified name always contains the name of an assignment, a volume
    or a device.

Example:

    /* Move the root window to position 10,30. */
    ADDRESS workbench

    MOVEWINDOW root LEFTEDGE 10 TOPEDGE 30

    /* Move the currently active window. */
    MOVEWINDOW active 20 40


13. NEWDRAWER command

Purpose:

    This command is for creating new drawers.

Format:

    NEWDRAWER [NAME] <Name of drawer to create>

Template:

    NEWDRAWER NAME/A

Parameters:

    NAME

        Name of the drawer to be created.

Errors:

    10 - If the named drawer could not be created.

Result:

    -

Notes:

    The drawer name given must be an absolute path, such as in
    "RAM:Empty". A relative path, such as "/fred/barney" will
    not work.

Example:

    /* Create a drawer by the name of "Empty" in the RAM disk. */
    ADDRESS workbench

    NEWDRAWER 'RAM:Empty'


14. RENAME command

Purpose:

    This command is for renaming files, drawers and volumes.

Format:

    RENAME [OLDNAME] <Name of file/drawer/volume to rename>
           [NEWNAME] <New name of the file/drawer/volume>

Template:

    RENAME OLDNAME/A,NEWNAME/A

Parameters:

    OLDNAME

        Name of the file/drawer/volume to be renamed. This must
        be an absolute path, such as in "RAM:Empty". A relative
        path, such as "/fred/barney", will not work.

    NEWNAME

        The new name to assign to the file/drawer/volume. This
        must not be an absolute or relative path. For example,
        "wilma" is valid new name, "/wilma" or "wilma:" would
        be invalid names.

Errors:

    10 - If the object cannot be renamed.

Result:

    -

Notes:

    The RENAME command does not work like for example the AmigaDOS
    "Rename" command. For example, "RENAME 'ram:empty' 'newname'"
    will rename the file 'RAM:empty' to 'RAM:newname'.

Example:

    /* Rename a drawer by the name of "Old" in the RAM disk to "New". */
    ADDRESS workbench

    RENAME 'RAM:Old' 'New'


15. RX command

Purpose:

    This command is for executing ARexx scripts and commands.

Format:

    RX [CONSOLE] [ASYNC] [CMD] <Command to execute>

Template:

    RX CONSOLE/S,ASYNC/S,CMD/A/F

Parameters:

    CONSOLE

        This switch indicates that a console (for default I/O)
        is needed.

    ASYNC

        This switch indicates that the command should be run
        asynchronously, i.e. the "RX" command will return as
        soon as ARexx has been instructed to run the command
        you specified. Otherwise, the "RX" command will wait
        for the specified ARexx command to complete execution.

    COMMAND

        This is the name of the ARexx program to execute.

Errors:

    10 - If the given ARexx program could not be executed.

Result:

    -

Example:

    /* Execute an ARexx program by the name of 'test.wb';
     * its output should be sent to a console window.
     */
    ADDRESS workbench

    RX CONSOLE CMD 'test.wb'


16. SIZEWINDOW command

Purpose:

    This command will attempt to change the size of a window.

Format:

    SIZEWINDOW [WINDOW] <ROOT|ACTIVE|Drawer name>
               [[WIDTH] <new window width>]
               [[HEIGHT] <new window height>]

Template:

    SIZEWINDOW WINDOW,WIDTH/N,HEIGHT/N

Parameters:

    WINDOW

        Either "ROOT" to resize the Workbench root window (where volume icons
        and AppIcons live), "ACTIVE" to resize the currently active Workbench
        window or the fully qualified name of a drawer window to change. Note
        that the drawer window must already be open.

        If no WINDOW parameter is specified, this command will try to operate
        on the currently active Workbench window.

    WIDTH

        New window width.

    HEIGHT

        New window height.

Errors:

    10 - If the named window cannot be resized; this can also happen if you
         specified "ACTIVE" as the window name and none of the Workbench
         windows is currently active. The error code will be placed in the
         WORKBENCH.LASTERROR variable.

Result:

    -

Notes:

    If you choose to have a window resized that is neither the root nor the
    active window you must make sure that the window name is given as a fully
    qualified path name. For example "Work:" is a fully qualified name, and so
    is "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A
    fully qualified name always contains the name of an assignment, a volume
    or a device.

Example:

    /* Change the root window size to 200100 pixels. */
    ADDRESS workbench

    SIZEWINDOW root 30 WIDTH 200 HEIGHT 100

    /* Resize the currently active window. */
    SIZEWINDOW active 200 100


17. UNLOCKGUI command

Purpose:

    This command will allow access to all Workbench drawer windows locked
    with the LOCKGUI command.

Format:

    UNLOCKGUI

Template:

    UNLOCKGUI

Parameters:

    -

Errors:

    -

Result:

    -

Notes:

    It takes as many UNLOCKGUI commands as there were LOCKGUI commands
    to make the Workbench drawer windows usable again. In other words,
    the LOCKGUI command "nests".

Example:

    /* Reallow access to all Workbench drawer windows. */
    ADDRESS workbench

    UNLOCKGUI


18. UNZOOMWINDOW command

Purpose:

    This command will attempt return a window to its original position and
    dimensions.

Format:

    UNZOOMWINDOW [WINDOW] <ROOT|ACTIVE|Drawer name>

Template:

    UNZOOMWINDOW WINDOW

Parameters:

    WINDOW

        Name of the window to operate on. "ROOT" will use the Workbench root
        window (where volume icons and AppIcons live), "ACTIVE" will use
        the currently active Workbench window. Any other fully qualified
        path name will use the drawer window corresponding to the path.
        If no WINDOW parameter is specified, this command will try to operate
        on the currently active Workbench window.

Errors:

    10 - If the named window cannot be found. The error code will be
         placed in the WORKBENCH.LASTERROR variable.

Result:

    -

Example:

    /* Change the root window. */
    ADDRESS workbench

    UNZOOMWINDOW root


19. VIEW command

Purpose:

    This command will change the position of the viewable display area of a
    window.

Format:

    VIEW [WINDOW] <ROOT|ACTIVE|Drawer name>
         [PAGE|PIXEL] [UP|DOWN|LEFT|RIGHT]

Template:

    VIEW WINDOW,PAGE/S,PIXEL/S,UP/S,DOWN/S,LEFT/S,RIGHT/S

Parameters:

    WINDOW

        Either "ROOT" to change the Workbench root window view (where volume
        icons and AppIcons live), "ACTIVE" to change the currently active
        Workbench window view or the fully qualified name of a drawer window
        to change. Note that the drawer window must already be open.

        If no WINDOW parameter is specified, this command will try to operate
        on the currently active Workbench window.

    UP

        Move the view up by about 1/8 of the window height. If PAGE is
        specified, moves the view up by a whole page. If PIXEL is specified,
        moves the view up by a single pixel.

    DOWN

        Move the view down by about 1/8 of the window height. If PAGE is
        specified, moves the view down by a whole page. If PIXEL is
        specified, moves the view down by a single pixel.

    LEFT

        Move the view left by about 1/8 of the window height. If PAGE is
        specified, moves the view left by a whole page. If PIXEL is
        specified, moves the view left by a single pixel.

    RIGHT

        Move the view right by about 1/8 of the window height. If PAGE is
        specified, moves the view right by a whole page. If PIXEL is
        specified, moves the view right by a single pixel.

Errors:

    10 - If the named window view cannot be changed; this can also happen if you
         specified "ACTIVE" as the window name and none of the Workbench
         windows is currently active. The error code will be placed in the
         WORKBENCH.LASTERROR variable.

Result:

    -

Notes:

    If you choose to have a window view changed that is neither the root nor
    the active window you must make sure that the window name is given as a
    fully qualified path name. For example "Work:" is a fully qualified name,
    and so is "SYS:Utilities". "Devs/Printers" would not be a fully qualified
    name. A fully qualified name always contains the name of an assignment, a
    volume or a device.

    To find out about a window's current view position, use the GETATTR
    command and query the window's WINDOW.VIEW.LEFT and WINDOW.VIEW.TOP
    attributes.

Example:

    /* Change the root window view; move it up by a whole page. */
    ADDRESS workbench

    VIEW root PAGE UP


20. WINDOW command

Purpose:

    This command will change, open, close or snapshot windows.

Format:

    WINDOW [WINDOWS] <Window name> .. <Window name>
           [OPEN|CLOSE] [SNAPSHOT] [ACTIVATE] [MIN|MAX]
           [FRONT|BACK] [CYCLE PREVIOUS|NEXT]

Template:

    WINDOW WINDOWS/M/A,OPEN/S,CLOSE/S,SNAPSHOT/S,ACTIVATE/S,MIN/S,MAX/S,
           FRONT/S,BACK/S,CYCLE/K

Parameters:

    WINDOWS

        Names of the windows to operate on. This can be "ROOT" to for the
        Workbench root window (where volume icons and AppIcons live),
        "ACTIVE" for the currently active Workbench window or the fully
        qualified name of a drawer window.

    OPEN

        Attempt to open the specified windows.

    CLOSE

        Close the specified windows. Note that if a window is closed no
        further operations (such as SNAPSHOT, ACTIVATE, etc.) can be
        performed on it.

    SNAPSHOT

        Snapshot the sizes and positions of the specified windows.

    ACTIVATE

        Activate the specified windows. With multiple windows to activate,
        only one window will wind up as the active one. Commonly, this will
        be the last window in the list.

    MIN

        Resize the windows to their minimum dimensions.

    MAX

        Resize the windows to their maximum dimensions.

    FRONT

        Move the windows into the foreground.

    BACK

        Move the windows into the background.

    CYCLE

        This command operates on the currently active drawer window.
        You can specify either "PREVIOUS", to activate the previous
        drawer window in the list, or "NEXT", to activate the next
        following drawer window in the list.

Errors:

    10 - If the named windows cannot be opened or operated on; this can
         also happen if you specified "ACTIVE" as a window name and none
         of the Workbench windows is currently active. The error code will
         be placed in the WORKBENCH.LASTERROR variable.

Result:

    -

Notes:

    If you choose to have a window operated on that is neither the root nor
    the active window you must make sure that the window name is given as a
    fully qualified path name. For example "Work:" is a fully qualified name,
    and so is "SYS:Utilities". "Devs/Printers" would not be a fully qualified
    name. A fully qualified name always contains the name of an assignment, a
    volume or a device.

Example:

    /* Open the "Work:" drawer. */
    ADDRESS workbench

    WINDOW 'Work:' OPEN

    /* Activate the root window. */
    WINDOW root ACTIVATE


21. WINDOWTOBACK command

Purpose:

    This command will push a window into the background.

Format:

    WINDOWTOBACK [WINDOW] <ROOT|ACTIVE|Drawer name>

Template:

    WINDOWTOBACK WINDOW

Parameters:

    WINDOW

        "ROOT" to push the the Workbench root window (where volume icons and
        AppIcons live) into to the background, "ACTIVE" to push the currently
        active Workbench window into the background or the fully qualified
        name of a drawer window. Note that the drawer window must already be
        open.

        If no WINDOW parameter is specified, this command will try to operate
        on the currently active Workbench window.

Errors:

    10 - If the named window cannot be found. The error code will be
         placed in the WORKBENCH.LASTERROR variable.

Result:

    -

Notes:

    If you choose to have a window pushed into the background that is not the
    root window or the currently active window you must make sure that the
    window name is given as a fully qualified path name. For example "Work:"
    is a fully qualified name, and so is "SYS:Utilities". "Devs/Printers"
    would not be a fully qualified name. A fully qualified name always
    contains the name of an assignment, a volume or a device.

Example:

    /* Push the root window into the background. */
    ADDRESS workbench

    WINDOWTOBACK root


22. WINDOWTOFRONT command

Purpose:

    This command will bring a window to the foreground.

Format:

    WINDOWTOFRONT [WINDOW] <ROOT|ACTIVE|Drawer name>

Template:

    WINDOWTOFRONT WINDOW

Parameters:

    WINDOW

        "ROOT" to bring the the Workbench root window (where volume icons and
        AppIcons live) to the foreground, "ACTIVE" to bring the currently
        active Workbench window to the foreground or the fully qualified name
        of a drawer window. Note that the drawer window must already be open.

        If no WINDOW parameter is specified, this command will try to operate
        on the currently active Workbench window.

Errors:

    10 - If the named window cannot be found. The error code will be
         placed in the WORKBENCH.LASTERROR variable.

Result:

    -

Notes:

    If you choose to have a window brought to the foreground that is not the
    root window or the currently active window you must make sure that the
    window name is given as a fully qualified path name. For example "Work:"
    is a fully qualified name, and so is "SYS:Utilities". "Devs/Printers"
    would not be a fully qualified name. A fully qualified name always
    contains the name of an assignment, a volume or a device.

Example:

    /* Bring the root window to the foreground. */
    ADDRESS workbench

    WINDOWTOFRONT root


23. ZOOMWINDOW command

Purpose:

    This command will change a window to alternate position and
    dimensions.

Format:

    ZOOMWINDOW [WINDOW] <ROOT|ACTIVE|Drawer name>

Template:

    ZOOMWINDOW WINDOW

Parameters:

    WINDOW

        Name of the window to operate on. "ROOT" will use the Workbench root
        window (where volume icons and AppIcons live), "ACTIVE" will use
        the currently active Workbench window. Any other fully qualified
        path name will use the drawer window corresponding to the path.
        If no WINDOW parameter is specified, this command will try to operate
        on the currently active Workbench window.

Errors:

    10 - If the named window cannot be found. The error code will be
         placed in the WORKBENCH.LASTERROR variable.

Result:

    -

Example:

    /* Change the root window. */
    ADDRESS workbench

    ZOOMWINDOW root
