- Inherits from:
- NSObject
- Conforms to:
- NSObject
- (NSObject)
Declared in:
- Foundation/NSUserDefaults.h
The NSUserDefaults class provides an programmatic interface for interacting with the defaults system.
- objectForKey: | Returns the default value for the specified key. |
- setObject:forKey: | 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 NSRegistrationDomain -a
cache of application-provided defaults that are used unless a user
overrides them. |
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 run time, 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.
WARNINGUser defaults are not thread safe.
Defaults are grouped in domains. For example, there's a domain for application-specific defaults and another for system-wide defaults that apply to all applications.
All defaults are stored and accessed per user. Defaults that affect all users are not provided for.
Each domain has a name by which it's identified and stores defaults as key-value pairs in an NSDictionary object. Each default is made up of three components:
A domain is either persistent or volatile. Persistent domains are permanent and last past the life of the NSUserDefaults object. Persistent domains are stored in a user's defaults database. If you use NSUserDefaults to make a changes to a default in a persistent domain, the changes are saved in the user's defaults database automatically. On the other hand, volatile domains last only as long as the NSUserDefaults object exists; they aren't saved in the user's defaults database. The standard domains are:
Domain | State |
NSArgumentDomain |
volatile |
Application (Identified by the application's name) | persistent |
NSGlobalDomain |
persistent |
Languages (Identified by the language names) | volatile |
NSRegistrationDomain |
volatile |
A search for the value of a given default proceeds through the domains in an NSUserDefaults 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 setSearchList method, you can reorder the default search list or set up one that is a subset of all the user's domains.
The following sections describe the purpose of each of the domains.
Default values can be set from command line arguments (if
you start the application from the command line) as well as from
a user's defaults database. Default values set from the command
line go in the NSArgumentDomain
.
They are set on the command line by preceding the default name with
a hyphen and following it with a value. For example, the following
command launches Project Builder and sets Project Builder's IndexOnOpen
default
to NO:
localhost> ProjectBuilder.app/ProjectBuilder -IndexOnOpen NO
Defaults set from the command line temporarily override values
from a user's defaults database. In the example above, Project
Builder won't automatically index projects even if the user's IndexOnOpen
preference
is set to YES in the defaults database.
The application domain contains application-specific defaults that are read from a user's defaults database. The application domain is identified by the bundle identifier of the application.
The global domain contains defaults that are read from a user's
defaults database and are applicable to all applications that a
user runs. Many Application Kit and Foundation objects use default
values from the NSGlobalDomain
. For
example, NSRulerView objects automatically use a user's preferred measurement
units, as stored in the user's defaults database under the key
"NSMeasurementUnit
." Consequently,
ruler views in all applications use the user's preferred measurement
units-unless an application overrides the default by creating
an NSMeasurementUnit
default in its
application domain. Another NSGlobalDomain
default, NSLanguages,
allows users to specify a preference of languages. For example,
a user could specify English as the preferred language, followed
by Spanish, French, German, Italian, and Swedish.
If a user has a value for the NSLanguages default, then NSUserDefaults records language-specific default values in domains identified by the language name. The language specific domains contain defaults for a locale. Certain classes from the Foundation Framework (NSCalendarDate, NSDate, NSTimeZone, NSString, and NSScanner, for example) use locale defaults to modify their behavior. For example, when you request an NSString representation of an NSCalendarDate, the NSCalendarDate looks at the locale to determine what the months and the days of the week are named in your preferred language.
The registration domain is a set of application-provided defaults
that are used unless a user overrides them. For example, the first
time you run Project Builder, there isn't an IndexOnOpen
value
saved in your defaults database. Consequently, Project Builder registers
a default value for IndexOnOpen
in
the NSRegistrationDomain
as a "catch
all" value. Project Builder can thereafter assume that an NSUserDefaults
object always has a value to return for the default, simplifying
the use of user defaults.
You set NSRegistrationDomain
defaults
programmatically with the method registerDefaults:.
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. Using the synchronize method, 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. 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.
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. Use the objectForKey: and setObject:forKey: methods to get and set default values.
For example, suppose that your application needs a default that specifies whether or not to delete backup files. You could use an NSUserDefaults object to manage your default, as follows:
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" andKey:@"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 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, 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.
NSUserDefaults provides the following constants as a convenience. They provide access to values of the keys to the locale dictionary, which was discussed earlier in "Languages" .
Constant | Type | Key Name and Description |
NSAMPMDesignation |
NSString | An array of strings that specify how the morning and afternoon designations are printed. The default is AM and PM. |
NSCurrencySymbol |
NSString | A string that specifies the symbol used to denote currency in this language. The default is "$". |
NSDateFormatString |
NSString | A format string that specifies how dates are printed using the date format specifiers. The default is to use weekday names with full month names and full years, as in "Sunday, January 01, 1995." |
NSDateTimeOrdering |
NSString | A string that specifies how to use ambiguous numbers in date strings. Specify this value as a permutation of the letters M (month), D (day), Y (year), and H (hour). For example, MDYH treats "2/3/95 10" as the 3rd day of February 1995 at 10:00am, whereas DMYH treats the same value as the 2nd day of March 1995 at 10:00am. If fewer numbers are specified than are needed, the numbers are prioritized to satisfy day first, then the month, and then the year. For example, if you supply only the value 12, it means the 12th day of this month in this year because the day must be specified. If you supply "2 12" it means either February 12 or December 2, depending on if the ordering is "MDYH" or "DMYH." |
NSDecimalDigits |
NSString | Strings that identify the decimal digits in addition to or instead of the ASCII digits. |
NSDecimalSeparator |
NSString | A string that specifies the decimal separator. The decimal separator separates the ones place from the tenths place. The default is ".". |
NSEarlierTimeDesignations |
NSString | An array of strings that denote a time in the past. These are adjectives that modify values from NSYearMonthWeekDesignations. The defaults are "prior," "last," "past," and "ago." |
NSHourNameDesignations |
NSString | Strings that identify the time of day. These strings should be bound to an hour. The default is this array of arrays: (0, midnight), (12, noon, lunch), (10, morning), (14, afternoon), (19, dinner). |
NSInternationalCurrencyString |
NSString | A string containing three letter abbreviation for currency, following the ISO 4217 standard. |
NSLaterTimeDesignations |
NSString | An array of strings that denote a time in the future.
This is an adjective that modifies a value from NSYearMonthWeekDesignations .
The default is "next.". |
NSMonthNameArray |
NSString | An array that specifies the full names for the months. |
NSNegativeCurrencyFormatString |
NSString | |
NSNextDayDesignations |
NSString | A string that identifies the day after today. The default is "tomorrow." |
NSNextNextDayDesignations |
NSString | A string that identifies the day after tomorrow. The default is "nextday". |
NSPositiveCurrencyFormatString |
NSString | |
NSPriorDayDesignations |
NSString | A string that identifies the day before today. The default is "yesterday." |
NSShortDateFormatString |
NSString | A format string that specifies how dates are abbreviated. The default is to separate the day month and year with slashes and to put the day first, as in 31/10/95. |
NSShortMonthNameArray |
NSString | An array that specifies the abbreviations for the months. |
NSShortTimeDateFormatString |
NSString | A format string that specifies how times and dates are abbreviated. The default is to use dashes to separate the day, month, and year and to use a 12-hour clock, as in "31-Jan-95 1:30 PM. |
NSShortWeekDayNameArray |
NSString | An array that specifies the abbreviations for the days of the week. Sunday should be the first day of the week. |
NSThisDayDesignations |
NSString | A string that identifies what this day is called. The default is "today." |
NSThousandsSeparator |
NSString | A string that specifier the separator character for the thousands place of a decimal number. The default is a comma. |
NSTimeDateFormatString |
NSString | A format string how dates with times are printed. The default is to use abbreviated months and days with a 24 hour clock, as in "Sun Jan 01 23:00:00 +6 2001." |
NSTimeFormatString |
NSString | A format string how dates with times are printed. The default is to use a 24 hour clock, as in 13:30:25. |
NSWeekDayNameArray |
NSString | An array that gives the names for the days of the week. Sunday should be the first day of the week. |
NSYearMonthWeekDesignations |
NSString | An array of strings that specify the word for year, month, and week in the current locale. The defaults are "year," "month," and "week." |
- Getting the shared instance
- + standardUserDefaults
- + resetStandardUserDefaults
- Initializing an NSUserDefaults
- - init
- - initWithUser:
- Getting a default
- - arrayForKey:
- - boolForKey:
- - dataForKey:
- - dictionaryForKey:
- - floatForKey:
- - integerForKey:
- - objectForKey:
- - stringArrayForKey:
- - stringForKey:
- Setting and removing defaults
- - removeObjectForKey:
- - setBool:forKey:
- - setFloat:forKey:
- - setInteger:forKey:
- - setObject:forKey:
- Setting and getting the search list
- - dictionaryRepresentation
- Maintaining persistent domains
- - persistentDomainForName:
- - persistentDomainNames
- - removePersistentDomainForName:
- - setPersistentDomain:forName:
- - synchronize
- Maintaining volatile domains
- - removeVolatileDomainForName:
- - setVolatileDomain:forName:
- - volatileDomainForName:
- - volatileDomainNames
- Registering defaults
- - registerDefaults:
+ (void)resetStandardUserDefaults
+ (NSUserDefaults *)standardUserDefaults
NSArgumentDomain
,
consisting of defaults parsed from the application's argumentsNSGlobalDomain
, consisting
of defaults meant to be seen by all applicationsNSRegistrationDomain
, 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-you can create custom instances using alloc along with initWithUser: or init.
- (NSArray *)arrayForKey:(NSString
*)defaultName
nil
otherwise. See Also: - boolForKey:, - dataForKey:, - dictionaryForKey:, - floatForKey:, - integerForKey:, - objectForKey:, - stringArrayForKey:, - stringForKey:
- (BOOL)boolForKey:(NSString
*)defaultName
See Also: - arrayForKey:, - dataForKey:, - dictionaryForKey: , - floatForKey:, - integerForKey:, - objectForKey:, - stringArrayForKey:, - stringForKey:
- (NSData *)dataForKey:(NSString
*)defaultName
See Also: - arrayForKey:, - boolForKey:, - dictionaryForKey:, - floatForKey:, - integerForKey:, - objectForKey:, - stringArrayForKey:, - stringForKey:
- (NSDictionary *)dictionaryForKey:(NSString
*)defaultName
nil
otherwise.See Also: - arrayForKey:, - boolForKey:, - dataForKey:, - floatForKey:, - integerForKey:, - objectForKey:, - stringArrayForKey:, - stringForKey:
- (NSDictionary *)dictionaryRepresentation
See Also: - searchList
- (float)floatForKey:(NSString
*)defaultName
See Also: - arrayForKey:, - boolForKey:, - dataForKey:, - dictionaryForKey:, - integerForKey:, - objectForKey:, - stringArrayForKey:, - stringForKey:
- (id)init
See Also: + standardUserDefaults
- (id)initWithUser:(NSString
*)username
You
wouldn't ordinarily use this method to initialize an instance
of NSUserDefaults. It is provided for applications intended for
use by a superuser who needs to update defaults databases for a
number of users. The user who started the application must have
appropriate access (read, write, or both) to the defaults database
of the new user, or this method returns nil
.
See Also: + standardUserDefaults
- (int)integerForKey:(NSString
*)defaultName
See Also: - arrayForKey:, - boolForKey:, - dataForKey:, - dictionaryForKey:, - floatForKey:, - objectForKey:, - stringArrayForKey:, - stringForKey:
- (id)objectForKey:(NSString
*)defaultName
nil
if
the default isn't found.See Also: - arrayForKey:, - boolForKey:, - dataForKey:, - dictionaryForKey:, - floatForKey:, - stringArrayForKey:, - stringForKey:
- (NSDictionary *)persistentDomainForName:(NSString
*)domainName
See Also: - removePersistentDomainForName:, - setPersistentDomain:forName:
- (NSArray *)persistentDomainNames
See Also: - removePersistentDomainForName:, - setPersistentDomain:forName:
- (void)registerDefaults:(NSDictionary
*)dictionary
NSRegistrationDomain
is added
to the end of the search list- (void)removeObjectForKey:(NSString
*)defaultName
See Also: - setObject:forKey:
- (void)removePersistentDomainForName:(NSString
*)domainName
See Also: - setPersistentDomain:forName:
- (void)removeVolatileDomainForName:(NSString
*)domainName
See Also: - setVolatileDomain:forName:
- (void)setBool:(BOOL)value
forKey:(NSString *)defaultName
See Also: - boolForKey:
- (void)setFloat:(float)value
forKey:(NSString *)defaultName
See Also: - floatForKey:
- (void)setInteger:(int)value
forKey:(NSString *)defaultName
See Also: - integerForKey:
- (void)setObject:(id)value
forKey:(NSString *)defaultName
See Also: - removeObjectForKey:
- (void)setPersistentDomain:(NSDictionary
*)domain
forName:(NSString *)domainName
See Also: - persistentDomainForName:, - persistentDomainNames
- (void)setVolatileDomain:(NSDictionary
*)domain
forName:(NSString *)domainName
See Also: - volatileDomainForName:, - volatileDomainNames
- (NSArray *)stringArrayForKey:(NSString
*)defaultName
nil
otherwise.See Also: - arrayForKey:, - boolForKey:, - dataForKey:, - dictionaryForKey:, - floatForKey:, - integerForKey:, - objectForKey:, - stringForKey:
- (NSString *)stringForKey:(NSString
*)defaultName
nil
otherwise.See Also: - arrayForKey:, - boolForKey:, - dataForKey:, - dictionaryForKey:, - floatForKey:, - integerForKey:, - objectForKey:, - stringArrayForKey:
- (BOOL)synchronize
See Also: - persistentDomainForName:, - persistentDomainNames, - removePersistentDomainForName:, - setPersistentDomain:forName:
- (NSDictionary *)volatileDomainForName:(NSString
*)domainName
See Also: - removeVolatileDomainForName:, - setVolatileDomain:forName:
- (NSArray *)volatileDomainNames
See Also: - removeVolatileDomainForName:, - setVolatileDomain:forName:
This notification is posted the first time after a synchronize when a change is made to defaults in a persistent domain.
This notification contains a notification object but no userInfo dictionary. The notification object is the NSUserDefaults instance.