June 94 - The Right Way to Implement Preferences Files
GARY WOODCOCK
Many Macintosh applications use preferences files to keep track of user preferences.
This article describes the characteristics of a well implemented preferences file and
introduces a library that manages this work for you.
Preferences files have become a standard feature of most Macintosh applications. With
these files being so commonplace, it's timely to investigate how to implement them
properly. We'll first take a look at what constitutes a well implemented preferences
file; then we'll inspect a library API that provides a simple means of creating and
interacting with preferences files. On this issue's CD you'll find source code for a
standard preferences library and a test application that illustrates how to use the
library. This library is written with version 6.0.1 of Symantec's THINK C for
Macintosh using the universal interface files (which can also be found on the CD).
Before we begin, let's take a look at when and when not to create a preferences file. A
preferences file needs to be created only when the user has altered the default
configuration of the application. Upon being launched for the first time, many
applications automatically search for a preferences file and, if it isn't found,
immediately create one. But why? Has the user changed anything? Nope. The user
probably hasn't even had an opportunity to pull down an application menu at this point.
So why do we need to create a preferences file? We don't, and we shouldn't.
But given those situations in which your applicationshould create a preferences file,
read on to learn how to do it the right way.
WHAT MAKES A WELL IMPLEMENTED PREFERENCES FILE
The two Finder info windows shown in Figure 1 illustrate a poorly implemented and a
well implemented preferences file. We can categorize the visible differences in Figure
1 by file type, document kind, Finder icon, and version information, as explained in
the following sections. Note that the concepts presented here apply to implementingany
kind of document file, not just preferences files.
Poorly implemented preferences file
Well implemented preferences file
Figure 1. Info windows for example preferences files
FILE TYPE
Like any other file created by your application, your preferences file should have a
unique file type, which is specified in a file reference ('FREF') resource in the
application. The file type of the preferences file should be associated with the
application signature so that the Finder can display which application created the file
when its info window is shown. This association is made in your application's bundle
('BNDL') resource, which includes the application signature, the file reference
resources, and the application and document file icons. The info window for the poorly
implemented preferences file shown in Figure 1 doesn't display any information about
which application created the file because the file type isn't associated with an
application signature.
Incidentally, you shouldnot use 'pref' as the file type for your preferences file; this
file type is reserved for the Finder Preferences file (as you'd find out if you tried to
register this file type with Apple's Developer Support Center -- youwere going to do
that for the file type of your preferences file, right?). If you were to give your
preferences file this file type, you'd notice that when the user turns on Balloon Help,
the Balloon Help for your preferences file is actually the Balloon Help for the Finder
Preferences file. I'll go out on a limb here and assume that we can all agree this is
confusing for users, and should therefore be avoided.
DOCUMENT KIND
A file's Finder info window also indicates the kind of document the file is. In many
cases, this field reads either "document" or something like "MegaWhizzyApp
document." But with the introduction of the Translation Manager (first made available
with Macintosh Easy Open), a new resource type has been defined that your application
can use to more accurately describe its files, including its preferences file. This
resource is called the 'kind' resource, and its Rez definition is as follows:
type 'kind' {
literal longint; /* App signature */
integer; /* Region code of kind string localizations */
integer = 0;
integer = $$CountOf(kindArray) /* Array size */
wide array kindArray {
literal longint; /* File type */
pstring; /* Custom kind strings */
align word;
};
};
An example 'kind' resource might look like this:
resource 'kind' (128) {
'TSTR',
0,
{
'TEXT', "MegaWhizzyApp text document
}
};
In this example, assuming the Translation Manager is present, a file with creator
'TSTR' and file type 'TEXT' will display the string "MegaWhizzyApp text document" in
the document kind field of its info window.
FINDER ICON
As suggested inMacintosh Human Interface Guidelines , the best icon for preferences
files is either the standard preferences file icon or an icon that incorporates some
elements of the standard preferences file icon (see Figure 2). It's not taboo to use a
unique preferences file icon, but this may make it difficult for users to recognize the
file as a preferences file.
Standard Icon
Movie Recorder
Figure 2. Example preferences file icons
As noted above, you provide a Finder icon for your preferences file the same way that
you provide Finder icons for your other document files -- through a bundle resource
in your application.
VERSION INFORMATION
A file's 'vers' (version) resources determine what version information is displayed in
the Finder info window. There are normally two 'vers' resources for a file -- 'vers'
IDs 1 and 2 -- and each contains the following: * A numeric code representing the
version. This code consists of a major revision number, a minor revision number, an
optional bug fix revision number, a stage code (development, alpha, beta, or final),
and a revision level (for non-final stages). * A region code, which indicates the
localized version of system software appropriate for use with the file. * A short
version string identifying the version number. * A long version string consisting of
the file version number and company copyright in 'vers' ID 1, and the product version
number and name in 'vers' ID 2.
For more information about these resources and how they affect what's displayed in the
Finder info window, see pages 7-31 to 7-32 ofInside Macintosh: Macintosh Toolbox
Essentials. For the structs corresponding to the 'vers' resource, check out the Files.h
header file.
Providing version information in your preferences files does more than just make the
Finder info window look pretty. You can use this information to identify the format of
the data contained in a preferences file. This is useful in determining how to translate
preferences data created by an older version of an application into the preferences
format for the current version of the application.
CAN USERS OPEN PREFERENCES FILES?
Users have a penchant for running rampant through their hard disks, looking for
interesting files to open, particularly if the files weren't explicitly created by them.
Files kept in the System Folder are no exception to this experimentation, so it should
come as no surprise to you that your application should be prepared to correctly
handle the case where its preferences file has been double-clicked.
There are several interesting possible behaviors that a preferences file might exhibit
under these circumstances. One alternative is that the application the preferences file
belongs to could launch, configuring itself with the data contained in the file. A
variation of this behavior would be to display the application's preferences dialog after
launching, if such a dialog were supported. A third behavior is that when a user
double-clicks a preferences file, its application isn't launched, but instead a dialog is
displayed describing what the file is, where it belongs, and why it can't be opened.
Today, the only preferences file behavior approved and documented by Apple is the last
one. The Human Interface Design Center of Apple's system software group has this to
say about preferences files:
• Preferences files should not be treated as if they were documents created
by the user. Launching an application and optionally opening a preferences
dialog support the misconception that theyare like documents.
• Not all applications have preferences dialogs. Launching an application
that doesn't have a preferences dialog when its preferences file is
double-clicked is confusing, because there's nothing specific to show the user
that represents the information stored in the file.
• The current thinking is that a user doesn't open the System Folder, see a
preferences file for MacWrite (for example), and wonder what the
preferences for MacWrite are set to; he's more likely to see the file and
wonder what it's used for. In this case, an informative dialog that's displayed
when the user attempts to open the preferences file better satisfies the user's
intent.
• Ideally, users shouldn't really even have to know about preferences files
(and therefore shouldn't be able to double-click them), but they're an
unavoidable artifact of the current system.
It should be pointed out that launching an application by double-clicking a file
containing configuration data is not necessarily a bad thing -- it just shouldn't be done
with a preferences file. Your application could use an application-specific
configuration file to allow users to store and set up custom configurations. By creating
a specific file type for this information, you make it explicit to users that the
behavior of this file type is different from that of preferences files, and that it is
unique to your application.
Now let's take a closer look at how to implement the recommended preferences file
behavior.
SUPPRESSING LAUNCH UPON DOUBLE-CLICK
As we learned in the previous section, a preferences file isn't intended to be a
document that users can open and directly interact with in the application that created
it. So how can you keep users from launching your application when they double-click
your preferences file?
Let's take a brief look at how the System 7 Finder handles opening document files.
Normally, when a user tries to open a document file, the Finder searches for an