NSUserDefaultsController Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/AppKit.framework
Availability
Available in OS X v10.3 and later.
Companion guide
Declared in
NSUserDefaultsController.h
Related sample code

Overview

NSUserDefaultsController is a Cocoa bindings compatible controller class. Properties of the shared instance of this class can be bound to user interface elements to access and modify values stored in NSUserDefaults.

Tasks

Obtaining the Shared Instance

Initializing a User Defaults Controller

Managing User Defaults Values

Class Methods

sharedUserDefaultsController

Returns the shared instance of NSUserDefaultsController, creating it if necessary.

+ (id)sharedUserDefaultsController
Discussion

This instance has no initial values, and uses [NSUserDefaults standardUserDefaults] to create the defaults. An application can get this object when an application launches and configure it as required.

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

Instance Methods

appliesImmediately

Returns whether any changes made to bound user default properties are saved immediately.

- (BOOL)appliesImmediately
Discussion

Default is YES.

This property is observable using key-value observing.

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

defaults

Returns the instance of NSUserDefaults in use by the receiver.

- (NSUserDefaults *)defaults
Discussion

This property is observable using key-value observing.

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

hasUnappliedChanges

Returns whether the receiver has user default values that have not been saved to NSUserDefaults.

- (BOOL)hasUnappliedChanges
Discussion

This property is observable using key-value observing.

Availability
  • Available in OS X v10.4 and later.
Declared In
NSUserDefaultsController.h

initialValues

Returns a dictionary containing the receiver’s initial default values.

- (NSDictionary *)initialValues
Discussion

These values are used when is no value found for the bound property in defaults.

This property is observable using key-value observing.

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

initWithDefaults:initialValues:

Returns an initialized NSUserDefaultsController object using the NSUserDefaults instance specified in defaults and the initial default values contained in the initialValues dictionary.

- (id)initWithDefaults:(NSUserDefaults *)defaults initialValues:(NSDictionary *)initialValues
Discussion

If defaults is nil, the receiver uses [NSUserDefaults standardUserDefaults].

This method is the designated initializer.

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

revert:

Causes the receiver to discard any unsaved changes to bound user default properties, restoring their previous values.

- (void)revert:(id)sender
Discussion

The receiver invokes discardEditing on any currently registered editors. The sender is typically the object that invoked this method.

If appliesImmediately is YES, this method only causes any bound editors with uncommitted changes to discard their edits.

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

revertToInitialValues:

Causes the receiver to discard all edits and replace the values of all the user default properties with any corresponding values in the initialValues dictionary.

- (void)revertToInitialValues:(id)sender
Discussion

This effectively sets the preferences that a user can change to their “out-of-the-box” values. This method has no effect if initial values were not specified. The sender is typically the object that invoked this method.

Availability
  • Available in OS X v10.3 and later.
Related Sample Code
Declared In
NSUserDefaultsController.h

save:

Saves the values of the receiver’s user default properties.

- (void)save:(id)sender
Discussion

This method has no effect if appliesImmediately returns YES.

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

setAppliesImmediately:

Sets whether any changes made to the receiver’s user default properties are saved immediately.

- (void)setAppliesImmediately:(BOOL)flag
Discussion

The default is YES.

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

setInitialValues:

Sets the receiver’s initial values to initialValues.

- (void)setInitialValues:(NSDictionary *)initialValues
Discussion

These values are used when a user default properties has no value in NSUserDefaults and by revertToInitialValues:.

The initial values must be set before loading a nib that uses the receiver, as those values may be referenced at load time. It is good practice to set the initial values–along with registering any defaults for the applications–in theinitialize class method of your preference dialog controller, or the application delegate.

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

values

Returns a key value coding compliant object that is used to access the user default properties.

- (id)values
Discussion

If present the value for the property in defaults is returned, otherwise a corresponding value in initialValues is returned.

This property is observable using key-value observing.

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