# AMPreferencePane Classes Documentation

http://www.harmless.de/cocoa.html

# Index

Introduction

Creating a Preferences Window

Writing a Preference Pane

Writing a Preference Plug-In

AMPreferenceWindowController Reference

AMPrefPaneProtocol Reference

# 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.

## Legalese

You are allowed to use the source code provided under the following conditions:

- If you redistribute the code or substantial parts of it, you need to include this documentation. Any modifications need to be clearly marked as yours.
- If you use this code or parts of it in your application, you need to give me credit in the application's About Window and in the documentation.

In case these requirements are inconvenient to you, tell me and we will find a solution.

# 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.

## AMPrefPaneDelegate informal protocol

All delegate methods are optional. (As is the delegate itself.)

- (NSString *)displayNameForCategory:(NSString *)category;

Return a localized display name for category.

- (NSString *)categoryForPreferencePane:(NSString *)identifier defaultCategory:(NSString *)category;

By implementing this method, the delegate has control over the association of preference panes to categories.

Return the value passed as defaultCategory if you want to use the category supplied by the preference pane.

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

Return YES if the preference pane with the given identifier should be loaded.

- (void)willSelectPreferencePane:(NSString *)identifier;

Informs the delegate that the preference pane with the identifier identifier has been selected and will be displayed in the preferences window.

- (void)didUnselectPreferencePane:(NSString *)identifier;

Informs the delegate that the preference pane with the identifier identifier has been deselected.

# AMPrefPaneProtocol Reference

## AMPrefPaneProtocol

This protocol is mandatory for all preference panes.

Plug-Ins are handled by the preferences window controller and will conform to this protocol automatically. They need to implement the AMPrefPaneBundleProtocol instead.

- (NSString *)identifier;

The preference pane's unique identifier.

- (NSView *)mainView;

The preference pane's main view.

The preferences window will automatically be resized to encompass this view when the preference pane is selected.

- (NSString *)label;

A localized label for the preference pane.

- (NSImage *)icon;

An icon for display in the preferences window.

- (NSString *)category;

The category the preference pane belongs to.

The category is used to sort the preference panes in the preferences window. Valid values are depending on the application.

## AMPrefPaneBundleProtocol

This is the protocol preference pane plug-ins have to conform to.

- (id)initWithBundle:(NSBundle *)theBundle;

Called when the bundle is loaded.

You may want to store the bundle reference for later use.

- (NSBundle *)bundle;

The plug-in's bundle.

- (NSView *)loadMainView;

This is gueranteed to be called before the main view is used for the first time.

- (NSView *)mainView;

The main view.

## AMPrefPaneInformalProtocol

These are optional methods that any preference pane class – plug-in or not – may implement.

- (void)willSelect;

The preference pane has been selected and will be shown after this call.

- (void)didSelect;

The preference pane has been selected and displayed.

- (int)shouldUnselect;

The preferences window controller wants to show a different preference pane or close the window.

Result should be of type NSPreferencePaneUnselectReply.

Not used at this time.

- (void)willUnselect;

The preference pane has been unselected and will be hidden after this call.

- (void)didUnselect;

The preference pane has been unselected and hidden.

- (NSString *)categoryDisplayName;

The localized category name.

- (NSString *)version;

Version information - e.g. "1.0"

This is not used by default. Applications may choose to use this information for their own purposes.