---

Introduction to Preference Panes

Contents:

Who Should Read This Document?
Organization of This Document
Limitations

Preference panes are dynamically loaded plug-ins that provide a graphical user interface to the system’s or an application’s user preferences. Preference panes can be presented to the user using the central System Preferences application, using a specialized preferences application, or as the Preferences menu item in an application’s application menu. In System Preferences, each icon in its Show All view represents an individual preference pane plug-in. You can develop preference panes for use by System Preferences or by your own application.

The most common situation for using preference panes is an application that lacks its own user interface (or has a very restricted user interface such as the Mac OS X Login application) but needs to be configurable. Possible cases include a server application that always runs in the background or an application that makes its services available to other applications through the Services menu. To allow configuration of these applications, you must provide a user interface in a separate application. You should not require the user to hand-edit configuration files or execute the application from the command line with special arguments. Instead, create one or more preference pane plug-ins that contain the user interface and the code that can read and write the preference settings. Then, either supply your own “Setup” application or, if appropriate, use System Preferences to display the preference panes.

Who Should Read This Document?

You should read this document if you are a Cocoa developer who wants to provide a custom preference pane, accessible from the System Preferences applications, to your users. You should have a working knowledge of Cocoa programming with the Application Kit before attempting preference pane programming.

Organization of This Document

This document describes how to create and manage a preference pane, how to have System Preferences load your own preference pane, and how to load a preference pane in your own application.

Here are the concepts covered:

• “Architecture of Preference Panes” describes the plug-in architecture of preference panes and how they interact with applications and the system.

• “The Preference Application” describes the ways the preference pane can be presented to the user: System Preferences, a specialized preferences application, or inside the main application.

• “Managing User Preferences” describes several ways the preference pane can interact with the system for manipulating preferences.

• “Life Cycle of a Preference Pane” describes how the application interacts with the preference pane.

• “Anatomy of a Preference Pane Bundle” describes the structure of a preference pane bundle.

Here are the tasks covered:

• “Preventing Name Conflicts” recommends a technique to prevent name conflicts between the global symbols in your preference pane and either the application or other preference panes.

• “Using Preference Services” describes the methods available for reading and writing preferences to a preference file.

• “Communicating With the Target Application” provides examples for notifying a separate target application of preference changes.

• “Creating a Preference Pane Bundle” walks you through the steps of creating a skeletal preference pane bundle in Project Builder and Interface Builder.

• “Implementing a Simple Preference Pane” walks you through the source code of a simple preference pane, showing an example of how to implement a working preference pane.

• “Using Preference Panes in Other Applications” describes the responsibilities of an application that loads a preference pane.

Limitations

The Preference Panes framework is available only in Mac OS X version 10.1 and later. You cannot create new plug-ins for System Preferences nor use preference panes in your applications on earlier versions of Mac OS X. If you want your application to run on 10.0.x systems, you need to build your own implementation for preferences. You can still use all the techniques described in this documentation, though, regarding storage of preferences and communication between applications as covered in “Managing User Preferences,” “Using Preference Services,” and “Communicating With the Target Application.”

The Preference Panes framework can be used only by an Objective-C Cocoa application. The preference pane also needs to be written in Objective-C with its user interface implemented using Cocoa.

---