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.64
Apple Inc.
+0.92
MSFT
$45.30
Microsoft Corpora
+0.47
GOOG
$593.40
Google Inc.
-1.35

MacTech Search:
Community Search:

Software Updates via MacUpdate

Together 3.2 - Store and organize all of...
Together helps you organize your Mac, giving you the ability to store, edit and preview your files in a single clean, uncluttered interface. Smart storage. With simple drag-and-drop functionality,... Read more
Cyberduck 4.5 - FTP and SFTP browser. (F...
Cyberduck is a robust FTP/FTP-TLS/SFTP browser for the Mac whose lack of visual clutter and cleverly intuitive features make it easy to use. Support for external editors and system technologies such... Read more
Airmail 1.4 - Powerful, minimal email cl...
Airmail is a powerful, minimal mail client.It was designed to retain the same experience with a single or multiple accounts and provide a quick, modern and easy-to-use user experience. Airmail... Read more
Macs Fan Control 1.1.12 - Monitor and co...
Macs Fan Control allows you to monitor and control almost any aspect of your computer's fans, with support for controlling fan speed, temperature sensors pane, menu-bar icon, and autostart with... Read more
A Better Finder Rename 9.37 - File, phot...
A Better Finder Rename is the most complete renaming solution available on the market today. That's why, since 1996, tens of thousands of hobbyists, professionals and businesses depend on A Better... Read more
MacBook Air EFI Firmware Update 2.9 - Fo...
MacBook Air EFI Firmware Update is recommended for MacBook Air (Mid 2011) models. This update addresses an issue where systems may take longer to wake from sleep than expected and fixes a rare issue... Read more
FileZilla 3.9.0.1 - Fast and reliable FT...
FileZilla (ported from Windows) is a fast and reliable FTP client and server with lots of useful features and an intuitive interface.Version 3.9.0.1: MSW: Fix installation issue with locked DLLs... Read more
OS X Yosemite 10.10 DP4 - Developer Prev...
Note: This is a Developer Preview. You must be a registered Apple Mac Developer to download this update. OS X Yosemite is Apple's newest operating system for Mac. An elegant design that feels... Read more
FinderPop 2.5.6 - Classic Mac utility, n...
FinderPop is a Universal preference pane that extends OS X's contextual menus using a FinderPop Items folder much as the Apple Menu Items folder used to do for the Apple menu. It has other features... Read more
SpiderOak 5.1.7 - Secure cloud backup, s...
SpiderOak is a multi-platform secure online backup, storage, access, and sharing solution engineered for the consumer and small businesses. You must first sign up to use SpiderOak. Running natively... Read more

Latest Forum Discussions

See All

Secret Files Tunguska Review
Secret Files Tunguska Review By Jennifer Allen on July 23rd, 2014 Our Rating: :: CONSPIRACY-LITTERED ADVENTURINGUniversal App - Designed for iPhone and iPad Offering traditional adventuring with no fear of in-app purchases, Secret... | Read more »
Celebrate Summer With a Cat in the Hat L...
Celebrate Summer With a Cat in the Hat Learning Library Sale Posted by Ellis Spice on July 22nd, 2014 [ permalink ] Universal App - Designed for iPhone and iPad | Read more »
Dragon Raiders Review
Dragon Raiders Review By Nadia Oxford on July 22nd, 2014 Our Rating: :: RUN, DRAGON, RUNUniversal App - Designed for iPhone and iPad Dragon Raiders is rough and scaly in some parts, but overall it’s an enjoyable level-based running... | Read more »
MyTaskList Review
MyTaskList Review By Jennifer Allen on July 22nd, 2014 Our Rating: :: EFFECTIVE IF PLAINUniversal App - Designed for iPhone and iPad It’s not the most stylish of task management apps, but MyTaskList has all the features you could... | Read more »
FlyCraft Herbie: Crazy Machines Review
FlyCraft Herbie: Crazy Machines Review By Jennifer Allen on July 22nd, 2014 Our Rating: :: TRICKY FLYINGUniversal App - Designed for iPhone and iPad A tough game of careful thrusting and navigation, FlyCraft Herbie: Crazy Machines... | Read more »
MTN Review
MTN Review By Jessica Fisher on July 22nd, 2014 Our Rating: :: ADORABLE, SERENE, AND AMUSINGUniversal App - Designed for iPhone and iPad MTN is an adorable, talking pet mountain that is less game and more zen garden.   | Read more »
Fly High with Ninja UP! Now Available o...
Fly High with Ninja UP! Now Available on the App Store Posted by Jessica Fisher on July 22nd, 2014 [ permalink ] Universal App - Designed for iPhone and iPad | Read more »
Bio Inc. Review
Bio Inc. Review By Nadia Oxford on July 22nd, 2014 Our Rating: :: SICKENING - IN A COMPELLING WAYUniversal App - Designed for iPhone and iPad Bio Inc is about orchestrating the medical destruction of a single person. If that doesn’... | Read more »
HELMUT Review
HELMUT Review By Andrew Fisher on July 21st, 2014 Our Rating: :: TRUNDLE SIMULATOR 2014Universal App - Designed for iPhone and iPad HELMUT is a fun, fleeting time-sink that offers a momentary distraction and nothing else.   | Read more »
Walkr Review
Walkr Review By Jennifer Allen on July 21st, 2014 Our Rating: :: ORIGINAL WALKINGiPhone App - Designed for the iPhone, compatible with the iPad Walking is a bit more exciting thanks to this planet building/discovering sim reliant... | Read more »

Price Scanner via MacPrices.net

Apple 27″ Thunderbolt Display (refurbished) a...
The Apple Store has Apple Certified Refurbished 27″ Thunderbolt Displays available for $799 including free shipping. That’s $200 off the cost of new models. Read more
WaterField Designs Unveils Cycling Ride Pouch...
High end computer case and bag maker WaterField Designs of San Francisco now enters the cycling market with the introduction of the Cycling Ride Pouch – an upscale toolkit with a scratch-free iPhone... Read more
Kingston Digital Ships Large Capacity Near 1T...
Kingston Digital, Inc., the Flash memory affiliate of Kingston Technology Company, Inc.,has announced its latest addition to the SSDNow V300 series, the V310. The Kingston SSDNow V310 solid-state... Read more
Apple’s Fiscal Third Quarter Results; Record...
Apple has announced financial results for its fiscal 2014 third quarter ended June 28, 2014, racking up quarterly revenue of $37.4 billion and quarterly net profit of $7.7 billion, or $1.28 per... Read more
15-inch 2.0GHz MacBook Pro Retina on sale for...
B&H Photo has the 15″ 2.0GHz Retina MacBook Pro on sale for $1829 including free shipping plus NY sales tax only. Their price is $170 off MSRP. B&H will also include free copies of Parallels... Read more
Apple restocks refurbished Mac minis for up t...
The Apple Store has restocked Apple Certified Refurbished Mac minis for up to $150 off the cost of new models. Apple’s one-year warranty is included with each mini, and shipping is free: - 2.5GHz Mac... Read more
Twelve South HiRise For MacBook – Height-Adju...
If you use your MacBook as a workhorse desktop substitute, as many of us do, a laptop stand combined with an external keyboard and pointing device are pretty much obligatory if you want to avoid... Read more
Why The Mac Was Not Included In The Apple/IBM...
TUAW’s Yoni Heisler cites Fredrick Paul of Network World whoi blogged last week that the Mac’s conspicuous absence from Apple and IBM’s landmark partnership agreement represents a huge squandered... Read more
Save $100 on 13-inch Retina MacBook Pros, plu...
Adorama has 13″ Retina MacBook Pros on sale for $100 off MSRP. Shipping is free, and Adorama charges sales tax in NY & NJ only: - 13″ 2.4GHz/128GB MacBook Pro with Retina Display: $1199 - 13″ 2.... Read more
Blurr it 2.3 for iOS – Quickly Blurs Selected...
Hyderabad, India based TouchLabs has announced a new update of Blurr it 2.3, their photography app for iOS users. Blurr it allows you to blur part of the image to hide potentially sensitive or... Read more

Jobs Board

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* 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
*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 *Apple* Engineer - IT - Requisition #: -...
For more information about TIAA-CREF, visit our website . The Apple Engineer will provide engineering and third-level incident support for 300- 500 MacOS desktop/laptop Read more
*Apple* Systems Administrator - DISH (United...
…satellite service provider, and Dish is currently looking for an experienced Apple /Mac Systems Administrator. Apple systems administrator will be responsible for Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.