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.
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.
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.
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.
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.
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.
Last updated: 2007-10-31