Class: NSUserDefaults

Inherits:
NSObject show all

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)

Instance Method Summary (collapse)

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.

Returns:

+ (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.

Returns:

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.

Parameters:

  • suiteName (String)

    The domain name to insert. This domain is inserted after the application domain.

Returns:

- (Array) arrayForKey(defaultName)

Returns the array associated with the specified key.

Parameters:

  • defaultName (String)

    A key in the current user's defaults database.

Returns:

  • (Array)

    The array associated with the specified key, or nil if the key does not exist or its value is not an NSArray object.

- (Boolean) boolForKey(defaultName)

Returns the Boolean value associated with the specified key.

Parameters:

  • defaultName (String)

    A key in the current user's defaults database.

Returns:

  • (Boolean)

    If a boolean value is associated with defaultName in the user defaults, that value is returned. Otherwise, NO is returned.

- (NSData) dataForKey(defaultName)

Returns the data object associated with the specified key.

Parameters:

  • defaultName (String)

    A key in the current user's defaults database.

Returns:

  • (NSData)

    The data object associated with the specified key, or nil if the key does not exist or its value is not an NSData object.

- (Hash) dictionaryForKey(defaultName)

Returns the dictionary object associated with the specified key.

Parameters:

  • defaultName (String)

    A key in the current user's defaults database.

Returns:

  • (Hash)

    The dictionary object associated with the specified key, or nil if the key does not exist or its value is not an NSDictionary object.

- (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.

Returns:

- (Float) doubleForKey(defaultName)

Returns the double value associated with the specified key.

Parameters:

  • defaultName (String)

    A key in the current user's defaults database.

Returns:

  • (Float)

    The double value associated with the specified key. If the key does not exist, this method returns 0.

- (Float) floatForKey(defaultName)

Returns the floating-point value associated with the specified key.

Parameters:

  • defaultName (String)

    A key in the current user's defaults database.

Returns:

  • (Float)

    The floating-point value associated with the specified key. If the key does not exist, this method returns 0.

- (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.

Returns:

  • (Object)

    An initialized NSUserDefaults object whose argument and registration domains are already set up.

- (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.

Parameters:

  • username (String)

    The name of the user account.

Returns:

  • (Object)

    An initialized NSUserDefaults object whose argument and registration domains are already set up. If the current user does not have access to the specified user account, this method returns nil.

- (Integer) integerForKey(defaultName)

Returns the integer value associated with the specified key..

Parameters:

  • defaultName (String)

    A key in the current user's defaults database.

Returns:

  • (Integer)

    The integer value associated with the specified key. If the specified key does not exist, this method returns 0.

- (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.

Parameters:

  • defaultName (String)

    A key in the current user's defaults database.

Returns:

  • (Object)

    The object associated with the specified key, or nil if the key was not found.

- (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.

Parameters:

  • key (String)

    The key whose status you want to check.

Returns:

  • (Boolean)

    YES if the value of the specified key is managed by an administrator, otherwise NO.

- (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.

Parameters:

  • key (String)

    The key whose status you want to check.

  • domain (String)

    The domain of the key.

Returns:

  • (Boolean)

    YES if the key is managed by an administrator in the specified domain, otherwise NO.

- (Hash) persistentDomainForName(domainName)

Returns a dictionary containing the keys and values in the specified persistent domain.

Parameters:

  • domainName (String)

    The domain whose keys and values you want. This value should be equal to your application's bundle identifier.

Returns:

- (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.

Returns:

  • (Array)

    An array of NSString objects containing the domain names.

- (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.

Parameters:

  • dictionary (Hash)

    The dictionary of keys and values you want to register.

Returns:

- (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.

Parameters:

  • defaultName (String)

    The key whose value you want to remove.

Returns:

- (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.

Parameters:

  • domainName (String)

    The domain whose keys and values you want. This value should be equal to your application’s bundle identifier.

Returns:

- (Object) removeSuiteNamed(suiteName)

Removes the specified domain name from the receiver’s search list.

Parameters:

  • suiteName (String)

    The domain name to remove.

Returns:

- (Object) removeVolatileDomainForName(domainName)

Removes the specified volatile domain from the user’s defaults.

Parameters:

  • domainName (String)

    The volatile domain you want to remove.

Returns:

- (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.

Parameters:

  • value (Boolean)

    The Boolean value to store in the defaults database.

  • defaultName (String)

    The key with which to associate with the value.

Returns:

- (Object) setDouble(value, forKey:defaultName)

Sets the value of the specified default key to the double value.

Parameters:

  • value (Float)

    The double value.

  • defaultName (String)

    The key with which to associate with the value.

Returns:

- (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.

Parameters:

  • value (Float)

    The floating-point value to store in the defaults database.

  • defaultName (String)

    The key with which to associate with the value.

Returns:

- (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.

Parameters:

  • value (Integer)

    The integer value to store in the defaults database.

  • defaultName (String)

    The key with which to associate with the value.

Returns:

- (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.

Parameters:

  • value (Object)

    The object to store in the defaults database.

  • defaultName (String)

    The key with which to associate with the value.

Returns:

- (Object) setPersistentDomain(domain, forName:domainName)

Sets the dictionary for the specified persistent domain. When a persistent domain is changed, an NSUserDefaultsDidChangeNotification is posted.

Parameters:

  • domain (Hash)

    The dictionary of keys and values you want to assign to the domain.

  • domainName (String)

    The domain whose keys and values you want to set. This value should be equal to your application's bundle identifier.

Returns:

- (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.

Parameters:

  • url (NSURL)

    The NSURL to store in the defaults database.

  • defaultName (String)

    The key with which to associate with the value.

Returns:

- (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.

Parameters:

  • domain (Hash)

    The dictionary of keys and values you want to assign to the domain.

  • domainName (String)

    The domain whose keys and values you want to set.

Returns:

- (Array) stringArrayForKey(defaultName)

Returns the array of strings associated with the specified key.

Parameters:

  • defaultName (String)

    A key in the current user's defaults database.

Returns:

  • (Array)

    The array of NSString objects, or nil if the specified default does not exist, the default does not contain an array, or the array does not contain NSString objects.

- (String) stringForKey(defaultName)

Returns the string associated with the specified key.

Parameters:

  • defaultName (String)

    A key in the current user's defaults database.

Returns:

  • (String)

    The string associated with the specified key, or nil if the default does not exist or does not contain a string.

- (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.

Returns:

  • (Boolean)

    YES if the data was saved successfully to disk, otherwise NO.

- (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.

Parameters:

  • defaultName (String)

    A key in the current user's defaults database.

Returns:

  • (NSURL)

    The NSURL instance value associated with the specified key. If the key does not exist, this method returns nil.

- (Hash) volatileDomainForName(domainName)

Returns the dictionary for the specified volatile domain.

Parameters:

  • domainName (String)

    The domain whose keys and values you want.

Returns:

- (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.

Returns:

  • (Array)

    An array of NSString objects with the volatile domain names.