Legacy Document

Inside Macintosh: Files /

Chapter 1 - Introduction to File Management / Using Files

Using a Preferences File

Many applications allow the user to alter various settings that control the operation or configuration of the application. For example, your application might allow the user to specify the size and placement of any new windows or the default font used to display text in those windows. You can create a preferences file in which to record user preferences, and your application can retrieve that file whenever it is launched.

In deciding how to structure your preferences file, it is important to distinguish document-specific settings from application-specific settings. Some user-specifiable settings affect only a particular document. For example, the user might have changed the text font in a particular window. When you save the text in the window, you also want to save the current font setting. Generally you can do this by storing the font name in a resource in the document file's resource fork. Then, when the user opens that document again, you check for the presence of such a resource, retrieve the information stored in it, and set the document font accordingly.

Some settings, such as a default text font, are not specific to a particular document. You might store such settings in the application's resource fork, but generally it is better to store them in a separate preferences file. The main reason for this is to avoid problems that can arise if an application is located on a server volume. If preferences are stored in resources in the application's resource fork, those preferences apply to all users executing that application. Worse yet, the resources can become corrupted if several different users attempt to alter the settings at the same time.

Thus, it is best to store application-specific settings in a preferences file. The Operating System provides a special folder in the System Folder, called Preferences, where you can store that file. Listing 1-18 illustrates a way to open your application's preferences file.

Listing 1-18 Opening a preferences file

PROCEDURE DoGetPreferences;
VAR
   myErr:      OSErr;
   myVRef:     Integer; {volume ref num of Preferences folder}
   myDirID:    LongInt; {dir ID of Preferences folder}
   mySpec:     FSSpec;  {FSSpec for the preferences file}
   myName:     Str255;  {name of the application}
   myRef:      Integer; {ref num of app's resource file; ignored}
   myHand:     Handle;  {handle to Finder information; ignored}
   myRefNum:   Integer; {file reference number}
CONST
   kPrefID = 128;       {resource ID of STR# with filename}
BEGIN
   {Determine the name of the preferences file.}
   GetIndString(myName, kPrefID, 1);
   
   {Find the Preferences folder in the System Folder.}
   myErr := FindFolder(kOnSystemDisk, kPreferencesFolderType,
                      kDontCreateFolder, myVRef, myDirID);
   IF myErr = noErr THEN
      myErr := FSMakeFSSpec(myVRef, myDirID, myName, mySpec);
   IF myErr = noErr THEN
      myRefNum := FSpOpenResFile(mySpec, fsCurPerm);
   
   {Read your preference settings here.}

   CloseResFile(myRefNum);
END;

The DoGetPreferences procedure first determines the name of the preferences file it is to open and read. To allow easy localization, you should store the name in a resource of type 'STR#' in your application's resource file. The DoGetPreferences procedure assumes that the name is stored as the first string in the resource having ID kPrefID.

The technique shown here assumes that your preference settings can all be stored in resources. As a result, Listing 1-18 calls the Resource Manager function FSpOpenResFile to open the resource fork of your preferences file. See the chapter "Resource Manager" in Inside Macintosh: More Macintosh Toolbox for complete details on opening resource files and reading resources from them.