From 1151d3ab169b9fcb26a1b3b8ec79a5f3c1ea678e Mon Sep 17 00:00:00 2001 From: CaS Date: Wed, 2 Jan 2002 08:05:55 +0000 Subject: [PATCH] Improve documentation git-svn-id: svn+ssh://svn.gna.org/svn/gnustep/libs/base/trunk@11934 72102866-910b-0410-8b05-ffd578937521 --- Source/NSUserDefaults.m | 212 +++++++++++++++++++++++++++++++++++++--- 1 file changed, 197 insertions(+), 15 deletions(-) diff --git a/Source/NSUserDefaults.m b/Source/NSUserDefaults.m index a4d3e7b6d..9b680c838 100644 --- a/Source/NSUserDefaults.m +++ b/Source/NSUserDefaults.m @@ -107,10 +107,85 @@ static void updateCache(NSUserDefaults *self) - (void) __timerTicked: (NSTimer*)tim; @end +/** + *

+ * NSUserDefaults provides an interface to the defaults system, + * which allows an application access to global and/or application + * specific defualts set by the user. A particular instance of + * NSUserDefaults, standardUserDefaults, is provided as a + * convenience. Most of the information described below + * pertains to the standardUserDefaults. It is unlikely + * that you would want to instantiate your own userDefaults + * object, since it would not be set up in the same way as the + * standardUserDefaults. + *

+ *

+ * Defaults are managed based on domains. Certain + * domains, such as NSGlobalDomain, are + * persistant. These domains have defaults that are stored + * externally. Other domains are volitale. The defaults in + * these domains remain in effect only during the existance of + * the application and may in fact be different for + * applications running at the same time. When asking for a + * default value from standardUserDefaults, NSUserDefaults + * looks through the various domains in a particular order. + *

+ * + * NSArgumentDomain ... volatile + * + * Contains defaults read from the arguments provided + * to the application at startup. + * + * Application (name of the current process) ... persistent + * + * Contains application specific defaults, + * such as window positions. + * NSGlobalDomain ... persistent + * + * Global defaults applicable to all applications. + * + * Language (name based on users's language) ... volatile + * + * Constants that help with localization to the users's + * language. + * + * NSRegistrationDomain ... volatile + * + * Temporary defaults set up by the application. + * + * + *

+ * The NSLanguages default value is used to set up the + * constants for localization. GNUstep will also look for the + * LANGUAGES environment variable if it is not set + * in the defaults system. If it exists, it consists of an + * array of languages that the user prefers. At least one of + * the languages should have a corresponding localization file + * (typically located in the Languages directory + * of the GNUstep resources). + *

+ *

+ * As a special extension, on systems that support locales + * (e.g. GNU/Linux and Solaris), GNUstep will use information + * from the user specified locale, if the NSLanguages + * default value is not found. Typically the locale is + * specified in the environment with the LANG + * environment variable. + *

+ *

+ * The first change to a persistent domain after a -synchronize + * will cause an NSUserDefaultsDidChangeNotification to be posted + * (as will any change caused by reading new values from disk), + * so your application can keep track of changes made to the + * defaults by other software. + *

+ *

+ * NB. The GNUstep implementation differs from the Apple one in + * that it is thread-safe while Apples (as of MacOS-X 10.1) is not. + *

+ */ @implementation NSUserDefaults: NSObject -/************************************************************************* - *** Getting the Shared Instance - *************************************************************************/ + static BOOL setSharedDefaults = NO; /* Flag to prevent infinite recursion */ + (void) initialize @@ -132,6 +207,11 @@ static BOOL setSharedDefaults = NO; /* Flag to prevent infinite recursion */ } } +/** + * Resets the shared user defaults object to reflect the current + * user ID. Needed by setuid processes whiich change the user they + * are running as. + */ + (void) resetStandardUserDefaults { [classLock lock]; @@ -352,7 +432,12 @@ static BOOL setSharedDefaults = NO; /* Flag to prevent infinite recursion */ return AUTORELEASE(sharedDefaults); } - +/** + * Returns the array of user languages preferences. Uses the + * NSLanguages user default if available, otherwise + * tries to infer setup from operating system information etc + * (in particular, uses the LANGUAGES environment variable). + */ + (NSArray*) userLanguages { NSArray *currLang = nil; @@ -449,6 +534,10 @@ static BOOL setSharedDefaults = NO; /* Flag to prevent infinite recursion */ return AUTORELEASE(userLanguages); } +/** + * Sets the array of user languages preferences. Places the specified + * array in the NSLanguages user default. + */ + (void) setUserLanguages: (NSArray*)languages { NSMutableDictionary *globDict; @@ -652,9 +741,10 @@ static NSString *pathForUser(NSString *user) return desc; } -/************************************************************************* - *** Getting and Setting a Default - *************************************************************************/ +/** + * Looks up a value for a specified default using -objectForKey: + * and checks that it is an NSArray object. Returns nil if it is not. + */ - (NSArray*) arrayForKey: (NSString*)defaultName { id obj = [self objectForKey: defaultName]; @@ -664,6 +754,10 @@ static NSString *pathForUser(NSString *user) return nil; } +/** + * Looks up a value for a specified default using -objectForKey: + * and checks that it is a boolean. Returns NO if it is not. + */ - (BOOL) boolForKey: (NSString*)defaultName { id obj = [self stringForKey: defaultName]; @@ -673,6 +767,10 @@ static NSString *pathForUser(NSString *user) return NO; } +/** + * Looks up a value for a specified default using -objectForKey: + * and checks that it is an NSData object. Returns nil if it is not. + */ - (NSData*) dataForKey: (NSString*)defaultName { id obj = [self objectForKey: defaultName]; @@ -682,6 +780,10 @@ static NSString *pathForUser(NSString *user) return nil; } +/** + * Looks up a value for a specified default using -objectForKey: + * and checks that it is an NSDictionary object. Returns nil if it is not. + */ - (NSDictionary*) dictionaryForKey: (NSString*)defaultName { id obj = [self objectForKey: defaultName]; @@ -691,6 +793,10 @@ static NSString *pathForUser(NSString *user) return nil; } +/** + * Looks up a value for a specified default using -objectForKey: + * and checks that it is a float. Returns 0.0 if it is not. + */ - (float) floatForKey: (NSString*)defaultName { id obj = [self stringForKey: defaultName]; @@ -700,6 +806,10 @@ static NSString *pathForUser(NSString *user) return 0.0; } +/** + * Looks up a value for a specified default using -objectForKey: + * and checks that it is an integer. Returns 0 if it is not. + */ - (int) integerForKey: (NSString*)defaultName { id obj = [self stringForKey: defaultName]; @@ -709,6 +819,12 @@ static NSString *pathForUser(NSString *user) return 0; } +/** + * Looks up a value for a specified default using. + * The lookup is performed by accessing the domains in the order + * given in the search list. + *
Returns nil if defaultName cannot be found. + */ - (id) objectForKey: (NSString*)defaultName { NSEnumerator *enumerator; @@ -741,6 +857,10 @@ static NSString *pathForUser(NSString *user) return AUTORELEASE(object); } +/** + * Removes the default with the specified name from the application + * domain. + */ - (void) removeObjectForKey: (NSString*)defaultName { id obj; @@ -768,6 +888,10 @@ static NSString *pathForUser(NSString *user) return; } +/** + * Sets a boolean value for defaultName in the application domain. + *
Calls -setObject:forKey: to make the change. + */ - (void) setBool: (BOOL)value forKey: (NSString*)defaultName { id obj = (value)?@"YES": @"NO"; @@ -776,6 +900,10 @@ static NSString *pathForUser(NSString *user) return; } +/** + * Sets a float value for defaultName in the application domain. + *
Calls -setObject:forKey: to make the change. + */ - (void) setFloat: (float)value forKey: (NSString*)defaultName { char buf[32]; @@ -785,6 +913,10 @@ static NSString *pathForUser(NSString *user) return; } +/** + * Sets an integer value for defaultName in the application domain. + *
Calls -setObject:forKey: to make the change. + */ - (void) setInteger: (int)value forKey: (NSString*)defaultName { char buf[32]; @@ -794,6 +926,12 @@ static NSString *pathForUser(NSString *user) return; } +/** + * Sets an object value for defaultName in the application domain. + *
Causes a NSUserDefaultsDidChangeNotification to be posted + * if this is the first change to a persistent-domain since the + * last -synchronize. + */ - (void) setObject: (id)value forKey: (NSString*)defaultName { if (value && defaultName && ([defaultName length] > 0)) @@ -820,6 +958,10 @@ static NSString *pathForUser(NSString *user) return; } +/** + * Calls -arrayForKey: to get an array value for defaultName and checks + * that the array contents are string objects ... if not, returns nil. + */ - (NSArray*) stringArrayForKey: (NSString*)defaultName { id arr = [self arrayForKey: defaultName]; @@ -841,6 +983,10 @@ static NSString *pathForUser(NSString *user) return nil; } +/** + * Looks up a value for a specified default using -objectForKey: + * and checks that it is an NSString. Returns nil if it is not. + */ - (NSString*) stringForKey: (NSString*)defaultName { id obj = [self objectForKey: defaultName]; @@ -872,9 +1018,9 @@ static NSString *pathForUser(NSString *user) [_lock unlock]; } -/************************************************************************* - *** Maintaining Persistent Domains - *************************************************************************/ +/** + * Returns the persistent domain specified by domainName. + */ - (NSDictionary*) persistentDomainForName: (NSString*)domainName { NSDictionary *copy; @@ -885,6 +1031,9 @@ static NSString *pathForUser(NSString *user) return AUTORELEASE(copy); } +/** + * Returns an array listing the name of all the persistent domains. + */ - (NSArray*) persistentDomainNames { NSArray *keys; @@ -895,6 +1044,13 @@ static NSString *pathForUser(NSString *user) return keys; } +/** + * Removes the persistent domain specified by domainName from the + * user defaults. + *
Causes a NSUserDefaultsDidChangeNotification to be posted + * if this is the first change to a persistent-domain since the + * last -synchronize. + */ - (void) removePersistentDomainForName: (NSString*)domainName { [_lock lock]; @@ -907,6 +1063,13 @@ static NSString *pathForUser(NSString *user) return; } +/** + * Replaces the persistent-domain specified by domainname with + * domain ... a dictionary containing keys and defaults values. + *
Causes a NSUserDefaultsDidChangeNotification to be posted + * if this is the first change to a persistent-domain since the + * last -synchronize. + */ - (void) setPersistentDomain: (NSDictionary*)domain forName: (NSString*)domainName { @@ -929,6 +1092,13 @@ static NSString *pathForUser(NSString *user) return; } +/** + * Ensures that the in-memory and on-disk representations of the defaults + * are in sync. You may call this yourself, but probably don't need to + * since it is invoked at intervals whenever a runloop is running.
+ * If any persistent domain is changed by reading new values from disk, + * an NSUserDefaultsDidChangeNotification is posted. + */ - (BOOL) synchronize { NSFileManager *mgr = [NSFileManager defaultManager]; @@ -1090,7 +1260,7 @@ static NSString *pathForUser(NSString *user) updateCache(self); [[NSNotificationCenter defaultCenter] postNotificationName: NSUserDefaultsDidChangeNotification - object: nil]; + object: self]; } else { @@ -1146,6 +1316,9 @@ static NSString *pathForUser(NSString *user) return AUTORELEASE(copy); } +/** + * Returns an array listing the name of all the volatile domains. + */ - (NSArray*) volatileDomainNames { NSArray *keys; @@ -1156,9 +1329,11 @@ static NSString *pathForUser(NSString *user) return keys; } -/************************************************************************* - *** Making Advanced Use of Defaults - *************************************************************************/ +/** + * Returns a dictionary representing the current state of the defaults + * system ... this is a merged version of all the domains in the + * search list. + */ - (NSDictionary*) dictionaryRepresentation { NSDictionary *rep; @@ -1199,6 +1374,13 @@ static NSString *pathForUser(NSString *user) return AUTORELEASE(rep); } +/** + * Merges the contents of the dictionary newVals into the registration + * domain. Registration defaults may be added to or replaced using this + * method, but may never be removed. Thus, setting registration defaults + * at any point in your program guarantees that the defaults will be + * available thereafter. + */ - (void) registerDefaults: (NSDictionary*)newVals { NSMutableDictionary *regDefs; @@ -1355,7 +1537,7 @@ static NSString *pathForUser(NSString *user) updateCache(self); [[NSNotificationCenter defaultCenter] postNotificationName: NSUserDefaultsDidChangeNotification - object: nil]; + object: self]; } enumerator = [_changedDomains objectEnumerator];