This chapter describes the Amiga Workbench, an icon-based environment that allows you to give instructions by manipulating graphic symbols with a mouse rather than by typing in commands at a keyboard. Included in this chapter are descriptions of the following:

The Workbench Screen
The Workbench Window
The Workbench Menus
Workbench Programs

Workbench Screen

The Workbench screen, illustrated in Figure 4-1, is the primary visual component of your system. Icons and other windows appear on it.

The Workbench screen is identified by the Amiga Workbench title bar located along the top border of the display. The Workbench screen's title bar also displays the number of bytes of graphics (Chip) memory and other (Fast) memory currently available when any window, except a Shell window is selected.

The Amiga provides Preferences editors (described in Chapter 5) that allow you to customize the Workbench screen. You can define an extra-large virtual Workbench screen that is larger than the viewable area with more space for windows.

Workbench Window

When you boot you Amiga, the Workbench window fills the Workbench screen. This window contains icons for any floppy disks inserted into floppy drives, the Ram Disk, and any other icons determined by your system's configuration.

Although the Workbench window appears and functions like an application window, it is an essential part of the Workbench screen.

Workbench Screen

Workbench Menus

The workbench has the following four menus:

Workbench	Contains options for working with Workbench and windows opened on the Workbench screen.
Windows	Contains options for working within the currently selected window.
Icons	Contains options for working with the currently selected icon or group of icons.
Tools	Is available for applications to use or for user-created menu items.

Workbench Menu

The Workbench menu contains general Workbench options and options for windows opened on the Workbench screen. You can, for example, use the Workbench menu to update the screen display or see which version of the system software is in use.

On the Workbench menu you can select the following options:

Update software

Backdrop

The Backdrop menu item creates more room on the Workbench screen for displaying windows and icons. Backdrop switches between a normal window for your Workbench and a special borderless window that is always behind other windows opened on the Workbench.

Choosing Backdrop removes the Workbench window borders so that the disk icons appear to be on the Workbench screen without being enclosed in a window. To return to the normal Workbench window, choose Backdrop again. Backdrop is reset to off if you power off or reboot your computer. To save your Backdrop selection choose the Snapshot item in the Windows menu while the Workbench window is selected.

Execute Command

Note
This menu item is provided for users familiar with AmigaDOS.

The Execute Command executes (starts) an AmigaDOS command without opening a Shell window. Figure 4-2 illustrates an Execute Command requester.

Execute Command Window

Enter the command and all of its arguments in the requester.

A Workbench Output Window is automatically opened when a command results in output and it remains there until you select its close gadget. The current directory for an Execute Command operation is RAM:.

Open volume

Redraw All

Redraw All redraws all open Workbench windows in the Workbench screen and can be used in the event of a disturbance to the Workbench. If Redraw All does not restore the windows to their proper appearance, reboot the computer.

Update All

Update All reopens each open Workbench window, updating its appearance to show its current state.

Note
If you have several windows open and have been using the Shell or an application to change to the contents of a disk, the changes may not be reflected in its windows until you close the windows and reopen them or choose Update All.

Last Message

Last Message retrieves the last information or error message that appeared on the title bar.

About

About opens a requester showing the internal version number of the Workbench and Kickstart software, as well as copyright information. Select the OK gadget to close the requester.

Quit

Quit closes all Workbench operations, making additional RAM available if needed. The Workbench does not close if there are any programs running, including programs that do not open a window and programs that are in your WBStartup drawer.

The only windows that can remain open while using Quit are the disk, drawer, and Shell windows. Once you OK the Quit requester, a Shell window is your only link to the Amiga. You can use the Shell icon in the System drawer to open a Shell window before quitting the Workbench.

Return to the Workbench by typing LOADWB (load Workbench) at the Shell prompt and pressing Return. If there is no Shell window open, you must reboot to return to the Workbench.

The close gadget on the Workbench window is the same as choosing Quit.

Window Menu

The Window menu is only available when a Workbench window is selected. The Window menu allows you to create new drawers, select the contents of the window, rearrange the contents, change how the contents are displayed, and close the window. The available window options are:

New Drawer

To create a new drawer:

Select the window in which you want to create the drawer.
Choose New Drawer from the Window menu. The drawer is created and named "Unnamed1".
A Rename requester prompts you to change the name of the drawer.
Delete the existing name using the DEL key, enter a new name, and press Return or select OK. Selecting Cancel leaves the default name on the new drawer.

Open Parent

A window's parent is the window that contains its icon. With the exception of the Workbench window, every Workbench disk window has a parent window.

Open Parent opens the selected window's parent or brings it to the front of the display if it is already open.

Close

Close closes and removes the selected window from the screen.

Mouse shortcut: For many windows, you can select the close gadget in the upper left corner of the window.

Update

Update redraws the selected window, including any changes made to the contents through the Shell or the Execute Command menu item. Such changes are not reflected until the window is updated or reopened.

Select Contents

Select Contents selects all of the icons in the current window.

Clean Up

Clean Up automatically arranges all the icons in the selected window so that they do not overlap. This arrangement is not saved until you use the Snapshot menu item described below.

Snapshot

Snapshot saves the arrangement and position of icons in a window. It is commonly used following Clean Up. Snapshot has a submenu containing two items: Window and All.

Snapshot Window saves the position and size of the selected window, as well as the Show and View By settings described below. However, it does not save the position of the icons in the window.

Snapshot All saves the position and other settings of all the icons in the selected window, as well as the position and size of the window.

Show

Show controls the types of icons that are displayed on a window. Show has two submenu items: Only Icons and All Files.

Show Only Icons is the default Show mode, displaying only those files and drawers that have icons (.info files).

Show All Files provides a pseudo-icon for each file or drawer in the selected window that does not have a real icon. Pseudo-icons can be treated like any other icon, including manipulating them with the menu items in the Icon menu.

You may have to scroll in the window to see the new pseudo-icons.

View By

View By changes how the information in the window is displayed. View By has four submenu items: Icons, Name, Date, and Size.

View By Icons is the window's default mode.

Choosing View By Name, View By Date, or View By Size displays a window's contents in text form, including the size of the file, its attributes (whether it can be read, deleted, executed, or written to), and its timestamp.

File and drawer names can be selected, opened, dragged, and manipulated just like icons.

View By Name sorts the file list in alphabetical order.

View By Date sorts the list in chronological order, with the most recently created file listed first.

View By Size sorts the list by size, listing the smallest file first.

Icons Menu

The Icons menu allows you to work with the icons on the screen. An icon must be selected before the menu options illustrated in Figure 4-3 become available.

Icons Menu

Open

Opening an icon makes a program or window available.

When you open a disk or drawer icon, a window displays the icons contained on that disk or in that drawer. When an individual project or tool is opened, the corresponding program starts.

Open an icon by selecting it an choosing Open.

Mouse Shortcut: Point to the icon and double-click the selection button.

Copy

Copy allows you to duplicate disks, drawers, programs, or files within a window. To copy material to another window, use the drag-copy method described in Chapter 3. Drag-copying is the easiest method of copying a disk on a two-floppy-system.

Use Copy for making backup copies of your disks.

To copy a drawer, project, or icon:

Select the icon.
Choose Copy from the Icons menu.

Copying disks on single-floppy disk drive systems entails a process known as swapping. Source and destination disks are swapped in the single drive as the system first reads information from the source disk and the writes it to the destination disk. The destination disk must be write-enabled, but need not be formatted since Copy formats the disk as it writes to it. Be sure to copy to disks of the same density as the original disks.

To copy a disk on a single-floppy disk drive system:

Insert the source disk into the Amiga's internal disk drive.
Select the source disk's icon.
Choose Copy from the Icons menu. Insert the Workbench disk, if necessary.
If the disk copy requires at least five swaps, a requester tells you how many swaps are needed. Closing any unnecessary windows or stopping any unwanted programs helps reduce the number of swaps.
Select the Continue gadget in the swap requester. During the disk copy, the icon for the disk being copied is unavailable and is labeled "BUSY".
Insert the source disk into the drive when prompted and select Continue. A horizontal bar gauge shows the percentage of the disk copy completed.
Insert the destination disk into the drive when prompted and select Continue to copy the information read in from the source disk. Swap the disks as often as requested. When the copy is finished, a Disk Copy Finished message appears.
Remove the destination disk from the drive and label it. The destination disk's icon is labeled with a copy_of_prefix (for example, copy_of_DataDisk).

Rename

Rename changes the name of an icon. It is used to remove the copy_of_prefix from something you copied, as well as for changing the names of drawers, disks, and files.

To rename an icon:

Select the icon.
Choose Rename from the Icons menu. A requester containing a text gadget displays the current name of the icon.
Delete the old name using Backspace or right Amiga+X and enter the new name. Do not use spaces before or after the new name. Because embedded spaces are not visible, they can cause confusion if you have to type in the icon name again.
Press Return. The new name appears under the icon.

Information

Information displays status information about the selected icon's file. Certain data can also be modified in the Information window. Figure 4-4 illustrates the Information window.

Icon Information Window

Although the contents of the window varies with the icon, the following information is always displayed:

title bar	The window title bar indicates the path to the icon.
name	The icon name and its type in parentheses (Volume, Drawer, Tool, Project, or Trashcan).
image	A picture of the icon.
size	The number of blocks and bytes that the disk, project, or tool fills.
stack	The amount of memory reserved as temporary storage for a specific tool.
last changed date	The date on which the icon was created or the last time it was changed (its timestamp).

For a disk icon, the window also shows whether a disk is write-enabled (Read/Write) or write-protected (Read Only).

For a drawer, trashcan, project, or tool, the following attributes can be set or cleared by clicking on the attribute's check box.

Script	If set, the file is a script (a text file of AmigaDOS commands) and can be run without using the EXECUTE command.
Archived	This attribute is set by backup programs to indicate that a file or directory has been archived (backed up). It is cleared whenever the file is saved.
Readable	If set, information in the file can be read. If this attribute is clear, a tool will not run and a project cannot be loaded by its Default Tool.
Writable	If set, information can be written into the file. Unless Writable is set, you cannot make changes to the file.
Executable	If set, the file is a tool that can be run from Workbench or the Shell. If this attribute is clear, the tool cannot be run from the Shell.
Deletable	If set, the drawer, project, or tool can be erased from the disk. If clear, the object is protected from deletion.

If the icon represents a project, there is a Default Tool gadget. This specifies the path to the tool that created the project. When the project icon is opened, the default toll is also opened to work on the project.

If there is a Comments box, you can add a note of up to 79 characters by selecting the text gadget next to Comments, entering the text, and pressing Return.

The Tool Types box specifies different startup options for some programs or files. Icon Tool Types are described in Chapter 3.

To save any changes made to the Information window, select the Save gadget in the lower left corner.

Snapshot

Snapshot saves the positions of all the currently selected icons. The next time you open the window, the icons that you selected appear in their saved positions. You can save the positions of several icons at one time by using drag selection or extended selection.

To save the position of an icon:

Select the icon.
Choose Snapshot.

UnSnapshot

UnSnapshot cancels the snapshot position of an icon. The next time you open the window, the icons are rearranged.

To release the snapshot position of an icon:

Select the icon.
Choose UnSnapshot.

Leave Out

Leave Out moves an often-used icon out of its original window and into the Workbench window for faster access. The file represented by the icon remains in its original drawer on the disk; only the icon is moved. The icon remains in the Workbench window, even if the machine is rebooted. This menu item cannot be used with disks or the Trashcan.

To use Leave Out:

Select the icon.
Choose Leave Out.

The icon moves into the Workbench window.

Put Away

Put Away returns an icon that was left out to its original drawer.

To use Put Away:

Select the icon.
Choose Put Away.

Delete

Delete erases files and their icons from your disks.

Caution
Use Delete with caution; you cannot retrieve something that was deleted.

To delete a file or drawer:

Select its icon. Use drag selection or extended selection to choose more than one icon to be deleted. Disks and the Trashcan cannot be removed with Delete.
Choose Delete from the Icons menu. A warning requester appears, listing the number of files and drawers currently selected. Verify that you want to erase permanently the items listed. Remember that if you delete a drawer, everything contained in it is also deleted.
Select the OK gadget. The icon and the files associated with it are erased from your disk. If you do not want to delete everything currently selected, select the Cancel gadget.

Format Disk

Formatting a disk prepares it for storing information. Format disks that are new and unformatted, disks that develop errors, or disks on which you wish to use different file system options.

Caution
Formatting erases all information on a disk. Be careful not to format disks that hold information that you do not want to lose, particularly your original system and software applications disks.

Select the icon of the disk to be formatted and choose Format Disk from the Icons menu. The Format window, illustrated in Figure 4-5, displays the current information about the disk. If the disk is already formatted, its volume name and the percentage of the disk currently in use are displayed. A text gadget allows you to enter a new Volume name for the disk.

Format Window

Five items can be selected (checked) in the Format window:

Put Trashcan	Allows you to put a Trashcan on the disk.
Fast File System	Allows the Amiga to fit more information on a disk. It is faster than the standard file system. Fast File System disks are incompatible with Workbench software releases prior to Release 2.
International Mode	Fully supports international characters in file names. We recommend that you set this option on. International Mode is incompatible with Workbench software releases prior to Release 2.
Directory Cache	Speeds up the opening of drawers, file requesters, and listings. This option is off by default. Disks using Directory Cache are incompatible with Workbench software releases prior to Release 3.
Long names

Fast File System, International Mode, and Directory Cache can only be specified for AmigaDOS disks. Selecting the Directory Cache option automatically selects International Mode. Disks created with the Directory Cache option can only be read by Amigas running Workbench Release 3.0 and above.

Quick format is for reformatting a disk that was previously formatted. You cannot format a new blank disk with Quick Format. Choosing the Quick Format option is faster than formatting the entire disk; however, it does not detect any read/write errors on the disk that could be eliminated by a full format.

When the disk is formatted, if you did not change he name in the Format window, it is labeled Empty. This name can be changed using the Rename item in the Icons menu.

Formatting Hard Disks

You must format your hard disk under the following conditions if:

It is a new unformatted disk.
You have a serious unrecoverable disk error.
You have repartitioned the disk.
You wish to use a different file system option on the disk, such as the Directory Cache option.

Before reformatting your hard disk, be sure to back up all important information from the disk.

The Ram Disk cannot be formatted. If you accidentally select the Ram Disk for formatting, a requester reports that there is a format failure and requires you to select Cancel.

If you have more than one disk icon selected, more than one Format window opens when the Format Disk item is selected from the Icons menu. The format windows open one on top of another so that only one Format window is initially visible. Drag the windows until all are visible. Be sure to check the Current Information field in the Format window for the intended Device and Volume names before allowing the format to continue.

Caution
Check the device and volume names carefully. If you accidentally reformat your hard disk instead of a floppy, you will eras all of your files.

Formatting Floppy Disks

The Amiga does not recognize floppy disks that are not formatted; therefore, blank disks must be formatted before anything can be written on them. Disks can be formatted at any time, including while running one or more applications. Disks usually have to be formatted only once.

To determine if a floppy disk is formatted, insert it into a floppy drive and check the disk icon on the Workbench screen. If the Amiga cannot recognize the disk, four question marks (????) follow the drive designation in the icon's label.

To format a blank disk:

Write-enable the disk and insert it into a floppy drive.
Select its disk icon when it appears on the Workbench screen.
Holding down the menu button, point to the Icons menu, move the pointer to the Format Disk item, and release the button.
If you have a hard drive on your Amiga, skip to Step 7. If you do not have a hard drive on your Amiga, at the requester insert the workbench disk into any drive.
When the Format program has been loaded from the Workbench disk remove the disk from the drive.
At the requester, insert the blank disk and select the Continue gadget.
In the Format window, change the volume name of the disk from the default Empty; choose whether to put the Trashcan on the disk an other options. Then select Format to continue.
A requester warning that all data will be lost if you continue the format appears on the screen. Select either Format or Cancel.
During the format a window is displayed that shows the percentage of disk that has been formatted. This window also has a Stop gadget that allows you to cancel the format at any time.

A disk that is partially formatted is not usable.

To format a disk as an MS-DOS disk through CrossDOS, you must have a CrossDos DOSdriver activated. If the PC0 DOSdriver is active, select the disk icon labeled PC0:???? for formatting.

Empty Trash

Empty Trash deletes the contents of the Trashcan. To use the Trashcan, drag an icon over the Trashcan icon and release the selection button. The icon is then stored in the Trashcan drawer until you decide to permanently throw it away with Empty Trash.

To delete an icon with Empty Trash:

Drag the icon over the Trashcan and release the selection button. If you open the Trashcan, the icon appears in the Trashcan window.
Make sure the Trashcan icon is selected (the lid is displayed open) and choose Empty Trash from the Icons menu. The Trashcan contents are deleted.

An icon can be retrieved from the Trashcan as long as Empty Trash is not chosen. Retrieve an icon by opening the Trashcan window and dragging the icon into any window. You may wish to open the Trashcan window in Show All Files mode and verify its contents before choosing Empty Trash.

The following rules apply to the Trashcan:

Icons can only be moved to a Trashcan on the same volume.
Disks cannot be deleted using the Trashcan.
The Trashcan cannot be moved into a drawer.
The Trashcan cannot be left out.
The Trashcan cannot be deleted with the Delete menu item.

Tools Menu

The Tools Menu initially contains only ResetWB for resetting the Workbench. Other Amiga applications and utilities can add items to the Tools menu. Consult the documentation that came with your applications software for information on adding items to the Tools menu.

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.

Command	Description
ACTIVATEWINDOW WINDOW	This command will attempt to make a window the active one.
CHANGEWINDOW WINDOW,LEFTEDGE/N,TOPEDGE/N,WIDTH/N,HEIGHT/N	This command will attempt to change the size and the position of a window.
DELETE NAME/A,ALL/S	This command is for deleting files and drawers (and their contents).
FAULT CODE/A/N	This command will return a human readable explanation corresponding to an error code.
GETATTR OBJECT/A,NAME/K,STEM/K,VAR/K	This command will retrieve information from the Workbench database, such the names of the drawers currently open and the icons currently selected.
HELP COMMAND/K,MENUS/S,PROMPT/S	This command can be used to open the online help and to obtain information on the supported menus, commands and command parameters.
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	This command is for manipulating the icons displayed in a window.
INFO NAME/A	This command is for opening the Workbench icon information requester.
KEYBOARD NAME/A,ADD/S,REMOVE/S,KEY,CMD/F	This command can be used to bind ARexx commands to key combinations.
LOCKGUI	This command will block access to all Workbench drawer windows.
MENU WINDOW/K,INVOKE,NAME/K,TITLE/K,SHORTCUT/K,ADD/S,REMOVE/S,CMD/K/F	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.
MOVEWINDOW WINDOW,LEFTEDGE/N,TOPEDGE/N	This command will attempt to change the position of a window.
NEWDRAWER NAME/A	This command is for creating new drawers.
RENAME OLDNAME/A,NEWNAME/A	This command is for renaming files, drawers and volumes.
RX CONSOLE/S,ASYNC/S,CMD/A/F	This command is for executing ARexx scripts and commands.
SIZEWINDOW WINDOW,WIDTH/N,HEIGHT/N	This command will attempt to change the size of a window.
UNLOCKGUI	This command will allow access to all Workbench drawer windows locked with the LOCKGUI command.
UNZOOMWINDOW WINDOW	This command will attempt to return a window to its original position and dimensions.
VIEW WINDOW,PAGE/S,PIXEL/S,UP/S,DOWN/S,LEFT/S,RIGHT/S	This command will change the position of the viewable display area of a window.
WINDOW WINDOWS/M/A,OPEN/S,CLOSE/S,SNAPSHOT/S,ACTIVATE/S,MIN/S,MAX/S, FRONT/S,BACK/S,CYCLE/K	This command will change, open, close or snapshot windows.
WINDOWTOBACK WINDOW	This command will push a window into the background.
WINDOWTOFRONT WINDOW	This command will bring a window to the foreground.
ZOOMWINDOW WINDOW	This command will change a window to alternate position and dimensions.

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:'

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

Parameter

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 WORBENCH.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 200x100 pixels. */
ADDRESS workbench
CHANGEWINDOW root LEFTEDGE 10 TOPEDGE 30 WIDTH 200 HEIGHT 100
 
/* Change the currently active window. */
CHANGEWINDOW active 20 40 200 100

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

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

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 provide 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. "6 26 12 6". 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 proportionally 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 proportionally 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 the name of the window to obtain information.

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

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

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

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:'

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

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

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.

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 is 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
 
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"
 
/* Remove the first menu item we added above. */
MENU REMOVE NAME test1

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 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

/* 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

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'

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'

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'

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 200x100 pixels. */
ADDRESS workbench
 
SIZEWINDOW root 30 WIDTH 200 HEIGHT 100
 
/* Resize the currently active window. */
SIZEWINDOW active 200 100

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

UNZOOMWINDOW command

Purpose: This command will attempt to 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

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

Moves 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

Moves 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

Moves the view left by about 1/8 of the window width. 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

Moves the view right by about 1/8 of the window width. 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

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" 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

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

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

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

Workbench Programs

Everything under this title is obsolete!

WBStartup Drawer

This drawer is obsolete!

The WBStartup drawer is provided to hold icons for programs that you want opened at the time the Workbench is started. For example, you may want the Clock program running when you reboot or power on your Amiga. Drag the icon for each desired program into the WBStartup window. The WBStartup drawer is empty by default.

Tool Types

Programs in the WBStartup drawer can include the following Tool Types:

DONOTWAIT	Normally the Workbench waits for one program to finish before it opens the next. DONOTWAIT overrides this, which can cause unwanted requesters after booting. DONOTWAIT does not take an argument.
WAIT=<seconds>	Specifies how many seconds the Workbench should wait before opening the next icon in the WBStartup drawer.
STARTPRI=<priority>	Assigns a priority to an icon so that it opens before or after other icons. By default, all icons have a priority of 0. The acceptable range is from -128 to +127; the higher the value, the higher the program's priority.

Expansion Drawer

This drawer is obsolete!

The Expansion drawer is used to store software drivers for additional hardware devices that you install on your Amiga. If a hardware device uses the Expansion drawer, it is explained in the documentation packaged with that product. To activate the new device, drag the icon for the device's software driver into the Expansion drawer and then reboot your system to make the device available.

AmigaOS Manual: Workbench Using

Contents

Workbench Screen

Workbench Window

Workbench Menus

Workbench Menu

Update software

Backdrop

Execute Command

Open volume

Redraw All

Update All

Last Message

About

Quit

Window Menu

New Drawer

Open Parent

Close

Update

Select Contents

Clean Up

Snapshot

Show

View By

Icons Menu

Open

Copy

Rename

Information

Snapshot

UnSnapshot

Leave Out

Put Away

Delete

Format Disk

Formatting Hard Disks

Formatting Floppy Disks

Empty Trash

Tools Menu

ARexx Interface

ACTIVATEWINDOW command

CHANGEWINDOW command

DELETE command

FAULT command

GETATTR command

HELP command

ICON command

INFO command

KEYBOARD command

LOCKGUI command

MENU command

MOVEWINDOW command

NEWDRAWER command

RENAME command

RX command

SIZEWINDOW command

UNLOCKGUI command

UNZOOMWINDOW command

VIEW command

WINDOW command

WINDOWTOBACK command

WINDOWTOFRONT command

ZOOMWINDOW command

Workbench Programs

WBStartup Drawer

Tool Types

Expansion Drawer

Navigation menu

Search