TweetFollow Us on Twitter

Building a System Preference Pane

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.


Figure 1. System Preferences window.

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.

They Thought of This

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.


Figure 2. New, empty 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.

First Things First

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.

Preparing for the Invasion

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.

More Details

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.


Figure 3. Our preference pane 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.

Summing Up

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.

 
AAPL
$95.60
Apple Inc.
-2.55
MSFT
$43.16
Microsoft Corpora
-0.42
GOOG
$571.60
Google Inc.
-15.82

MacTech Search:
Community Search:

Software Updates via MacUpdate

OneNote 15.2 - Free digital notebook fro...
OneNote is your very own digital notebook. With OneNote, you can capture that flash of genius, that moment of inspiration, or that list of errands that’s too important to forget. Whether you’re at... Read more
iStat Menus 4.22 - Monitor your system r...
iStat Menus lets you monitor your system right from the menubar. Included are 8 menu extras that let you monitor every aspect of your system. Some features: CPU -- Monitor cpu usage. 7 display... Read more
Ember 1.8 - Versatile digital scrapbook....
Ember (formerly LittleSnapper) is your digital scrapbook of things that inspire you: websites, photos, apps or other things. Just drag in images that you want to keep, organize them into relevant... Read more
OmniPlan 2.3.6 - Robust project manageme...
With OmniPlan, you can create logical, manageable project plans with Gantt charts, schedules, summaries, milestones, and critical paths. Break down the tasks needed to make your project a success,... Read more
Command-C 1.1.1 - Clipboard sharing tool...
Command-C is a revolutionary app which makes easy to share your clipboard between iOS and OS X using your local WiFi network, even if the app is not currently opened. Copy anything (text, pictures,... Read more
Knock 1.1.7 - Unlock your Mac by knockin...
Knock is a faster, safer way to sign in. You keep your iPhone with you all the time. Now you can use it as a password. You never have to open the app -- just knock on your phone twice, even when it's... Read more
Mellel 3.3.6 - Powerful word processor w...
Mellel is the leading word processor for OS X and has been widely considered the industry standard since its inception. Mellel focuses on writers and scholars for technical writing and multilingual... Read more
LibreOffice 4.3.0.4 - Free Open Source o...
LibreOffice is an office suite (word processor, spreadsheet, presentations, drawing tool) compatible with other major office suites. The Document Foundation is coordinating development and... Read more
Freeway Pro 7.0 - Drag-and-drop Web desi...
Freeway Pro lets you build websites with speed and precision... without writing a line of code! With it's user-oriented drag-and-drop interface, Freeway Pro helps you piece together the website of... Read more
Drive Genius 3.2.4 - Powerful system uti...
Drive Genius is an OS X utility designed to provide unsurpassed storage management. Featuring an easy-to-use interface, Drive Genius is packed with powerful tools such as a drive optimizer, a... Read more

Latest Forum Discussions

See All

Dawn of the Immortals Review
Dawn of the Immortals Review By Jennifer Allen on July 31st, 2014 Our Rating: :: RESPECTABLE EXPLORATIONUniversal App - Designed for iPhone and iPad Dawn of the Immortals might not re-invent the wheel, but it does tweak it a little... | Read more »
80 Days Review
80 Days Review By Jennifer Allen on July 31st, 2014 Our Rating: :: EPIC ADVENTUREUniversal App - Designed for iPhone and iPad A fantastic and fascinating re-envisioning of the classic novel by Jules Verne, 80 Days is a delightful... | Read more »
Battleheart Legacy Guide
The world of Battleheart Legacy is fun and deep; full of wizards, warriors, and witches. Here are some tips and tactics to help you get the most enjoyment out of this great game. | Read more »
Puzzle Roo Review
Puzzle Roo Review By Jennifer Allen on July 31st, 2014 Our Rating: :: PUZZLE-BASED TWISTUniversal App - Designed for iPhone and iPad A different take on the usual block dropping puzzle game, Puzzle Roo is quite pleasant.   | Read more »
Super Crossfire Re-Release Super Crossfi...
Super Crossfire Re-Release Super Crossfighter Coming Soon, Other Radiangames Titles Go 50% Off Posted by Ellis Spice on July 31st, 2014 [ | Read more »
Hexiled Review
Hexiled Review By Rob Thomas on July 31st, 2014 Our Rating: :: HEX SELLSUniversal App - Designed for iPhone and iPad In space, no one can hear you… spell? Hexiled is a neat concept for a word scramble puzzle, but it doesn’t go too... | Read more »
Summoners War: Sky Arena Passes 10 Milli...
Summoners War: Sky Arena Passes 10 Million Installs! Posted by Jessica Fisher on July 31st, 2014 [ permalink ] Universal App - Designed for iPhone and iPad | Read more »
Deep Loot Review
Deep Loot Review By Jennifer Allen on July 31st, 2014 Our Rating: :: DIVE DEEPUniversal App - Designed for iPhone and iPad Dive deep in this fun explore-em-up that’s a little grind heavy but ultimately quite entertaining.   | Read more »
Despicable Me: Minion Rush is One Year O...
Despicable Me: Minion Rush is One Year Old, Gets its Biggest Update Yet Posted by Jennifer Allen on July 31st, 2014 [ permalink ] Universal App - Designed for iPhone and iPad | Read more »
Fish & Shark Review
Fish & Shark Review By Jordan Minor on July 31st, 2014 Our Rating: :: FLAPPY FISHUniversal App - Designed for iPhone and iPad Fish & Shark’s beauty is only scale deep.   | Read more »

Price Scanner via MacPrices.net

Save up to $130 on an iPad mini with Apple re...
The Apple Store has Certified Refurbished 2nd generation iPad minis with Retina Displays available for up to $130 off the cost of new models, starting at $339. Apple’s one-year warranty is included... Read more
iPad Cannibalization Threat “Overblown”
Seeking Alpha’s Kevin Greenhalgh observes that while many commentators think Apple’s forthcoming 5.5-inch panel iPhone 6 will cannibalize iPad sales, in his estimation, these concerns are being... Read more
Primate Labs Releases July 2014 MacBook Pro P...
Primate Labs’ John Poole has posted Geekbench 3 results for most of the new MacBook Pro models that Apple released on Tuesday. Poole observes that overall performance improvements for the new MacBook... Read more
Apple Re-Releases Bugfixed MacBook Air EFI Fi...
Apple has posted a bugfixed version EFI Firmware Update 2.9 a for MacBook Air (Mid 2011) models. The update addresses an issue where systems may take longer to wake from sleep than expected, and... Read more
Save $50 on the 2.5GHz Mac mini, plus free sh...
B&H Photo has the 2.5GHz Mac mini on sale for $549.99 including free shipping. That’s $50 off MSRP, and B&H will also include a free copy of Parallels Desktop software. NY sales tax only. Read more
Save up to $140 on an iPad Air with Apple ref...
Apple is offering Certified Refurbished iPad Airs for up to $140 off MSRP. Apple’s one-year warranty is included with each model, and shipping is free. Stock tends to come and go with some of these... Read more
$250 price drop on leftover 15-inch Retina Ma...
B&H Photo has dropped prices on 2013 15″ Retina MacBook Pros by $250 off original MSRP. Shipping is free, and B&H charges NY sales tax only: - 15″ 2.3GHz Retina MacBook Pro: $2249, $250 off... Read more
More iPad Upgrade Musings – The ‘Book Mystiqu...
Much discussed recently, what with Apple reporting iPad sales shrinkage over two consecutive quarters, is that it had apparently been widely assumed that tablet users would follow a two-year hardware... Read more
13-inch 2.5GHz MacBook Pro on sale for $999,...
Best Buy has the 13″ 2.5GHz MacBook Pro available for $999.99 on their online store. Choose free shipping or free instant local store pickup (if available). Their price is $100 off MSRP. Price is... Read more
Save up to $300 on an iMac with Apple refurbi...
The Apple Store has Apple Certified Refurbished iMacs available for up to $300 off the cost of new models. Apple’s one-year warranty is standard, and shipping is free. These are the best prices on... Read more

Jobs Board

*Apple* Retail - Multiple Positions (US) - A...
Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, you're also the Read more
Sr. Product Leader, *Apple* Store Apps - Ap...
**Job Summary** Imagine what you could do here. At Apple , great ideas have a way of becoming great products, services, and customer experiences very quickly. Bring Read more
Sr Software Lead Engineer, *Apple* Online S...
Sr Software Lead Engineer, Apple Online Store Publishing Systems Keywords: Company: Apple Job Code: E3PCAK8MgYYkw Location (City or ZIP): Santa Clara Status: Full Read more
Sr Software Lead Engineer, *Apple* Online S...
Sr Software Lead Engineer, Apple Online Store Publishing Systems Keywords: Company: Apple Job Code: E3PCAK8MgYYkw Location (City or ZIP): Santa Clara Status: Full Read more
*Apple* Solutions Consultant (ASC) - Apple (...
**Job Summary** The ASC is an Apple employee who serves as an Apple brand ambassador and influencer in a Reseller's store. The ASC's role is to grow Apple Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.