This is NSUserDefaults.rtf in view mode; [Download] [Up]
paperh18648 margl-907 margr0 margt0 margb0 fi0 ri0 ql sb0 f1 fs24 Copyright f3 'e3f1 1994 by NeXT Computer, Inc. All Rights Reserved.
s8 li100 fi0 ri1007 ql f0 b fs36 fs100
fs36 NSUserDefaults
pard s18 li2872 fi-2771 ri1007 ql tx2872 f1 b0 fs28 fs48
fs28 f0 b fs24 Inherits From:tab b0 fs28 f1 NSObject
fs20
fs28 s11 f0 b fs24 Conforms To:tab b0 fs28 f1 NSObject (NSObject)
fs20
fs28 s12 f0 b fs24 Declared In:tab b0 fs28 f1 Foundation/NSUserDefaults.h
fs20
fs28 pard s32 li100 fi0 ri1007 ql f0 b fs28 fs20
fs28 Class Description
fs14
fs28 pard s2 li477 fi0 ri1007 ql tx2494 tx2872 tx3250 f1 b0 fs2
fs28 The NSUserDefaults class allows an application to query and manipulate a user'27s defaults settings.
fs16
fs28 Defaults are grouped in domains. For example, there'27s 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:
fs16
fs28 pard s35 li854 fi0 ri1007 ql tx4509 tx10180 f0 b fs24 Domaintab Identifier
fs6
fs24 s33 f1 b0 fs28 Argument tab NSArgumentDomain
fs6
fs28 Application tab Identified by the application'27s name
fs6
fs28 Globaltab NSGlobalDomain
fs6
fs28 Languagestab Identified by the language names
fs6
fs28 Registrationtab NSRegistrationDomain
fs6
fs28 pard s2 li477 fi0 ri1007 ql tx2494 tx2872 tx3250 fs10
fs28 The identifiers starting with 'aaNS'ba above are global constants.
fs16
fs28 The argument domain is composed of defaults parsed from the application'27s arguments. The application domain contains the defaults set by the application. It'27s identified by the name of the application, as returned by this message:
fs16
fs28 pard s9 li1231 fi0 ri1007 ql f2 fs20 NSString *applicationName = [[NSProcessInfo processInfo] processName];
pard s2 li477 fi0 ri1007 ql tx2494 tx2872 tx3250 f1 fs28 fs16
fs28 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.
fs16
fs28 A search for the value of a given default proceeds through the domains listed in an NSUserDefault object'27s i search listi0 . 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'27s value. Using the b searchListb0 method, you can reorder the default search list or set up one that is a subset of all the user'27s domains.
fs16
fs28 Typically, you use this class by invoking the b standardUserDefaultsb0 class method to get an NSUserDefaults object. This method returns a global NSUserDefaults object with a search list already initialized. Then use the b setObject:forKey:b0 andb objectForKey:b0 methods to set and access user defaults.
fs16
fs28 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 b synchronizeb0 method saves any modifications to the persistent domains and updates all persistent domains that were not modified to what is on disk. b synchronizeb0 is automatically invoked at periodic intervals.
fs16
fs28 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.
fs16
fs28 b Warnings:
fs16
fs28 pard s4 li1231 fi-376 ri1007 ql tx1231 tx2872 tx3250 b0 'b7tab User defaults are not thread safe.
fs16
fs28 'b7tab Automatic saving of changes to disk (through b synchronizeb0 ) depends on a run-loop being present.
fs16
fs28 'b7tab You should synchronize any domain you have altered before exiting a process.
fs16
fs28 pard s32 li100 fi0 ri1007 ql f0 b fs24
fs28 Getting the Shared Instance
fs14
fs28 pard s13 li7029 fi-6552 ri1007 ql tx6652 tx7030 f1 b0 fs2
fs28 fi-6552 + (NSUserDefaults *)b standardUserDefaultsb0 tab Returns the shared defaults object. If it doesn'27t exist yet, it'27s
s14 li7030 fi-6553 fi-5796 tab tab created with a search list containing the names of the following domains, in order: the NSArgumentDomain (consisting of defaults parsed from the application'27s arguments), a domain with the process'27 name, separate domains for each of the user'27s 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 again'd0the 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.
pard s32 li100 fi0 ri1007 ql f0 b fs48
fs28 Getting and Setting a Default
fs14
fs28 pard s13 li7029 fi-6552 ri1007 ql tx6652 tx7030 f1 b0 fs2
fs28 fi-6552 {f3 -} (NSArray *)b arrayForKey:b0 (NSString *)i defaultName
s14 li7030 fi-6553 fi-5796 i0 tab Invokes b objectForKey:b0 with key i defaultNamei0 . Returns the corresponding value if it'27s an NSArray object (according to the b isKindOfClass:b0 test) and b nilb0 otherwise.
s13 li7029 fi-5794 fi-6552 fs16
fs28 fi-6552 {f3 -} (BOOL)b boolForKey:b0 (NSString *)i defaultNamei0 tab Invokes b stringForKey:b0 with key i defaultNamei0 . Returns YES if the corresponding value is an NSString containing uppercase or lowercase 'aaYES'ba or responds to the b intValueb0 message by returning a non-zero value. Otherwise, returns NO.
fi-6552 fs16
fs28 fi-6552 {f3 -} (NSData *)b dataForKey:b0 (NSString *)i defaultNamei0 tab Invokes b objectForKey:b0 with key i defaultNamei0 . Returns the corresponding value if it'27s an NSData object (according to the b isKindOfClass:b0 test) and b nilb0 otherwise.
fi-6552 fs16
fs28 fi-6552 {f3 -} (NSDictionary *)b dictionaryForKey:b0 (NSString *)i defaultName
s14 li7030 fi-6553 fi-5796 i0 tab Invokes b objectForKey:b0 with key i defaultNamei0 . Returns the corresponding value if it'27s an NSDictionary object (according to the b isKindOfClass:b0 test) and b nilb0 otherwise.
s13 li7029 fi-5794 fi-6552 fs16
fs28 fi-6552 {f3 -} (float)b floatForKey:b0 (NSString *)i defaultNamei0 tab Invokes b stringForKey:b0 with key i defaultNamei0 . Returns 0 if no string is returned. Otherwise, the resulting string is sent a b floatValueb0 message, which provides this method'27s return value.
fi-6552 fs16
fs28 fi-6552 {f3 -} (int)b integerForKey:b0 (NSString *)i defaultNamei0 tab Invokes b stringForKey:b0 with key i defaultNamei0 . Returns 0 if no string is returned. Otherwise, the resulting string is sent a b intValueb0 message, which provides this method'27s return value.
fi-6552 fs16
fs28 fi-6552 {f3 -} (id)b objectForKey:b0 (NSString *)i defaultNamei0 tab Returns the value of the first occurrence of the specified default, searching the domains included in the search list. Returns b nilb0 if the default isn'27t found.
fi-6552 fs16
fs28 fi-6552 {f3 -} (void)b removeObjectForKey:b0 (NSString *)i defaultName
s14 li7030 fi-6553 fi-5796 i0 tab Removes the value for the given default in the standard application domain. Removing a default has no effect on the value returned by the b objectForKey:b0 method if the same key exists in a domain that precedes the standard application domain in the search list.
s13 li7029 fi-5794 fi-6552 fs16
fs28 fi-6552 {f3 -} (void)b setBool:b0 (BOOL)i valuei0 tab Sets the value of the specified default to a string
s14 li7030 fi-6553 fi-5796 b forKey:b0 (NSString *)i defaultNamei0 tab tab representation of YES or NO, depending on i valuei0 . Invokes b setObject:forKey:b0 as part of its implementation.
s13 li7029 fi-5794 fi-6552 fs16
fs28 fi-6552 {f3 -} (void)b setFloat:b0 (float)i valuei0 tab Sets the value of the specified default to a string
s14 li7030 fi-6553 fi-5796 b forKey:b0 (NSString *)i defaultNamei0 tab tab representation of i valuei0 . Invokes b setObject:forKey:b0 as part of its implementation.
s13 li7029 fi-5794 fi-6552 fs16
fs28 fi-6552 {f3 -} (void)b setInteger:b0 (int)i valuei0 tab Sets the value of the specified default to a string
s14 li7030 fi-6553 fi-5796 b forKey:b0 (NSString *)i defaultNamei0 tab tab representation of i valuei0 . Invokes b setObject:forKey:b0 as part of its implementation.
s13 li7029 fi-5794 fi-6552 fs16
fs28 fi-6552 {f3 -} (void)b setObject:b0 (id)i valuei0 tab Sets the value of the specified default in the standard
s14 li7030 fi-6553 fi-5796 b forKey:b0 (NSString *)i defaultNamei0 tab tab application domain. Setting a default has no effect on the value returned by the b objectForKey:b0 method if the same key exists in a domain that precedes the application domain in the search list.
s13 li7029 fi-5794 fi-6552 fs16
fs28 fi-6552 {f3 -} (NSArray *)b stringArrayForKey:b0 (NSString *)i defaultName
s14 li7030 fi-6553 fi-5796 i0 tab Invokes b objectForKey:b0 with key i defaultNamei0 . Returns the corresponding value if it'27s an NSArray object containing NSStrings, and b nilb0 otherwise. The class of each object is determined using the b isKindOfClass:b0 test.
s13 li7029 fi-5794 fi-6552 fs16
fs28 fi-6552 {f3 -} (NSString *)b stringForKey:b0 (NSString *)i defaultName
s14 li7030 fi-6553 fi-5796 i0 tab Invokes b objectForKey:b0 with key i defaultNamei0 . Returns the corresponding value if it'27s an NSString object (according to the b isKindOfClass:b0 test) and b nilb0 otherwise.
pard s32 li100 fi0 ri1007 ql f0 b fs48
fs28 Initializing the User Defaults
fs14
fs28 pard s13 li7029 fi-6552 ri1007 ql tx6652 tx7030 f1 b0 fs2
fs28 fi-6552 {f3 -} (id)b initb0 tab Initializes defaults for the current user (who'27s identified by examining the environment). This method doesn'27t put anything in the search list. Invoke it only if you'27ve allocated your own NSUserDefaults object instead of using the shared one. Returns b selfb0 .
fi-6552 fs16
fs28 fi-6552 {f3 -} (id)b initWithUser:b0 (NSString *)i userNamei0 tab Like b initb0 , but initializes defaults for the specified user.
pard s32 li100 fi0 ri1007 ql f0 b fs48
fs28 Returning the Search List
fs14
fs28 pard s13 li7029 fi-6552 ri1007 ql tx6652 tx7030 f1 b0 fs2
fs28 fi-6552 {f3 -} (NSMutableArray *)b searchListb0 tab Returns a mutable array of domain names, signifying the domains that b objectForKey:b0 will search. You can customize the search list by modifying the array that'27s returned. Non-existent domain names in the list are ignored.
pard s32 li100 fi0 ri1007 ql f0 b fs48
fs28 Maintaining Persistent Domains
fs14
fs28 pard s13 li7029 fi-6552 ri1007 ql tx6652 tx7030 f1 b0 fs2
fs28 fi-6552 {f3 -} (NSDictionary *)b persistentDomainForName:b0 (NSString *)i domainName
s14 li7030 fi-6553 fi-5796 i0 tab 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.
s13 li7029 fi-5794 fi-6552 fs16
fs28 fi-6552 {f3 -} (NSArray *)b persistentDomainNamesb0 tab Returns an array containing the names of the persistent domains. Each domain can then be retrieved by invoking b persistentDomainForName:b0 .
fi-6552 fs16
fs28 fi-6552 {f3 -} (void)b removePersistentDomainForName:b0 (NSString *)i domainName
s14 li7030 fi-6553 fi-5796 i0 tab Removes the named persistent domain from the user'27s defaults. The first time that a persistent domain is changed after b synchronizeb0 , an NSUserDefaultsChanged notification is posted.
s13 li7029 fi-5794 fi-6552 fs16
fs28 fi-6552 {f3 -} (void)b setPersistentDomain:b0 (NSDictionary *)i domaini0
s14 li7030 fi-6553 fi-5796 b forName:b0 (NSString *)i domainNametab i0 Sets the dictionary for the persistent domain named i domainNamei0 ; raises an NSInvalidArgumentException if a volatile domain with i domainNamei0 already exists. The first time that a persistent domain is changed after b synchronizeb0 , an NSUserDefaultsChanged notification is posted.
s13 li7029 fi-5794 fi-6552 fs16
fs28 fi-6552 {f3 -} (BOOL)b synchronizeb0 tab 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 b synchronizeb0 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.
pard s32 li100 fi0 ri1007 ql f0 b fs48
fs28 Maintaining Volatile Domains
fs14
fs28 pard s13 li7029 fi-6552 ri1007 ql tx6652 tx7030 f1 b0 fs2
fs28 fi-6552 {f3 -} (void)b removeVolatileDomainForName:b0 (NSString *)i domainName
s14 li7030 fi-6553 fi-5796 i0 tab Removes the named volatile domain from the user'27s defaults.
s13 li7029 fi-5794 fi-6552 fs16
fs28 fi-6552 {f3 -} (void)b setVolatileDomain:b0 (NSDictionary *)i domaini0
s14 li7030 fi-6553 fi-5796 b forName:b0 (NSString *)i domainNametab i0 Sets the dictionary to i domaini0 for the volatile domain named i domainNamei0 . This method raises an NSInvalidArgumentException if a persistent domain with i domainNamei0 already exists.
s13 li7029 fi-5794 fi-6552 fs16
fs28 fi-6552 {f3 -} (NSDictionary *)b volatileDomainForName:b0 (NSString *)i domainName
s14 li7030 fi-6553 fi-5796 i0 tab 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.
s13 li7029 fi-5794 fi-6552 fs16
fs28 fi-6552 {f3 -} (NSArray *)b volatileDomainNamesb0 tab Returns an array containing the names of the volatile domains. Each domain can then be retrieved by calling b volatileDomainForName:b0 .
pard s32 li100 fi0 ri1007 ql f0 b fs48
fs28 Making Advanced Use of Defaults
fs14
fs28 pard s13 li7029 fi-6552 ri1007 ql tx6652 tx7030 f1 b0 fs2
fs28 fi-6552 {f3 -} (NSDictionary *)b dictionaryRepresentationb0 tab Returns a dictionary that contains a union of all key-value pairs in the domains in the search list. As with b objectForKey:b0 , key-value pairs in domains that are earlier in the search list take precedence. The combined result doesn'27t preserve information about which domain each entry came from.
fi-6552 fs16
fs28 fi-6552 {f3 -} (void)b registerDefaults:b0 (NSDictionary *)i dictionaryi0 tab
s14 li7030 fi-6553 fi-5796 tab Adds the contents of i dictionaryi0 to the registration domain. If there is no registration domain yet, it'27s created using i dictionaryi0 , and NSRegistrationDomain is added to the end of the search list.
}These are the contents of the former NiCE NeXT User Group NeXTSTEP/OpenStep software archive, currently hosted by Netfuture.ch.