View source for UI Style Guide Preferences

[[Category:User Interface Style Guide]]
== Preferences ==

On the Amiga, the term "Preferences" refers to the set of programs and data used to configure the machine's working environment. They come in two basic varieties: system preferences (the basic ones in the operating system) and application preferences (any you choose to add).

[[File:SG12-1.png|frame|center|Workbench's Prefs Directory]]

A variety of editors in the Prefs drawer of Workbench allows the user to set various system defaults. These represent the system preferences. Some of these control settings for peripherals such as printers, while others control the look and feel of the system. The Palette editors, for instance, allows the user to set the default colors use by Workbench.

== Prefs in Moderation ==

Every additional selection in your application means additional complexity for the user. Before writing any preference controls for your application, consider these two warnings:

Don't add a preferences item just because you couldn't reach a decision. It's very easy to settle a dispute about how something should work by adding yet another preferences item.

Don't add a preferences item just because it's technically feasible to do it. Make sure it adds real value in the eyes of the user. (Note: we speak from experience here. Trust us on this one.)

{{Note|text=Make sure that a preferences item adds real value in the eyes of the user.}}

== The 90% Rule ==

If 90% of your users prefer A, and all but the most obstinate of those who prefer B could live with A, don't bother making it a preferences item. Remember, it is far easier to add a control next version than it is to take one away.

== Two Choices ==

Two basic design decisions confront you when it comes to preferences.

=== Duplicate System Prefs? ===

First, if one of the system preference editors contains an item relevant to your program, you must decide whether to duplicate the control in your program so that the user can override the system setting locally. For example, if you are writing a terminal package, you can use the baud rate the user has set with the Serial preferences editor or you can provide a control that allows the user to set the baud rate inside your application.

Here's a guideline: if in the course of using your program, a user is likely to change an option, provide controls local to your application even if the control duplicates an item in a system preference editor. In that case, your controls should override the system preferences within the scope of your application.

Whether you add controls local to your application or not, your program should look at the defaults the user has set up in the Workbench preferences editors and use them as the starting values for the preferences controls in your application.

{{Note|text=Your application should look at the defaults the user has set up in the Workbench Prefs editors and use these as the starting values in your application.}}

=== Menu or Editor? ===

The second design concern: you must decide where to put the controls for application-specific preferences. You can allow the user to access them through your application's Settings menu (see Chapter 6), or you can have an application preferences editor in your application's drawer; or you can provide both.

In general, try to use your application's Settings menu rather than a stand-alone editor to set preferences. Any menu item could lead to submenus or a series of requesters for more complex settings.

However, there are times when a preferences editor makes more sense than the Settings menu. For instance, your application might be a compiler that is used only from the Shell, or your application may have environment controls that need to be adjusted only when the user's hardware setup changes. In these cases, an application preferences editor may be better than using the Settings menu.

==== System-Wide Preferences ====

If, for some reason, your preferences will control options system-wide, the editor can go in SYS:Prefs. One example of this is a stand-alone PostScript printer driver.

== The System Preference Editors ==

Here's a list of the system preference editors and the system defaults they control. You should know what the system controls provide before writing any controls of your own.

{| class="wikitable"
! Name
! Description
|-
| Font
| Specification of default screen, system and Workbench fonts. The file format is IFF FORM PREF (FONT chunk). The filenames are screenfont.prefs, sysfont.prefs, and wbfont.prefs, respectively.
|-
| IControl
| Intuition-specific control items, including verify timeout and command key definitions. The file format is IFF FORM PREF (ICTL chunk). The filename is icontrol.prefs.
|-
| Input
| Mouse and keyboard control items. The file format is IFF FORM PREF (INPT chunk). The filename is input.prefs.
|-
| Overscan
| Standard video and text overscan areas for the various modes supported by the system. The file format is IFF FORM PREF (OSCN chunk). The filename is oscan.prefs.
|-
| Palette
| Color selections for the Workbench screen. The file format is IFF FORM ILBM (the main chunk is CMAP). The filename is palette.ilbm.
|-
| Pointer
| Design of the mouse pointer image. The file format is IFF FORM ILBM. The filename is pointer.ilbm.
|-
| Printer
| Printer text preferences and printer driver selection. The file format is IFF FORM PREF (PTXT chunk). The filename is printer.prefs.
|-
| PrinterGfx
| Printer graphic preferences. The file format is IFF FORM PREF (PGFX chunk). The filename is printergfx.prefs.
|-
| ScreenMode
| Display information such as the Workbench display mode and the raster dimensions. The file format is IFF FORM PREF (SCRM chunk). The filename is screenmode.prefs.
|-
| Serial
| Serial port definitions including baud rate, handshaking and parity. The file format is IFF FORM PREF (SERL chunk). The filename is serial.prefs.
|-
| Time
| System and real-time clock date and time. No file is used. Data is stored into the system and the battery-backed clock/calendar.
|-
| WBPattern
| The backdrop patterns used in Workbench and its windows. The file format is custom. Names are wb.pat and win.pat respectively.
|}

=== Storage of System Settings ===

Users can change system-wide settings for their current session by clicking the Use gadget in an editor, or they can change the permanent settings by clicking the Save gadget.

The system stores these settings files in four different locations. (Your application should follow these steps only if it installs a system-wide preferences editor in the [SYS:]Prefs drawer. Otherwise, you should follow the conventions outlined in the next section.)

* Defaults are imbedded in the system preferences themselves.

* If the user modifies a preference item and selects Save on the requester, the settings are stored in the preference archive ENVARC:sys/<filename> and ENV:sys/<filename> (see the list above for the filename).

* If the user selects Use on the requester (instead of Save), the current settings are stored only in ENV:sys/<filename>. The archived settings in ENVARC:sys remain unchanged. ENV: does not survive a reboot.

* Alternate settings called presets are stored in the Workbench:Prefs/Presets drawer or in other user-specified places.

=== Preference Presets ===

Preferences presets are alternate versions of the recognized preferences files. Their purpose is to support a variety of user configurations that can be "turned on" at the user's discretion.

For example, the default definition of the Amiga's mouse pointer is archived in ENVARC:sys/pointer.ilbm. However, the user may have an alternate pointer he favours when working with a paint program. An alternate image can be designed in the Pointer editor and saved in Workbench:Prefs/Presets.

Once it's saved as a preset, the user can activate the alternate image at any time by double-clicking on its icon. (The icon's default tool is the Pointer preferences editor.) The preset can also be activated from the Shell or from the editor. The original version will still be available in the ENVARC:sys directory.

== Conventions for Your Application's Prefs ==

The general rules: whenever possible, your application should allow the user to save his preferred settings and should initialize on startup to the user's settings - whether they are the user's default settings or another settings file specified by the user in a startup argument.

Also, whenever possible, the settings controls should be contained within your applications and accessed via the Settings menu. (See Chapter 6 for information about the Settings menu.)

=== Format ===

There is no strict structure for preferences files. They may be ASCII, IFF, binary, or any form suggested by the preferences data therein. Many of the system files are made up of structured binary data and are saved with only a small amount of identifying header information. Others, such as pointer.ilbm, are actual IFF ILBM files.

It is recommended that you use an IFF FORM for preferences files. If you wish to use a new or modified IFF FORM to contain your preference data, you should register the form at the [[IFF_FORM_and_Chunk_Registry|IFF FORM and Chunk Registry]].

{{Note|text=Preferences files may be ASCII, IFF, binary or any form suggested by the data. Using an IFF FORM is recommended.}}

=== Accessing Settings Files ===

Keeping the preferences operations simple yet viable for all types of users gets somewhat tricky for the application designer. To help with this, the following rules for accessing user preferences settings were devised.

Upon startup, your application should look for its application preferences settings in the following places, and in the following order. You should use built-in defaults only if no user-specified settings are found.

Note: keep in mind that allowing the user to save individual aspects of your program, rather than a general Save Settings, will change this scenario and the next one about saving settings files. Instead of looking for an individual file containing the settings, your program would be searching for a subdirectory of preferences settings. That directory would contain files such as pointer.ilbm or beepsound.8svx.

1.  Look first in a file specified in startup arguments. Users should be able to specify a filename and path in either to icon's Tool Types field or on the command line in the Shell. The keyword in both cases would be SETTINGS. The specified file would be a settings file or directory saved during a previous session with your program.

This will allow users without hard disks to save their settings wherever convenient - perhaps on a separate disk (some boot disks are too full already). It will also allow networked users to specify their individual settings files in project Tool Types or on the command line.

2.  If no SETTINGS argument is specified, look for the file <basename>.prefs in your application's directory. Accessing and storing the settings file in your application's directory instead of the SYS: directory may benefit users without a hard disk whose boot disks may be full. In most cases this will effectively be the default since most users will not specify a settings file in Tool Types or [on] the command line.

3.  If the settings aren't found in places 1 or 2, look for your application preferences settings file in ENV:<basename>/<basename>.prefs.

4.  Use the built-in default settings.

=== Saving Settings Files ===

The general rule here is to save any new settings chosen by the user to the place from which the settings were loaded - but allow the user to specify another place.

However, this changes if the settings were loaded from your built-in defaults - which would be the case if this is the first time a user is using your program. In this case you should go through what are basically the same steps [as] for loading a settings file.

Remember that if you allow individual aspects of your application to be saved, this changes from a search for a file to a search for a subdirectory and then a file or list of files.

1.  As stated in the general rule above, save to the same path and file from which you loaded the settings.

2.  If a file was not specified, save to the file called <basename>.prefs found in your application's directory. In most cases, this would be far enough to look and a good solution, but if your application is being used on a network, the network moderator would most likely set this file to be write-protected. He wouldn't want every user saving his settings on top of those optimized for the network.

3.  If you are unable to write to the file in step 2, save the settings in ENVARC:<basename>/<basename>.prefs and in ENV:<basename>/<basename>.prefs.

=== Application Preference Editors ===

The common way to handle user preferences is through a Settings menu item, but in more complex cases or when the settings will affect the overall system, you may want to use a stand-alone preferences editor.

Complex cases include those where a number of invocations of your program are running concurrently or sequentially, and your application needs to know the settings from previous invocations.

An example of a case where your program's settings affect the system is software for a multi-serial card.

The design guidelines for preferences editors given here will ensure that each one presents a familiar and consistent user interface. Be sure to include all of the following standard operations in your application's preferences editors. See Chapter 2 as well for general design guidelines.

==== Editor Startup ====

Every application preferences editor should have a set of reasonable default settings imbedded in the editor code. When the editor is started it should display the current internal settings unless a preset file name was given as an argument. If no preferences data is found, then revert to the default settings embedded in the code itself.

==== Editor Gadgets ====

Every application preferences editor should open a window with at least three gadgets: Save, Use and Cancel. The gadgets should be near the bottom of the window (Save on the left, Use in the middle, Cancel on the right). Here are the functions the three gadgets should perform:

; Save
: Use the new preferences settings the user has chosen and save the data to the assigned file. By default, it should be stored to the file ENVARC:<basename>/basename.prefs and ENV:<basename>/basename.prefs. The editor should terminate. Note that only system editors should store their data in the ENV:sys and ENVARC:sys directories.

; Use
: Use the new preferences settings the user has chosen and save the data to ENV:<basename>/<basename>.prefs. The editor should terminate. Because no change is made to the copy in ENVARC:<basename>/<basename>.prefs, any changes the user makes this way will be lost if the system is reset.

; Cancel
: Exit the editor. Any changes in preferences settings the user has chosen should be ignored.

Note: applications with a stand-alone preferences editor shared by default should read in their settings from ENV:<basename>/<basename>.prefs and use file notification to watch for changes to that file.

==== Editor Menus ====

Every application preferences editor should have at least three menus, a Project menu, an Edit menu and an Options menu. The Project menu should contain these menu items:

; Open
: Load preferences data from a preset file. A requester should appear that allows the user to specify the file's name as well as its path. The command key is Right-Amiga-O.

; Save As...
: Save preferences data in a preset file. A requester should appear that allows the user to specify the filename and path. The new file can be used as a preset. The command key is Right-Amiga-A.

; Quit
: Exit the editor without saving. The command key is Right-Amiga-Q.

The Edit menu should contain these items:

; Reset to Defaults
: Reset the preferences editor to the default values embedded in the editor code.

; Last Saved
: Reset the editor with the data from the preferences archive data file in ENVARC:<basename>/<basename>.prefs.

; Restore
: Reset the editor to the settings that were in effect when it was started.

; Undo
: Undo the most recent change the user made to the preferences settings.

The Options menu should contain at least this one menu item:

; Create Icons?
: Controls whether or not the editor will save a project icon with each preset saved.

==== Arguments ====

Editors should also accept command line arguments when executed from the Shell. When started from the Shell, the editor will not always open its window. Instead, the editor should perform the action as detailed in the arguments.

For both Shell usage and Tool Types usage, the command template should be of the form:

  FROM,EDIT/S,USE/S,SAVE/S,PUBSCREEN/K

* FROM tells which preset file to use. If this argument is left out, use the archived preferences settings in <programdirectory>:<basename>.prefs or revert to the defaults coded into the editor itself.

* EDIT opens the editor window and loads the preferences data in the file named in the FROM argument. This is the default switch. If no FROM is specified, the window should open with the defaults.

* USE performs a "Use" on the data found in the data file named in the FROM argument. Do not open the editor window.

* SAVE performs a "Save" on the data file named in the FROM argument. Do not open the editor window.

* PUBSCREEN opens the window on the named public screen.

Here's an example command line:

  1> Serial FROM SYS:ENVARC/Prefs/Presets/myserial.pre USE

With this command, the serial device Preferences editor is run invisibly from the Shell. Without opening its window, the editor loads the serial preset file named myserial.pre, performs the Use function and then exits. If this command is placed in the Amiga's Startup-sequence, it will override normal default preferences with the preset named in the FROM argument.

== Icons ==

The user should also have ultimate control over what icons look like.

Under past releases of the operating system, most applications hard coded their project icons into the program. You should name your default project icons in a standard manner and store them where the user can access them.

=== Naming Conventions ===

{{Note|text=These rules for icon naming and storage are designed so the user can control the look of your program's default icons.}}

Use the following naming convention:
 
  def_<icon type>.info
 
The placeholder <icon type> indicates the type of file represented. For example, the types of icons in the system are: disk, drawer, tool, project and trashcan.

The default icons for IFF files should use the FORM name as the <icon type>. For instance, a default icon for an IFF picture would be def_ILBM.info since ILBM is the FORM name. See Chapter 11 for more information on the IFF standard.

=== Storage and Access Conventions ===

Store your default icons in ENV:<basename> and in ENVARC:<basename>. If the user wants to change the default icon he can find it in that directory.

When your application needs an icon, direct it to look in ENV:<basename> first, then ENV:sys for the system default icon for that type of file. If it fails to find that, it should revert to the system's default project icon.

Here's an example: when the user saves a text file in an application named MystrEd, the application will first look in ENV:mysed for an icon file named def_TXT.info. Finding none, it will then look in ENV:sys for a file named the same. None is found there, so it uses the system's default project icon.

If, however, the MyStred user creates a default TXT icon in IconEdit and stores it as ENV:mysed/def_TXT.info, that icon should be used as the
default.

== Notification ==

Notification is an Amiga facility whereby an application may be informed whenever a change is made to a file of interest. Through notification it is possible for an application to find out whenever the user has made a change to any preferences data file. This allows the application to make an adjustment to reflect the new preferences settings. See Chapter 11 for more information.

Since an application has to handle its own preferences, there is not much point in getting notification about changes to application preferences files. However, changes to system preferences files may be relevant. For instance, a publishing program may want to be notified whenever the user changes the  printer graphic setting from black-and-white to color.

Under previous versions of the operating system, an application could ask Intuition to send it a message whenever system preferences data
changed. This method still works for Preferences items that existed under Release 1.3.

In either case, the important thing to understand is that your application is not expected to respond to every change made to system preferences. This is an extra feature you may add to your application if you believe it is warranted.