Volume Number: 19 (2003)
Issue Number: 11
Column Tag: Programming

Mac OS X Programming Secrets

Building a System Preference Pane

by Scott Knaster

Most applications include a Preference item in their application menu that lets users tweak the way things work. In fact, the very program I'm using to type these words includes a vast set of preferences with over 100 settings divided into ten categories. Even the Finder includes its own preferences.

Sometimes, little bits of software need to have preferences, but are not substantial enough to easily provide a user interface for them. These can include parts of the system, such as the Dock or the built-in Screen Effects, or cool third-party utilities. In Mac OS 9, users often tweaked these settings in control panels. As with so many things, the preferences world has changed radically since those bygone days. Mac OS X provides a System Preferences application that includes preference panes for these assorted but important system settings.

OS X comes with a bunch of preference panes used for system settings, as you can see in Figure 1. But in addition, System Preferences (since OS X 10.1, anyway) provides a plug-in framework that you can use to create you own preference panes that appear in the System Preferences window right alongside the system's built-in panes.

For this month's column, I'm borrowing code and the concept from Joe Zobkiw's cool new book, Mac OS X Advanced Development Techniques. This book provides real code and information about a nifty collection of OS X topics, including applications, system services, multiple threads, and more. If you want to read a fun, well-written book that will broaden your knowledge of OS X programming topics, check it out.

For our sample in this column, we'll create a simple preference pane called BigPane that has a checkbox and a text field. To get started, crank up Project Builder and choose New Project from the File menu. When you get the New Project Assistant, take a look under the Standard Apple Plug-ins section. Hey, there's a project type called PreferencePane! By choosing that one, we get a project that's already hooked up to the preference pane framework. We'll go ahead and create our new preference pane project.

Once the project has been created, we can move forward with the primary task of writing the code. The empty project declares BigPanePref, a subclass of NSPreferencePane. The listing follows:

@interface BigPanePref : NSPreferencePane 
{
   CFStringRef m_appID;   // our application ID
   
   IBOutlet   NSButton   *m_checkBox;
   IBOutlet   NSTextField   *m_textField;
}
- (IBAction)checkboxClicked:(id)sender;
@end

Here we're simply declaring the class, including a string to hold the application ID so we can find our preferences file, references to the controls that are included in the pane, and the checkBoxClicked action that we'll implement.

Getting into the actual code, the first thing we'll deal with is overriding initWithBundle, which is called when the preference pane starts up.

#import "MyPreferencePanePref.h"
@implementation MyPreferencePanePref
- (id)initWithBundle:(NSBundle *)bundle
// System Preferences calls this method when 
// the pane is initialized.
{
   // Initialize the location of our preferences
    if ((self = [super initWithBundle:bundle]) != nil) {
        m_appID = CFSTR("com.knaster.bigpane");
    }
    
    return self;
}

This override gets us the appID, which we'll use to locate the file that preferences are stored in. You should use a filename that is unlikely to be the same as any other file, and is named after the application or service whose preferences it contains. Also, because this is an init method, Apple says we should be good citizens and call the inherited implementation, which we do.

Once the view is created and the nib file is loaded, our mainViewDidLoad method will be called. This is where we get a chance to initialize the preference controls with their saved values:

- (void)mainViewDidLoad
{
    CFPropertyListRef value;
      // Get the value of the checkbox from the saved prefs
      // (if any)
    value = CFPreferencesCopyAppValue
(CFSTR("Boolean Value Key"), m_appID);
    if (value && CFGetTypeID(value) == CFBooleanGetTypeID()) {
        [m_checkBox setState:CFBooleanGetValue(value)];
    } else {
        [m_checkBox setState:NO];         
      // Turn it off if we can't find a saved value
    }
    if (value) CFRelease(value);
    // Get the contents of the text field
    value = CFPreferencesCopyAppValue
(CFSTR("String Value Key"), m_appID);
    if (value && CFGetTypeID(value) == CFStringGetTypeID()) {
        [m_textField setStringValue:(NSString *)value];
    } else {
        [m_textField setStringValue:@""];   
      // Make the string empty if there's no saved value
    }
    if (value) CFRelease(value);
}

In our override of mainViewDidLoad, we get the values of our two preferences (a checkbox and a text field, remember) from the file. We're getting some help from the cool Core Foundation Preference Services here. We call CFPreferencesCopyAppValue to get the values out of the file, and we use CFGetTypeID to ensure the values are valid. If not, we set the controls to default values. Continuing in our quest for good citizenship in case we have to run for governor some day, we release the value objects when we don't need them any more.

Now that the pane is up and running and the controls have their values loaded, what happens when the user starts changing stuff? If the user clicks on the checkbox, we'll get a checkboxClicked message, so we'll override that method to change the associated preference at the same time:

- (IBAction)checkboxClicked:(id)sender 
{
      if ( [sender state] ) 
         CFPreferencesSetAppValue(CFSTR("Boolean Value Key"), 
         kCFBooleanTrue, appID ); 
      else 
         CFPreferencesSetAppValue(CFSTR("Boolean Value Key"), 
         kCFBooleanFalse, appID ); 
}

In this method, we're simply setting the value of the preference based on the state of the checkbox. We use the handy CFPreferencesSetAppValue call from Core Foundation Preference Services. Why don't we save the value of the text field this way, too? We could, by watching for various NSText messages, but it's probably sufficient just to save the text field when the user is done with the pane, which we'll do in didUnselect, coming up next.

Can you believe we're almost finished writing the code for our little sample? All that's left is the implementation of the didUnselect method:

- (void)didUnselect
// The system calls didUnselect when another pane is
// opening or the user quits System Preferences.
{
    CFNotificationCenterRef center;
   
   // Save the value in the text field
   // to our preferences file.
    CFPreferencesSetAppValue(CFSTR("String Value Key"), [m_textField stringValue], m_appID);
    
   // Make sure the file is flushed and its contents written
   // to disk.
   CFPreferencesAppSynchronize(m_appID);
   // Broadcast a notification that preferences have
   // changed, in case Big Brother is watching.
center = CFNotificationCenterGetDistributedCenter();
    CFNotificationCenterPostNotification(center, CFSTR("Preferences Changed"), m_appID, NULL, TRUE);
}

The main work of the didUnselect override is to save the contents of the text field to our prefs file, which we do by calling CFPreferencesSetAppValue and CFPreferencesAppSynchronize. Also, we call CFNotificationCenterPostNotification to send a notification to any interested code that our prefs have changed - probably, nobody cares, but you never know.

Putting together the nib file and finishing the project are pretty straightforward. Using Interface Builder, just place the controls you're using - in this case, our check box and text field - in the window provided by the project. Figure 3 shows how this looks in Interface Builder.

Of course, when you're making your own preference pane, just arrange the controls and other user interface elements however you like. You can even add a tabbed view (NSTabView) to the window and place controls in multiple tabs. Your code doesn't know or care which tab contains a particular control.

Another neat trick is to add your own custom 32 by 32 pixel Finder icon for the pane. You can do this by putting your icon into the project's .tiff file - in our example, that would be BigPane.tiff. This file is automatically created by ProjectBuilder with the default light switch icon.

If you're building a preference pane as part of a real project, you'll want to include the pane in your installer. The pane should go into ~/Library/PreferencePanes. When you're just practicing, you can drag the preference bundle there and install it yourself. If the System Preferences application is running, quit it and run it again. You should see your new preference pane listed in the "Other" ghetto at the bottom of the screen if you're viewing by category, and in proper alphabetical order otherwise. Note that you can't place your pane into an existing category, nor can you create new categories. Bummer. Maybe that ability will come in a future version.

This covers the basics of creating a system preference pane, so you should now be able to go forward with your plans for that awesome system service or other minimal-UI widget. If you want to learn more about this topic, or many other related cool OS X tricks, please check out Mac OS X Advanced Development Techniques, written by Joe Zobkiw and published by Sams Publishing Developer's Library. See http://www.triplesoft.com/macosx/ to find out more.

Scott Knaster has been writing about Macs for as long as there have been Macs. Scott's books How To Write Macintosh Software and Macintosh Programming Secrets were required reading for Mac programmers for more than a decade. Scott wrote developer books for General Magic and worked on Mac software for Microsoft. Scott's books have been translated into Japanese and Pascal. Scott has every issue of Mad magazine, which explains a lot.