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.

 

Community Search:
MacTech Search:

Software Updates via MacUpdate

Sound Studio 4.8.6 - Robust audio record...
Sound Studio lets you easily record and professionally edit audio on your Mac. Easily rip vinyls and digitize cassette tapes, or record lectures and voice memos. Prepare for live shows with live... Read more
Capo 3.5.1 - Slow down and learn to play...
Capo lets you slow down your favorite songs so you can hear the notes and learn how they are played. With Capo, you can quickly tab out your songs atop a highly-detailed OpenCL-powered spectrogram... Read more
Google Earth 7.1.8.3036 - View and contr...
Google Earth gives you a wealth of imagery and geographic information. Explore destinations like Maui and Paris, or browse content from Wikipedia, National Geographic, and more. Google Earth combines... Read more
QuickBooks 16.1.11.1556 R12 - Financial...
QuickBooks helps you manage your business easily and efficiently. Organize your finances all in one place, track money going in and out of your business, and spot areas where you can save. Built for... Read more
Google Earth 7.1.8.3036 - View and contr...
Google Earth gives you a wealth of imagery and geographic information. Explore destinations like Maui and Paris, or browse content from Wikipedia, National Geographic, and more. Google Earth combines... Read more
QuickBooks 16.1.11.1556 R12 - Financial...
QuickBooks helps you manage your business easily and efficiently. Organize your finances all in one place, track money going in and out of your business, and spot areas where you can save. Built for... Read more
FileZilla 3.24.0 - Fast and reliable FTP...
FileZilla (ported from Windows) is a fast and reliable FTP client and server with lots of useful features and an intuitive interface. Version 3.24.0: New The context menu for remote file search... Read more
Bookends 12.7.8 - Reference management a...
Bookends is a full-featured bibliography/reference and information-management system for students and professionals. Bookends uses the cloud to sync reference libraries on all the Macs you use.... Read more
Duplicate Annihilator 5.8.3 - Find and d...
Duplicate Annihilator takes on the time-consuming task of comparing the images in your iPhoto library using effective algorithms to make sure that no duplicate escapes. Duplicate Annihilator detects... Read more
BusyContacts 1.1.6 - Fast, efficient con...
BusyContacts is a contact manager for OS X that makes creating, finding, and managing contacts faster and more efficient. It brings to contact management the same power, flexibility, and sharing... Read more

Super Mario Run dashes onto Android in M...
Super Mario Run was one of the biggest mobile launches in 2016 before it was met with a lukewarm response by many. While the game itself plays a treat, it's pretty hard to swallow the steep price for the full game. With that said, Android users... | Read more »
WarFriends Beginner's Guide: How to...
Chillingo's new game, WarFriends, is finally available world wide, and so far it's a refreshing change from common mobile game trends. The game's a mix of tower defense, third person shooter, and collectible card game. There's a lot to unpack here... | Read more »
Super Gridland (Entertainment)
Super Gridland 1.0 Device: iOS Universal Category: Entertainment Price: $1.99, Version: 1.0 (iTunes) Description: Match. Build. Survive. "exquisitely tuned" - Rock Paper Shotgun No in-app purches, and no ads! | Read more »
Red's Kingdom (Games)
Red's Kingdom 1.0 Device: iOS Universal Category: Games Price: $4.99, Version: 1.0 (iTunes) Description: Mad King Mac has kidnapped your father and stolen your golden nut! Solve puzzles and battle goons as you explore and battle your... | Read more »
Turbo League Guide: How to tame the cont...
| Read more »
Fire Emblem: Heroes coming to Google Pla...
Nintendo gave us our first look at Fire Emblem: Heroes, the upcoming mobile Fire Emblem game the company hinted at last year. Revealed at the Fire Emblem Direct event held today, the game will condense the series' tactical RPG combat into bite-... | Read more »
ReSlice (Music)
ReSlice 1.0 Device: iOS Universal Category: Music Price: $9.99, Version: 1.0 (iTunes) Description: Audio Slice Machine Slice your audio samples with ReSlice and create flexible musical atoms which can be triggered by MIDI notes or... | Read more »
Stickman Surfer rides in with the tide t...
Stickson is back and this time he's taken up yet another extreme sport - surfing. Stickman Surfer is out this Thursday on both iOS and Android, so if you've been following the other Stickman adventures, you might be interested in picking this one... | Read more »
Z-Exemplar (Games)
Z-Exemplar 1.4 Device: iOS Universal Category: Games Price: $3.99, Version: 1.4 (iTunes) Description: | Read more »
5 dastardly difficult roguelikes like th...
Edmund McMillen's popular roguelike creation The Binding of Isaac: Rebirth has finally crawled onto mobile devices. It's a grotesque dual-stick shooter that tosses you into an endless, procedurally generated basement as you, the pitiable Isaac,... | Read more »

Price Scanner via MacPrices.net

12-inch 1.2GHz Space Gray Retina MacBook on s...
Amazon has the 2016 12″ 1.2GHz/512GB Space Gray Retina MacBook (Apple model #MLH82LL/A) on sale for $1299.99 including free shipping. Their price is $300 off MSRP. Read more
Twelve South Releases RelaxedLeather Cases fo...
Inspired by the laid-back luxury of burnished leather boots and crafted in rich tones of taupe, herb and marsala, RelaxedLeather cases deliver smart, easy protection for the iPhone 7. Each genuine... Read more
Week’s Best Deal: New 2016 13-inch 2.0GHz Mac...
Amazon has the new 2016 13″ 2.0GHz non-Touch Bar MacBook Pros on sale for a limited time for $225 off MSRP including free shipping: - 13″ 2.0GHz MacBook Pro, Space Gray (MLL42LL/A): $1274.99 $225 off... Read more
Back in stock: Apple refurbished Mac minis fr...
Apple has Certified Refurbished Mac minis available starting at $419. Apple’s one-year warranty is included with each mini, and shipping is free: - 1.4GHz Mac mini: $419 $80 off MSRP - 2.6GHz Mac... Read more
Apple Ranked ‘Most Intimate Brand’
The top ranked ‘”intimate” brands continued to outperform the S&P and Fortune 500 indices in revenue and profit over the past 10 years, according to MBLM’s Brand Intimacy 2017 Report, the largest... Read more
B-Eng introduces SSD Health Check for Mac OS
Fehraltorf, Switzerland based independant Swiss company- B-Eng has announced the release and immediate availability of SSD Health Check 1.0, the company’s new hard drive utility for Mac OS X. As the... Read more
Apple’s Education discount saves up to $300 o...
Purchase a new Mac or iPad using Apple’s Education Store and take up to $300 off MSRP. All teachers, students, and staff of any educational institution qualify for the discount. Shipping is free: -... Read more
4-core 3.7GHz Mac Pro on sale for $2290, save...
Guitar Center has the 3.7GHz 4-core Mac Pro (MD253LL/A) on sale for $2289.97 including free shipping or free local store pickup (if available). Their price is a $710 savings over standard MSRP for... Read more
128GB Apple iPad Air 2, refurbished, availabl...
Apple has Certified Refurbished 128GB iPad Air 2s WiFis available for $419 including free shipping. That’s an $80 savings over standard MSRP for this model. A standard Apple one-year warranty is... Read more
13-inch 2.7GHz Retina MacBook Pro on sale for...
B&H Photo has the 2015 13″ 2.7GHz/128GB Retina Apple MacBook Pro on sale for $100 off MSRP. Shipping is free, and B&H charges NY tax only: - 13″ 2.7GHz/128GB Retina MacBook Pro (MF839LL/A): $... Read more

Jobs Board

*Apple* macOS Systems Integration Administra...
…most exceptional support available in the industry. SCI is seeking an Junior Apple macOS systems integration administrator that will be responsible for providing Read more
*Apple* Retail - Multiple Positions- Deer Pa...
Job Description: Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, Read more
*Apple* Retail - Multiple Positions - Apple,...
Job Description: Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, Read more
*Apple* Technician - nfrastructure (United S...
Let’s Work Together Apple Technician This position is based in Portland, ME Life at nfrastructure At nfrastructure, we understand that our success results from our Read more
*Apple* Mobile Master - Best Buy (United Sta...
**467692BR** **Job Title:** Apple Mobile Master **Location Number:** 000602-Columbia MO-Store **Job Description:** **What does a Best Buy Apple Mobile Master Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.