Return to the Alphabetic Index
Return to the Class Browser
Return to the Picture Browser
Copyright (c) 1994 by NeXT Computer, Inc. All Rights Reserved.

NSUserDefaults

Inherits From: NSObject

Conforms To: NSObject (NSObject)

Declared In: Foundation/NSUserDefaults.h

Class Description

The NSUserDefaults class allows an application to query and manipulate a user's defaults settings.

Defaults are grouped in domains. For example, there's a domain for application-specific defaults and another for global defaults. Each domain has a name and stores defaults as key-value pairs in an NSDictionary object. A default is identified by a string key, and its value can be any property-list object (NSData, NSString, NSArray, or NSDictionary). The standard domains are:

Domain Identifier

Argument NSArgumentDomain

Application Identified by the application's name

Global NSGlobalDomain

Languages Identified by the language names

Registration NSRegistrationDomain

The identifiers starting with NS above are global constants.

The argument domain is composed of defaults parsed from the application's arguments. The application domain contains the defaults set by the application. It's identified by the name of the application, as returned by this message:

NSString *applicationName = [[NSProcessInfo processInfo] processName];

The global domain contains defaults that are meant to be seen by all applications. The registration domain is a set of temporary defaults whose values can be set by the application to ensure that searches for default values will always be successful. Applications can create additional domains as needed.

A search for the value of a given default proceeds through the domains listed in an NSUserDefault object's search list. Only domains in the search list are searched. The standard search list contains the domains from the table above, in the order listed. A search ends when the default is found. Thus, if multiple domains contain the same default, only the domain nearest the beginning of the search list provides the default's value. Using the searchList method, you can reorder the default search list or set up one that is a subset of all the user's domains.

Typically, you use this 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. Then use the setObject:forKey: and objectForKey: methods to set and access user defaults.

The rest of the methods allow more complex defaults management. You can create your own domains, modify any domain, set up a custom search list, and even control the synchronization of the in-memory and on-disk defaults representations. The synchronize method saves any modifications to the persistent domains and updates all persistent domains that were not modified to what is on disk. synchronize is automatically invoked at periodic intervals.

You can create either persistent or volatile domains. Persistent domains are permanent and last past the life of the NSUserDefaults object. Any changes to the persistent domains are committed to disk. Volatile domains last only last as long as the NSUserDefaults object exists. The NSGlobalDomain domain is persistent; the NSArgumentDomain is volatile.

Warnings:

. User defaults are not thread safe.

. Automatic saving of changes to disk (through synchronize) depends on a run-loop being present.

. You should synchronize any domain you have altered before exiting a process.

Getting the Shared Instance

Getting and Setting a Default

Initializing the User Defaults

Returning the Search List

Maintaining Persistent Domains

Maintaining Volatile Domains

Making Advanced Use of Defaults