/* Interface for for GNUStep Copyright (C) 1995, 1996 Free Software Foundation, Inc. Written by: Georg Tuparev, EMBL & Academia Naturalis, Heidelberg, Germany Tuparev@EMBL-Heidelberg.de This file is part of the GNUstep Base Library. This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public License for more details. You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02111 USA. */ #ifndef __NSUserDefaults_h_OBJECTS_INCLUDE #define __NSUserDefaults_h_OBJECTS_INCLUDE #include #include #include #if defined(__cplusplus) extern "C" { #endif @class NSArray; @class NSMutableArray; @class NSDictionary; @class NSMutableDictionary; @class NSData; @class NSTimer; @class NSRecursiveLock; @class NSDistributedLock; /* Standard domains */ /** * User defaults domain for process arguments. Command-line arguments * (attribute-value pairs, as in "-NSFoo bar") are placed into this domain. */ GS_EXPORT NSString* const NSArgumentDomain; /** * User defaults domain for system defaults. */ GS_EXPORT NSString* const NSGlobalDomain; /** * User defaults domain for application-registered "default defaults". */ GS_EXPORT NSString* const NSRegistrationDomain; #ifndef NO_GNUSTEP /** * User defaults domain for GNUstep config file and for any defaults * stored in the GlobalDefaults.plist file alongside the config file. */ GS_EXPORT NSString* const GSConfigDomain; #endif /* Public notification */ /** * Notification posted when a defaults synchronize has been performed (see * [NSUserDefaults-synchronize]) and changes have been loaded in from disk. */ GS_EXPORT NSString* const NSUserDefaultsDidChangeNotification; /* Backwards compatibility */ #define NSUserDefaultsChanged NSUserDefaultsDidChangeNotification /* Keys for language-dependent information */ /** Key for locale dictionary: names of days of week. */ GS_EXPORT NSString* const NSWeekDayNameArray; /** Key for locale dictionary: abbreviations of days of week. */ GS_EXPORT NSString* const NSShortWeekDayNameArray; /** Key for locale dictionary: names of months of year. */ GS_EXPORT NSString* const NSMonthNameArray; /** Key for locale dictionary: abbreviations of months of year. */ GS_EXPORT NSString* const NSShortMonthNameArray; /** Key for locale dictionary: format string for feeding to [NSDateFormatter].*/ GS_EXPORT NSString* const NSTimeFormatString; /** Key for locale dictionary: format string for feeding to [NSDateFormatter].*/ GS_EXPORT NSString* const NSDateFormatString; /** Key for locale dictionary: format string for feeding to [NSDateFormatter].*/ GS_EXPORT NSString* const NSShortDateFormatString; /** Key for locale dictionary: format string for feeding to [NSDateFormatter].*/ GS_EXPORT NSString* const NSTimeDateFormatString; /** Key for locale dictionary: format string for feeding to [NSDateFormatter].*/ GS_EXPORT NSString* const NSShortTimeDateFormatString; /** Key for locale dictionary: currency symbol. */ GS_EXPORT NSString* const NSCurrencySymbol; /** Key for locale dictionary: decimal separator. */ GS_EXPORT NSString* const NSDecimalSeparator; /** Key for locale dictionary: thousands separator. */ GS_EXPORT NSString* const NSThousandsSeparator; /** Key for locale dictionary: three-letter ISO 4217 currency abbreviation. */ GS_EXPORT NSString* const NSInternationalCurrencyString; /** Key for locale dictionary: text formatter string for monetary amounts. */ GS_EXPORT NSString* const NSCurrencyString; /** Key for locale dictionary: array of strings for 0-9. */ GS_EXPORT NSString* const NSDecimalDigits; /** Key for locale dictionary: array of strings for AM and PM. */ GS_EXPORT NSString* const NSAMPMDesignation; #if OS_API_VERSION(GSAPI_MACOSX, GSAPI_LAST) /** * Array of arrays of NSStrings, first member of each specifying a time, * followed by one or more colloquial names for the time, as in "(0, * midnight), (12, noon, lunch)". */ GS_EXPORT NSString* const NSHourNameDesignations; /** Strings for "year", "month", "week". */ GS_EXPORT NSString* const NSYearMonthWeekDesignations; /** Key for locale dictionary: adjectives that modify values in NSYearMonthWeekDesignations, as in "last", "previous", etc.. */ GS_EXPORT NSString* const NSEarlierTimeDesignations; /** Key for locale dictionary: adjectives that modify values in NSYearMonthWeekDesignations, as in "next", "subsequent", etc.. */ GS_EXPORT NSString* const NSLaterTimeDesignations; /** Key for locale dictionary: one or more strings designating the current day, such as "today". */ GS_EXPORT NSString* const NSThisDayDesignations; /** Key for locale dictionary: one or more strings designating the next day, such as "tomorrow". */ GS_EXPORT NSString* const NSNextDayDesignations; /** Key for locale dictionary: one or more strings designating the next day, such as "day after tomorrow". */ GS_EXPORT NSString* const NSNextNextDayDesignations; /** Key for locale dictionary: one or more strings designating the previous day, such as "yesterday". */ GS_EXPORT NSString* const NSPriorDayDesignations; /** Key for locale dictionary: string with 'Y', 'M', 'D', and 'H' designating the default method of writing dates, as in "MDYH" for the U.S.. */ GS_EXPORT NSString* const NSDateTimeOrdering; /** Key for locale dictionary: name of language. */ GS_EXPORT NSString* const NSLanguageName; /** Key for locale dictionary: two-letter ISO code. */ GS_EXPORT NSString* const NSLanguageCode; /** Key for locale dictionary: formal name of language. */ GS_EXPORT NSString* const NSFormalName; #ifndef NO_GNUSTEP /** Key for locale dictionary: name of locale. */ GS_EXPORT NSString* const GSLocale; #endif #endif /* General implementation notes: OpenStep spec currently is neither complete nor consistent. Therefore we had to make several implementation decisions which may vary in other OpenStep implementations. - We add a new instance method initWithFile: as a designated initialization method because it allows to create user defaults database from a "default user" and also it will work for various non-posix implementations. - We add two new class methods for getting and setting a list of user languages (userLanguages and setUserLanguages: ). They are somehow equivalent to the NS3.x Application's systemLanguages method. - Definition of argument (command line parameters) (-GSxxxx || --GSxxx) [value] Note: As far as I know, there is nothing like home directory for the M$ hell. God help the Win95/WinNT users of NSUserDefaults ;-) To Do: - polish & optimize; - when tested, fix NSBundle (the system languages stuff); - write docs : -( */ @interface NSUserDefaults : NSObject { #if GS_EXPOSE(NSUserDefaults) @private NSMutableArray *_searchList; // Current search list; NSMutableDictionary *_persDomains; // Contains persistent defaults info; NSMutableDictionary *_tempDomains; // Contains volatile defaults info; NSMutableArray *_changedDomains; /* ..after first time that persistent user defaults are changed */ NSDictionary *_dictionaryRep; // Cached dictionary representation NSString *_defaultsDatabase; NSDate *_lastSync; NSRecursiveLock *_lock; NSDistributedLock *_fileLock; void *_unused; #endif } /** * Returns the shared defaults object. If it doesn't exist yet, it's * created. The defaults are initialized for the current user. * The 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. */ + (NSUserDefaults*) standardUserDefaults; #if OS_API_VERSION(GSAPI_MACOSX, GSAPI_LAST) /** * Resets the shared user defaults object to reflect the current * user ID. Needed by setuid processes which change the user they * are running as.
* In GNUstep you should call GSSetUserName() when changing your * effective user ID, and that function will call this function for you. */ + (void) resetStandardUserDefaults; #endif #if OS_API_VERSION(GSAPI_NONE, GSAPI_NONE) /** * 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; /** * Sets the array of user languages preferences. Places the specified * array in the NSLanguages user default. */ + (void) setUserLanguages: (NSArray*)languages; #endif #if OS_API_VERSION(GSAPI_MACOSX, GSAPI_LAST) /** * Adds the domain names aName to the search list of the receiver.
* The domain is added after the application domain.
* Suites may be removed using the -removeSuiteNamed: method. */ - (void) addSuiteNamed: (NSString*)aName; #endif /** * 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; /** * Looks up a value for a specified default using -objectForKey: * and returns its boolean representation.
* Returns NO if it is not a boolean.
* The text 'yes' or 'true' or any non zero numeric value is considered * to be a boolean YES. Other string values are NO.
* NB. This differs slightly from the documented behavior for MacOS-X * (August 2002) in that the GNUstep version accepts the string 'TRUE' * as equivalent to 'YES'. */ - (BOOL) boolForKey: (NSString*)defaultName; /** * 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; /** * 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; /** * 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; /** * Initializes defaults for current user calling initWithUser: */ - (id) init; /** * Initializes defaults for the specified user calling -initWithContentsOfFile: */ - (id) initWithUser: (NSString*)userName; /** * * Initializes defaults for the specified path. Returns an object with * an empty search list. */ - (id) initWithContentsOfFile: (NSString*)path; // This is a new method /** * Looks up a value for a specified default using -objectForKey: * and returns its integer value or 0 if it is not representable * as an integer. */ - (NSInteger) integerForKey: (NSString*)defaultName; /** * 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; /** * Removes the default with the specified name from the application * domain. */ - (void) removeObjectForKey: (NSString*)defaultName; #if OS_API_VERSION(GSAPI_MACOSX, GSAPI_LAST) /** * Removes the named domain from the search list of the receiver.
* Suites may be added using the -addSuiteNamed: method. */ - (void) removeSuiteNamed: (NSString*)aName; #endif /** * Returns an array listing the domains searched in order to look up * a value in the defaults system. The order of the names in the * array is the order in which the domains are searched. */ - (NSArray*) searchList; /** * Sets a boolean value for defaultName in the application domain.
* Calls -setObject:forKey: to make the change by storing a string * containing either the word YES or NO. */ - (void) setBool: (BOOL)value forKey: (NSString*)defaultName; /** * Sets a float value for defaultName in the application domain.
* Calls -setObject:forKey: to make the change by storing a float * [NSNumber] instance. */ - (void) setFloat: (float)value forKey: (NSString*)defaultName; /** * Sets an integer value for defaultName in the application domain.
* Calls -setObject:forKey: to make the change by storing an intege * [NSNumber] instance. */ - (void) setInteger: (NSInteger)value forKey: (NSString*)defaultName; /** * Sets a copy of an object value for defaultName in the * application domain.
* The defaultName must be a non-empty string.
* The value to be copied into the domain must be an instance * of one of the [NSString-propertyList] classes.
*

Causes a NSUserDefaultsDidChangeNotification to be posted * if this is the first change to a persistent-domain since the * last -synchronize. *

* If value is nil, this is equivalent to the -removeObjectForKey: method. */ - (void) setObject: (id)value forKey: (NSString*)defaultName; /** * Sets the list of the domains searched in order to look up * a value in the defaults system. The order of the names in the * array is the order in which the domains are searched.
* On lookup, the first match is used. */ - (void) setSearchList: (NSArray*)newList; /** * 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; /** * 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; /** * Returns the persistent domain specified by domainName. */ - (NSDictionary*) persistentDomainForName: (NSString*)domainName; /** * Returns an array listing the name of all the persistent domains. */ - (NSArray*) persistentDomainNames; /** * 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; /** * Replaces the persistent-domain specified by domainName with * domain ... a dictionary containing keys and defaults values. *
Raises an NSInvalidArgumentException if domainName already * exists as a volatile-domain. *
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; /** * 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; /** * Removes the volatile domain specified by domainName from the * user defaults. */ - (void) removeVolatileDomainForName: (NSString*)domainName; /** * Sets the volatile-domain specified by domainName to * domain ... a dictionary containing keys and defaults values.
* Raises an NSInvalidArgumentException if domainName already * exists as either a volatile-domain or a persistent-domain. */ - (void) setVolatileDomain: (NSDictionary*)domain forName: (NSString*)domainName; /** * Returns the volatile domain specified by domainName. */ - (NSDictionary*) volatileDomainForName: (NSString*)domainName; /** * Returns an array listing the name of all the volatile domains. */ - (NSArray*) volatileDomainNames; /** * 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; /** * 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; @end #if defined(__cplusplus) } #endif #endif /* __NSUserDefaults_h_OBJECTS_INCLUDE */