Original URL: https://www.theregister.com/2008/03/11/mac_secrets_preferences/
A better way to build OS X preferences
Behind the interface
Posted in Devops, 11th March 2008 06:02 GMT
Mac Secrets Welcome to Dave Jewell’s new Mac Secrets column, focused at Apple Mac developers — particularly those using Cocoa. Here, on a regular basis, Dave will introduce you to unknown and undocumented aspects of the Foundation and AppKit class libraries that Apple has, er, neglected to tell you about…
In my opinion, there’s no sense in re-inventing the wheel if Apple has already done the job for you. Over the coming months you’ll find there are an amazing number of undocumented wheels within the Apple libraries that let you get on with writing great applications without having to reinvent what Apple have already done. They are just waiting for you to set ’em spinning!
At this point, a few folks will doubtless be sharpening their quill pens (or even wooden stakes!) and preparing to chastise me for using undocumented features. After all, it’s possible that the techniques I’m going to describe may not work in some future version of the operating system, right? That’s true, but I’d offer a couple of counter arguments in return.
First, Leopard (OS X 10.5) has only recently been released, and is likely to be good for several years — it’s very unlikely that minor system updates would impact what I’m describing here. And if they do, I’ll obviously make every effort to bring you a workaround.
Next, and more importantly, you can spend more time making your great Mac application even greater — and surely that’s what we’d all like to see, including Apple. Right, Apple?
Implementing preference dialogs
Let’s start by taking a look at preference dialogs. As you’ll know, the standard way of building a preference dialog is to create a window complete with toolbar buttons for each “page” of preferences. You can see an example of this in the advanced portion of the Safari preferences dialog box (below).
A preference dialog box from Safari
In recent years, the mechanics of automatically saving and loading your application preferences have become easier, largely due to the introduction of Cocoa bindings. You can read more on this here. What I’m concerned with in this article, however, is the user interface rather than persistence issues.
There are really two undocumented classes we need to focus on here. These are NSPreferences and NSPreferencesModule. You can think of the former as a sort of supervisory class that handles the display of the preferences window. Most of the real work is done by this class, but — for our purposes — the interface is extremely simple. You will typically have one subclass of NSPreferences, and it will be instantiated by AppKit, not by you.
The other class, NSPreferencesModule, corresponds to one page of your tabbed preferences dialog. If you’ve got three preference categories (for example), then you’ll need three subclasses of NSPreferencesModule. Again, you don’t need to instantiate them.
To use these classes, you’ll first need to get the corresponding header files NSPreferences.h and NSPreferencesModule.h. The simplest way of doing this is to use Steve Nygard’s excellent class-dump utility, which you can find here. Run it on the actual executable inside Appkit.framework and redirect the output to a temporary text file. You can then edit this file to extract the class declarations you’re interested in.
Create a new, empty Cocoa application to serve as a test bed for this stuff. You’ll typically want to invoke the preferences window in response to a menu option, but in my test application, I just used a button press in the main window. Here’s what the action procedure (inside AppController.m) looks like:
- (IBAction) showPreferences: (id) sender
{
[NSPreferences setDefaultPreferencesClass: [AppPreferences class]];
[[NSPreferences sharedPreferences] showPreferencesPanel];
}
Here, we’ve set up a subclass of NSPreferences called AppPreferences. This code tells NSPreferences to use that class, and then displays the preferences dialog. It’s inside AppPreferences.m that the interesting stuff happens:
- (id) init
{
_nsBeginNSPSupport(); // MUST come before [super init]
[super init];
[self addPreferenceNamed: @"General"
owner: [GeneralPreferences sharedInstance]];
[self addPreferenceNamed: @"HotKeys"
owner: [HotKeyPreferences sharedInstance]];
return self;
}
- (BOOL) usesButtons
{
return NO;
}
In this case, the init method (called from AppKit) adds two pages to our preference dialogs: GeneralPreferences and HotKeyPreferences. Both of these are sub classed from NSPreferencesModule.
Two points: first, in real-world code you’d typically localize the page names, “General” and “HotKeys” in this case. Second, by default, NSPreferences will assume the needed NIB files and image files have the same name as the module class, such as GeneralPreferences.nib or GeneralPreferences.png for example. Image files should be 32×32 pixels in size.
You’ll also note that evil-looking call to _nsBeginNSPSupport. This is a fairly recent addition by Apple that is designed, I suspect, to prevent third-party use of NSPreferences. Without a preceding call to this extern void routine, the call to super init will return nil.
A very simple demo project can be downloaded here.
There’s more that can be said about NSPreferences and NSPreferencesModule, of course, but I’ll mention just one other interesting feature of NSPreferences for now. When you call the init method for this class, it will look in your application’s resource path for a file called PreferencePanels.plist. If found, this file is used to add all your application’s preference panels in one go. For more on this, have a peek at the aforementioned PreferencePanels.plist file inside your Mail.app.
Until next time, have fun! ®