---

NSPreferencePane Class Reference

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

• – initWithBundle:

Obtaining the Preference Pane Bundle

• – bundle

Setting Up the Main View

• – assignMainView
• – loadMainView
• – mainNibName
• – mainView
• – mainViewDidLoad
• – setMainView:

Handling Keyboard Focus

• – firstKeyView
• – initialKeyView
• – lastKeyView
• – setFirstKeyView:
• – setInitialKeyView:
• – setLastKeyView:
• – autoSaveTextFields

Handling Preference Pane Selection

• – isSelected
• – didSelect
• – willSelect
• – didUnselect
• – replyToShouldUnselect:
• – shouldUnselect
• – willUnselect

Help Menu Support

• – updateHelpMenuWithArray:

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 Mac 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 Mac 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 Mac 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 Mac OS X v10.1 and later.

See Also

• – willSelect

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 Mac OS X v10.1 and later.

See Also

• – willUnselect

Declared In

NSPreferencePane.h

firstKeyView

Returns the first view in the keyboard focus chain.

- (NSView *)firstKeyView

Availability

• Available in Mac OS X v10.1 and later.

See Also

• – setFirstKeyView:

Declared In

NSPreferencePane.h

initialKeyView

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

- (NSView *)initialKeyView

Availability

• Available in Mac OS X v10.1 and later.

See Also

• – setInitialKeyView:

Declared In

NSPreferencePane.h

initWithBundle:

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

- (id)initWithBundle:(NSBundle *)bundle

Availability

• Available in Mac 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 Mac 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 Mac OS X v10.1 and later.

See Also

• – setLastKeyView:

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 Mac OS X v10.1 and later.

See Also

• – mainViewDidLoad

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 Mac OS X v10.1 and later.

See Also

• – loadMainView

Declared In

NSPreferencePane.h

mainView

Returns the main view of the preference pane.

- (NSView *)mainView

Availability

• Available in Mac OS X v10.1 and later.

See Also

• – setMainView:

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 Mac 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 Mac 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 Mac OS X v10.1 and later.

See Also

• – firstKeyView

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 Mac OS X v10.1 and later.

See Also

• – initialKeyView

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 Mac OS X v10.1 and later.

See Also

• – lastKeyView

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 Mac OS X v10.1 and later.

See Also

• – mainView

Declared In

NSPreferencePane.h

shouldUnselect

Returns a value indicating 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 Mac 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 Mac 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 Mac OS X v10.1 and later.

See Also

• – didSelect

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 Mac OS X v10.1 and later.

See Also

• – didUnselect

Declared In

NSPreferencePane.h

Constants

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

The following constants are defined by NSPreferencePane for use in the input parameter of 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

• Available in Mac OS X v10.1 and later.

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

• Available in Mac OS X v10.1 and later.

Declared In

NSPreferencePane.h

---