PATH Documentation > Cocoa


SS_PrefsController


Inherits from:
NSObject
Conforms to:
NSObject (NSObject)
Declared in:
SS_PrefsController.h


Created by Matt Gemmell


Class at a Glance


An SS_PrefsController creates and manages a Preferences window with an NSToolbar and multiple preference panes loaded from bundles. The preference pane bundles must conform to the simple SS_PreferencePaneProtocol protocol.


Principal Attributes



Creation


+ preferences
Returns a Preferences Controller with the default panes search path (the application bundle's Resources directory), and the default bundle extension (preferencePane).
+ preferencesWithPanesSearchPath:
Returns a Preferences Controller with the specified panes search path and the default bundle extension (preferencePane).
+ preferencesWithBundleExtension:
Returns a Preferences Controller with the default panes search path (the application bundle's Resources directory), and the specified bundle extension.
+ preferencesWithPanesSearchPath:bundleExtension:
Returns a Preferences Controller with the specified panes search path and bundle extension.

Commonly Used Methods


- setPanesOrder:
Sets the order of the preference panes in the Preferences window's toolbar.
- showPreferencesWindow:
Displays the Preferences window, creating it if necessary.

Class Description


SS_PrefsController manages a "Preferences" window for an application, loading multiple preference panes from bundles. The Preferences window follows the modern Apple design as used in applications such as iChat, Safari and Mail. An example is shown below:

Example Preferences Window

SS_PrefsController automatically takes care of loading bundles, creating the window and its toolbar, responding to clicks on toolbar items by switching the visible preference pane, determining whether the window should be resizable for each preference pane, and so on. Preferences windows will automatically remember the last selected preference pane, and will reopen that pane by default when the window is next shown, even between launches of the application. This information is remembered on a per-application basis, so SS_PrefsController can be safely used in as many applications as desired.

The two primary properties of a Preferences controller (both of which must be configured at initialization time) are the search path to use when looking for loadable preference pane bundles, and the filename extension of those bundles. If these properties are not specified, default values will be used: the search path will be set to the application bundle's Resources directory, and the bundle extension will be set to "preferencePane".

Many aspects of the Preferences window's behaviour can be configured, including whether or not it uses a textured ("metal") appearance (- setUsesTexturedWindow:), the display mode and size of its toolbar (- setToolbarDisplayMode: and - setToolbarSizeMode:), whether to show the toolbar if there is only one preference pane available (- setAlwaysShowsToolbar:), the order of the preference panes in the toolbar (- setPanesOrder:), and whether or not the window always opens centered on the screen (- setAlwaysOpensCentered:). SS_PrefsController can also optionally dump diagnostic messages to the console, to aid debugging of your preference pane bundles (- setDebug:).

The preferences window can be accessed directly if necessary (- preferencesWindow), and its delegate can be set programmatically. It is also possible to make the Preferences window load a specific preference pane explicitly using - loadPreferencePaneNamed:.

The Preferences window is shown (being automatically created if necessary) using - showPreferencesWindow, or can be created off-screen (to permit further customization before display) with - createPreferencesWindow. The Preferences window is maintained in memory after being shown for the first time, or can be manually destroyed safely using - destroyPreferencesWindow. Each of these methods can be called as many times as required, for example by the action methods of interface elements.

In most cases, having first created appropriate preference pane bundles, it is sufficient to simply create an instance of SS_PrefsController and call - showPreferencesWindow.




Method Types


Determining the version of this class
+ version
Creating a Preferences controller
+ preferences
+ preferencesWithPanesSearchPath:
+ preferencesWithBundleExtension:
+ preferencesWithPanesSearchPath:bundleExtension:
- init
- initWithPanesSearchPath:
- initWithBundleExtension:
- initWithPanesSearchPath:bundleExtension: (designated initializer)
Configuring behaviour
- setAlwaysOpensCentered:
- alwaysOpensCentered
- setAlwaysShowsToolbar:
- alwaysShowsToolbar
- setDebug:
- debug
Configuring display characteristics
- setPanesOrder:
- panesOrder
- setToolbarDisplayMode:
- toolbarDisplayMode
- setToolbarSizeMode:
- toolbarSizeMode
- setUsesTexturedWindow:
- usesTexturedWindow
Accessing properties related to preference pane bundles
- bundleExtension
- loadedPanes
- searchPath
Creating and showing the Preferences window
- createPreferencesWindow
- showPreferencesWindow
Explicitly loading a specific preference pane
- loadPreferencePaneNamed:
Accessing the Preferences window directly
- preferencesWindow
Manually destroying the Preferences window
- destroyPreferencesWindow


Class Methods



preferences

+ (id)preferences

Creates and returns an autoreleased Preferences Controller with the default search path and bundle extension (see Class Description for details of default values).

See Also: + preferencesWithPanesSearchPath:, + preferencesWithBundleExtension:, + preferencesWithPanesSearchPath:bundleExtension:



preferencesWithBundleExtension:

+ (id)preferencesWithBundleExtension:(NSString *)extension

Creates and returns an autoreleased Preferences Controller with the default search path and bundle extension extension (see Class Description for details of default values).

See Also: + preferences, + preferencesWithPanesSearchPath:, + preferencesWithPanesSearchPath:bundleExtension:



preferencesWithPanesSearchPath:

+ (id)preferencesWithPanesSearchPath:(NSString *)path

Creates and returns an autoreleased Preferences Controller with the search path path and the default bundle extension (see Class Description for details of default values).

See Also: + preferences, + preferencesWithBundleExtension:, + preferencesWithPanesSearchPath:bundleExtension:



preferencesWithPanesSearchPath:bundleExtension:

+ (id)preferencesWithPanesSearchPath:(NSString *)path bundleExtension:(NSString *)extension

Creates and returns an autoreleased Preferences Controller with search path path and bundle extension extension.

See Also: + preferences, + preferencesWithPanesSearchPath:, + preferencesWithBundleExtension:



version

+ (int)version

Returns the version number of the SS_PrefsController class.


Instance Methods



alwaysOpensCentered

- (BOOL)alwaysOpensCentered

Queries the receiver to determine whether the Preferences window is always centered on screen when it is opened. The window will always be centered the first time it is opened after being created; this method indicates whether it will be automatically recentered on subsequent openings. The default value is YES, duplicating the behaviour of various Apple applications.

See Also: - setAlwaysOpensCentered:



alwaysShowsToolbar

- (BOOL)alwaysShowsToolbar

Queries the receiver to determine whether the Preferences window always shows its toolbar, regardless of how many preference panes have been loaded. The window will always show its toolbar if there is more than one pane loaded; this method indicates whether the toolbar will still be shown even if there is only one loaded preference pane. The default value is NO.

If NO, when only one preference pane is available, no toolbar will be shown and the window's title will be "Preferences". If YES, or if more than one preference pane is available, the toolbar will be visible and the window's title will be the name of the currently displayed preference pane.

See Also: - setAlwaysShowsToolbar:



bundleExtension

- (NSString *)bundleExtension

Returns the filename extension which the receiver uses to recognize preference pane bundles. The extension can only be set during initialization, either via one of the init... methods or one of the preferences... convenience constructors. The default value is "preferencePane".

createPreferencesWindow

- (void)createPreferencesWindow

Creates the Preferences window, but does not display it. This method is normally only used if the Preferences window requires to be customized in some way before being shown (such as altering its opacity or position). This method is identical to showPreferencesWindow, except that showPreferencesWindow also displays the window after creating it.

It is safe to call showPreferencesWindow after calling this method, to display the window after customization. It is also safe, though unnecessary, to call this method multiple times.

See Also: - showPreferencesWindow, - destroyPreferencesWindow



debug

- (BOOL)debug

Queries the receiver to determine whether debug mode is enabled. If YES, diagnostic messages will be dumped to the console whenever a notable situation is encountered (such as not being able to locate or load a preference pane). The default value is NO.

See Also: - setDebug:



destroyPreferencesWindow

- (void)destroyPreferencesWindow

Destroys the Preferences window. You should not normally need to call this method, as the Preferences window will be automatically destroyed when the receiver is deallocated. One possible reason to use this method would be if you wanted to change the style of the Preferences window (using setUsesTexturedWindow:) in response to user interaction, without having to deallocate and recreate the receiver.

Note that calling this method will not cause the receiver to rescan its search path for preference panes.

See Also: - createPreferencesWindow, - showPreferencesWindow



init

- (id)init

Initializes and returns a newly-allocated Preferences Controller with the default search path and bundle extension (see Class Description for details of default values).

See Also: - initWithPanesSearchPath:, - initWithBundleExtension:, - initWithPanesSearchPath:bundleExtension:



initWithBundleExtension:

- (id)initWithBundleExtension:(NSString *)extension

Initializes and returns a newly-allocated Preferences Controller with the default search path and bundle extension extension (see Class Description for details of default values).

See Also: - init, - initWithPanesSearchPath:, - initWithPanesSearchPath:bundleExtension:



initWithPanesSearchPath:

- (id)initWithPanesSearchPath:(NSString *)path

Initializes and returns a newly-allocated Preferences Controller with the search path path and the default bundle extension (see Class Description for details of default values).

See Also: - init, - initWithBundleExtension:, - initWithPanesSearchPath:bundleExtension:



initWithPanesSearchPath:bundleExtension:

- (id)initWithPanesSearchPath:(NSString *)path bundleExtension:(NSString *)extension

Initializes and returns a newly-allocated Preferences Controller with search path path and bundle extension extension. This is the designated initializer for this class.

See Also: - init, - initWithPanesSearchPath:, - initWithBundleExtension:



loadedPanes

- (NSArray *)loadedPanes

Returns an array of strings, specifying the names (in alphabetical order of their bundles' filenames) of all preference panes which were successfully loaded. Because it is possible to limit which panes are displayed (using setPanesOrder:), the returned array may be different from the return value of panesOrder, which lists only those panes which are currently available in the Preferences window.

See Also: - panesOrder - setPanesOrder:,



loadPreferencePaneNamed:

- (BOOL)loadPreferencePaneNamed:(NSString *)name

Attempts to load the preference pane whose name is name, and display it in the Preferences window. This method will have no effect if the Preferences window does not already exist. The return value is YES if the specified pane exists and was successfully loaded into the Preferences window, otherwise the return value is NO. If you encounter problems loading a specific preference pane, use setDebug: to enable debugging messages.

It is important to understand that name is not the filename of the preference pane's bundle; rather, it is the value returned by the preference pane when the -(NSString *)paneName method is called. For further details, see the SS_PreferencePaneProtocol protocol definition.

panesOrder

- (NSArray *)panesOrder

Returns an array of strings, specifying the names (in order) of all preference panes which are shown in the Preferences window. Only panes whose names are in this array are made available in the window. This array is constructed automatically by the receiver as it locates and loads preference panes, but it can also be set using setPanesOrder:. This is useful when you want the panes to be listed in the Preferences window in an order other than alphabetically by their bundles' filenames (which is the default ordering), or when you want to "disable" certain panes.

Since the array can be explicitly set, the returned array may not contain the names of all of the preference panes which were initially loaded. Do not rely on panesOrder to indicate which preference pane bundles were successfully loaded; the returned array only indicates which panes are currently shown in the Preferences window's toolbar. To instead obtain an array of the names of all preference panes which were loaded, use loadedPanes.

See Also: - setPanesOrder:, - loadedPanes



preferencesWindow

- (NSWindow *)preferencesWindow

Returns the receiver's Preferences window, if it exists, or else nil. This method is most useful for performing direct customization of the Preferences window before or during display.

Note: A Preferences Controller does not set itself to be the delegate of its Preferences window, nor does it require to be, so you are free to set your own delegate as with any other window.

searchPath

- (NSString *)searchPath

Returns the receiver's search path, as specified during initialization. The search path cannot be changed after the receiver has initialized. Upon initialization, a Preferences Controller will search for all bundles in its search path whose filename extension is bundleExtension, and will attempt to load each one as a preference pane. If no search path was explicitly specified during initialization, the search path defaults to the Resources directory within the application's bundle.

See Also: - bundleExtension



setAlwaysOpensCentered:

- (void)setAlwaysOpensCentered:(BOOL)flag

Determines whether the Preferences window is always recentered on screen before being displayed each time it is opened. The window is always centered the first time it is shown after the receiver has been initialized. The default value is YES, duplicating the behaviour of various Apple applications.

See Also: - alwaysOpensCentered



setAlwaysShowsToolbar:

- (void)setAlwaysShowsToolbar:(BOOL)flag

Determines whether the Preferences window's toolbar is shown even if there is only one preference pane. The toolbar will always be shown if there is more than one pane, but setting flag to YES will force the toolbar to always be visible. The default value is NO. See the alwaysShowsToolbar method for more information on how this setting affects the behaviour of the Preferences window.

See Also: - alwaysShowsToolbar



setDebug:

- (void)setDebug:(BOOL)flag

Determines whether the Preferences Controller dumps diagnostic messages to the console upon encountering errors or notable situations (such as not being able to load a preference pane, or encountering a bundle which does not conform to the preference pane protocol). The default value is NO. This is useful for aiding developers in debugging their preference panes.

See Also: - debug



setPanesOrder:

- (void)setPanesOrder:(NSArray *)array

Sets the order in which the loaded preference panes are shown in the toolbar, using an array of strings which correspond to the names of the relevant preference panes. Any pane which is not mentioned in array will not be made available in the Preferences window. Any name in array which does not correspond to an existing or loaded preference pane will be discarded, such that panesOrder will always reflect the ordered list of all visible panes in the Preferences window.

A full list of all loaded panes, regardless of which are available in the Preferences window, can be obtained using loadedPanes.

See Also: - panesOrder, - loadedPanes



setToolbarDisplayMode:

- (void)setToolbarDisplayMode:(NSToolbarDisplayMode)mode

This is a convenience accessor to allow direct setting of the display mode of the Preferences window's toolbar. See the NSToolbar documentation for further explanation, and for a list of possible values.

See Also: - toolbarDisplayMode, - setDisplayMode: (NSToolbar)



setToolbarSizeMode:

- (void)setToolbarSizeMode:(NSToolbarSizeMode)mode

This is a convenience accessor to allow direct setting of the size mode of the Preferences window's toolbar. See the NSToolbar documentation for further explanation, and for a list of possible values.

Note: this method is only available on Mac OS X 10.2 or later.

See Also: - toolbarSizeMode, - setSizeMode: (NSToolbar)



setUsesTexturedWindow:

- (void)setUsesTexturedWindow:(BOOL)flag

Determines whether the Preferences window has a textured ("metal") appearance; the default value is NO. This method will only take effect if it is called before the Preferences window has been created (i.e. before calling either createPreferencesWindow or showPreferencesWindow).

See Also: - usesTexturedWindow



showPreferencesWindow

- (void)showPreferencesWindow

Creates the Preferences window (if necessary) and displays it. This is one of the most commonly-used methods, and is ideal for calling from the action method of an interface item (such as the Preferences menu-item in the application menu). This method is identical to createPreferencesWindow, except that createPreferencesWindow does not display the window after creating it.

Calling createPreferencesWindow after using this method will have no effect.

See Also: - createPreferencesWindow, - destroyPreferencesWindow



toolbarDisplayMode

- (NSToolbarDisplayMode)toolbarDisplayMode

This is a convenience accessor for the display mode of the Preferences window's toolbar. See the NSToolbar documentation for further explanation, and for a list of possible return values. The default value is NSToolbarDisplayModeIconAndLabel.

See Also: - setToolbarDisplayMode:, - displayMode (NSToolbar)



toolbarSizeMode

- (NSToolbarSizeMode)toolbarSizeMode

This is a convenience accessor for the size mode of the Preferences window's toolbar. See the NSToolbar documentation for further explanation, and for a list of possible return values. The default value is NSToolbarSizeModeDefault.

Note: this method is only available in Mac OS X 10.2 or later.

See Also: - setToolbarSizeMode:, - sizeMode (NSToolbar)



usesTexturedWindow

- (BOOL)usesTexturedWindow

Queries the receiver to determine whether the Preferences window has a textured ("metal") appearance. The default value is NO.

See Also: - setUsesTexturedWindow:



© 2003 Scotland Software (Last Published June 28, 2003)