Mac Developer Library

Developer

PreferencePanes Framework Reference NSPreferencePane Class Reference

Options
Deployment Target:

On This Page
Language:

NSPreferencePane

Inheritance


Conforms To


Import Statement


Swift

import PreferencePanes

Objective-C

@import PreferencePanes;

Availability


Available in OS X v10.1 and later.

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

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

    Declaration

    Swift

    init!(bundle bundle: NSBundle!)

    Objective-C

    - (instancetype)initWithBundle:(NSBundle *)bundle

    Import Statement

    Objective-C

    @import PreferencePanes;

    Swift

    import PreferencePanes

    Availability

    Available in OS X v10.1 and later.

  • bundle bundle Property

    The preference pane’s bundle. (read-only)

    Declaration

    Swift

    var bundle: NSBundle! { get }

    Objective-C

    @property(readonly, strong) NSBundle *bundle

    Import Statement

    Objective-C

    @import PreferencePanes;

    Swift

    import PreferencePanes

    Availability

    Available in OS X v10.1 and later.

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

    Declaration

    Swift

    func assignMainView()

    Objective-C

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

    Import Statement

    Objective-C

    @import PreferencePanes;

    Swift

    import PreferencePanes

    Availability

    Available in OS X v10.1 and later.

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

    Declaration

    Swift

    func loadMainView() -> NSView!

    Objective-C

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

    Import Statement

    Objective-C

    @import PreferencePanes;

    Swift

    import PreferencePanes

    Availability

    Available in OS X v10.1 and later.

  • The name of the preference pane’s nib file. (read-only)

    Declaration

    Swift

    var mainNibName: String! { get }

    Objective-C

    @property(readonly, strong) 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”.

    Import Statement

    Objective-C

    @import PreferencePanes;

    Swift

    import PreferencePanes

    Availability

    Available in OS X v10.1 and later.

  • mainView mainView Property

    The main view of the preference pane.

    Declaration

    Swift

    var mainView: NSView!

    Objective-C

    @property(strong) NSView *mainView

    Discussion

    Subclasses should not need to override this unless they override loadMainView or assignMainView.

    Import Statement

    Objective-C

    @import PreferencePanes;

    Swift

    import PreferencePanes

    Availability

    Available in OS X v10.1 and later.

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

    Declaration

    Swift

    func mainViewDidLoad()

    Objective-C

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

    Import Statement

    Objective-C

    @import PreferencePanes;

    Swift

    import PreferencePanes

    Availability

    Available in OS X v10.1 and later.

  • The first view in the keyboard focus chain.

    Declaration

    Swift

    var firstKeyView: NSView!

    Objective-C

    @property(strong) NSView *firstKeyView

    Discussion

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

    Import Statement

    Objective-C

    @import PreferencePanes;

    Swift

    import PreferencePanes

    Availability

    Available in OS X v10.1 and later.

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

    Declaration

    Swift

    var initialKeyView: NSView!

    Objective-C

    @property(strong) NSView *initialKeyView

    Discussion

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

    Import Statement

    Objective-C

    @import PreferencePanes;

    Swift

    import PreferencePanes

    Availability

    Available in OS X v10.1 and later.

  • The last view in the keyboard focus chain.

    Declaration

    Swift

    var lastKeyView: NSView!

    Objective-C

    @property(strong) NSView *lastKeyView

    Discussion

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

    Import Statement

    Objective-C

    @import PreferencePanes;

    Swift

    import PreferencePanes

    Availability

    Available in OS X v10.1 and later.

  • Boolean value that indicates whether text fields save their values before changing preference panes. (read-only)

    Declaration

    Swift

    var autoSaveTextFields: Bool { get }

    Objective-C

    @property(readonly) BOOL autoSaveTextFields

    Discussion

    If this property is YEStrue, text fields are forced to give up their responder status before shouldUnselect is called on the preference pane. If it is NOfalse, the preference pane is responsible for forcing text fields to give up their responder status before saving them. The default value is YEStrue.

    Import Statement

    Objective-C

    @import PreferencePanes;

    Swift

    import PreferencePanes

    Availability

    Available in OS X v10.2 and later.

  • selected selected Property

    Boolean value that indicates whether the preference pane is currently selected. (read-only)

    Declaration

    Swift

    var selected: Bool { get }

    Objective-C

    @property(getter=isSelected, readonly) BOOL selected

    Discussion

    YEStrue if preference pane is currently selected by user, NOfalse otherwise.

    Import Statement

    Objective-C

    @import PreferencePanes;

    Swift

    import PreferencePanes

    Availability

    Available in OS X v10.10 and later.

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

    Declaration

    Swift

    func didSelect()

    Objective-C

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

    Import Statement

    Objective-C

    @import PreferencePanes;

    Swift

    import PreferencePanes

    Availability

    Available in OS X v10.1 and later.

    See Also

    – willSelect

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

    Declaration

    Swift

    func willSelect()

    Objective-C

    - (void)willSelect

    Discussion

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

    Import Statement

    Objective-C

    @import PreferencePanes;

    Swift

    import PreferencePanes

    Availability

    Available in OS X v10.1 and later.

    See Also

    – didSelect

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

    Declaration

    Swift

    func didUnselect()

    Objective-C

    - (void)didUnselect

    Discussion

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

    Import Statement

    Objective-C

    @import PreferencePanes;

    Swift

    import PreferencePanes

    Availability

    Available in OS X v10.1 and later.

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

    Declaration

    Swift

    func replyToShouldUnselect(_ shouldUnselect: Bool)

    Objective-C

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

    Import Statement

    Objective-C

    @import PreferencePanes;

    Swift

    import PreferencePanes

    Availability

    Available in OS X v10.1 and later.

  • Boolean value that indicates whether the receiver is willing to be deselected. (read-only)

    Declaration

    Swift

    var shouldUnselect: NSPreferencePaneUnselectReply { get }

    Objective-C

    @property(readonly) NSPreferencePaneUnselectReply shouldUnselect

    Discussion

    The possible 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.

    Import Statement

    Objective-C

    @import PreferencePanes;

    Swift

    import PreferencePanes

    Availability

    Available in OS X v10.1 and later.

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

    Declaration

    Swift

    func willUnselect()

    Objective-C

    - (void)willUnselect

    Discussion

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

    Import Statement

    Objective-C

    @import PreferencePanes;

    Swift

    import PreferencePanes

    Availability

    Available in OS X v10.1 and later.

    See Also

    – didUnselect

  • Updates the help menu.

    Declaration

    Swift

    func updateHelpMenuWithArray(_ inArrayOfMenuItems: [AnyObject]!)

    Objective-C

    - (void)updateHelpMenuWithArray:(NSArray *)inArrayOfMenuItems

    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.

    Import Statement

    Objective-C

    @import PreferencePanes;

    Swift

    import PreferencePanes

    Availability

    Available in OS X v10.3 and later.