Class: NSUserDefaults
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.
Class Method Summary (collapse)
-
+ resetStandardUserDefaults
Synchronizes any changes made to the shared user defaults object and releases it from memory.
-
+ standardUserDefaults
Returns the shared defaults object.
Instance Method Summary (collapse)
-
- addSuiteNamed:
Inserts the specified domain name into the receiver’s search list.
-
- arrayForKey:
Returns the array associated with the specified key.
-
- boolForKey:
Returns the Boolean value associated with the specified key.
-
- dataForKey:
Returns the data object associated with the specified key.
-
- dictionaryForKey:
Returns the dictionary object associated with the specified key.
-
- dictionaryRepresentation
Returns a dictionary that contains a union of all key-value pairs in the domains in the search list.
-
- doubleForKey:
Returns the double value associated with the specified key.
-
- floatForKey:
Returns the floating-point value associated with the specified key.
-
- init
Returns an NSUserDefaults object initialized with the defaults for the current user account.
-
- initWithUser:
Returns an NSUserDefaults object initialized with the defaults for the specified user account.
-
- integerForKey:
Returns the integer value associated with the specified key..
-
- objectForKey:
Returns the object associated with the first occurrence of the specified default.
-
- objectIsForcedForKey:
Returns a Boolean value indicating whether the specified key is managed by an administrator.
-
- objectIsForcedForKey:inDomain:
Returns a Boolean value indicating whether the key in the specified domain is managed by an administrator.
-
- persistentDomainForName:
Returns a dictionary containing the keys and values in the specified persistent domain.
-
- persistentDomainNames
Returns an array of the current persistent domain names.
-
- registerDefaults:
Adds the contents of the specified dictionary to the registration domain.
-
- removeObjectForKey:
Removes the value of the specified default key in the standard application domain.
-
- removePersistentDomainForName:
Removes the contents of the specified persistent domain from the user’s defaults.
-
- removeSuiteNamed:
Removes the specified domain name from the receiver’s search list.
-
- removeVolatileDomainForName:
Removes the specified volatile domain from the user’s defaults.
-
- setBool:forKey:
Sets the value of the specified default key to the specified Boolean value.
-
- setDouble:forKey:
Sets the value of the specified default key to the double value.
-
- setFloat:forKey:
Sets the value of the specified default key to the specified floating-point value.
-
- setInteger:forKey:
Sets the value of the specified default key to the specified integer value.
-
- setObject:forKey:
Sets the value of the specified default key in the standard application domain.
-
- setPersistentDomain:forName:
Sets the dictionary for the specified persistent domain.
-
- setURL:forKey:
Sets the value of the specified default key to the specified URL.
-
- setVolatileDomain:forName:
Sets the dictionary for the specified volatile domain.
-
- stringArrayForKey:
Returns the array of strings associated with the specified key.
-
- stringForKey:
Returns the string associated with the specified key.
-
- synchronize
Writes any modifications to the persistent domains to disk and updates all unmodified persistent domains to what is on disk.
-
- URLForKey:
Returns the NSURL instance associated with the specified key.
-
- volatileDomainForName:
Returns the dictionary for the specified volatile domain.
-
- volatileDomainNames
Returns an array of the current volatile domain names.
Methods inherited from NSObject
#!, #!=, #!~, #, #==, #===, #=~, #Rational, #__callee__, #__method__, #__send__, #__type__, `, alloc, allocWithZone:, #autoContentAccessingProxy, autoload, autoload?, autorelease_pool, #awakeAfterUsingCoder:, binding, block_given?, caller, cancelPreviousPerformRequestsWithTarget:, cancelPreviousPerformRequestsWithTarget:selector:object:, catch, class, classFallbacksForKeyedArchiver, #classForCoder, #classForKeyedArchiver, classForKeyedUnarchiver, #clone, conformsToProtocol:, #copy, copyWithZone:, #dealloc, #define_singleton_method, description, display, #doesNotRecognizeSelector:, #dup, #enum_for, #eql?, #equal?, #extend, fail, #finalize, format, #forwardInvocation:, #forwardingTargetForSelector:, framework, #freeze, #frozen?, getpass, gets, global_variables, initialize, #initialize_clone, #initialize_copy, #initialize_dup, #inspect, instanceMethodForSelector:, instanceMethodSignatureForSelector:, #instance_eval, #instance_exec, #instance_of?, #instance_variable_defined?, #instance_variable_get, #instance_variable_set, #instance_variables, instancesRespondToSelector:, isSubclassOfClass:, #is_a?, iterator?, #kind_of?, lambda, load, load_bridge_support_file, load_plist, local_variables, loop, #method, #methodForSelector:, #methodSignatureForSelector:, #methods, #mutableCopy, mutableCopyWithZone:, new, #nil?, open, p, #performSelector:onThread:withObject:waitUntilDone:, #performSelector:onThread:withObject:waitUntilDone:modes:, #performSelector:withObject:afterDelay:, #performSelector:withObject:afterDelay:inModes:, #performSelectorInBackground:withObject:, #performSelectorOnMainThread:withObject:waitUntilDone:, #performSelectorOnMainThread:withObject:waitUntilDone:modes:, print, printf, #private_methods, proc, #protected_methods, #public_method, #public_methods, #public_send, putc, puts, raise, rand, readline, readlines, #replacementObjectForCoder:, #replacementObjectForKeyedArchiver:, require, resolveClassMethod:, resolveInstanceMethod:, #respond_to?, #respond_to_missing?, select, #send, setVersion:, #singleton_methods, sprintf, srand, superclass, #taint, #tainted?, #tap, test, throw, #to_plist, #to_s, trace_var, trap, #trust, #untaint, untrace_var, #untrust, #untrusted?, version
Constructor Details
This class inherits a constructor from NSObject
Dynamic Method Handling
This class handles dynamic methods through the method_missing method in the class NSObject
Class Method Details
+ (Object) resetStandardUserDefaults
Synchronizes any changes made to the shared user defaults object and releases it from memory. A subsequent invocation of standardUserDefaults creates a new shared user defaults object with the standard search list.
+ (NSUserDefaults) standardUserDefaults
Returns the shared defaults object.
If the shared defaults object does not exist yet, it is created with a search list containing the names of the following domains, in this order: NSArgumentDomain, consisting of defaults parsed from the application’s arguments
A domain identified by the application’s bundle identifier NSGlobalDomain, consisting of defaults meant to be seen by all applications Separate domains for each of the user’s preferred languages 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 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.
Instance Method Details
- (Object) addSuiteNamed(suiteName)
Inserts the specified domain name into the receiver’s search list. 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.
- (Array) arrayForKey(defaultName)
Returns the array associated with the specified key.
- (Boolean) boolForKey(defaultName)
Returns the Boolean value associated with the specified key.
- (NSData) dataForKey(defaultName)
Returns the data object associated with the specified key.
- (Hash) dictionaryForKey(defaultName)
Returns the dictionary object associated with the specified key.
- (Hash) 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 does not preserve information about which domain each entry came from.
- (Float) doubleForKey(defaultName)
Returns the double value associated with the specified key.
- (Float) floatForKey(defaultName)
Returns the floating-point value associated with the specified key.
- (Object) init
Returns an NSUserDefaults object initialized with the defaults for the current user account. This method does not put anything in the search list. Invoke it only if you’ve allocated your own NSUserDefaults instance instead of using the shared one.
- (Object) initWithUser(username)
Returns an NSUserDefaults object initialized with the defaults for the specified user account. This method does not put anything in the search list. Invoke it only if you’ve allocated your own NSUserDefaults instance instead of using the shared one.You do not normally use this method to initialize an instance of NSUserDefaults. Applications used by a superuser might use this method to update the 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.
- (Integer) integerForKey(defaultName)
Returns the integer value associated with the specified key..
- (Object) objectForKey(defaultName)
Returns the object associated with the first occurrence of the specified default. This method searches the domains included in the search list in the order they are listed.
- (Boolean) objectIsForcedForKey(key)
Returns a Boolean value indicating whether the specified key is managed by an administrator. This method assumes that the 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.
- (Boolean) objectIsForcedForKey(key, inDomain:domain)
Returns a Boolean value indicating whether the key in the specified domain is managed by an administrator. This method assumes that the 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.
- (Hash) persistentDomainForName(domainName)
Returns a dictionary containing the keys and values in the specified persistent domain.
- (Array) persistentDomainNames
Returns an array of the current persistent domain names. You can get the keys and values for each domain by passing the returned domain names to the persistentDomainForName: method.
- (Object) registerDefaults(dictionary)
Adds the contents of the specified dictionary to the registration domain. If there is no registration domain, one is created using the specified dictionary, and NSRegistrationDomain is added to the end of the search list.The contents of the registration domain are not written to disk; you need to call this method each time your application starts. You can place a plist file in the application's Resources directory and call registerDefaults: with the contents that you read in from that file.
- (Object) removeObjectForKey(defaultName)
Removes the value of the specified default key 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.
- (Object) removePersistentDomainForName(domainName)
Removes the contents of the specified persistent domain from the user’s defaults. When a persistent domain is changed, an NSUserDefaultsDidChangeNotification is posted.
- (Object) removeSuiteNamed(suiteName)
Removes the specified domain name from the receiver’s search list.
- (Object) removeVolatileDomainForName(domainName)
Removes the specified volatile domain from the user’s defaults.
- (Object) setBool(value, forKey:defaultName)
Sets the value of the specified default key to the specified Boolean value. Invokes setObject:forKey: as part of its implementation.
- (Object) setDouble(value, forKey:defaultName)
Sets the value of the specified default key to the double value.
- (Object) setFloat(value, forKey:defaultName)
Sets the value of the specified default key to the specified floating-point value. Invokes setObject:forKey: as part of its implementation.
- (Object) setInteger(value, forKey:defaultName)
Sets the value of the specified default key to the specified integer value. Invokes setObject:forKey: as part of its implementation.
- (Object) setObject(value, forKey:defaultName)
Sets the value of the specified default key in the standard application domain. The value parameter can be only property list objects: NSData, NSString, NSNumber, NSDate, NSArray, or NSDictionary. For NSArray and NSDictionary objects, their contents must be property list objects. See “What is a Property List?” in Property List Programming Guide.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.
- (Object) setPersistentDomain(domain, forName:domainName)
Sets the dictionary for the specified persistent domain. When a persistent domain is changed, an NSUserDefaultsDidChangeNotification is posted.
- (Object) setURL(url, forKey:defaultName)
Sets the value of the specified default key to the specified URL. When an NSURL is stored using -[NSUserDefaults setURL:forKey:], some adjustments are made:Any non-file URL is written by calling +[NSKeyedArchiver archivedDataWithRootObject:] using the NSURL instance as the root object.Any file reference file: scheme URL will be treated as a non-file URL, and information which makes this URL compatible with 10.5 systems will also be written as part of the archive as well as its minimal bookmark data.Any path-based file: scheme URL is written by first taking the absolute URL, getting the path from that and then determining if the path can be made relative to the user's home directory. If it can, the string is abbreviated by using stringByAbbreviatingWithTildeInPath and written out. This allows pre-10.6 clients to read the default and use -[NSString stringByExpandingTildeInPath] to use this information.
- (Object) setVolatileDomain(domain, forName:domainName)
Sets the dictionary for the specified volatile domain. This method raises an NSInvalidArgumentException if a volatile domain with the specified name already exists.
- (Array) stringArrayForKey(defaultName)
Returns the array of strings associated with the specified key.
- (String) stringForKey(defaultName)
Returns the string associated with the specified key.
- (Boolean) synchronize
Writes any modifications to the persistent domains to disk and updates all unmodified persistent domains to what is on disk. Because this 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 the user defaults to what is on disk even though you have not made any changes.
- (NSURL) URLForKey(defaultName)
Returns the NSURL instance associated with the specified key. When an NSURL is read using -[NSUserDefaults URLForKey:], the following logic is used:If the value for the key is an NSData, the NSData is used as the argument to +[NSKeyedUnarchiver unarchiveObjectWithData:]. If the NSData can be unarchived as an NSURL, the NSURL is returned otherwise nil is returned.If the value for this key was a file reference URL, the file reference URL will be created but its bookmark data will not be resolved until the NSURL instance is later used (e.g. at -[NSData initWithContentsOfURL:]).If the value for the key is an NSString which begins with a ~, the NSString will be expanded using -[NSString stringByExpandingTildeInPath] and a file: scheme NSURL will be created from that.
- (Hash) volatileDomainForName(domainName)
Returns the dictionary for the specified volatile domain.
- (Array) volatileDomainNames
Returns an array of the current volatile domain names.
You can get the contents of each domain by passing the returned domain names to the volatileDomainForName: method.