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
Preferences files may be ASCII, IFF, binary or any form suggested by the data. Using an IFF FORM is recommended.
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 with Commodore Applications and Technical Support.
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.
Follow these steps to access settings files.
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 cshould 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.
Follow this order when your application is saving settings 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 nuimber 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 filename was given as an argument. If no preferences data is found, then revert to the default settings embedded in the code itself.
The design guidelines given here for preference editors are intended to ensure that each has a familiar and consistent user interface.
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
Reset the preferences editor to the default values embedded
Defaults
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.