Next Page >

Hide TOC

Legacy Document

Important: The information in this document is obsolete and should not be used for new development.

NSUserDefaults

Inherits from	NSObject
Package	com.apple.cocoa.foundation
Companion guide	User Defaults Programming Topics for Cocoa

Class at a Glance

The NSUserDefaults class provides a programmatic interface for interacting with the defaults system.

Principal Attributes

A dictionary of defaults

Commonly Used Methods

objectForKey: Returns the default value for the specified key.
setObjectForKey: Sets the default value for the specified key.
removeObjectForKey: Removes the default entry identified by the specified key.
registerDefaults: Adds the specified defaults to the RegistrationDomain—a cache of application-provided defaults that are used unless a user overrides them.

Overview

The NSUserDefaults class provides a programmatic interface for interacting with the defaults system. The defaults system allows an application to customize its behavior to match a user’s preferences. For example, you can allow users to determine what units of measurement your application displays or how often documents are automatically saved. Applications record such preferences by assigning values to a set of parameters in a user’s defaults database. The parameters are referred to as defaults since they’re commonly used to determine an application’s default state at startup or the way it acts by default.

A defaults database is created automatically for each user.

At runtime, you use an NSUserDefaults object to read the defaults that your application uses from a user’s defaults database. NSUserDefaults caches the information to avoid having to open the user’s defaults database each time you need a default value. The synchronize method, which is automatically invoked at periodic intervals, keeps the in-memory cache in sync with a user’s defaults database.

If your application supports managed environments, you can use an NSUserDefaults object to determine which preferences are managed by an administrator for the benefit of the user. Managed environments correspond to computer labs or classrooms where an administrator or teacher may want to configure the systems in a particular way. In these situations, the teacher can establish a set of default preferences and force those preferences on users. If a preference is managed in this manner, applications should prevent users from editing that preference by disabling any appropriate controls.

A default’s value can be only property list objects: NSData, string, number, NSDate, NSArray, or NSDictionary.

Warning: User defaults are not thread safe.

Tasks

Constructors

Getting the Shared Instance

Getting a Default

Setting and Removing Defaults

Accessing Managed Environment Keys

Setting and Getting the Search List

Maintaining Persistent Domains

Maintaining Volatile Domains

Registering Defaults

Maintaining Suites

Constructors

NSUserDefaults

Creates an NSUserDefaults for the current user account and with the argument and registration domains set up.

public NSUserDefaults()

Discussion

This constructor does not put anything in the search list.

Static Methods

resetStandardUserDefaults

Synchronizes any changes made to the shared user defaults object and releases it from memory.

public static void resetStandardUserDefaults()

Discussion

A subsequent invocation of standardUserDefaults creates a new shared user defaults object with the standard search list.

standardUserDefaults

Returns the shared defaults object.

public static NSUserDefaults standardUserDefaults()

Discussion

If it does not exist yet, it is created with a search list containing the names of the following domains, in this order:

ArgumentDomain, consisting of defaults parsed from the application’s arguments
A domain identified by the application’s bundle identifier
GlobalDomain, consisting of defaults meant to be seen by all applications
Separate domains for each of the user’s preferred languages
RegistrationDomain, 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 again—the search list is guaranteed to be standard only the first time this method is invoked. The shared instance is provided as a convenience.

Instance Methods

addSuiteNamed

Inserts a new domain, suiteName, into the receiver’s search list.

public void addSuiteNamed(String suiteName)

Discussion

The suite domain is inserted after the application domain.

The suiteName domain is similar to a bundle identifier string, but is not tied to a particular application or bundle. A suite can be used to hold preferences that are shared between multiple applications.

arrayForKey

Invokes objectForKey with key defaultName.

public NSArray arrayForKey(String defaultName)

Discussion

Returns the value associated with defaultName if it’s an NSArray object and null otherwise.

booleanForKey

Invokes stringForKey with key defaultName.

public boolean booleanForKey(String defaultName)

Discussion

Returns true if the value associated with defaultName is an String containing the word “yes” in uppercase or lowercase or responds to the intValue message by returning a nonzero value. Otherwise, returns false.

dataForKey

Invokes objectForKey with key defaultName.

public NSData dataForKey(String defaultName)

Discussion

Returns the corresponding value if it’s an NSData object and null otherwise.

dictionaryForKey

Invokes objectForKey with key defaultName.

public NSDictionary dictionaryForKey(String defaultName)

Discussion

Returns the corresponding value if it’s an NSDictionary object and null otherwise.

dictionaryRepresentation

Returns a dictionary that contains a union of all key-value pairs in the domains in the search list.

public NSDictionary dictionaryRepresentation()

Discussion

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.

doubleForKey

Invokes stringForKey with key defaultName.

public double doubleForKey(String defaultName)

Discussion

Returns 0 if no string is returned. Otherwise, the resulting string is sent a doubleValue message, which provides this method’s return value.

floatForKey

Invokes stringForKey with key defaultName.

public float floatForKey(String defaultName)

Discussion

Returns 0 if no string is returned. Otherwise, the resulting string is sent a floatValue message, which provides this method’s return value.

integerForKey

Invokes stringForKey with key defaultName.

public int integerForKey(String defaultName)

Discussion

Returns 0 if no string is returned. Otherwise, the resulting string is sent an intValue message, which provides this method’s return value.

longForKey

Invokes stringForKey with key defaultName.

public long longForKey(String defaultName)

Discussion

Returns 0 if no string is returned. Otherwise, the resulting string is sent a longValue message, which provides this method’s return value.

objectForKey

Returns the value of the first occurrence of the default identified by defaultName, searching the domains included in the search list in the order they’re listed.

public Object objectForKey(String defaultName)

Discussion

Returns null if the default isn’t found.

objectForKeyInDomain

Returns the value for defaultName in the domain domainName.

public Object objectForKeyInDomain(String defaultName, String domainName)

Discussion

Only the defaults defined in the domainName for the current user for any host are searched. If defaultName is not found, null is returned.

objectIsForcedForKey

Determines whether key is managed by an administrator.

public boolean objectIsForcedForKey(String key)

Discussion

Returns true if the value of key is managed by an administrator; otherwise returns false. This method assumes that key is a preference associated with the current user and application. For managed keys, the application should disable any user interface that allows the user to modify the value of key.

Availability

Available in Mac OS X v10.2 and later.

objectIsForcedForKeyInDomain

Determines whether key is managed by an administrator.

public boolean objectIsForcedForKeyInDomain(String key, String domain)

Discussion

Returns true if the value of key in the specified domain is managed by an administrator; otherwise returns false. This method assumes that key is a preference associated with the current user. For managed keys, the application should disable any user interface that allows the user to modify the value of key.

Availability

Available in Mac OS X v10.2 and later.

persistentDomainForName

Returns a dictionary representing the persistent domain identified by domainName.

public NSDictionary persistentDomainForName(String domainName)

Discussion

The keys in the dictionary are names of defaults, and the value corresponding to each key is a property list object (NSData, String, Number, NSDate, NSArray, or NSDictionary). domainName should be your application’s bundle identifier.

persistentDomainNames

Returns an array containing the names of the current persistent domains.

public NSArray persistentDomainNames()

Discussion

You can get each domain by using the domain names in the array as arguments to persistentDomainForName.

registerDefaults

Adds the contents of dictionary to the registration domain.

public void registerDefaults(NSDictionary dictionary)

Discussion

If there is no registration domain, it’s created using dictionary, and RegistrationDomain is added to the end of the search list.

removeObjectForKey

Removes the value for the default identified by defaultName in the standard application domain.

public void removeObjectForKey(String defaultName)

Discussion

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.

removeObjectForKeyInDomain

Deletes defaultName from the domain domainName for the current user on any host.

public void removeObjectForKeyInDomain(String defaultName, String domainName)

Discussion

If domainName is part of the receiver’s search list, posts an UserDefaultsDidChangeNotification.

removePersistentDomainForName

Removes the persistent domain identified by domainName from the user’s defaults.

public void removePersistentDomainForName(String domainName)

Discussion

The first time a persistent domain is changed after synchronize, a UserDefaultsDidChangeNotification is posted. domainName should be your application’s bundle identifier.

removeSuiteNamed

Removes the suiteName domain from the receiver’s search list.

public void removeSuiteNamed(String suiteName)

removeVolatileDomainForName

Removes the volatile domain identified by domainName from the user’s defaults.

public void removeVolatileDomainForName(String domainName)

searchList

This method has been deprecated.

public NSArray searchList()

setBooleanForKey

Sets the value of the default identified by defaultName to a string representation of true or false, depending on value.

public void setBooleanForKey(boolean value, String defaultName)