Anatomy of a Preference Pane Bundle
A preference pane plug-in is packaged on disk as a bundle with the .prefPane
extension. Like all bundle packages, a preference pane consists of an executable (in the Mac OS X native Mach-O format), an information property list (Info.plist
), and localizable and global (nonlocalized) resources.
The structure of a sample preference pane bundle is shown in Figure 1.
When created within Xcode, the basic structure and the files are created for you. Creating a Preference Pane Bundle describes the steps required to produce a working preference pane bundle. The following sections describe the individual elements of the bundle.
Information Property Lists
Every bundle contains a dictionary, the Info.plist
file, that defines certain properties of the bundle, such as the names of important resources. Preference pane bundles should provide values for the following keys in the information property list:
Key |
Description |
---|---|
|
The unique identifier string for the bundle. Every bundle should have a unique |
|
The name of the main nib file. If this key is omitted, the default preference pane implementation assumes a value of “Main”. The value must not include the |
|
The name of an image file resource used in the Show All view and favorites area of the System Preferences application to represent the preference pane. The icon should be 32 x 32 pixels in size. If this key is omitted, System Preferences looks for the |
|
The name of the preference pane displayed by System Preferences beneath the pane’s icon and in the Pane menu. You can include a newline character in the string (“ |
|
The name of the main controller class of the preference pane. This class must be defined in the Mach-O binary of the bundle and it must be a subclass of NSPreferencePane. To avoid symbol name collisions, the name of the class must be prefixed by a specially munged version of the bundle identifier (see Preventing Name Conflicts for details). For example, “ |
Localizable Resources
A bundle’s resources can be localized to different languages and regions. Generally, these are resources that present text to the user, such as menu names and labels in windows. The resource files are stored in separate subdirectories in the Contents/Resources
directory of the bundle. The directories are named after the language, such as English.lproj
or Spanish.lproj
. When your preference pane accesses a localized resource, such as a nib file containing a window, the operating system selects the version according to the user’s language preferences.
The simplest way for a preference pane to define its user interface is through a main nib file. This nib file should be a localized resource. The name of the main nib file can be anything, but it must match the value of the NSMainNibFile
key in the bundle’s property list.
Like application bundles, preference pane bundles should include a localized InfoPlist.strings
resource. This file contains individual strings the user sees, but cannot be stored within the nib file. This file should contain an entry for the NSPrefPaneIconLabel
property whose value is the localized display name of the preference pane.
Global Resources
Not all resources need to be localized. Images without textual content can be used for all languages. These global resources are stored in the Contents/Resources
directory.
The preference pane icon file (usually an .icns
or .tiff
file) is the 32 x 32 pixel icon used in the System Preferences application to represent the preference pane in the Show All view and the favorites area. The name of the preference pane icon file is specified by the NSPrefPaneIconFile
key in the bundle’s property list. Typically, this is a global (nonlocalized) resource. However, if the icon contains locale-specific information (such as text), it can be made localized.
Where Preference Panes Live
Preference pane bundles for System Preferences live in the PreferencePanes
family of library directories. This family of directories consists of these directories:
Directory |
Description |
---|---|
|
Mac OS X built-in preference panes |
|
Third-party preference panes available to all users on the network |
|
Third-party preference panes available to all users on the computer |
|
Third-party preference panes available only to the current user |
System Preferences searches these directories in the reverse order that they are listed here. If multiple preference panes are found with identical bundle identifiers (CFBundleIdentifier
key value), only the first preference pane found is displayed.
When creating a custom preference application or if you use preference panes to implement the Preferences menu item of the target application, store the preference pane bundles inside the application’s bundle in the Resources
directory. If the preference pane needs to be shared by a suite of applications, store the preference pane bundles in a subdirectory in /Library/Application Support
.
Copyright © 2003, 2012 Apple Inc. All Rights Reserved. Terms of Use | Privacy Policy | Updated: 2012-12-13