macdevcenter.com
oreilly.comSafari Books Online.Conferences.

advertisement

AddThis Social Bookmark Button

Adding a New Style Preferences Window to Your App, Part 2

by Martin Redington
01/27/2006

In part one of this series, I discussed how to create the necessary scaffolding for a new style preferences window. In this second part, I'll cover the creation of the actual preference panes.

Creating Preference Panes

To keep things tidy, I like to keep my preference panes code in a separate directory. In the Finder or the Terminal, create a new PreferencePanes directory, underneath your NewPreferencesExample project directory.

In Xcode, create a new PreferencePanes group under the NewPreferencesExample project.

Your First Preference Pane

Directory and Group

Now create another directory, GeneralPrefs, under the PreferencePanes directory, and a GeneralPrefs group in Xcode, under the PreferencePanes group.

A New Target

Still in Xcode, create a new target (from the Project Menu, or from the contextual menu for the project in the Groups and Files pane). Set the target's type to Cocoa "Loadable Bundle," and its name to GeneralPrefs.

Open the inspector for the main NewPreferencesExample target. In the General tab of the inspector, drag the new GeneralPrefs target from Xcode's Groups and Files pane to the "Direct Dependencies" list.

We also need to link our new target against the Cocoa framework. Expanding both targets in the Groups and Files pane, drag Cocoa.framework from the "Link Binary with Libraries" build phase of the NPEPreferencesController target to the corresponding build phase of the GeneralPrefs target.

Open the inspector for NPEPreferencePaneController.m, and add it to the GeneralPrefs target, as well as to NPEPreferencesExample.

A Preference Pane Icon

We will "borrow" GeneralPreferences.tiff from Safari.app--in the Terminal, cd to the top-level directory for your project, and run the following command:

cp /Applications/Safari.app/Contents/Resources/GeneralPreferences.tiff \
PreferencePanes/GeneralPrefs

Then, in Xcode, use the "Add to Project" item in the Project menu to add the GeneralPreferences.tiff file to your project, as an "Existing File." In the dialog that appears when adding the file, uncheck the "Copy items into destination group's folder" item, and make sure that GeneralPreferences.tiff is only being added to the GeneralPrefs target.

GeneralPreferencePaneController

Add a new Objective-C class, called GeneralPreferencePaneController, to the GeneralPrefs group, with target GeneralPrefs only. The source code for the GeneralPreferencePaneController.h class is shown below:

#import <Cocoa/Cocoa.h>
#import "NPEPreferencePaneController.h"

@interface GeneralPreferencePaneController : NPEPreferencePaneController {
}

@end

GeneralPreferencePaneController.m is even simpler:

#import "GeneralPreferencePaneController.h"

@implementation GeneralPreferencePaneController

@end

GeneralPrefs.nib

In Interface Builder, create a new empty Cocoa nib, and save it in the PreferencePanes/GeneralPrefs folder as GeneralPrefs.nib--when you are presented with a dialog asking if you want to add it to the NewPreferencesExample project, and which targets to add it to, add it to the GeneralPrefs target only.

Still in Interface Builder, select the Classes tab, and parse the NPEPreferencePaneController.h and GeneralPreferencePaneController.h header files (you need to parse the superclass header before you can parse the subclass). Then set the custom class of "File's Owner" to be the GeneralPreferencePaneController class.

Then drag a CustomView from the Interface Builder Cocoa Containers palette into your nib file. Hook this custom view up to the _prefsView outlet of File's Owner.

GeneralPrefs-Info.plist

Back in Xcode, In the Info panel for the new GeneralPrefs target, in the Properties tab, set the Principal Class to be GeneralPreferencePaneController, and the Main Nib File to be "GeneralPrefs."

In the Build tab of the Info panel for the new target, set "Wrapper Extension" to be "preferencePane." Also in the Build tab, set the Info.plist entry to read PreferencePanes/GeneralPrefs/GeneralPrefs-Info.plist instead of GeneralPrefs-Info.plist.

In the Finder or the Terminal, move the GeneralPrefs-Info.plist file to the PreferencePanes/GeneralPrefs subdirectory. Then find the GeneralPrefs-Info.plist entry in the Groups and Files pane of Xcode, drag it into the GeneralPrefs group, and using "Get Info" (Command-I) in Xcode, adjust the path for GeneralPrefs-Info.plist to match its new location.

We now need to add a few preferencePane-specific properties to the GeneralInfo.plist file, specifying at minimum the preference pane name, icon path, and tooltip.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" 
   "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
  <dict>
    <!-- existing entries -->
    ...

    <!-- new mandatory entries -->
    <key>paneName</key>
    <string>General</string>    
    <key>iconPath</key>
    <string>GeneralPreferences.tiff</string>        
    <key>toolTip</key>
    <string>General Preferences</string> 

    <!-- new optional entries -->
    <key>helpAnchor</key>
    <string>GeneralPreferencesHelp</string> 
    <key>allowsHorizontalResizing</key>
    <string>NO</string> 
    <key>allowsVerticalResizing</key>
    <string>NO</string> 

  </dict>
</plist>

Finishing Up

Now build and run the NPEPreferencesExample target in Xcode. As before, select the "Preferences..." item from the NewApplication menu. Once again, "Preferences are not available."

Although we have successfully built both the NPEPreferencesExample and GeneralPrefs products, NPEPreferencesExample cannot find the GeneralPrefs bundle.

Select the NPEPreferencesExample target in Xcode, and add a new Copy Files build phase. The destination will be Resources (which should be the default), but there is no need to enter anything in the path field. Instead, drag GeneralPrefs.preferencePane from the Products group into the new Copy File build phase.

Now, build and run the NPEPreferencesExample target again, and once the main window has launched, hit Command-Minus, to bring up the Preferences Window. Tada! You now have a new style preferences window.

figure

Figure 1. The first preference pane

Running Mac OS X Tiger

Related Reading

Running Mac OS X Tiger
A No-Compromise Power User's Guide to the Mac
By Jason Deraleau, James Duncan Davidson

Pages: 1, 2, 3

Next Pagearrow