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

• + (NSUserDefaults *)standardUserDefaults Returns the shared defaults object. If it doesn't exist yet, it's created with a search list containing the names of the following domains, in order: the NSArgumentDomain (consisting of defaults parsed from the application's arguments), a domain with the process' name, separate domains for each of the user's preferred languages, the NSGlobalDomain (consisting of defaults meant to be seen by all applications), and the NSRegistrationDomain (a set of temporary defaults whose values can be set by the application to ensure that searches will always be successful). The defaults are initialized for the current user. Subsequent modifications to the standard search list remain in effect even when this method is invoked againthe search list is guaranteed to be standard only the first time this method is invoked. The shared instance is provided as a convenience; other instances may also be created.

• - (NSArray *)arrayForKey:(NSString *)defaultName Invokes objectForKey: with key defaultName. Returns the corresponding value if it's an NSArray object (according to the isKindOfClass: test) and nil otherwise.
• - (BOOL)boolForKey:(NSString *)defaultName Invokes stringForKey: with key defaultName. Returns YES if the corresponding value is an NSString containing uppercase or lowercase YES or responds to the intValue message by returning a non-zero value. Otherwise, returns NO.
• - (NSData *)dataForKey:(NSString *)defaultName Invokes objectForKey: with key defaultName. Returns the corresponding value if it's an NSData object (according to the isKindOfClass: test) and nil otherwise.
• - (NSDictionary *)dictionaryForKey:(NSString *)defaultName Invokes objectForKey: with key defaultName. Returns the corresponding value if it's an NSDictionary object (according to the isKindOfClass: test) and nil otherwise.
• - (float)floatForKey:(NSString *)defaultName Invokes stringForKey: with key defaultName. Returns 0 if no string is returned. Otherwise, the resulting string is sent a floatValue message, which provides this method's return value.
• - (int)integerForKey:(NSString *)defaultName Invokes stringForKey: with key defaultName. Returns 0 if no string is returned. Otherwise, the resulting string is sent a intValue message, which provides this method's return value.
• - (id)objectForKey:(NSString *)defaultName Returns the value of the first occurrence of the specified default, searching the domains included in the search list. Returns nil if the default isn't found.
• - (void)removeObjectForKey:(NSString *)defaultName Removes the value for the given default in the standard application domain. Removing a default has no effect on the value returned by the objectForKey: method if the same key exists in a domain that precedes the standard application domain in the search list.
• - (void)setBool:(BOOL)value Sets the value of the specified default to a string forKey:(NSString *)defaultName representation of YES or NO, depending on value. Invokes setObject:forKey: as part of its implementation.
• - (void)setFloat:(float)value Sets the value of the specified default to a string forKey:(NSString *)defaultName representation of value. Invokes setObject:forKey: as part of its implementation.
• - (void)setInteger:(int)value Sets the value of the specified default to a string forKey:(NSString *)defaultName representation of value. Invokes setObject:forKey: as part of its implementation.
• - (void)setObject:(id)value Sets the value of the specified default in the standard forKey:(NSString *)defaultName application domain. Setting a default has no effect on the value returned by the objectForKey: method if the same key exists in a domain that precedes the application domain in the search list.
• - (NSArray *)stringArrayForKey:(NSString *)defaultName Invokes objectForKey: with key defaultName. Returns the corresponding value if it's an NSArray object containing NSStrings, and nil otherwise. The class of each object is determined using the isKindOfClass: test.
• - (NSString *)stringForKey:(NSString *)defaultName Invokes objectForKey: with key defaultName. Returns the corresponding value if it's an NSString object (according to the isKindOfClass: test) and nil otherwise.

• - (id)init Initializes defaults for the current user (who's identified by examining the environment). This method doesn't put anything in the search list. Invoke it only if you've allocated your own NSUserDefaults object instead of using the shared one. Returns self.
• - (id)initWithUser:(NSString *)userName Like init, but initializes defaults for the specified user.

• - (NSMutableArray *)searchList Returns a mutable array of domain names, signifying the domains that objectForKey: will search. You can customize the search list by modifying the array that's returned. Non-existent domain names in the list are ignored.

• - (NSDictionary *)persistentDomainForName:(NSString *)domainName Returns a dictionary corresponding to the specified persistent domain. The keys in the dictionary are names of defaults, and the value corresponding to each key is a property list data object.
• - (NSArray *)persistentDomainNames Returns an array containing the names of the persistent domains. Each domain can then be retrieved by invoking persistentDomainForName:.
• - (void)removePersistentDomainForName:(NSString *)domainName Removes the named persistent domain from the user's defaults. The first time that a persistent domain is changed after synchronize, an NSUserDefaultsChanged notification is posted.
• - (void)setPersistentDomain:(NSDictionary *)domain forName:(NSString *)domainName Sets the dictionary for the persistent domain named domainName; raises an NSInvalidArgumentException if a volatile domain with domainName already exists. The first time that a persistent domain is changed after synchronize, an NSUserDefaultsChanged notification is posted.
• - (BOOL)synchronize Saves any modifications to the persistent domains and updates all persistent domains that were not modified to what is on disk. Returns NO if it could not save data to disk. Since the synchronize method is automatically invoked at periodic intervals, use this method only if you cannot wait for the automatic synchronization (for example if your application is about to exit), or if you want to update user defaults to what is on disk even though you have not made any changes.

• - (void)removeVolatileDomainForName:(NSString *)domainName Removes the named volatile domain from the user's defaults.
• - (void)setVolatileDomain:(NSDictionary *)domain forName:(NSString *)domainName Sets the dictionary to domain for the volatile domain named domainName. This method raises an NSInvalidArgumentException if a persistent domain with domainName already exists.
• - (NSDictionary *)volatileDomainForName:(NSString *)domainName Returns a dictionary corresponding to the specified volatile domain. The keys in the dictionary are names of defaults, and the value corresponding to each key is a property list data object.
• - (NSArray *)volatileDomainNames Returns an array containing the names of the volatile domains. Each domain can then be retrieved by calling volatileDomainForName:.

• - (NSDictionary *)dictionaryRepresentation Returns a dictionary that contains a union of all key-value pairs in the domains in the search list. As with objectForKey:, key-value pairs in domains that are earlier in the search list take precedence. The combined result doesn't preserve information about which domain each entry came from.
• - (void)registerDefaults:(NSDictionary *)dictionary Adds the contents of dictionary to the registration domain. If there is no registration domain yet, it's created using dictionary, and NSRegistrationDomain is added to the end of the search list.