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

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

ResEdit

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?

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 application that has a signature matching the file creator. If the search is successful, the Finder launches the application and (if the application supports the required Apple event suite) sends an Open Documents Apple event to the application, with the document file as a parameter. If the search for the application that created the file isn't successful, an alert similar to the one shown in Figure 3 is displayed.

Figure 3. Application-unavailable alert

Our problem is that we don't want the Finder to launch our application when a user attempts to open its preferences file. One way to solve this (as suggested on pages 7-29 to 7-30 of Inside Macintosh: Macintosh Toolbox Essentials ) is to register a "dummy" application signature that's different from the real signature of your application, and then set this signature as the preferences file creator.

Normally, an application has only a single signature resource and a single bundle resource. By creating a second bundle resource with a dummy application signature and associating our preferences file with that signature, we fool the Finder into looking for a nonexistent application for our preferences file, thus preventing the Finder from launching our application when the preferences file is double-clicked. Figure 4 shows examples of a normal application bundle resource and a dummy bundle resource for the application's preferences file.

Remember to register both creators -- the real one and the dummy one -- with the Developer Support Center (AppleLink DEVSUPPORT, or Apple Computer, Inc., Creator/File Type Registration, 20525 Mariani Avenue, M/S 303-2T, Cupertino, CA 95014).

If you use this technique, you should also supply an application-missing message string resource -- an 'STR ' resource with an ID of -16397 -- in the preferences file. When the user tries to open a file and the application can't be found, the Finder looks for this resource in the file. That string is displayed in the alert that comes up when the user tries to open the file and -- due to the dummy bundle resource -- fails (see Figure 5).

Application bundle resource

Dummy bundle resource for preferences files Figure 4. Bundle resources

Figure 5. Can't open preferences file alert

Now for the catch: There are two ways this mechanism can be circumvented. First, it can be overridden if Macintosh Easy Open is running. Macintosh Easy Open uses the Translation Manager to open a file with an alternate application if the application that created the file isn't available. It determines the file type of the file that the user is trying to open and then looks for applications that support that file type by checking their bundle resources. If no applications can be found that support the file type, an alert notifying the user is displayed (see Figure 6). However, if any alternate applications are found, an alert allowing the user to open the file with one of them is displayed (see Figure 7). When Macintosh Easy Open is installed, one of these two alerts will always be displayed in place of the normal application-unavailable alert.

Because our application has a dummy bundle resource that refers to the file type of our preferences file, Macintosh Easy Open will always find the application that created the preferences file as an alternate application. Fortunately, the Translation Manager provides a mechanism to help us hide our preferences file -- the 'open' resource. In the 'open' resource, an application can specify to the Translation Manager exactly what file types it can actually open, regardless of what may be specified in any bundle resources. By creating an 'open' resource that doesn't contain our preferences file type, we can prevent Macintosh Easy Open from trying to open the file.

The Rez definition for the 'open' resource is given below.

type 'open' {
    literal longint;               /* App signature */
    integer = 0;
    integer = $$CountOf(typeArray) /* Array size */
    wide array typeArray {         /* File types that app can open */
        literal longint;           /* File type */
    };
};

An example 'open' resource might look like this:

resource 'open' (128) {
    'TSTR',
    {
        'TEXT'
    }
};

Figure 6. Modified application-unavailable alert

Figure 7. Translation choices alert

In this example, we've declared that the application with creator 'TSTR' can only open files of type 'TEXT' -- the Translation Manager will not attempt to use this application to open any other type of file.

Our mechanism is also circumvented if the file type of the preferences file is 'PICT' or 'TEXT' and TeachText is installed. In this case, the Finder displays an alert asking whether the user wants to open the document in TeachText, even if you supplied an application-missing message string resource in the file and provided the appropriate dummy bundle and 'open' resource in your application. This is a pretty good reason for not using 'PICT' or 'TEXT' as the file type for your preferences file.

WHAT GOES IN A PREFERENCES FILE

Keep your preferences as resources.
As we all know, you can put program data into either the data fork or the resource fork of a Macintosh HFS file. The popular response to the question "What is a resource?" is "Everything!", and this is still reasonable advice. It's fairly easy to design C structs that mirror the structures of your preferences data, and you can even design 'TMPL' resources that will let you look at your raw preferences data in a structured way by opening your preferences file with ResEdit. Plus, you've got the Resource Manager to do all the work of finding and loading the preferences data into memory for you. What more could you ask?

Keep only global user preferences in your preferences file.
Bear in mind that some user preferences are global (application or environment related) and some are local (document related) -- don't confuse the two. For example, keeping track of the size and position of every document window that's ever been opened by your application in its preferences file isn't a good idea (this information should be kept with the document file corresponding to the document window), but keeping a user-specified default window size and position in its preferences fileis  a good idea.

Avoid keeping machine-specific information in your preferences file.
It's rare that you really need to keep information such as the system software version or the Macintosh model that your software is running on in your preferences file. Your application generally should examine its environment at launch, and take appropriate measures at that time to avoid using features that aren't supported in the current environment.

Be careful of storing dynamic information in your preferences file.
A good example of something not to store in your preferences file is a volume reference number. To quote Inside Macintosh: Files , "A volume reference number is valid only until the volume is unmounted -- if a single volume is mounted and then unmounted, the File Manager may assign it a different volume reference number when it is next mounted." In this example, a better solution is to store an alias to the volume of interest in the preferences file.

Use discretion in deciding what preferences to keep.
To a large degree, this means limiting user options to those that actually improve the overall user experience. The only proven way to find out what those options are is to conduct user testing on a variety of interface prototypes. It may turn out that while you thought keeping track of the last known number of documents open during the user's last session with your application was important, it actually adds little or nothing when translated into the user's experience.

Don't keep static program data in your preferences file.
A file that just contains a lot of canned program data (such as tax forms) isnot  a preferences file -- it's simply a program data file, and it should normally reside in the same folder as the application. That way, the user doesn't disable the application if she throws away what she thinks is simply the application's preferences file (users often do this to cause an application to reset back to its "factory" defaults, which, when you think about it, is a pretty nasty way to make users reset a program).

THE STANDARD PREFERENCES LIBRARY

CREATING AND MANIPULATING A PREFERENCES FILE
In the routines described here, you'll notice that a preferences file is primarily identified not by its name, but by its creator and file type. This is done to allow you to localize the name of your preferences file easily, without requiring any code or resource changes. Also, should a userinadvertently rename your preferences file, your application can still find it. Because preferences files are identified in this manner, it's important to remember to give each preferences file that your application uses a unique creator/file type combination. The search sequence for a preferences file is as follows: 1. If there's a Preferences folder in the System Folder, search it and any folders within it (including nested ones). 2. If there's no Preferences folder, or if no preferences file is found in the Preferences folder, search the files (not the folders) in the System Folder.

pascal OSErr NewPreferencesFile (OSType creator, OSType fileType,
    ConstStr31Param fileName, ConstStr31Param folderName, 
    ConstStr31Param ownerName);

pascal OSErr OpenPreferencesFile (OSType creator, OSType fileType, 
    short *refNum);

pascal OSErr ClosePreferencesFile (short refNum);

pascal OSErr DeletePreferencesFile (OSType creator, OSType fileType);

pascal OSErr DeletePreferencesFolder (ConstStr31Param folderName);

pascal OSErr PreferencesFileExists (OSType creator, OSType fileType);

ACCESSING INFORMATION IN A PREFERENCES FILE
These routines get or set the indicated resource information in the preferences file specified by the refNum parameter.

pascal OSErr GetPreferencesFileVersion (short refNum, short versID,
    NumVersion *numVersion, short *regionCode, ConstStr255Param
    shortVersionStr, ConstStr255Param longVersionStr);

For those of you wondering why GetPreferencesFileVersion doesn't simply pass a pointer to a VersRec (defined in Files.h) instead of passing each of the separate fields of a VersRec, it's because the short version string and the long version string are packed in a VersRec (it's possible that the shortVersion field of the VersRec will actually contain part of the long version string). GetPreferencesFileVersion takes care of unpacking the strings properly, and SetPreferencesFileVersion takes care of packing them properly.

pascal OSErr SetPreferencesFileVersion (short refNum, short versID,
    NumVersion *numVersion, short regionCode, ConstStr255Param
    shortVersionStr, ConstStr255Param longVersionStr);

pascal OSErr ReadPreference (short refNum, ResType resourceType,
    short *resourceID, Handle *preference);

pascal OSErr WritePreference (short refNum, ResType resourceType,
    short *resourceID, Handle preference);

pascal OSErr DeletePreference (short refNum, ResType resourceType,
    short resourceID);

PLEASE PROVIDE PREFERRED PREFERENCES FILES (SAY THAT  THREE TIMES FAST!)

REFERENCES

• Inside Macintosh: Macintosh Toolbox Essentials  (Addison-Wesley, 1992), Chapter 7, "Finder Interface," orInside Macintosh  Volume VI (Addison-Wesley, 1991), Chapter 9, "The Finder Interface."
• Inside Macintosh: More Macintosh Toolbox  (Addison-Wesley, 1993), Chapter 7, "Translation Manager."
• Inside Macintosh: Overview  (Addison-Wesley, 1992), Chapter 3, "Resources," pages 60 to 67.
• Macintosh Human Interface Guidelines  (Addison-Wesley, 1992), Chapter 3, "Human Interface Design and the Development Process," pages 37 and 38, and Chapter 8, "Icons," page 250.

GARY WOODCOCK, formerly of Apple but now at 3DO, is currently assimilating experiences accrued during his annual pilgrimage to the South by Southwest Music Conference in Austin, Texas. For those readers who find stimulation in spending four days and nights attending live performances by a diverse assortment of interesting, boisterous, and relatively unknown bands playing in a variety of beer-drenched pubs, in the company of equally interesting, boisterous, and beer-drenched people, a better venue Gary cannot recommend. *

Thanks to our technical reviewers Nick Kledzik, Jim Luther, and John Mitchell. Special thanks to Jim Luther for his excellent file system utilities (collect 'em all -- they're on this issue's CD) and to Elizabeth Moller for her assistance on human interface issues.*