User Interface Style Guide

This page is currently being updated to AmigaOS 4.x. Some of the information contained here may not yet be applicable in part or totally.

Written by the technical experts at Commodore-Amiga, the Amiga User Interface Style Guide provides an introduction to, and in-depth explanation of, the issues programmers must understand to create the best user interface for Amiga applications. The book includes:

• the design principles and metaphors underlying Intuition, the Amiga's graphical user interface;

• guidelines for programs that use the Amiga's high-performance ARexx and Shell interfaces;

• detailed specifications on how to arrange the elements of the Amiga's user interface to make applications consistent, powerful, and easy to use.

This new addition to the Amiga Technical Reference Series covers the entire Amiga line of computers.

For the serious programmer who wants to take full advantage of the Amiga's impressive capabilities, the Amiga User Interface Style Guide is the definitive source of information on designing the front end to Amiga applications.

Preface

Like any written work with a distribution wider than a personal letter, this style guide attempts to be many things to many readers.

After much deliberation we developed the following profiles of the average reader: a current Amiga developer working alone or with one partner; a developer from another platform who would like to develop for the Amiga; a first-time developer; a graphic artist designing a user interace for a developer; a team of developers working for a medium-sized company...the list goes on.

So our intention was to write a manual that introduced the Amiga from basics - in terms a non-technical reader could understand. The GUI sections were especially targeted for the layman. Other sections, such as the ARexx chapter, were structured more like reference guides since they will likely be used by readers with more of a technical background.

Release 2 Assumed

This book was written with Release 2 of the Amiga operating system in mind. All functions, examples and elements herein refer to Release 2.

Amiga Mail Updates

Of course this manual, especially in its first edition, isn't the final word on style for Amiga applications. Interim updates may be published in Amiga Mail, the bi-monthly newsletter for Amiga developers.

nyone may subscribe to Amiga Mail. If you live in North America and want more subscription information, send a self-addressed stamped envelope to:

   CATS - Information
   1200 Wilson Drive
   West Chester, PA 19380-4231

Elsewhere, write to your local Commodore office.

Introduction

The purpose of this book is to describe how the user interface of a standard Amiga application should look and operate. It is intended to be read by current developers as well as developers who are considering writing and/or designing application software for the Amiga.

This book assumes some familiarity with computers and their interfaces in general, and with the Amiga's graphic user interface (GUI) in particular, but, for the most part, you do not have to be a programmer to understand the material.

Only the behavioural guidelines for an Amiga application are presented here. The details of how to implement them are covered in other volumes of the Amiga [Technical] Reference Series.

What's In This Book

This document provides the following information:

• the benefits of a standard user interface;

• an overview of the components of the Amiga user interface;

• specifications showing how to use the components of the Amiga user interface to create a standard Amiga application.

The Amiga hardware and system software provide the basic building blocks of the user interface: a mouse and pointer, windows and icons, menus and requesters and more. But it is your software that combines these elements and ultimately determines how the machine will be used.

Non-Stifling Standards

In one sense, this style guide can be considered a book of rules for you to follow when designing application software for the Amiga. It describes the best ways to combine and use elements of the Amiga system software to communicate with the user.

Unlike rule books such as a state's driving code or a company's employee handbook, the style guide's originators don't suggest penalties for violators. In fact, penalties of that sort would be counterproductive. The aim of this book is to establish standards for Amiga applications without stifling creativity. New versions of the Amiga and new types of applications will probably require refinement and expansion of these standards in the future.

That's not to say no penalties exist. In a free, competitive market the only real penalties are financial and self-inflicted. This book has been created under this premise: standardized software will be better for reasons described later in this chapter, and thus, in a competitive situation it should sell better.

In short, these standards were devised to improve your program and the Amiga platform in the eyes of the user.

This manual describes the best ways to communicate with the user.

A Point on the Horizon

No one expects every application to conform to every one of the rules and guidelines in this manual.

These rules have not been created in a vacuum. Many of the standards discussed in this manual have been culled from experience - experience gained through the multitudes of Amiga applications released since the Amiga's inception. The writers of this document first looked at what has worked best in specific applications and then tried to transform that raw experience into a standard, efficient and accepted way to do things on the Amiga. The trick was to come up with ideas that worked well and would work well in a variety of situations.

Clearly there will always be exceptions to these rules. Even applications created by Commodore may not comply with every idea in this book.

The hope is that the idealized application described in this manual will be like a point on the horizon you keep in sight throughout the development of your very real program.

The rules in this manual describe an idealized application not yet created.

Some Perspective

The user is the most important part of any application. In the past, improving the speed or increasing the capacity of application software has been a major focus of computer programmers. The idea of emphasizing the user interface of a computer system over its performance and capacity is a relatively recent innovation in computer history.

Historically, most users of computer systems were technical people who could tolerate the exacting requirements of expensive computer hardware and their "unfriendly" application designs. Complex commands had to be remembered and typed into a terminal in the proper sequence and thus required these early computers to have a professional staff in order to run them. This made sense because the computing hardware of that era was much more expensive than human labour. The user was there to serve the needs of these expensive machines.

The advent of microprocessors and the long-term trend to lower-priced computers has changed all that. Today's computer user is trying to get work done. The user probably does not know much about computers and may not even know how to type. The human-machine interface has been reversed, and now computers must serve the needs of the user.

The User's Needs

The user's needs are simple:

• the operation of the software should be predictable;

• learning the software should be easy; the software's functions should be easily scannable;

• the software's operations should be consistent throughout tools, applications and similar objects;

• feedback should be provided to the user, so he knows what has happened and what he can do;

• the software should adapt to the users's level of experience.

The user needs: predictability, intuitiveness, accessibility, consistency, feedback, adaptability and simplicity.

Consistency

The user's needs listed above really all combine into one: consistency. If your interface is consistent with the model, it becomes predictable; if it can be scanned easily, it provides feedback; if it provides feedback in a reasonable manner, the user always feels comfortable and can master increasing levels of complexity.

Consistency in a user interface allows the user to apply previously learned knowledge to each new application. The user will spend less time figuring out how to get work done, and can therefore be more productive. Learning a new application is much easier if it works just like one the user already understands.

The Amiga is a multitasking computer that allows the user to run more than one application at a time. This makes consistency even more important because the user can easily switch from one application to another. Consistency between applications allows the user to make this switch without having to make a "mental jump" between one way of working and another.

Following standards also makes new applications more familiar; thus the user will probably be less afraid of inadvertently wiping out data or making other non-recoverable mistakes.

Once again: predictability, intuitiveness, accessibility, consistency, feedback, adaptability and simplicity.

Filling the Needs

A graphic user interface (GUI) is current the best method available for simplifying the user interface and meeting the needs of the user.

Amongst the first computers to use GUIs were the Xerox Star and Apple Lisa. Based on pioneering research performed at the Xerox Palo Alto Research Centre in the 1970s, these computers allow the user to issue commands with a mouse and pointer. Resources represented by graphic icons can be activated by pointing to them with the mouse, and actions can be performed through mouse-activated menus.

GUIs provide immediate feedback and scanning ability, so users can tell what their options are and don't have to memorize commands. They allow for enormous growth and adaptability of an application, because levels of functions and commands can be buried yet still be graphically accessible. In short, they provide a user interface that lets the user operate, without learning, the computer - in much the same way that the average driver doesn't need to be versed in internal combustion.

By utilitizing standardized tools and objects provided in the GUI, programmers are less likely to invent needlessly different ways of doing things. The interface becomes predictable and consistent.

The Amiga

The Commodore Amiga is a further refinement of this philosophy that puts the needs of the user foremost. Like many other systems, the Amiga has a GUI with a mouse, pointer, windows and menus which makes it easier for users - especially beginners.

But the Amiga also offers two other built-in interfaces: a text-oriented interface, the Shell, an an inter-process scripting language, ARexx.

Together, these three interfaces provide a powerful and flexible environment for both the novice and the expert. In fact a philosophy for the design of the Amiga user interface might be "Power to the User".

Developer-Oriented Benefits to Standarsd

The obvious beneficiary of a good user interface design is the user. He can pick up a new application and learn how to use it, scan its functions to see what it does, apply old knowledge to cut the learning curve, and so on.

But a disciplined approach to designing and building an application also has enormous benefits for the software developer.

Market Acceptance

Marketing is simplified when a product "belongs" in a comfortable environment, sharing features and tools with other popular applications. A user trying out a demo version of your software and your competitor's software in a store rarely has the time to learn a new way of doing things. A familiar environment and controls that work in a predictable manner will allow him to experience what you are really selling - how well your application does its job.

Some real market-oriented reasons exist for standards too.

Coexistence

By following the recommended guidelines, applications acquire the ability to inter-operate, thereby increasing each application's value. When applications can inter-operate and share data as well as they can on the Amiga, users can combine in off-the-shelf software packages to create custom solutions for the work they want to do with the Amiga.

Secondly, it is important that applications behave well in a multitasking environment. Sticking to the standards assures peaceful coexistence.

Easier Creation and Maintenance

Design is also simplified when you follow standards.

For one thing, Release 2 of the operating system features toolkits such as GadTools which provide you with pre-coded elements of the GUI. Even when elements aren't provided "prefab", standards allow you to spend less time devising and designing environments and more time working on the actual operations of your program. It also allows you more time for testing. For instance, if you are designing a CAD program, chances are that it is computer-aided design which really interests you. Instead of spending a lot of time working on gadgets to control your application, you could be spending more time working on the actual CAD operations.

Also in the absence of any stanards, progress is more difficult because each application will require an individual upgrade plan.

Power to the User

Clearly, this book was created to sell the idea of standards as much as to simply present those standards. But the reasons for those standards goes beyond an innate need for order originating from some corporate boardroom. The reasons set forth here have been set forth honestly in an attempt to provide more power to the user. This book intends to make clear what features of the user interface will help to make the interface simple - and predicatable - and consistent - and adaptable - and intuitive. This in turn should improve the Amiga market for all of us.

Some Basics

The Amiga is a true multitasking system with three built-in interfaces:

• a graphic user interface (GUI);

• a command line interface [CLI] (the Shell);

• a scripting language that can handle inter-process communication (ARexx).

Of these three interfaces, the GUI dominates. By default, the Amiga presents the user with a graphic interface, Workbench, upon startup. Likewise, even a simple Amiga application will generally present a graphic interface of some sort; text editors, for instance, usually include mouse-driven gadgets and menus.

In addition to the GUI, users can control the Amiga through the Shell. The Shell is a text-based interface that preserves the best features of the "old way" of operating computers - by typing in commands. The Shell trades the GUI's ease of use for a finer level of control and greater power.

The GUI is the Amiga's default interface.

With Release 2 of the operating system came a third way of interfacing with the Amiga: inter-process communication (IPC) via ARexx. Simply put, ARexx is a scripting language, but it also acts as a central hub which applications can use to send data and commands to each other. ARexx allows software created by different companies to interface, letting the user create custom applications by integrating off-the-shelf software products. For example, with ARexx it is possible to set up a telecommunications package to dial an electronic bulletin board, download financial data, and then pass that data to a separate spreadsheet package for statistical analysis - without user intrevention other than the original scripting. Arexx is based on REXX, an IPC language used in various forms across many platforms.

Many users consider the choice of interface to be one of the best features of the Amiga. Not only does it offer the user the freedom to choose his favorite means of interacting with the Amiga and with your program, it's also an effective way to provide the right tool for the job and user's level of expertise. For these reasons, your application should support all three interfaces in the manner described in this manual.

Support all three of the Amiga's interfaces.

Basics of the Operating System

The following are basic concepts to keep in mind throughout your design work on the Amiga:

Design for the Novice

Designing for the lowest common denominator does not mean your application is doomed to mediocrity. In most cases it just means pondering a little longer on how to solve a problem or present a procedure so that almost anyone can grasp it easily. Even power users appreciate it when you give them simple solutions for such things as hard disk installation or navigation through procedural steps. Conserve your user's energy for creative tasks.

Conserve the user's energy for creative tasks.

Let the System Work for You

In general, if the system will do something for you, let it. For example, GadTools provides pre-programmed gadgets for use in your application. If one of these gadgets suits your needs, use it instead of coding your own. Two other examples of using this built-in support are:

• using Intuition (see #Basics of the Gui) to provide many functions of your application's GUI;

• using DOS ReadArgs() to provide support for argument passing.

If the system will do something for you... let it.

The Amiga's Resources

Remember that the Amiga is a multitasking system. Any time you allocate a part of the system for your use, you prevent other tasks from using it.

Try your best to economize your use of shared resources. If possible, only obtain a resource when needed and free it as soon as you are done. This applies to just about every computing activity your application can perform. There are only limited amounts of RAM, serial ports, printers and disk drives for all applications to share.

Your application should provide controls that allow the user to temporarily suspend usage of any non-shareable resource it may use, such as the serial or parallel device. For example, a MIDI application should allow the user to suspend serial port usage so he can switch to a terminal package and download a new sample without having to exit the MIDI application.

Speech and Sound

Speech and sound can be excellent ways to provide feedback to the user, especially if the user is visually impaired or if your application includes lengthy processes during which the user might walk away from the system.

However, a significant number of users may be hearing impaired, so don't use sound and speech as the only cue. Use it in conjunction with other cues such as position, size and rendering.

Sounds can be annoying. Provide a means for the user to turn off sound [and/or] speech.

Provide a means for the user to turn off sounds and/or speech.

Controls

It may be a good idea to provide additional controls so the user can modify the speech or sound in your program. Consider this if speech/sound is integral to the application. If they are secondary, you may just be over-complicating the controls in your program.

Closing Down the Workbench

If your application needs more memory than is available, it may attempt to close Workbench.

If your application does this, it should allow the user to re-enable Workbench from a menu item if more memory becomes available. A preference setting should also be made available so the user can specify that Workbench should always be closed (or not) on entry to the application.

If your application closes Workbench, it must reopen it again before exiting.

Defining Your Basename

A basename is a short, one-word name that you assign to your application. It's usually (and preferably) the same word as the name of your program's executable - the word a user types into the Shell in order to run your program.

All user-accessible names from your program should be built from the basename. These include such things as ARexx ports, public screen names, and configuration settings names.

For example, a database program called MondoBase may have the basename of MBase. Users running the program from the Shell would type MBase on the command line. The program may open on a public screen named MBase.1 with an ARexx port of the same name.

Basenames should be logical to the user, easily remembered and short. Making it too short, however, could raise the likelihood of conflicts with other programs. If MondoBase's basename were simply M, it could conflict with MusicBoard's basename.

Basics of the GUI

For a sytem with three interfaces, a relatively large section of this book is devoted to the GUI. This isn't surprising when you think about the popularity of GUIs and the fact that a GUI designer needs to worry as much about form as function.

The Amiga GUI has two parts: Intuition and Workbench. As a developer, you will be more concerned with Intuition. It consists of the function libraries and tools you will use to create and run GUIs for your application.

Before talking specifically about the elements of the Amiga GUI (in the next five chapters), some basic elements and techniques need to be discussed.

Metaphor

One of the reasons for the success of GUIs is that they greatly reduce the need to memorize commands and command structures. One technique used to accomplish this is the use of metaphor - GUIs try to mimic the traditional work world in some way.

By presenting what can be frighteningly complex workings as familiar, real-world objects and activities, even novice users can understand and use a computer quickly. Hierarchical filing systems become drawers. RAM caches that spool to disk become clipboards. Pulling an ASCII clip from a buffer into a document becomes pasting.

To employ a metaphor in your application, look for some common physical system that is analogous to the behaviour of the application.

For example, a 3-D modelling package could be designed to work on wire-frame objects as though they were actually physical objects. The user could rotate the object by "grabbing" a corner of the object and pulling just as one would grab the corner of a real object.

Of course, it is not always necessary or even desirable for every interface to be modelled after some physical object.

Object-Action

Most of the popular GUIs today encourage the use of object-action methodology. This simply means that first the user selects the thing he wants something done to, then he selects what he wants to do with it. For example, first he clicks on the object he wants deleted then he chooses the delete function, rather than choosing delete then clicking on the objects to be deleted.

This is done mainly to prevent modality. Modes are generally avoided in GUIs because they can easily become restrictive and confusing to the user. If the user were to select delete before selecting the object(s), he would be in delete mode and could accidentally delete something he wanted to save - especially if he were to go away and come back later. There is also the problem of how to indicate the last object to delete. In general, any mode is limiting and should be avoided if possible.

Focus

When a user is looking at a computer screen, he is most likely to concentrate his attention on one particular spot. In a word processor, he will most likely be looking at the cursor. Or in a CAD program, the focus may be the currently selected line or polygon. Very often, the pointer itself is the focus.

It's important to identify the user's focus because this can be a very effective channel of information. For example, you can animate or change the appearance of the focus object to indicate some change in the program's state. The wait or busy pointer is an example of this. If the wait pointer's clock imagery appeared in the title bar instead of on the pointer, it would be far less effective.

Feedback

Users expect to see an immediate reaction to every action. Even if the action will take some time, they expect to see some indication of "I'm working on it" such as the normal pointer changing to a wait pointer.

Try to provide feedback through as many appropriate media as you can. For example, when a user drags a note in a music package, he could hear the pitch change as well as see the note move. After all, the visual graphic of the note is only a representation of the sound of the note - and that's what the user is really interested in.

It's usually easy to provide instantaneous feedback to simple actions, but for more complex or time-consuming actions, a surrogate feedback may be necessary. A familiar example of this is the way windows are dragged on the Amiga - you don't drag a window, you drag an outline of it. Another example of feedback on time-consuming activities is the word processor that refreshes just the line being worked on as the user is typing, and the whole display whenever there is some processing time to spare. This gives the illusion of responsiveness, which from the user's point of view is as good as the real thing.

When the user attempts an action, provide feedback.

Color

Color is a very powerful medium of communication. Be conscious of what message you are communicating.

Keep in mind that simple images with fewer colors usually work better than complicated colorful ones. When choosing default colors for an application, do not use intense combinations like blue/yellow, red/green, red/blue or green/blue. Use subdued colors instead of fully saturated colors. Color can set the mood of your program and that mood should be one that the user can live with for extended periods of time.

Give Controls

For all the screens you set up within your application, provide the user with the ability to load, save and edit the colour palette. When the user makes a change to the color palette, examine the new palette to assign the appropriate colors for rendering.

Color as a Cue

Be consistent when using color to indicate meaning. Window backgrounds should be in the background color, text in the text color and headings in highlighted text.

Beware of using color alone to convey information - especially in small areas of the display. Some users may work on a monochrome display. Keep in mind also that many people are color blind. For these reasons, try to reserve the use of color only as an extra cue, used in conjunction with other cues such as position, size and rendering.

Don't use color as the sole cue - some users work in monochrome.

Check Visibility

The Amiga's Preferences editors allow users to run their applications in two colours. Certain high-resolution monitors have only grey-scale displays. Because of these cases, if your application can open on Workbench or a public custom screen, you should check that your graphics and text can be read on a monochrome or grey-scale display.

Elements should be visible, should continue to provide visual feedback, and should be recognizable as the same element whether in color or monochrome. Basically, you should make sure that all your functionally significant colors contrast with adjacent functionally significant colors. It's more a matter of the color's brightness or luminance than the actual color itself.

Commodore's high-resolution grey-scale monitor (A2024), for instance, uses patterns made up of its four basic greys to make more shades when running in medium and low resolutions. At these resolutions, things look best if you choose a color that maps to a solid, not patterned, grey. But these colors are not obvious.

One palette that produces solid greys follows:

   Colour 0:  Light Grey, RGB=10,8,6
   Colour 1:  Black, RGB=0,0,2
   Colour 2:  White, RGB=15,15,15
   Colour 3:  Dark Grey, RGB=7,7,9

Fonts

Users can specify which font the system should use for the Workbench icon font, the screen font (the preferred system font) and the system default font (a default monospaced font). These are selected with the Font Preference editor in the Workbench's Prefs drawer.

Your application should try to adjust itself to whatever size the user may select. Menus, windows, requesters and gadgets must all be adjusted to allow the various text sizes to fit.

Keep in mind that the chosen font may be monospaced or proportionally spaced, and not every application can handle a proportional font. A spreadsheet, for example, depends on the font being monospaced to properly handle the columnar data it manipulates. If your application needs a monospaced font it should honour whatever the user has chosen to be the default system font - that font is guaranteed to be monospaced.

If your application can handle a proportional font, however, it should honour whatever the user has chosen to be the screen font.

Internationalization

Since the Amiga is sold in a world market, internationalization is an important design factor in your application. One of the most important and fundamental issues to consider when thinking about internationalization is the difference in length of the text between English and any other language.

English is one of the most terse language, and when converting English to, say, German the text the text is bound to grow 30-50% in size.

Another thing to keep in mind is the desirability of building a text table that is centrally located so that it can be adjusted by the user. Do not scatter embedded text throughout your application; consider putting it in a file instead. This way, the text can be easily localized by updating one central table, or even by loading a new text table from disk.

Don't make every text item adjustable. For instance, if your application incorporates a procedural language or ARexx keywords, do not allow these special words to be localized. To do so would severely hurt the ability to share scripts between international users.

If your application provides database-like operations that involve money, numbers, telephone numbers and addresses, remember that these sort of fields vary in usage from country to country. The table below lists some of the differences.

International Formats

Language	Date	Time	Hours	Decimal	Thousands Separator
American English	mm/dd/yy	hh:mm:ss	12 hr	period	comma
Australian English	dd/mm/yy	hh:mm:ss	12 hr	period	comma
British English	dd/mm/yy	hh:mm:ss	12 hr	period	comma
Canadian French	dd/mm/yy	hh:mm:ss	24 hr	comma	space
Danish	dd/mm/yy	hh:mm:ss	24 hr	comma	period
Dutch	dd-mm-yy	hh:mm:ss	24 hr	comma	period
Finnish	dd.mm.yy	hh:mm:ss	24 hr	comma	space
Flemish	dd-mm-yy	hh:mm:ss	24 hr	comma	period
French	dd.mm.yy	hh:mm:ss	24 hr	comma	space
German	dd.mm.yy	hh:mm:ss	24 hr	comma	period
Italian	dd-mm-yy	hh:mm:ss	24 hr	comma	period
Norwegian	dd-mm-yy	hh:mm:ss	24 hr	comma	space
Portuguese	yy/mm/dd	hh:mm:ss	24 hr	comma	space
Spanish	dd/mm/yy	hh:mm:ss	24 hr	comma	period
Swedish	yy-mm-dd	hh.mm.ss	24 hr	comma	space
Swiss French	dd.mm.yy	hh:mm:ss	24 hr	period	apostrophe
Swiss German	dd.mm.yy	hh:mm:ss	24 hr	period	apostrophe

It is best to build internationalization into your application from the start.

The 3-D Look

Release 2 of the Amiga operating system features a three-dimensional look to its GUI. Whenever possible, elements are drawn so that light appears to come from the upper left of the display with shadows cast to the lower right. This gives the illusion of depth.

The outside border of a raised object has thin lines forming the top and left sides; dark lines for the bottom and right sides. Reverse these colours for a recessed image.

Using this simulated depth, you can make images appear to be standing out or recessed in the display, thus giving the user a context cue at the same time.

Fig 2.1: Raised and recessed images.

Fig 2.2: Closeup view of 3-D box corner with a pixel grid superimposed.

If an icon or gadget appears raised, this means it is available for use or modifiable. If its default appearance is recessed, this means it is unmodifiable or for display purposes only.

Another context cue: when a user clicks on an icon or a button-like gadget, it should change from a raised image to a recessed, highlighted image. This goes along the basic idea of providing feedback that the attempted action (clicking on an action gadget, for example) has worked.

Objects that highlight should show distinctly different imagery between highlighted and non-highlighted states. One convention used by Workbench is to display the image in complementary colors.

Ghosting

When a control is unavailable for selection, it should be obviously unselectable. Do not allow the user to select something that does nothing in response.

Fig 2.3: Examples of non-highlighted and highlighted gadgets.

Intuition will automatically display a ghosting pattern - a grid of dots in the "shadow" colour - over an unavailable control. If, however, you need to do it manually, follow the example shown below:

Fig 2.4: A normal and enlarged view of a ghosted gadget.

GadTools

If you are developing for the Release 2 environment, you don't need to worry about incorporating the 3-D look into your gadgets - GadTools will do it for you. GadTools is a toolkit that supplies pre-programmed, standard application gadgets for use in your application.

Whenever possible you should let GadTools work for you. Even beyond the standardization of function it provides, this tool frees you to spend more time and effort on the crux of your application.

The System as your Guide

In the absence of any system-provided support, or if the special needs of your application require you to build your own elements, use existing system elements as a general guide to style and function.

The Mouse

Having graphics on the screen that represent something to the user is good, but you need a way for the user to interact with those graphics. Although a number of devices can be used to do this on the Amiga (including a touch screen, a joystick or even the keyboard), most often the user will interface with the GUI via a two-button mouse.

Using a mouse can become a seamless, unconscious act for most users in the same way that a typist can type the letter "k" without consciously thinking: "Let's see...right hand, third finger from the right." Typists are able to do that because typewriter manufacturers make their keyboards consistent. Likewise, it is important that your software follows rules of mouse usage so that the GUI is "mechanically" consistent.

The standard Amiga mouse has two buttons: the selection button (left) and the menu button (right).

Fig 2.5: The mouse buttons.

The selection button (the left mouse button) selects or operates gadgets, icons, windows and screens. It can also be used to select special objects unique to your application (eg. the note object in a music package) or to set the pen "down" in a drawing operation.

The menu button (the right mouse button) actives the menu system and allows the user to choose a menu item. The menu button may also be used to abort a selection button operation. For example, the user is dragging a window around by holding [down] the selection button and moving the mouse. If he decides that this action was a mistake and wants the window back where it was originally, he can press the menu button and the window should snap back to its original position.

Follow basic rules for the mouse so that its use becomes instinctive.

Activating Tools

Clicking on a tool gadget, such as the Fill tool in a paint package, with the selection button should activate the tool. If appropriate, a double-click could activate a settings editor for the tool so that the user can fine-tune the way the tool works.

Triggering a Process

When the selection of something will trigger a process, the action should occur on the release of the mouse button - not the downpress. This way the user can change his mind about the operation and move the mouse away from the object before he releases the button.

Actions should be triggered on the release of the selection button.

Current Objects

When an object is selected, that object is considered to be the current object. Some examples are: the highlighted section in a CAD program, a note in a music program, or the character under the cursor in a word processor. When the user chooses an action (via a menu item, for example) that action is carried out on the current object. For example, in a desktop publishing program the user can click on a text box and make that the current object. If the user selects an action such as "erase" or "copy", that action is performed on that text box.

Shift Selecting

In some instances, a user can select more than one item at once by using shift selection. The user clicks on an item with the selection button. While holding the Shift key down, the user can then select any number of objects. The result is called a @{i}selected group@{ui}. Some examples of objects that could be grouped are: columnar text boxes in a DTP program, notes in a music program and text items in a list.

Some actions that can be carried out on current objects will still apply to a group, such as copy or delete, but others may not. For example, you can have a requester showing the attributes of a current object but it would be difficult to have such a requester for a group of dissimilar objects.

Dragging

Objects can also be grouped by dragging. Dragging, a common mouse operation on many platforms, involves holding the selection button down while moving the mouse. There are two types of dragging: contiguous and non-contiguous.

A good example of contiguous dragging can be found in a word processor. The user clicks on a letter then, without releasing the selection button, moves the cursor somewhere else in the text. The first letter he clicked on becomes the "anchor" point and all the text between the anchor point and the point where the selection button was released should be highlighted. The highlighted text is now a selected group.

Objects can also be grouped contiguously by the use of the marquee. When the mouse is dragged on Workbench, for example, an animated dotted line, the marquee, marks the area covered by the mouse. All the icons within the marquee will be selected.

Fig 2.6: Grouping by using the marquee.

Less common is non-contiguous dragging. One example of this is a program that allows the user to drag select a section of text and then deselect individual lines by clicking on them. The deselected line can be in between two selected lines.

In both styles of dragging, the display should scroll automatically if the mouse goes beyond the boundaries of the display region.

Four Ways to Highlight Text

There are four methods you can use in your program to highlight text: dragging (see the previous section), extended selection, multiple-clicking and selecting all.

With extended sselection, the user clicks the cursor in the text (this becomes the anchor point), then shift-clicks the cursor at another place in the text. The area between the anchor point and where he shift-clicked will be highlighted. Note that the user can adjust the window's scroll bar between clicks and thus highlight a very wide range.

If you employ the multiple-click method, the user can select a word by double-clicking on it, or select a paragraph by triple-clicking on it. (Note: these are not timed clicks.) A "word" can be defined simply as anything with spaces around it, or you can use a more complex definition. A fourth click should revert back to a normal cursor.

Selecting all would feature a menu item that would select all the characters in the document. This action shouldn't select the document as well; that is, any actions chosen for the selected group should not act upon the document itself. For example, if the user chooses select all and then erase, all the characters should vanish from the document's window but the window should remain.

Current Objects vs. Selected Groups

Current objects and selected groups should not co-exist in the same application. In other words, no matter how many projects your application may run simultaneously, there should be only one current object or one selected group at any one time. If the user has a current object, then creates a group through shift selection, there should no longer be a current object.

There should only be one current object or one selected group at one time.

Selection Context

Confine the user's ability to select to a single context or "level". For example, don't let the user select documents and characters at the same time. You can allow him to select any numbers of characters in a document, or any number of documents, but not both at once.

The Pointer

The Amiga uses a pointer that the user can redesign.

The default pointer looks like this:

Fig 2.7: The default pointer with a superimposed pixel grid.

Your application can use a custom pointer instead of the standard. The arrangement of color intensity in your custom pointer should be consistent with that of the standard pointer - especially since two different applications can share the same screen.

Technical note: here's how the colours should be set up:

   Colour 0   Transparent
   Colour 1   Medium intensity
   Colour 2   Darkest
   Colour 3   Brightest

The pointer should be framed by either color 1 or color 3 to ensure its contrast on most screens.

Waiting

When your application is busy with a task and temporarily cannot accept input, another pointer, known as a wait pointer, appears.

Currently the wait pointer used by Workbench is not accessible by developers. Shown here is a pixel-by-pixel view of Workbench's wait pointer if you want to make yours look similar.

Fig 2.8: Workbench's wait pointer with a superimposed pixel grid.

If the wait is for a measured amount of work, such as in a ray-tracing program, your application should provide a requester that shows the progress of the activity. The progress requester should have a gadget on it allowing the user to stop the activity.

Fig 2.9: A sample progress requester indicating the progress of a time-consuming activity.

Use a progress requester like the one shown on the previous page instead of an animated pointer to indicate that the application is busy. Here's why: A man is rendering a simple object with a ray-tracing package. While waiting for that to finish, he decides to write a letter in a word processing package that opens on the same screen but in a different window. If the ray-tracing program displayed a progress requester, he could see when the rendering was done. But if it used an animated pointer, that pointer would disappear when he clicked in the word processing window.

Don't tie a wait pointer to the progress requester (i.e. when the user clicks on the progress the pointer changes to a wait pointer). If you do, the user may think he can't activate the "Stop" gadget.

Don't show multiple cycles in the same progress bar. For example, if the progress bar reads "Calculating...", fills up and then reads "Rendering...", you've falsely built up the hopes of the user. Instead, use multiple bars if knowing the progress of each task is important to the user, or a single bar that is filled only once if knowing when the job is done is all that is important.

Pointers with Purpose

Pointers can be used to give the user a context cue.

For instance, if your application supports different tools, such as the sketch tool or the fill tool in a paint program, the pointer imagery can reflect the currently selected tool.

Or, if your window is divided into distinct areas with different uses, it might be more appropriate to have the pointer image reflect its current purpose based on its position. The pointer for a CAD program, for example, might be a cross-hair while it is over the drawing area, but turn into the standard arrow when it is over the control panel area.

Resolutions

The Amiga hardware and software offers a variety of resolutions for the user to choose from. The resolution refers to the number of pixels in that mode. For instance, a common Amiga resolution of 640x200 refers to the number of pixels in height and width, respectively.

If you allow the user to choose resolutions, make sure that your GUI fits comfortably on whatever screen the user has chosen. A good way to do this is by checking it on a least common denominator resolution - a non-interlaced, non-overscan NTSC screen (640x200) with a Topaz 8 font. You don't need to set these as defaults; just make sure that what you create will look and function normally when set to these settings.

If your original target audience will most likely be using PAL, it's still a good idea to design with a 640x200 NTSC screen in mind so your distribution isn't limited later.

Respect the choices the user has made in his Preferences setup for resolution and how large a display should be set up.

Design your GUI on a 640x200 screen with the Topaz 8 font.

Technical note: If your application is text-oriented, make sure you use the text overscan setting. If it's graphic-oriented, use the "standard" overscan setting. The user can set both of these by using Workbench's Overscan Preferences editor.

Screens

By organizing raw data into neat and friendly metaphors, GUIs make using a computer more intuitive and comprehensible. Still, sifting through the many possibilities in an effort to get to a desired task can often lead the user to wonder: "Where am I?" and "What should I do next?" The fact that the Amiga multitasks - that is, it allows the user to run a number of applications at the same time - only increases the need for strong context cues.

When your application is run, it indicates the new context by either opening up in a window or on its own screen. Thus, screens and windows provide the main cues that tell the user where they are at any given moment.

Defining Screens

Screens are unique to the Amiga. Other platforms have a single environment filling the monitor view or perhaps extending beyond that in height and width. On the Amiga, a user can have multiple screens, each an environment unto itself with its own palette, resolution and fonts - running at the same time.

Typically, screens are at least as wide as the monitor display and have a single title bar at the top of the screen which is shared by all the applications that operate within that screen. It is possible, however, to have screens that are larger than the display area (known as virtual screens), or to have a screen that is not as tall as the monitor display. Applications will sometimes use the shorter screens as control panels in a different resolution than the display area. Workbench is the default screen a user is presented with upon booting the machine.

Screens cannot be resized. New screens usually appear in front of existing screens. The user can access screens in the back by dragging the front screen down or flipping through the screens by using the screen depth gadget or keyboard combinations.

Fig 3.1: The Workbench Screen.

Types of Screens

Your application can open on one of three types of screens: the Workbench screen, a public custom screen that your application shares with other programs, or your own private custom screen.

When your application uses the Workbench screen, it opens a window on the Workbench, using the palette, resolution and fonts that are defined in the Workbench Prefs.

Fig 3.2: A text editor open on the Workbench screen.

The Workbench screen is a public screen - that is, it can be used by any application. If your program needs a different resolution or palette than the user has chosen for his Workbench preferences, it should open on a public custom screen unless its requirements are restrictive enough to warrant a private custom screen.

By keeping your custom screen public, you allow users to access other, perhaps supportive, applications without having to flip your application to the rear. Or, if the user is already running an application on a public screen with the proper palette and resolution requirements, he can open your program on that screen.

Fig 3.3: A text editor opened on an interlaced public custom screen.

A private custom screen is one that you set up to your specifications and which only your application may use. Private custom screens should be used only when your application has unusual rendering or resolution requirements, or when you need to be able to operate on the whole screen directly. An example of this would be an animation program that needs to switch viewports rapidly in order to get smooth motion.

Technical note: If your application opens a custom screen, make sure you redirect requesters to the custom screen - this applies to relevant DOS requesters as well as your application's requesters.

Respect User Choice

Let the user decide, if possible, whether to open your application on Workbench or on another screen. If he decides to open it on a custom public screen, let him choose whether it will be a new screen or one that has already been created by a different application.

Likewise, respect choices the user has already made. All custom screens, whether public or private, should default to the basic parameters established in Workbench's Preferences, unless your application has special requirements.

If your application provides overscan capabilities you should respect the settings that the user has established in the Overscan editor found in Workbench's Prefs directory.

Screen Design

Screens should have a depth gadget. If you have room, you should try not to obscure the screen depth gadget from view by opening windows that cover up the screen's depth gadget.

The screen your application opens on should open in front of any other screens that are open.

Auto-scrolling

Applications that open screens larger than the display area should provide the ability to auto-scroll. Moving the mouse to any of the display bounds should automatically scroll the screen to show more information in that area.

Screens that open larger than the display area should offer an auto-scrolling function.

Naming Your Public Screens

Public screens are identified by their name. To name a public screen, use your application's basename (see Defining Your Basename) followed by an invocation count. The name should be in upper-case.

For instance, a terminal package with the basename Axelterm that opens its own public screen should name the screen AXELTERM.1. On a system with a multi-serial port card, the user may decide to run a second copy of the package. That second public screen should be named AXELTERM.2.

Some applications may use two screens during the same invocation of the program. For example, a paint program named VanGogh (with the basename VGOGH) may use one screen for the "canvas" and another screen with a different resolution for the control panel. In that case, the screens could be named VGOGHPAD.1 and VGOGHPANEL.1.

Windows and Requesters

The last chapter noted that context cues on the Amiga come in the form of screens, windows and requesters. Whereas screens represent general environments, windows and requesters show the user where he is much more specifically.

A Safe Place to Click

Try to provide a safe place on each window where the user can activate it without altering any previous work. For instance, if the user were to return to a text processor window after checking his email, he should be able to activate the window and not have his cursor move. The title bar is a good area for this.

If your application uses the whole window for operations and has has no window title bar (like some paint packages), let the first click of the mouse on an inactive window activate the window instead of doing an operation.

Fig 4.1: A window.

Size and Position

Each window opened by your application should be able to fit within a medium resolution screen, 640x200, with the Topaz 8 font. These don't need to be the defaults, just a working guideline. See Resolutions for more information on this.

Your application should provide a default location and size for its windows. By default the windows should open within the current view area of the screen (remember that some users work with virtual screens) and should be scaled per the current resolution. You should, however, let the user override these defaults both temporarily and permanently.

For example, if the user moves or resizes a window during a session and later closes the window, your application should remember those settings and use them if the user reopens the window within that session (a "session" being the time between when the user starts the application and when he chooses the Quit Program menu item). In this case, your program should remember the user-specified positions only for the length of the session.

Let the user store his preferred window position "permanently" via the Save Settings menu option (see Menu for more information on menus). Unlike the scenario in the previous paragraph where the position is remembered only for that session, Save Settings saves the position for use each time the application is opened.

The save Settings menu option allows the user to specify a default size and position for windows.

Opening at Different Resolutions

Save Settings should also save the screen width and height so that the window rectangle can be scaled, if necessary, according to the screen size.

For instance, imagine that the user has set his preferred window position to the lower half of a 640x400 screen. If he later runs the same application on a 640x200 screen, the window will have to be adjusted to fit properly on the screen. The first action to take would be to move the window to a place on the screen where it will fit. If this doesn't take care of the problem, the window should be scaled.

In the example above, the screen height was halved, so the position of the window's top edge should be moved up halfway to the top of the screen. If the window has a sizing gadget, the window size should be scaled as well. Be sure to take into consideration the font used in the window title bar when computing the window's maximum/minimum sizes.

If you're window can't be scaled and doesn't fit in a certain resolution, consider restricting the screen's resolution that the window opens on. Try, though, to respect whatever choices the user makes.

Opening on a Virtual Screen

Screens can be many times the size of the actual display area. When opening a window within one of these screens, make sure the window is positioned by default in the onscreen display area, but if the user changes those defaults via the Save Settings menu option, respect the user's settings, even if it causes your window to open offscreen. He may have a reason for wanting the window to appear where it does.

Successive Windows

When your application opens a number of project windows, you may want to position each successive window slightly lower than the previous one - preferably, the height of the title bar plus one pixel. This will leave the window depth arrangement gadget open.

Fig 4.2: Overlapping windows.

Window Gadgets

Here is a specific discussion of when and how to use system gadgets on your windows. More about gadgets can be found in the next chapter.

Fig 4.3: Window gadgets.

Dragging Windows

Whenever possible, windows should be draggable.

Requesters and support windows should always have a title bar that can be used to drag the window. An immovable support window could block important information that relates to it. A Find and Replace window, for example, may obscure the view and thus the spelling of the word the user wants to search for in the document.

Sizing and Scrolling Gadgets

When a window contains a view or editing area, like in a text editor, it should have a sizing gadget so the user can adjust the window to show more information. If the entire window is used as the view area, a scroll gadget should be added in the right-hand border of the window.

Zooming Windows

The first click on the window's zoom gadget changes the window to its alternate size; the next click restores it to the size it was before the gadget was clicked.

You will have to specify what the small size of your window will be; Intuition will handle the rest. If the window is sizable and your application opens full size, the setting should be the minimum size of the window, which can vary according to your application's needs. If your application opens small, the zoom gadget's alternate size should be initialized to full size. If the window isn't sizable, the minimum size should be the height of the title bar and whatever width is necessary to fit the title of the window; or you may choose to omit the zoom gadget altogether.

AppWindows

The active part of an AppWindow (see Chapter 7 for a discussion of AppWindows) should be indicated by an icon drop box gadget. This gadget should be an outlined rectangle. If your AppWindow has different areas that perform different operations, each area should have a separate icon drop box.

Fig 4.4: An icon drop box gadget.

Requesters

Many times when attempting a task, a user will reach a time of choice, a fork in the road. At these junctures, good road signs can be provided by requesters. Requesters can be broadly defined as sub-windows that allow the user to control options, access files and confirm actions.

Types of Requesters

Requesters can be modal or non-modal.

Non-modal requesters, also called support windows, act basically like windows. The choices and/or information are presented to the user, but he can temporarily ignore the requester and continue entering data if he wishes.

Modal requesters block input to the application until options are chosen or actions are confirmed.

Use Non-Modal if Possible

Generally, you should use non-modal requesters unless there is some reason to block further input. Modal requesters confine the user's movements - that is always something to avoid if possible.

However, there are times when a modal requester is preferable. One example is a requester found in the utility HDToolbox. When the user tries to save changes he has made to a hard disk's partitions, a requester appears warning that saving the changes will wipe out all the data on the hard disk. Naturally, this requester should and will block further activity until the user acknowledges the warning.

Use the Wait Pointer with Modal Requesters

While a modal requester is on the screen, the parent window or screen should set its pointer to a wait pointer.

The Modified Project Requester

Whenever the user makes changes to a project currently in memory and subsequently selects an action such as New, Open or Quit, any changes made to the current project will be lost. In that case, a modified project requester similar to the one below should be presented to the user:

Fig 4.5: A requester which should be used if the user tries to leave a file before saving the changes.

Requester Design

If possible, use the standard requesters provided in the ASL library. Requesters are base-level operations and the user shouldn't have to learn new requester operations with each new software package he buys.

If you need to create your own, follow the ASL design. Here's an example of the ASL file requester:

Fig 4.6: The standard ASL file requester shown here is the actual size it would be on a 640x200 screen.

Spend some time on the wording and design of your requesters. Make sure they communicate clearly and succinctly what choices the user has and what will happen as a result of his choice.

Draggable

Both types of requester should be draggable. Even if the user can't enter data to the program, there may be information on the screen that he needs to see and a non-draggable requester may cover that information.

Where to Open Requesters

Requesters should be opened adjoining or within the boundaries of the parent window. Use coordinates relative to the parent window rather than absolute coordinates when positioning a child window.

Fig 4.7: A find and replace support window opening within the boundaries of the parent window.

Positioning is especially important when the user is working with an extremely large virtual screen or a high-resolution monitor such as Commodore's A2024. On a monitor like the A2024, not limiting your requesters to the parent window boundaries can cause an annoying break in the work flow. Here's an example: the user is working in the lower right corner and you open a requester in the upper left. Relatively, that's a lot of screen real estate to move the pointer across. On a virtual screen the requester may not even show up on the current monitor view, leaving the user to wonder if his action had a result at all.

Always Give a Safe Way Out

Operations should always provide a safe way for the user to back out of a requester. Normally this is handled through a "Cancel" action gadget in the lower right of the requester.

Give Directions

When your program produces a requester indicating its failure to find a file, the requester's title bar should name the program that is looking for the file and the specific name of the file should be given in the text of the requester. For instance, getting the following requester at boot up could severely limit any troubleshooting:

Fig 4.8: The wrong way to do a requester stating that a file can't be found.

Fig 4.9: The correct way to tell the user that your application can't find a file.

OK and OK

Don't create requesters with two identical action gadgets, such as OK and OK. A single gadget for each choice will suffice.

Fig 4.10: Another incorrect requester. This one gives two identical action gadgets and no way for the user to back out of the operation.

Gadgets

Gadgets are graphic symbols that represent a specific action or control. They are usually contained in a window or requester.

There are two basic types of gadgets on the Amiga: system gadgets and application gadgets

System Gadgets

System gadgets control aspects of the GUI environment like window size and screen positioning. System gadgets can be thought of basically as environment maintenance tools. This screen's in the way - click it to the back. This window needs to be bigger - click and drag on the sizing gadget.

Fig 5.1: System gadgets.

System gadgets are highly standardized in when and how they are used. Intuition will handle most of their functions. The table that follows lists the gadgets and how they operate. This is mainly for quick reference. Since the gadgets are tied closely to windows and screens, consult those chapters for more detailed information.

Name	Description
Close	Located on a window's upper left corner, the close gadget removes the window from the screen and quits whatever program or file the window was running
Depth	Located on a window or screen's upper right corner, the depth gadget adjusts which window or screen is in front of all the others. For example, if a window is in front of all the other windows on that screen, clicking once on the depth gadget will put it behind all the other windows. Clicking again on that window's depth gadget will bring that window in front of all the other windows.
Sizing	Located on a window's lower right corner, the sizing gadget allows the user to resize the window by clicking on the gadget and dragging. Not all windows have or need a sizing gaget although its use and support is strongly encouraged.
Zoom	Located on windows next to the depth gadget, the zoom gadget allows users to quickly reduce a window to its minimum size to temporarily get it out of the way. When it is needed again, another click on the zoom gadget will bring the window back to the size it had been. Not all windows have or need a zoom gadget although its use and support is strongly encouraged.

Note: This is only a reference listing of system gadgets. For more information about these see the chapters on Screens and Windows.

Application Gadgets

Application gadgets represent choices the user can make and thus proceed with his task. As a developer, you will have to make more decisions about how and when to use application gadgets than you will with system gadgets.

Design

Like other aspects of the GUI, gadget layout and size should be based on a 640x200 screen resolution with the Topaz 8 font. See @{"Resolutions" link Basi2} for more information.

At run-time, your application should check the size of the font and the screen resolution to determine if the gadgets used will fit in the window with the user's preferred settings. If not, revert to the Topaz 8 font.

Labelling

Put a label on gadgets whose purpose is not immediately obvious. Labels should be terse without being obscure - preferabluy one to three words. Ponder on these a while and test them if possible before incorporating them into your program. Capitalization should follow good grammatical sense for the language being used. If in doubt, refer to a writing or journalism style guide for your language. The Glossary in the back of this manual gives the English capitalization of many Amiga terms.

Ghosting

As with other elements of the GUI, a gadget that is temporarily unavailable for selection should be obviously disabled. Don't allow the user to select something that does nothing in response. Follow the ghosting standard shown in Ghosting.

Fig 5.2: A ghosted text gadget.

Keyboard Equivalents

As a convenience, a key may be bound to each gadget so that its actions can be controlled from the keyboard as well as through the mouse.

Use a logical letter from the gadget label as the key control for the gadget. For instance, a gadget labelled "Spacing" could use "S" as its keyboard control, whereas a gadget labelled "Get Fonts" may use "F". The letter you use should be underlined on the gadget.

Fig 5.3: Gadgets with keyboard equivalents.

Restrictions

Never provide keyboard equivalents for asynchronous requesters. An asynchronous requester is one that occurs due to an action of the application rather than an action of the user. In a hard disk backup program, for example, asynchronous requesters appear asking for a new floppy disk when the current disk is full.

Because asynchronous requesters can appear when the user isn't expecting them, keyboard equivalents can lead to the user choosing an unwanted action. Backup programs, to use that example again, don't require a lot of user attention, so there's a good chance the user will go to another application. If the backup program's requester comes up asking for a new floppy disk while the user is typing in a word processor, unwanted actions could easily occur.

An asynchronous requester will have two default however, that are built into the system. Left-Amiga-V and Left-Amiga-B will, respectively, activate the extreme left and extreme right gadgets at the bottom of a requester.

Another restriction on keyboard equivalents for gadgets: don't use the Return key to activate the OK gadget. This applies to both synchronous and asynchronous requesters.

Left-Amiga-V and Left-Amiga-B will, respectively, activate the extreme left and extreme right gadgets in a requester.

Visual Feedback

Visual feedback should be given when a keyboard equivalent is used. This feedback should be the same as the feedback given when the mouse is used. The specific feedback for each gadget is listed with the gadget description later in this chapter.

Grouping

Gadgets should be grouped logically on your requesters or support windows. Some general premises about grouping follow. Use these premises and your own common sense when grouping elements.

The general rule is that gadgets should be grouped according to function. On a print requester, for example, gadgets controlling text would go in one area, while those affecting graphics would go in another.

Another rule is to place commonly used functions within easy reach, especially on a crowded control panel.

Don't put dangerous controls, such as Delete or Format, near commonly used controls.

Think of the user's work flow when you order the gadgets. Try to emulate a logical and intuitive order. If there is an order of events, start in the upper left and work to the lower right (depending on local language, of course).

Fig 5.4: A requester that has grouped gadgets according to function.

Application Gadgets by Type

Each of the Amiga's application gadgets has a particular use and limitation. This section gives an overview of each type. Each type of gadget can be recognized by its appearance. Do not make gadgets that look like these standard gadgets but act differently.

Action Gadgets

Action gadgets (often referred to as buttons) are graphic rectangles usually containing a few words. Clicking on an action gadget should perform the activity named on the action gadget.

Fig 5.5: An action gadget.

Labels

Make the label descriptive. "OK" and "Cancel" may not always be the best choice. Use friendly, less technical terms (ie. "Stop", rather than "Abort").

The user shouldn't have to read an entire body of text before deciding which action gadget to press. Instead, a carefully selected label should tell the user what the gadget does in one to three words.

Triggering the Action

The action should be triggered on the release of the mouse's select button - not the downpress. This gives the user a chance to "roll off" the gadget before activating it.

More Choices

When an action gadget brings up another window or requester, the label should end in an ellipsis (three periods).

Fig 5.6: A gadget which brings up another window or requester should have a label ending in an ellipsis.

Use of Cancel

An action gadget labelled "Cancel" should only be used if it actually allows the user to back out, leaving the application exactly as it was before the requester appeared. For example, "Cancel" is not appropriate for a gadget on a requester that is displayed while printing is occurring. "Stop" would be a better label.

Gadget Placement

The positive choice, or continuation of the requested action, should be displayed on the lower left side of the requester/window, while the negative choice or discontinuation of the action should be displayed on the lower right.

Fig 5.7: The positive choice should be placed in the lower left, while the negative choice should go in the lower right corner.

Keystroke Activation

If activated through a keystroke, the state of the check mark should toggle within the box.

Scroll Gadget

Scroll gadgets are used to adjust the position of a view. By themselves, scroll gadgets are used to adjust a large display area within a window's view, such as a text file that won't all fit within one window's view. Scroll gadgets are also a component of a scrolling list gadget (see next section).

A scroll gadget is comprised of the scroll bar, scroll box and scroll arrows.

Fig 5.9: A scroll gadget.

Any window that displays only a portion of the file's entire contents should have scroll gadgets. If your application allows the editing of files that are wider than the window, it would be good to have a horizontal scroll gadget as well.

Moving Through in Steps

The display area should be updated immediately as the scroll bar is dragged.

When the user clicks in the scroll box (the rectangle containing the scroll bar) but not directly on the scroll bar, the display should move in viewfuls. For instance, if the user clicks in the scroll box above the scroll bar, the user's view of the list should move up so that the line which was first is now at the bottom of the view. The inverse applies where the user clicks below the scroll bar. This lets the user walk through the list in steps without missing anything on the list. Leaving one line from the previous view assures the user that he hasn't missed anything.

Scrolling List

A scrolling list features a view box showing textual names of files or objects accompanied by a scroll gadget to the right of the view box. If the list is longer than can be accommodated by the view box, the user can move through the list using the scroll gadget.

A scrolling list should be used whenever you need to present the user with a variable list of objects. Probably the most common example is found in the requester presented when a user chooses to open or save a file.

Fig 5.10: A scrolling list.

Custom Scrolling Gadgets

On the Amiga, only one of the items in the system-supplied scrolling list may be selected at a time. Using custom code, it is possible to create a scrolling list gadget that supports multiple selection. If implemented, that gadget should still follow the multiple selection guidelines for text covered in Highlighting Text.

Keystroke Activation

The scrolling list gadget reacts differently to shifted and unshifted keystrokes. An unshifted keystroke should cause the list to scroll forwards through the choices. A shifted keystroke should cause the list to scroll backwards through the choices.

Note: Using the Shift key in tandem with another key should never be the only way to do things since it is usually a choice that is not immediately apparent to the user. In the above case, it is backed up by the mouse.

Radio Buttons

Radio buttons are a group of mutually exclusive gadgets - one and no more than one is always selected. Use this when the user must choose one option from a short list of possibilities.

Fig 5.11: Radio buttons.

Radio buttons are similar to cycle gadgets in functionality. Each has its benefits and drawbacks. See later for a discussion on this subject.

Keystroke Activation

Radio buttons react differently to shifted and unshifted keystrokes. An unshifted keystroke should cause the highlighted button to cycle in one direction. A shifted keystroke should cause the highlighted button to cycle in the opposite direction.

Cycle Gadgets

Like radio buttons, cycle gadgets allow the user to choose one option from several but only the selected option is visible.

Fig 5.12: A cycle gadget.

Cycle gadgets should be used to set attributes, not trigger actions. Never use a cycle gadget for an on/off choice - use a check box instead.

Keystroke Activation

The cycle gadget reacts differently to shifted and unshifted keystrokes. An unshifted keystroke should cause the gadget to cycle forwards through the choices. A shifted keystroke should cause the gadget to cycle backwards through the choices.

Cycle Gadgets vs. Radio Buttons vs. Scrolling Lists

If the user needs to choose one option from a choice of three or more, cycle gadgets, radio buttons and scrolling lists are viable options. Which one you choose to implement depends on your application, your preference and common sense. Consider the following points:

• A cycle gadget presents a cleaner interface. The selected choice is quickly evident and the unwanted choices are hidden away. Theoretically it's also able to handle a larger number of choices, although users will probably have trouble remembering a really large number of choices. Large numbers of choices may work well in a cycle gadget if they are ordered choices, such as the months of the year.

• In general though, options with more than about a dozen choices should use a scrolling list.

• Radio buttons present a clear choice to the user - the possible choices are always visible. Radio buttons work well with a small number of options. They are probably also slightly more intuitive than cycle gadgets.

Color Selection Gadget

The color selection gadget (sometimes referred to as the palette gadget) allows the user to pick a color from a set palette.

Fig. 5.13: A color selection gadget.

Keystroke Activation

The color selection gadget reacts differently to shifted and unshifted keystrokes. An unshifted keystroke should cause the gadget to cycle forwards through the choices. A shifted keystroke should cause the gadget to cycle backwards through the choices.

Slider

Sliders are used to choose a value in a given range. Usually, this value represents a level or an intensity such as volume or color.

Sliders look similar to scrollers without arrows, but when the user clicks in the slider box above or below the slider bar, the slider value should change in single increments rather than entire views.

Fig 5.14: Slider gadgets.

Keystroke Activation

The slider reaacts differently to shifted and unshifted keystrokes. An unshifted keystroke should cause the horizontal bar in the slider to move up. A shifted keystroke should cause the horizontal bar to move down. When the horizontal bar reaches either the top or bottom it should change directions automatically. Don't tie the direction solely to a shifted keystroke.

Text Gadget

Text gadgets (sometimes referred to as string gadgets) are rectangular boxes used to accept keyboard input for alphanumeric fields.

Fig 5.15: A text gadget.

Activating Text Gadgets

When a window or requester appears containing a text gadget, have the gadget immediately activated and ready for keyboard input if:

• there are no gadgets on the requester that can be activated by the keyboard;

• the window or requester appeared in direct response to user activity (ie. it is not asynchronous).

If the window or requester has other gadgets that can be activated from the keyboard, the user should also be able to activate the text gadget from the keyboard. In this case, it should not be activated by default.

The user should not have to select the text gadget with the mouse before typing an entry (if he chose an action that directly called that requester up). If may seem like a small delay to go from keyboard to mouse to keyboard, but all breaks in the flow of your program should be minimized.

Ordering of Text Gadgets

When a window contains a series of text gadgets, activate the gadget in the far upper left region of the window first (depending on the scanning direction of the local language).

Moving Through Fields

Let the user move through fields with the Tab key. When the user presses Tab, activate the next text or number gadget in the series. When the user reaches the end of the series and presses Tab, the cursor should return to the first entry gadget. This function is supported by Intuition.

Shift-Tab should activate the previous gadget in the series.

Let the user move through fields with the Tab key.

Display Box

A display box is a rectangle that shows non-editable textual or numeric information.

Display boxes look similar to text gadgets, but since they are read-only, they appear recessed.

Fig 5.16: A display gadget.

Icon Drop Box

Icon drop boxes are used for manipulation of icons. If a user drags an icon to an icon drop box, the image of the icon is copied into the box. Depending on the function assigned to that icon drop box, the icon imagery may then be redrawn or used to represent other files.

Fig 5.17: An icon drop box.

Custom Gadgets

Sometimes a system-supported control does not provide the exact function you need. In that case, you may choose to create a custom gadget.

If a custom gadget is an extension to an existing gadget type, then you should try to emulate the features of the existing gadget.

For example, a custom multi-line text gadget should support the same keyboard functions that the standard single-line text gadget does. Right-Amiga-X should erase the text and Right-Amiga-Q should undo changes. Refer to Keyboard for more information on the keyboard conventions used in text gadgets.

All custom gadgets should support a minimum of three images: normal, selected and disabled. The gadget images must be usable on a monochrome screen.

Custom Icons

Custom icons are application-specific gadgets that can be moved and manipulated. The note object in a music package is one example.

Take care when using custom icons alongside action gadgets that have graphical labels. Since it is not clear which symbols trigger an action when clicked and which symbols move when clicked, users could be triggering unwanted actions. If you use both in the same application, be sure the user can tell at a glance which is which. Grouping them spatially is one possible solution. Colour cues may provide a solution. Boxing them may be a third solution.

Menus

Menus are used either to invoke an action from a fixed list of choices or to set an option within an application.

The Amiga's menu system is a very appealing part of the user interface for a number of reasons:

• Even novice users can quickly understand how a menu works.

• Menus allow the user to browse through the set of possible actions that can be performed. This gives an outline-like overview of what functions are offered by a program.

• They give the user familiar landmarks that can always be brought into view by pressing the menu button.

• The menu system keeps the Amiga's GUI from being too cluttered since menus stay neatly tucked away until the user wants to see them.

Menu Anatomy

The menu system consists of the menu bar which shows the name of each menu, a drop-down menu under each name showing the list of choices (also known as menu items), and an optional group of secondary choices called a submenu, which are attached to a menu item. Submenus should appear to the right of the menu.

Fig 6.1: Elements of the menu system.

General Rules

Throughout your design of a menu system, keep the user in mind. Think of what the user will have to go through to choose a menu item. Working with a mouse is simple for simple tasks, but when menus get long or are complicated and illogically arranged, working with a mouse can be very frustrating indeed.

Strive for Fixed Menus

When possible, your menus should offer a fixed set of visible choices. A large, variable set of choices such as fonts can make a menu unwieldy. Usually, a variable set of choices should be presented in either a requester or a scrolling list gadget. There are rare exceptions such as the standard User menu described later in this chapter.

Multiple Selection

The user should be able to select a number of menu items at one time by clicking the multiple items with the selection button before releasing the menu button.

Anticipate conflicting choices that can occur during multiple selection. If the user chooses an item and then chooses one that conflicts with the first, the second item should override the first.

Let Intuition work for You

Many of the functions described here can be handled for you automatically through Intuition. Let Intuition do the work for you whenever possible rather than coding your own menus.

Menu Design

Use the same criteria for designing the menu system as for other elements of the GUI: design it on a 640x200 screen with the Topaz 8 font. At run-time, your application should test to see if the menu will fit in the user's preferred font and screen size. If not, revert to the Topaz 8 font.

Colors

When possible, menus should use dark text on a light background. Note: the examples shown in this chapter don't follow this rule because the version of Release 2 they were taken from had color constraints that prevented this rule from being obeyed.

Font

A uniform font is recommended for all the menu items within an application. A change in font style could be appropriate, however, if it symbolizes a change in the style of text in your application. For example, in a word processor, a menu called Style may list the type styles Bold, Italic and Underline. Those menu items may be rendered in bold, italic and underline text, respectively.

Toggle Items

Some menu items turn an option on or off. To show this, use a check mark that toggles visible and invisible in a space in front of the item. Don't add a submenu with items such as "on" and "off".

Toggle items should be indented to allow room for the check mark. This will give the user a visual cue that it is a toggle item.

Fig 6.2: A toggle menu item shown in both states.

Organization

Within a menu, items should be grouped according to function. Distinct groups should be separated with a separator bar. "Function" can be deefined by these three rules:

Separate the toggle items from the non-toggle items. This will help the user quickly distinguish one type from the other. It will also look better if the left-hand side of the menu text doesn't indent more than once.

Group similar choices together. For example, if a menu includes the items

• Save as ASCII
• Save as MystrEd doc
• Quit
• New
• Save as IFF clip

the three Save as... items should be grouped together.

Frequently used items should be placed towards the top of the menu. When ordering the items, make sure to separate commonly used items from dangerous ones. It's relatively easy for a user to choose the wrong menu item by mistake - try to anticipate such mistakes and their possible outcomes and arrange your menus to avoid them.

When ordering menu items, make sure to separate commonly used items from dangerous ones.

Limit the Size

Try to limit the number of items in a menu to about a dozen. Submenus should have about a half dozen items at most. The utility of a menu decreases as its length increases.

On the Menu Bar

When it comes to ordering the menus themselves on the menu bar, remember that the user can most easily access the outside menus. Put menus that are used less towards the middle.

Follow the order given in the Standard Menus section of this chapter for any standard menus.

Ghosting

Whenever a menu or menu item is inappropriate or unavailable for selection, it should be ghosted. Never allow the user to select something that does nothing in response.

Fig 6.3: A menu with ghosted items.

Labeling

Menu and menu items labels should be terse - preferably one to three words. Use the capitalization rules that apply in the language at hand.

Menu items that represent an action should reflect that action in the item's label. For instance, "Print" is better than "Printer". Try, also, to keep the terminology user-friendly and non-technical.

Don't repeat a menu's title on every item's label. For instance, in a Macros menu use the label "Load..." rather than "Load Macros...". Repeat the menu title, however, if user comprehension will suffer.

Toggle Items

As discussed earlier, indenting toggle items lets the user know that they represent a choice. Another cue you can give to the user is to end the label in a question mark. In some Settings menus, for example, an item labelled "Create Icons?" is preceded by a check mark (or placeholder) and ended with a question mark. Both are cues to the user that this is a toggle item.

Ellipsis

When a menu item brings up a window or requester, an ellipsis (three dots) should be appended to the menu item's label.

Fig 6.4: A menu item that brings up a requester or another window.

Submenus

When an item has a submenu, the symbol » should be placed on the far right side of the menuy item. These should be flush right (see the next section).

Fig 6.5: A menu item that brings up a submenu.

Lining up on the Right

If you have any symbols or text that you want to line up on the right side of the menu item, make sure it is flush right (ie. right justified) or it won't line up properly when used with a proportional font.

Standard Menus

Some menus and menu items appear so often in applications that their use and design can be standardized. Using standard menus will enhance the feeling of consistency across applications and help the user feel more comfortable with your program.

Listed below are standard menus that your application should use whenever appropriate. The order in which the menus and their items are presented is an important part of the specification.

Project Menu

Applications that create, edit and save data should have a Project menu. The Project menu should be the first menu on the left side of the menu bar and should contain as many of these items as appropriate - in the order shown.

Fig 6.6: The Project menu.

Label	Shortcut	Description
New	Right-Amiga-N	New should open a blank, untitled project.
Open...	Right-Amiga-O	Open... should bring up a file requester. If an unsaved project currently exists, the modified project requester (Save project?) should be brought up when Open... is selected - unless your application supports multiple projects.
---
Save	Right-Amiga-S	If the project had been saved previously, Save should copy the current version over the old version. If the project has never been saved, Save should bring up a file requester.
Save As...	Right-Amiga-A	Save As... should bring up a file requester to prompt the user for a name, and then save the file.
---
Print	Right-Amiga-P	Print should send the project to the printer using the current settings. The current settings may either be those found in Workbench's Prefs directory or individual program settings previously saved by the user.
Print As...		Print As... brings up a requester that can be used to set your progam's print options.
---
Hide		This menu item is for programs that can handle multiple projects at one time. Hide should remove a project's window from the screen. If the user selects Quit Program before returning to a hidden project that has unsaved changes, the modified project requester should come up asking if he wants to save the project first. A separate modified project requester should be presented for each unsaved, hidden project.
Reveal...		Reveal... is for programs that can handle multiple projects at one time. Reveal... should bring up a requester with a scrolling list gadget containing all opened projects whether hidden or not. Although its true purpose is to return hidden projects to the screen, it is more user-friendly to allow the user to view all open projects from this item. The chosen project's window should open an jump in fron of any other windows. If no projects are hidden, this item should be ghosted.
Close		This menu item is for programs that can handle multiple projects at one time. Close should remove the current project's window from the screen. If there are unsaved changes, a modified project requester should come up first.
---
About...		About... should bring up a window with information about your program and the current project. What information is included is up to you, but it should include at least the version number of your software. Some suggested information to provide: ARexx port name, project size and tool name.
---
Exit [Level]		Exit [Level] should allow the user to leave the current level, such as the slide editing level in an electronic slide show program, and return to the next highest level. The word [Level] on the label can be replaced with the name of the current level.
---
Quit [Program]...	Right-Amiga-Q	Quit [Program]... should exit the entire program. The word [Program] can be replaced by the name of your application. A separate modified project requester should come up for any open or hidden projects with unsaved changes. Quit [Program]... should not be modal; i.e. it should be available at any level.

Note:

• Print and Print As... are optional items for applications that support printing.
• Hide, Reveal... and Close... are optional items for multi-project applications. Exit is an option for multi-level programs.

Edit Menu

Any application that can perform editing functions should have the Edit menu in the second position. The following items represent the suggested list with Redo as an optional item. A basic rule is that any menu item that operates on blocks of data should go in the Edit menu.

You should support the Clipboard as your buffer for cut-and-paste operations. This will allow the user to share the clips between applications. See Chapter 11 for more information on the Clipboard.

Fig 6.7: The Edit menu.

Label	Shortcut	Description
Cut	Right-Amiga-X	Cut should remove the highlighted text or current object and place it in the buffer.
Copy	Right-Amiga-C	Copy should retain the highlighted text or current object in the project while also placing a duplicate of it in the buffer. The text should then be unhighlighted to show that the copy took place.
Paste	Right-Amiga-V	Paste should take whatever is in the buffer and place it at the insertion point in the project window.
---
Erase		Erase should remove the highlighted text or current object.
---
Undo	Right-Amiga-Z	Undo should restore the project to the state it was in before the user's last action. If, for instance, the user imported a text clip by mistake in a word processor, Undo should automatically take it out. Some programs support multiple steps of Undo. Using the example in the previous paragraph, say the user had deleted a paragraph before inserting the text clip. Selecting Undo twice should take out the mistaken text clip and return his original paragraph.
Redo		Redo is an option for programs supporting multiple steps of Undo. In a program that doesn't support multiple steps of Undo, hitting Undo twice would take the user back to where he was before he selected Undo - it's cyclical. He imports a text clip, selects Undo and the text clip is gone. Select Undo again and the text clip is back again. In this program, Undo undoes Undo. But in applications with multiple steps of Undo, the user can undo anything except Undo. He just keeps going back another step instead of going through cyclical actions. So Redo is there to undo any mistaken Undos.

Macros Menu

If your application supports macros, it should use ARexx, the Amiga's built-in scripting language, rather than its own internal scripting language. See Chapter 9 for more information on ARexx.

The Macros menu should allow the user to create and assign macros. Optionally, you can include the ability to load and save macros as well.

Fig 6.8: The Macros menu.

Label	Shortcut	Description
Start Learning		When Start Learning is selected, all subsequent user actions should be written in ARexx script form to an internal buffer - until Stop Learning is selected. Feedback to the user is essential, so it would be a good idea to let the user know that the Start Learning command was accepted. The indicated can be subtle but should be noticeable if the user wants to look for it. One idea is to put a small glyph, letter or word in the project's title bar.
Stop Learning		When Stop Learning is selected, your program should stop writing user actions to the internal buffer created by Start Learning. Any visual feedback that originated with Start Learning should go away.
Assign Macro...		Assign Macro... should bring up a requester through which the user can assign the script created by the previous two commands. Macros can be implemented [in] a number of ways. One longtime favorite is to assign the macro to the function keys, the ten keys across the top of the keyboard, or to some other keyboard combination. Or the Macro can be assigned to the User menu (see section later in this chapter). Or the macro can be given a name and saved to disk; from there it can be implemented via an ARexx command console. Some programs may choose to support one, some or all of these methods. Your Assign Macro... requester should reflect all the possible choices your program supports.
Load...		Load... should bring up a requester listing the macros that can be loaded into memory. This, along with Save..., forms an optional set of items.
Save...		The macros design as discussed above assumes that key- and menu-activated macros will be assigned and used on a per-session basis. The next time the user returns to your program, the macros he had assigned to keys and menus will no longer exist. Save... should allow the user to name a macro and save it to disk. At another session, the macro could be loaded and then assigned to a key or menu. This, along with Load..., forms an optional set of items. Otherwise, if the user wishes to save the macros and their assigned positions, he should do it through the Save Settings item found in the Settings menu.

Settings Menu

Provide a Settings menu if you allow the user to change and save aspects of your program's environment. This menu should be located in the second position from the right.

Consult Chapter 12 for more information about preferences in general.

Two items should be accessible through this menu (if your program supports them): a toggle item asking if icons should be created and an overall Save Settings item. They may be directly in the menu or in a requester brought up by a menu item.

Fig 6.9: The Settings menu.

Label	Shortcut	Description
[options]		Listed in this menu should be any specific options you wish to handle through a menu item, such as what screen resolution to operate in or baud rate for a terminal package. Or you could have an option labelled Set Settings... that would bring up a control panel which could be used to set all the program's options. [options] can be toggle items, or they can bring up submenus or requesters - it all depends on your application's needs. Whatever these options are, they would change the user's preferences for that session only. To save them as defaults the user would have to use one of the Save Settings items. Note: the word [option] shown here is only a placeholder to be replaced with a descriptive menu label.
Create Icons?		Create Icons? is a toggle item that should allow the user to choose whether a .info file will be created with each project. A .info file contains a graphic image for the file's icon. User's who don't use the GUI as a filing system may find .info files to be extraneous and a waste of storage space. Your program should provide this menu item.
---
Load Settings...		Load Settings... is an optional item that should allow the user to change from his current settings to a new set of previously-saved settings. Load Settings... should be included if you think your users will want or need multiple settings files.
Save Settings		Save Settings should save the user's settings as your application's default preferences. Each time your application is opened thereafter, it should use these user-specified settings. By default, Save Settings should save the new settings in the current settings file. See Chapter 12 for more information on saving settings files.
Save Settings As...		Save Settings As... is an optional item that brings up a file requester. Save Settings As... will be used when the user wishes to save multiple settings files. There are a couple of reasons why this option may be helpful to users. A user may save different settings for different types of projects; eg. settings.vid for projects being output to video and settings.prt for projects being output to a printer. Also, if your application is being used on a network, users may wish to save personal settings.

User Menu

The User menu is a variable-length menu that contains user-defined macros and any other optional features a user may want to add as a menu item. This should be located at the far right.

Fig 6.10: A sample User menu.

Workbench

In a way, Workbench is just another program - but as the default interface on the Amiga, it's one program that many users will pass through on their way to your application. Although it has other facets and functions, it's the interface between your program and Workbench that is of concern in this chapter.

Fig 7.1: The workbench screen.

Icons

Icons are pictorial representations of directories, files, applications, objects or actions. Your program should have icons for anything the user can access including the main program itself, documentation files, and any tools that may accompany the program.

The .info File

The icon imagery is found in a file bearing the suffix ".info". For example, the icon for a data file called "myletter" would be found, along with some other information, in the file "myletter.info".

Icon Design

A good icon quickly communicates the function it represents. The Calculator icon and the SetMap icon are good examples.

Fig 7.2: The Calculator and SetMap icons.

Size

Icons should be small. The maximum recommended size for an icon is 80 pixels wide by 40 pixels high. Large icons take up valuable screen and disk space, make for an unprofessional Workbench look and, in general, can be just plain annoying.

The 3-D Look

Icons should be designed with the light source coming from the upper left-hand corner. They should be viewable in one bitplane as well as two.

Text in Icons

Before you use words in an icon, think about how extensive a distribution you would like to see your product achieve. It's better to have an icon communicate through symbolism than language.

Before using words in an icon, think about how wide a distribution you envision for you product.

Icon Types

There are five types of icons on the Workbench: disk icons, drawer icons, trashcan icons, tool icons and project icons. Of these, only tool icons and project icons bear discussion here.

Tool Icons

A tool icon represents an executable file such as an application. A double-click on a tool icon will run the application. The look of tool icons varies from application to application.

Project Icons

A project icon represents a data file. Typically, a double-click on this icon will cause the application that created the data to run and automatically load this data.

The look of a project icon is usually determined by the application that created it and by the type of data it represents. However there is also a default project icon included in the system.

Fig 7.3: The default project icon.

Create Icons?

When your application creates a data file, it should, by default, create a .info file to go with it. Many users are accustomed to accessing their projects via an icon.

Create the icon after the user successfully saves the project. This will prevent the possibility of project-less icons in the system.

Your application, however, should allow the user the option of saving files without creating icons. The recommended way of doing this is to have an item in the Settings menu called Create Icons?. This item should be enabled by default. See Chapter 6 for more information.

Positioning

New project icons should never be saved in a specific position. Rather they should be positioned algorithmically by Workbench (see the Workbench flag NO_ICON_POSITION). In the same vein, if the imagery of an existing icon is changed (eg. the application creates a reduced version of the project for use as the icon imagery) the icon should be saved without a specific position.

Argument Passing

To make the common operation of starting up programs more powerful, the Amiga provides ways of passing along more specific information to the application. This process of providing additional information to a program that's about to run is known as argument passing.

When using the Shell, the system is straightforward. The user runs an application by typing its name along with additional information such as the name of a file to operate on and any command options. The entire command line is then passed to the program as an argument.

The Workbench also provides means of passing arguments - but it is tied to icons instead of lines of type.

Tool Types and Default Tool

Applications started from Workbench receive startup information from the system in the form of a WBStartup message. The WBStartup message can be used to get various Workbench arguments including those found in the Tool Types and Default Tool fields of the icon the user clicked on.

Tool Types

If you click once on any tool icon and choose "Information..." from the Workbench's Icon menu, you should see a requester with a field for Tool Types.

Fig 7.4: The Information requester for a tool icon.

Arguments placed in this field take the form KEYWORD=value. KEYWORD is an argument name specified by your application, and value is a number or string that should be assigned to that argument.

For instance, the Tool Types field of a text display program might be set to LINES=20 to indicate how many lines to display at once.

Normally, the Tool Types information is filled in when the .info file is created; subsequent operations only read this information.

Default Tool

The Information requester for a project icon is different than that of a tool icon - it has both a Default Tool field and a Tool Types field. The Default Tool field tells the system which application is used to edit the project. When a user double-clicks on a project icon, the application specified in the Default Tool field gets run and the data is passed to that application via the WBStartup message.

Fig 7.5: An Information requester for a project icon.

Altering Icons

If your application needs to alter an icon for some reason, change only the things you intend to change and preserve the rest. If your application needs to change the Tool Types field, for instance, leave the imagery, position and Default Tool field alone.

More important, change only the Tool Types entries relevant to your application - do not rewrite Tool Types from scratch for an existing project. If the icon has a Tool Types entry that your application does not recognize, that entry should be preserved.

Tool Types and Networks

You should support project-specific Tool Types arguments. With the advent of networked Amigas sharing the same applications, this becomes increasingly important. Tool Types arguments written to specific projects will allow networked users to override Tool Types arguments written to the application's tool icon - arguments that have probably been set for the least common denominator.

Standard Tool Types Arguments

Some Tool Types arguments are already used in the system. If they apply to your application, support them; if not, take care that your Tool Types arguments don't conflict with these. Listed below are some of the more common Tool Types arguments found in the system:

Take care that your Tool Types arguments don't conflict with those listed here.

Tool Type	Notes
WINDOW=CON:<window spec>
DONOTWAIT	Don't wait for return; used by wbstartup
TOOLPRI=<priority> STARTPRI=<priority (-127 to 128)	Used to set your program's priority
PUBSCREEN=<name>	The name of the public screen to open on
STARTUP=<name>	ARexx script to run at startup time
PORTNAME=<name>	Name to assign to your application's ARexx port; overrides default naming system
SETTINGS=<name>	Allows a user to specify a settings file
UNIT=<number>	Device or unit number
DEVICE=<parallel/serial>	The name of the device to use
FILE=<file pathname>
WAIT=<number (of seconds)>
PREFS=<prefstype>
CX_POPUP=<yes/no>
CX_POPKEY=<CX key specifier>
CX_PRIORITY=<CX priority level>
<CX fkey spec>=<CX string spec>

The Apps

Other facilities also exist in Workbench that allow an application to get more information while the application is already running. These are known as AppWindow, AppIcon and AppMenu.

For example, a text editor's windows may function as AppWindows. A user would be able to drag the icon of a file into the window and that file would be loaded automatically.

AppWindows, AppIcons and AppMenus are aimed at the user. By using techniques that are totally graphic-oriented (Tool Types arguments still eventually come down to a line of type), the Apps bring the power of argument passing more into line with the "point-and-click" metaphor.

AppWindows

An AppWindow is a special kind of Workbench window that allows the user to drag icons into it. It's basically a graphical alternative to a file requester.

Applications that set up an AppWindow will receive a message from Workbench whenever the user moves an icon into that AppWindow. The message contains the name of the file or directory that the icon represents.

For instance, Workbench's IconEdit is an AppWindow with three different areas which users can drag icons into - each with a different purpose. When the user drags an icon into the large box, the icon is loaded as a project. When an icon is dragged into the box labelled "Normal", its image is used for the normal (not selected) image. Likewise for an icon that is dragged into the box labelled "Selected" - its image becomes the activated image for the icon.

Fig 7.6: IconEdit is an example of an AppWindow. It has three different drop areas which do three different things.

An AppWindow will often use icon drop box gadgets to indicate the active area where the user may drop an icon. Note: IconEdit did not follow this convention because it was more important to indicate the function of each area by its imagery (eg. the "normal" area can be clicked on, etc.).

The window should activate when an icon is dragged into it.

AppWindows only work when your application is running on the Workbench screen. This makes sense because you need to be able to drag icons from Workbench to the AppWindow and draggable objects can't be dragged across screens. If the user opts to run your application on a screen other than Workbench, set your AppWindows so they will revert to AppMenus (see below).

As a general rule, AppWindows are appropriate when your application needs to have a window anyway.

AppIcons

An AppIcon is similar an AppWindow - it allows the user to pass a graphical argument to a running application. The only difference is that AppWindows use a window to accept the argument and AppIcons use an icon.

The image for an AppIcon should give some indication what operations it supports; ie. whether it represents an iconized application or supports dropped projects. Avoid vague imagery.

AppIcons are useful for programs that operate in the background with little other user interaction - a print spooler is a good example.

Double-clicking on an AppIcon should normally open a window offering information and controls. For example, a print spooler could open a status window in which the user could rename, abort or re-order the things he sent to be printed.

AppMenus

An AppMenu allows your application to add a custom menu item to the Tools menu on Workbench. An application that sets up an AppMenu item will receive a message from Workbench whenever the user picks that item from the Workbench menu.

Preferences

Applications can also get arguments from Preferences. Via Preferences, the user can graphically set up the system defaults to suit his taste and needs.

Through Preferences, the user can control such things as screen fonts, colours and other global information that your application should respect.

You can create a preference editor to handle the defaults used by your application. See Chapter 12 for more information.

The Shell

One of the best things about the Amiga is its versatility. While the rest of the personal computing community continues to argue about the best type of interface, Amiga users have both - a graphic interface with Workbench and a text-based interface with the Shell.

The Shell (also known as the Command Line Interface or CLI) preserves the best features of operating computers the "old-fashioned way", that is, by typing commands at a console. Although that is in some ways more difficult than clicking on graphics with a mouse, it provides a finer level of control, less overhead and greater power than is possible through a GUI.

Virtually anything that can be done through Workbench can also be done through the Shell. On Workbench, for instance, a user can move into a subdirectory by double-clicking on its drawer icon. The equivalent of this in the Shell is to type

 cd <subdirectory name>

The command dir will then list the contents of the directory.

The same example can be used to illustrate the greater power of the Shell. In addition to dir, which gives a brief listing of files and subdirectories, the user can also use list which gives a more in-depth listing including the size of each file, information about the file and when it was last updated. Or you could list only a subset of files by using wildcards in the command. For example,

 list #?.info

would list only those files ending with ".info".

Fig 8.1: The Shell

In addition to being able to do things with finer control than Workbench, the Shell can also do some things that Workbench cannot do at all. For instance, from the Shell you can create a script - a pre-recorded set of commands that helps to automate repetitive tasks.

Your application should support all three interfaces built into the Amiga: the GUI, the Shell and ARexx.

Parsing Commands

You should use the command template method for parsing the command line:

Standard Form

In general, Shell commands take the form:

 COMMAND [redirection-argument] [<argument1>,<argument2>, ...]

where COMMAND is the name of an executable file, [redirection-argument] is a "<", ">", and/or ">>" symbol followed by an AmigaDOS device name, and [<argument1>, <argument2>, ...] is a list of arguments that will be passed to the executable file.

Here's a sample Shell command:

 play myanim loops 20

The command is play' (an executable program), there is no direction and three arguments are passed to the play program: myanim (the name of the data file), loops (a command option) and 20 (another command option).

Built-in Parsing

The Amiga, like UNIX and many other systems, passes command line arguments to your application. The system automatically provides the list of arguments and counts them for the application.

The system also needs to parse these arguments. Parsing refers to the job of examining the arguments to find out what they mean so the appropriate operation can be performed.

Prior to Release 2 of the Amiga operating system, each application designer had to manage his own parsing. This resulted in a variety of command styles and a more complicated Shell environment for the user. So the designers of Release 2 built a standard way of processing Shell arguments into the system.

When your application is started from the Shell, any arguments should be parsed using the command template method - the same method used to parse all the system-supplied Shell commands. This argument parsing method should also be used by your ARexx or scripting commands.

By far, the greatest benefit of this method is that it allows you to use AmigaDOS routines to handle the chore of parsing the command line. The DOS routines will handle errors and give help messages so both your code and your development time can be shorter. Using standard argument parsing also makes the Shell interface more consistent and more comfortable for the user.

Using AmigaDOS routines to handle command line parsing can shorten both your code and your development time.

The Command Template

In order for your application to use standard argument parsing, a command template must be constructed to describe the arguments that the command understands.

In the command template, each argument is specified by a keyword (a preset argument that the program understands) followed by a modifier that describes the properties of that argument. Modifiers take the form "/X" where X is one of the characters from the table below. Each keyword can have none or many of the modifiers.

Neither the keywords nor the modifiers are case-dependent. The format shown here corresponds to the way the system displays command templates in the Shell.

Modifier	Description
,(comma) - No arguments	The comma indicates a null argument. It also separates arguments in the command template.
= - Equivalents	The equal sign indicates equivalent abbreviations for keywords, eg. PS=PUBSCREEN/K.
A - Always required	The argument must be supplied in order for the command to be accepted.
F - Final argument	If this is specified, the entire rest of the line is taken together as a single argument, even if other keywords appear in it.
K - Keyword required	This means [that] the actual keyword must be typed on the command line along with its argument in order for the argument to be processed (often the keyword is optional). The argument will not be interpreted unless the keyword appears. For example, if the template is NAME/K, then unless Name=<string> or Name <string> appears in the command line, the command will be interpreted as having no Name argument at all.
M - Multiple argument	There can be a number of instances of this argument. For example, the AmigDOS Join command lets your merge together any number of files into a single file. The template is: FILE/M,AS=TO/K/A This allows commands such as: Join file1 file2 file3 as bigfile When the /M modifier is the first argument in a template, any number of filenames may be specified by the user. If a command line has any leftover arguments, they will be interpreted as belonging to the /M argument. So only specify one /M per template. For example, in the command Join one two as bigfile three, the word three is an extra argument. In this case, one, two and three will be merged together to form bigfile; the extra argument is tacked onto the /M arguments. The /M argument also interacts with the /A argument. If there aren't enough arguments given to fill all the /As, then part of the previous /M argument will be used to fill in the /As.
N - Number	This argument is a decimal number. If an invalid number is specified, an error message will be returned to the user. Unless the /N modifier is specified, all arguments are assumed to be strings.
S - Switch keyword	This modifier indicates a switch keyword argument. If the keyword is given, the switch is "on". If the keyword isn't given, the switch is "off"
T - Toggle keyword	This is similar to /S but, when specified, it causes the switch value to toggle from "on" to "off" or vice-versa.

Use the standard command template described here in your Shell and ARexx commands.

Displaying the Command Template

When a user types a command name in the Shell followed by a space and a question mark, the command template should be shown to him. This acts as a sort of help message that gives the syntax of the command. For instance, in the above example of play myanim loops 20' the command is play. When the user types play ? in the Shell he should see this:

 ANIM/A,LOOPS/K/N

This means the command has two arguments: the Anim argument and the Loops argument. The Anim argument consists of the optional keyword ANIM followed by an animation filename. The /A modifier means this argument must always be given.

In the Loops part of the argument, the /K means that the keyword LOOPS is required for the argument to be processed correctly, and the /N means that the LOOPS keyword should be followed by a decimal number. Notice that since the Loops argument does not have a /A modifier, it could be left out altogether.

Other possible commands a user could come up with include:

 play myanimfile loops 20
 play myanimfile
 play anim myanimfile

These commands, however, would be illegal:

 play myanimfile 20         (the required keyword LOOPS is missing)
 play anim                  (no filename is given)
 play anim myanimfile loops (the numeric value for LOOPS is missing)

Standard Arguments

The following Shell arguments are standard within the system. Don't use these names for application-specific arguments with purposes different than those given below:

 FILES/M      List of files to work with as projects
 PUBSCREEN/K  Name of the public screen to open on
 PORTNAME/K   Name to assign to the ARexx port
 STARTUP/K    ARexx script to run at startup time
 NOGUI/S      Indicates that no GUI is desired
 SETTINGS/K   Name of preferences file to load at startup

If you need a keyword for your application, try to find an applicable one that is already in use - and use it the same way. If you need to make a new keyword, don't make it the same as a common command name; e.g. "list".

Pattern Matching

When most people think of pattern matching, they think of using wilcards, but pattern matching is actually much more. It's a powerful feature that enables more efficient operations, especially on systems like the Amiga that have a hierarchical file system with few size limits.

Pattern matching is part of the appeal of the Shell. It would be difficult to use icons to perform an operation on 50 files at once - not to mention the problem of fitting all the icons on a 12-inch monitor. Some complex operations are just easier to do with a text interface.

Standard Available Tokens

Token	Description
?	Matches a single character. For instance a? matches any string with two characters that starts with the letter a.
#	Matches a subsequent expression 0 or more times. For instance, the pattern #? will match any string.
(ab|cd)	Matches any one of the items separated by |.
~	Negates the following expression. For instance the pattern ~x? will match any two letter string except those starting with x. Another corollary of this is the pattern ~(x?) which will match anything except two-letter strings beginning with x; ie. xaa or ab but not xa.
[abc]	Character class; matches any one of the characters in the brackets.
[a-z]	Character range (must be within character classes). You can also use [a-e,x-z] style.
%	Matches 0 characters always. For example, the pattern (foo|whiskey|%)bar matches foobar, whiskeybar and bar.
*	Synonym for #?. Not available by default but it is an option that can be turned on.

Expression in this table means either a single token or character token (such as ? or x), or an alternation (such as (ab|cd|ef)), or a character class (such as [a-z,A-Z]).

The Amiga's Wildcard

On the Amiga, the wilcard is #? - as opposed to * on other platforms. For example, the command

 delete #?.info

would delete all the files in the current directory that end in .info.

Within Applications

In addition to its usefulness on the filing system, pattern matching is also useful within applications. For example, the Find function within a text editor should be able to find strings according to a pattern.

Your application should support pattern matching from the Shell and from functions within the application itself, through AmigaDOS system routines.

Embedded Version IDs

Follow the standard method for indicating the version of your software.

The Shell command VERSION provides support for version identification, but you have to follow a standard template.

A text sequence that indicates the current version of your application should be embedded within your code. (It should also be put in your ARexx scripts and your configuration files.) The format of this text sequence is:

 $VER: <name> <version>.<revision> (<d>.<m>.<y>)

 <name>         The name of your application
 <version>      Major version number
 <revision>     Minor revision number
 <d>            Day created
 <m>            Numeric month created
 <y>            Year created

If you follow this template, the user can find out what version of your software he is using with the Shell command VERSION.

ARexx

Previous chapters covered aspects of the GUI and the Shell. The third built-in Amiga interface is ARexx.

Like the Shell, ARexx is a text-based facility for giving commands to the Amiga, but while the Shell operates externally to programs (copy, delete, etc.), ARexx can operate internally with programs.

ARexx has two main uses: as a scripting lanauguage and for Inter-Process Communication (IPC). With the latter, ARexx acts as the standard hub for programs to communicate with each other by sending command and data messages.

Scripting and IPC

The ability to handle macros, or scripts, is a powerful feature for any application. Whenever a user has a repetitive, well-defined job to do with application software, scripts allow him to automate.

For example, many communications programs allow the user to set up a macro that will dial the phone number of a host system, log into it, check for messages and download those messages for later reading. The macro allows the user to do automatically what is usually done interactively.

ARexx provides Amiga users with a standard macro language.