< Previous PageNext Page > Hide TOC

Using NSUserDefaults

Typically, you use the NSUserDefaults class by invoking the standardUserDefaults class method to get an NSUserDefaults object. This method returns a global NSUserDefaults object with a search list already initialized. Use the objectForKey: and setObject:forKey: methods to get and set default values. Note that a default’s value can be only property list objects: NSData, NSString, NSNumber, NSDate, NSArray, or NSDictionary (for more on property lists, see Property List Programming Guide).

The following sections discuss various aspects of using the NSUserDefaults class.

Contents:

Setting a Default in the NSRegistrationDomain
Allowing the User to Specify a Different Default Behavior
Using the Default Value to Determine Behavior
Synchronizing an NSUserDefaults Object with the Defaults Database
Using CFPreferences

Setting a Default in the NSRegistrationDomain

An application can set values for all its defaults in the NSRegistrationDomain. If users specify a different preference in their defaults database, the users’ preferences override the values from the NSRegistrationDomain. An NSUserDefaults object only uses values from the NSRegistrationDomain when a user hasn’t specified a different preference. So, you need to decide whether or not your application should delete backup files by default.

To register the application’s default behavior, you get the application's shared instance of NSUserDefaults and register default values with it. A good place to do this is in the initialize method of the class that uses the default. The following example registers the value “YES” for the default named “DeleteBackup”.

+ (void)initialize{

    NSUserDefaults *defaults = [NSUserDefaults standardUserDefaults];

    NSDictionary *appDefaults = [NSDictionary

        dictionaryWithObject:@"YES" forKey:@"DeleteBackup"];

    [defaults registerDefaults:appDefaults];

}

The initialize message is sent to each class before it receives any other message, ensuring that the application's defaults are set before the application needs to read them.

Allowing the User to Specify a Different Default Behavior

To allow users to specify a different default behavior for deleting backups, you must provide an interface in which they can express their preference. Most applications provide a Preferences panel for this purpose. When your application detects that a user has specified a new preference, it should save it in the shared instance of NSUserDefaults.

For example, assume that your application has an instance variable called deleteBackupButton that is an outlet to an NSButton, and that users toggle this button’s state to indicate whether or not the application should delete its backup files. You could use the following code to update the user’s value for the DeleteBackup default:

if ([deleteBackupButton state]) {

    // The user wants to delete backup files.

    [[NSUserDefaults standardUserDefaults]

        setObject:@"YES" forKey:@"DeleteBackup"];

} else {

    // The user doesn’t want to delete backup files.

    [[NSUserDefaults standardUserDefaults]

        setObject:@"NO" forKey:@"DeleteBackup"];

}

After determining the button’s state, setObject:forKey: is used to set the value of the specified default in the application domain.

You don’t have to use a Preferences panel to manage all defaults. For example, an NSWindow object can store its placement in the user defaults system, so that it appears in the same location the next time the user starts the application.

Using the Default Value to Determine Behavior

To find out whether or not to delete a backup file, you can use the following statement:

[[NSUserDefaults standardUserDefaults] boolForKey:@"DeleteBackup"];

As a convenience, NSUserDefaults provides boolForKey:, floatForKey:, and so on. Recall that a default’s value can be only an NSData, NSString, NSNumber, NSDate, NSArray, or NSDictionary. boolForKey: and similarly named methods attempt to get the value for the specified default and interpret it as a different data type.

Synchronizing an NSUserDefaults Object with the Defaults Database

Since other applications (and the user) can write to a defaults database, the database and an NSUserDefaults object might not agree on the value of a given default at all times.

You can update the defaults database with an NSUserDefaults object’s new values and update the NSUserDefaults object with any changes that have been made to the database using the synchronize method.

On Mac OS X v10.5 and later, in applications in which a run-loop is present, synchronize is automatically invoked at periodic intervals. Consequently, you might synchronize before exiting a process, but otherwise you shouldn’t need to.

Using CFPreferences

Since CFPreferences currently has some features not yet supported in NSUserDefaults, you may want to use CFPreferences to perform some of your defaults operations. For example, CFPreferences supports per-host preferences, and NSUserDefaults currently does not.

For more information about CFPreferences see the Core Foundation Programming Topic Preferences Programming Topics for Core Foundation.

< Previous PageNext Page > Hide TOC