Introduction

This set of classes and protocols is used to build, organise and display preference panes. The preferences window allows the same kind of display and sorting of panes as Apple's System Preferences. Preference panes may be build in to the application or provided as loadable bundles.

If – after reading this documentation and looking at the provided sample source code – you have any other questions about these classes, send mail to andreas@harmless.de.

Creating a Preferences Window

Creating a Preferences Window is simply a matter of creating an instance of AMPreferenceWindowController:

AMPreferenceWindowController *controller = [[AMPreferenceWindowController alloc] initWithAutosaveName:@"PreferenceWindow"];

After you added preference panes and set some options the preference window is displayed using:

[controller showWindow:self];
[[controller window] makeKeyAndOrderFront:self];

For more options see the AMPreferenceWindowController Reference.

Writing a Preference Pane

To build a preference pane you create a new class that conforms to the AMPrefPaneProtocol:

@interface MyPreferencePane : NSObject <AMPrefPaneProtocol> {
}
- (NSString *)identifier;
- (NSView *)mainView;
- (NSString *)label;
- (NSImage *)icon;
- (NSString *)category;
@end

After you created an instance of this class, you add the preference pane to the preference window controller:

MyPreferencePane *myPreferencePane = [[[MyPreferencePane alloc] init] autorelease];
[controller addPane:myPreferencePane withIdentifier:@"myPrefPaneIdentifier"];

The identifier is just a unique string that is used to distinguish between multiple panes.

For more information see the AMPrefPaneProtocol Reference.

Writing a Preference Plug-In

When creating a new project for a preference plug-in, select Cocoa Bundle in Xcode's Project Assistant window.

A preference plug-in needs to conform to the AMPrefPaneBundleProtocol:

@interface MyPreferencePlugin : NSObject <AMPrefPaneBundleProtocol> {
}
- (id)initWithBundle:(NSBundle *)theBundle;
- (NSBundle *)bundle;
- (NSView *)loadMainView;
- (NSView *)mainView;
@end

For the preference pane to appear in your preferences window you have to tell the controller where to load the plug-ins from. In this example we assume that they reside inside the application bundle's default plug-in folder:

[controller addPluginsOfType:nil fromPath:[[NSBundle mainBundle] builtInPlugInsPath]];

The preferences window controller will only load a preference pane bundle if it is actually selected by the user. General information like the name and the icon of the preference pane is loaded separately from the bundle. For that reason the bundle's info.plist needs to contain some additional keys:

<key>NSPrefPaneIconFile</key>
<string>IconFileName</string>

<key>NSPrefPaneIconLabel</key>
<string>Pref Pane Label</string>

<key>AMPrefPaneCategory</key>
<string>Pref Pane Category</string>

Note that you will also need the standard keys for bundles:

<key>CFBundleIdentifier</key>
<string>DoublesAsPrefPaneIdentifier</string>

<key>NSPrincipalClass</key>
<string>MyPreferencePlugin</string>

<key>NSMainNibFile</key>
<string>PrefPaneNib</string>

You'll find more information in the AMPrefPaneProtocol Reference.

AMPreferenceWindowController Reference

The preferences window controller is reponsible for handling preference panes, loading plug-ins and displaying the preferences window.

- (id)initWithAutosaveName:(NSString *)name;

designated initializer

name is an identifier used to save the window's position in the standard user defaults database.

- (id)delegate;

the objects delegate

- (void)setDelegate:(id)newDelegate;

sets the objects delegate

see the AMPrefPaneDelegate informal protocol for more information

- (BOOL)usesConfigurationPane;

tells wether the user will be able to display a configuration pane

- (void)setUsesConfigurationPane:(BOOL)newUsesConfigurationPane;

sets wether the user will be able to display a configuration pane

A configuration pane shows all preference panes sorted by name or by category. Enabling this option also allows reordering of selected panes in the preference window's toolbar.

Needs to be set before actually showing the prefs window.

- (BOOL)sortByCategory;

YES if preference panes will be sorted by category, NO else

- (void)setSortByCategory:(BOOL)newSortByCategory;

Pass YES as parameter if preference panes should be sorted by category, NO else.

- (NSArray *)categorySortOrder;

A sorted list of categories.

- (void)setCategorySortOrder:(NSArray *)newCategorySortOrder;

Categories will be sorted according to the contents of this array.

If no sort order is given, categories will be sorted by alphabet. Also any categories not included in the sort order will be appended in alphabetical order.

- (NSString *)title;

The preferences window's title.

- (void)setTitle:(NSString *)newTitle;

Specify a title for the preferences window.

- (BOOL)addPane:(AMPreferencePane *)newPane withIdentifier:(NSString *)identifier;

Add a single preference pane to the preferences window.

Preference panes need to conform to the AMPrefPaneProtocol.

See Writing a Preference Pane.

- (void)addPluginFromPath:(NSString *)path;

Load a single preference pane plug-in.

You will normally want to load all plug-ins from inside a given folder. See addPluginsOfType:fromPath:

- (void)addPluginsOfType:(NSString *)extension fromPath:(NSString *)path;

Load all plug-ins from path with extension extension.

If you do not require a special type, pass nil as pluginType (see NSBundle's pathForResource:ofType:).

- (BOOL)selectPaneWithIdentifier:(NSString *)identifier;

Use this method to select a specific pane programatically.

Returns YES if pane was selected successfully.

- (BOOL)selectIconViewPane;

Select the icon view pane.

Returns YES if pane was selected successfully.

- (void)replyToShouldUnselect:(BOOL)shouldUnselect;

not used

- (NSDictionary *)prefPanes;

A dictionary of all available preference panes.

The key is the preference pane's identifier. The object is known to implement the AMPrefPaneProtocol.

- (NSString *)categoryForIdentifier:(NSString *)identifier;

The category the preference pane with identifier identifier belongs to.

This value may have been changed by the controller's delegate. See the AMPrefPaneDelegate informal protocol.

- (NSArray *)categories;

a list of all known categories.

- (NSString *)categoryDisplayNameForIdentifier:(NSString *)identifier;

The localized display name for the category of preference pane identifier.

This value may have been changed by the controller's delegate. See the AMPrefPaneDelegate informal protocol.

AMPrefPaneProtocol Reference