NSPreferencePane Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/PreferencePanes.framework
Availability
Available in OS X v10.1 and later.
Companion guide
Declared in
NSPreferencePane.h

Overview

NSPreferencePane is an abstract class that defines the interface for subclassers to provide preference panes to System Preferences or other applications.

Preference panes are subclasses of NSPreferencePane, packaged up in bundles and loaded by a preference application, such as System Preferences. These bundles have a suffix of .prefPane. Bundles intended for use by System Preferences are located in the Library/PreferencePanes directories of the various file system domains. See the chapter “File-System Domains” in File System Overview for information about domains.

The preference pane bundle normally contains a nib file with the user interface for modifying user preferences. The nib file contains a window assigned to the _window outlet of the preference pane instance (the nib’s File’s Owner). The NSPreferencePane implementation of loadMainView, invoked by the preference application, loads the nib file and uses the content view of _window as the preference pane’s main view. Override this method if you need a different technique for creating the user interface.

The NSPreferencePane subclass is responsible for initializing the user interface with the current preference settings and recording any modifications the user makes. Through a series of will..., did..., and should... methods, the preference application notifies the preference pane when the pane is selected (displayed) and deselected, allowing the pane to perform the necessary actions at the appropriate times. Implement these methods (and any additional target-action methods connected to the interface) as needed to produce the desired behavior for your preference pane.

Preference panes support Help menu items. You specify static help menu items under NSPrefPaneHelpAnchors in the bundle’s Info.plist file; for dynamic items you implement updateHelpMenuWithArray:.

Tasks

Initializing the Preference Pane

Obtaining the Preference Pane Bundle

Setting Up the Main View

Handling Keyboard Focus

Handling Preference Pane Selection

Help Menu Support

Instance Methods

assignMainView

Locates and assigns the receiver’s main view from the nib file loaded by loadMainView.

- (void)assignMainView
Discussion

The default implementation sets the receiver’s main view to the content view of the window referenced by the _window outlet. Before returning, assignMainView releases the window and sets the _window outlet to nil. Returns the main view if successful, nil otherwise.

Override this method if your main view is located in the nib file loaded by loadMainView, but is not the content view of a window in the file. Call setMainView: to set the main view of the preference pane before returning. Also call setInitialKeyView:, setFirstKeyView:, and setLastKeyView: to set the initial, first, and last keyboard focus views, respectively.

Availability
  • Available in OS X v10.1 and later.
Declared In
NSPreferencePane.h

autoSaveTextFields

- (BOOL)autoSaveTextFields
Discussion

If this method returns YES, text fields are forced to give up their responder status before shouldUnselect is called on the preference pane. If this method returns NO, the preference pane is responsible for forcing text fields to give up their responder status before saving them. The default return value is YES.

Availability
  • Available in OS X v10.2 and later.
Declared In
NSPreferencePane.h

bundle

Returns the NSBundle instance representing the preference pane’s bundle.

- (NSBundle *)bundle
Availability
  • Available in OS X v10.1 and later.
Declared In
NSPreferencePane.h

didSelect

Notifies the receiver that the main application has just displayed the preference pane’s main view.

- (void)didSelect
Discussion

Default implementation does nothing. Override this method to perform actions right after the main view has been placed into a window on the screen.

Availability
  • Available in OS X v10.1 and later.
Declared In
NSPreferencePane.h

didUnselect

Notifies the receiver that the main application has just stopped displaying the preference pane’s main view.

- (void)didUnselect
Discussion

Default implementation does nothing. Override this method to perform actions right after the main view has been removed from the screen.

Availability
  • Available in OS X v10.1 and later.
Declared In
NSPreferencePane.h

firstKeyView

Returns the first view in the keyboard focus chain.

- (NSView *)firstKeyView
Availability
  • Available in OS X v10.1 and later.
Declared In
NSPreferencePane.h

initialKeyView

Returns the view that should have the keyboard focus when the pane is selected.

- (NSView *)initialKeyView
Availability
  • Available in OS X v10.1 and later.
Declared In
NSPreferencePane.h

initWithBundle:

Initializes the receiver with the preference pane’s bundle, returning self.

- (id)initWithBundle:(NSBundle *)bundle
Availability
  • Available in OS X v10.1 and later.
Declared In
NSPreferencePane.h

isSelected

Returns YES if the receiver is currently selected by the user, otherwise NO.

- (BOOL)isSelected
Availability
  • Available in OS X v10.3 and later.
Declared In
NSPreferencePane.h

lastKeyView

Returns the last view in the keyboard focus chain.

- (NSView *)lastKeyView
Availability
  • Available in OS X v10.1 and later.
Declared In
NSPreferencePane.h

loadMainView

Loads the receiver’s user interface into its main view.

- (NSView *)loadMainView
Discussion

The default implementation loads the main nib file (identified by mainNibName) and invokes assignMainView to set the main view of the preference pane. Returns the main view if successful, nil otherwise.

Subclasses should rarely need to override this method. Override this method if you need to use a non-nib based technique for creating the main view. Call setMainView: to set the main view of the preference pane before returning. Also call setInitialKeyView:, setFirstKeyView:, and setLastKeyView: to set the initial, first, and last keyboard focus views, respectively.

Availability
  • Available in OS X v10.1 and later.
Declared In
NSPreferencePane.h

mainNibName

Returns the name of the preference pane’s nib file.

- (NSString *)mainNibName
Discussion

The name should not include the .nib extension.

The default implementation returns the value of the NSMainNibFile key in the bundle's information property list. If the key does not exist, it returns a default value of @"Main".

Availability
  • Available in OS X v10.1 and later.
Declared In
NSPreferencePane.h

mainView

Returns the main view of the preference pane.

- (NSView *)mainView
Availability
  • Available in OS X v10.1 and later.
Declared In
NSPreferencePane.h

mainViewDidLoad

Notifies the receiver that the main view is set up and prepared to be displayed.

- (void)mainViewDidLoad
Discussion

Invoked by the default implementation of loadMainView after the main nib file has been loaded and the main view of the preference pane has been set. The default implementation does nothing. Override this method to initialize the main view with the current preference settings.

Availability
  • Available in OS X v10.1 and later.
Declared In
NSPreferencePane.h

replyToShouldUnselect:

Notifies the main application of the receiver’s willingness (or unwillingness) to be deselected.

- (void)replyToShouldUnselect:(BOOL)shouldUnselect
Discussion

If you override shouldUnselect to return NSUnselectLater, you must invoke replyToShouldUnselect: when you have determined whether or not the preference pane can be deselected.

You should not override this method.

Availability
  • Available in OS X v10.1 and later.
Declared In
NSPreferencePane.h

setFirstKeyView:

Sets the first view in the keyboard focus chain.

- (void)setFirstKeyView:(NSView *)view
Discussion

The first view can be set in the nib file by connecting a view to the receiver’s _firstKeyView outlet.

Availability
  • Available in OS X v10.1 and later.
Declared In
NSPreferencePane.h

setInitialKeyView:

Sets the view that should have keyboard focus when the pane is selected.

- (void)setInitialKeyView:(NSView *)view
Discussion

The initial view can be set in the nib file by connecting a view to the receiver’s _initialKeyView outlet.

Availability
  • Available in OS X v10.1 and later.
Declared In
NSPreferencePane.h

setLastKeyView:

Sets the last view in the keyboard focus chain.

- (void)setLastKeyView:(NSView *)view
Discussion

The last view can be set in the nib file by connecting a view to the receiver’s _lastKeyView outlet.

Availability
  • Available in OS X v10.1 and later.
Declared In
NSPreferencePane.h

setMainView:

Sets the main view of the preference pane.

- (void)setMainView:(NSView *)view
Discussion

You should not need to call this directly unless you override loadMainView or assignMainView.

Availability
  • Available in OS X v10.1 and later.
See Also
Declared In
NSPreferencePane.h

shouldUnselect

Returns whether the receiver is willing to be deselected.

- (NSPreferencePaneUnselectReply)shouldUnselect
Discussion

The possible return values are described in “Constants.” The default implementation always returns NSUnselectNow. Override this method if your pane needs to cancel or delay a deselect action. If you override this method to return NSUnselectLater, you must invoke replyToShouldUnselect: when you have determined whether or not the deselection can occur.

Availability
  • Available in OS X v10.1 and later.
Declared In
NSPreferencePane.h

updateHelpMenuWithArray:

- (void)updateHelpMenuWithArray:(NSArray *)arrayOfMenuItems
Discussion

Call this method if you need to update help menu items dynamically. If you have static help menu items, you should not use this method. Specify them under the NSPrefPanelHelpAnchors key in the bundle’s Info.plist instead.

The array contains dictionaries with two keys. Use title for the help menu item title, and anchor for the anchor reference for AHLookupAnchor.

Availability
  • Available in OS X v10.3 and later.
Declared In
NSPreferencePane.h

willSelect

Notifies the receiver that the main application is about to display the preference pane’s main view.

- (void)willSelect
Discussion

Default implementation does nothing. Override this method to perform actions right before the main view is displayed.

Availability
  • Available in OS X v10.1 and later.
Declared In
NSPreferencePane.h

willUnselect

Notifies the receiver that the main application is about to stop displaying the preference pane’s main view.

- (void)willUnselect
Discussion

Default implementation does nothing. Override this method to perform actions right before the main view is removed from the screen.

Availability
  • Available in OS X v10.1 and later.
Declared In
NSPreferencePane.h

Constants

The following constants are defined by NSPreferencePane for use as the return values of shouldUnselect:

Constant

Description

NSUnselectCancel

Cancel the deselection

Available in OS X v10.1 and later.

Declared in NSPreferencePane.h.

NSUnselectNow

Continue the deselection

Available in OS X v10.1 and later.

Declared in NSPreferencePane.h.

NSUnselectLater

Delay the deselection until the preference pane invokes replyToShouldUnselect:

Available in OS X v10.1 and later.

Declared in NSPreferencePane.h.

The following constants are defined by NSPreferencePane for use in the input parameter of updateHelpMenuWithArray::

Constant

Description

title

Key for the help menu item in the dictionary supplied as an argument to updateHelpMenuWithArray:

anchor

Key for the anchor reference for AHLookupAnchor in the dictionary supplied as an argument to updateHelpMenuWithArray:

Notifications

NSPreferencePaneDoUnselectNotification

Notifies the main application that the preference pane is willing to be deselected. Posted when replyToShouldUnselect: is invoked with an argument of YES after shouldUnselect has returned a value of NSUnselectLater.
Availability
Declared In
NSPreferencePane.h

NSPreferencePaneCancelUnselectNotification

Notifies the main application that the preference pane is not willing to be deselected. Posted when replyToShouldUnselect: is invoked with an argument of NO after shouldUnselect has returned a value of NSUnselectLater.
Availability
Declared In
NSPreferencePane.h