X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/e54c96f187f46c06bd36be8cd52b35c19884aa2b..63b37a4e648320827a5b4a3161be13154370b5c3:/interface/config.h diff --git a/interface/config.h b/interface/config.h index d6630c659d..fe056247c8 100644 --- a/interface/config.h +++ b/interface/config.h @@ -10,26 +10,250 @@ @class wxConfigBase @wxheader{config.h} - wxConfigBase class defines the basic interface of all config classes. It can - not be used by itself (it is an abstract base class) and you will always use one - of its derivations: wxFileConfig, - wxRegConfig or any other. - - However, usually you don't even need to know the precise nature of the class - you're working with but you would just use the wxConfigBase methods. This - allows you to write the same code regardless of whether you're working with - the registry under Win32 or text-based config files under Unix (or even - Windows 3.1 .INI files if you're really unlucky). To make writing the portable - code even easier, wxWidgets provides a typedef wxConfig - which is mapped onto the native wxConfigBase implementation on the given - platform: i.e. wxRegConfig under Win32 and - wxFileConfig otherwise. - - See @ref overview_wxconfigoverview "config overview" for the descriptions of all - features of this class. - - It is highly recommended to use static functions @e Get() and/or @e Set(), - so please have a @ref overview_wxconfigstaticfunctions "look at them." + wxConfigBase defines the basic interface of all config classes. It can not + be used by itself (it is an abstract base class) and you will always use + one of its derivations: wxFileConfig, wxRegConfig or any other. + + However, usually you don't even need to know the precise nature of the + class you're working with but you would just use the wxConfigBase methods. + This allows you to write the same code regardless of whether you're working + with the registry under Win32 or text-based config files under Unix (or + even Windows 3.1 .INI files if you're really unlucky). To make writing the + portable code even easier, wxWidgets provides a typedef wxConfig which is + mapped onto the native wxConfigBase implementation on the given platform: + i.e. wxRegConfig under Win32 and wxFileConfig otherwise. + + See @ref overview_config for a description of all features of this class. + + It is highly recommended to use static functions Get() and/or Set(), so + please have a look at them. + + Related Include Files: + + @li @c - Let wxWidgets choose a wxConfig class for your + platform. + @li @c - Base config class. + @li @c - wxFileConfig class. + @li @c - wxRegConfig class. + + + @section configbase_example Example + + Here is how you would typically use this class: + + @code + // using wxConfig instead of writing wxFileConfig or wxRegConfig enhances + // portability of the code + wxConfig *config = new wxConfig("MyAppName"); + + wxString str; + if ( config->Read("LastPrompt", &str) ) { + // last prompt was found in the config file/registry and its value is + // now in str + // ... + } + else { + // no last prompt... + } + + // another example: using default values and the full path instead of just + // key name: if the key is not found , the value 17 is returned + long value = config->ReadLong("/LastRun/CalculatedValues/MaxValue", 17); + + // at the end of the program we would save everything back + config->Write("LastPrompt", str); + config->Write("/LastRun/CalculatedValues/MaxValue", value); + + // the changes will be written back automatically + delete config; + @endcode + + This basic example, of course, doesn't show all wxConfig features, such as + enumerating, testing for existence and deleting the entries and groups of + entries in the config file, its abilities to automatically store the + default values or expand the environment variables on the fly. However, the + main idea is that using this class is easy and that it should normally do + what you expect it to. + + @note In the documentation of this class, the words "config file" also mean + "registry hive" for wxRegConfig and, generally speaking, might mean + any physical storage where a wxConfigBase-derived class stores its + data. + + + @section configbase_static Static Functions + + The static functions provided deal with the "default" config object. + Although its usage is not at all mandatory it may be convenient to use a + global config object instead of creating and deleting the local config + objects each time you need one (especially because creating a wxFileConfig + object might be a time consuming operation). In this case, you may create + this global config object in the very start of the program and Set() it as + the default. Then, from anywhere in your program, you may access it using + the Get() function. This global wxConfig object will be deleted by + wxWidgets automatically if it exists. Note that this implies that if you do + delete this object yourself (usually in wxApp::OnExit()) you must use + Set(@NULL) to prevent wxWidgets from deleting it the second time. + + As it happens, you may even further simplify the procedure described above: + you may forget about calling Set(). When Get() is called and there is no + current object, it will create one using Create() function. To disable this + behaviour DontCreateOnDemand() is provided. + + @note You should use either Set() or Get() because wxWidgets library itself + would take advantage of it and could save various information in it. + For example wxFontMapper or Unix version of wxFileDialog have the + ability to use wxConfig class. + + + @section configbase_paths Path Management + + As explained in the @ref overview_config "config overview", the config + classes support a file system-like hierarchy of keys (files) and groups + (directories). As in the file system case, to specify a key in the config + class you must use a path to it. Config classes also support the notion of + the current group, which makes it possible to use the relative paths. To + clarify all this, here is an example (it is only for the sake of + demonstration, it doesn't do anything sensible!): + + @code + wxConfig *config = new wxConfig("FooBarApp"); + + // right now the current path is '/' + conf->Write("RootEntry", 1); + + // go to some other place: if the group(s) don't exist, they will be created + conf->SetPath("/Group/Subgroup"); + + // create an entry in subgroup + conf->Write("SubgroupEntry", 3); + + // '..' is understood + conf->Write("../GroupEntry", 2); + conf->SetPath(".."); + + wxASSERT( conf->ReadLong("Subgroup/SubgroupEntry", 0) == 3 ); + + // use absolute path: it is allowed, too + wxASSERT( conf->ReadLong("/RootEntry", 0) == 1 ); + @endcode + + It is highly recommended that you restore the path to its old value on + function exit: + + @code + void foo(wxConfigBase *config) + { + wxString strOldPath = config->GetPath(); + + config->SetPath("/Foo/Data"); + // ... + + config->SetPath(strOldPath); + } + @endcode + + Otherwise the assert in the following example will surely fail (we suppose + here that the foo() function is the same as above except that it doesn’t + save and restore the path): + + @code + void bar(wxConfigBase *config) + { + config->Write("Test", 17); + + foo(config); + + // we're reading "/Foo/Data/Test" here! -1 will probably be returned... + wxASSERT( config->ReadLong("Test", -1) == 17 ); + } + @endcode + + Finally, the path separator in wxConfigBase and derived classes is always + "/", regardless of the platform (i.e. it is not "\\" under Windows). + + + @section configbase_enumeration Enumeration + + The enumeration functions allow you to enumerate all entries and groups in + the config file. All functions here return @false when there are no more + items. + + You must pass the same index to GetNext() and GetFirst() (don't modify it). + Please note that it is not the index of the current item (you will have + some great surprises with wxRegConfig if you assume this) and you shouldn't + even look at it: it is just a "cookie" which stores the state of the + enumeration. It can't be stored inside the class because it would prevent + you from running several enumerations simultaneously, that's why you must + pass it explicitly. + + Having said all this, enumerating the config entries/groups is very simple: + + @code + wxConfigBase *config = ...; + wxArrayString aNames; + + // enumeration variables + wxString str; + long dummy; + + // first enum all entries + bool bCont = config->GetFirstEntry(str, dummy); + while ( bCont ) { + aNames.Add(str); + + bCont = GetConfig()->GetNextEntry(str, dummy); + } + + // ... we have all entry names in aNames... + + // now all groups... + bCont = GetConfig()->GetFirstGroup(str, dummy); + while ( bCont ) { + aNames.Add(str); + + bCont = GetConfig()->GetNextGroup(str, dummy); + } + + // ... we have all group (and entry) names in aNames... + @endcode + + There are also functions to get the number of entries/subgroups without + actually enumerating them, but you will probably never need them. + + + @section configbase_keyaccess Key Access + + The key access functions are the core of wxConfigBase class: they allow you + to read and write config file data. All Read() functions take a default + value which will be returned if the specified key is not found in the + config file. + + Currently, supported types of data are: wxString, @c long, @c double, + @c bool, wxColour and any other types for which the functions + wxToString() and wxFromString() are defined. + + Try not to read long values into string variables and vice versa: + although it just might work with wxFileConfig, you will get a system + error with wxRegConfig because in the Windows registry the different + types of entries are indeed used. + + Final remark: the @a szKey parameter for all these functions can + contain an arbitrary path (either relative or absolute), not just the + key name. + + @beginWxPythonOnly + In place of a single overloaded method name, wxPython implements the + following methods: + - Read(key, default="") - Returns a string. + - ReadInt(key, default=0) - Returns an integer. + - ReadFloat(key, default=0.0) - Returns a floating point number. + - ReadBool(key, default=0) - Returns a boolean. + - Write(key, value) - Writes a string. + - WriteInt(key, value) - Writes an int. + - WriteFloat(key, value) - Writes a floating point number. + @endWxPythonOnly + @library{wxbase} @category{misc} @@ -38,70 +262,67 @@ class wxConfigBase : public wxObject { public: /** - ) This is the default and only constructor of the wxConfigBase class, and derived classes. - + @param appName - The application name. If this is empty, the class will - normally use wxApp::GetAppName to set it. The - application name is used in the registry key on Windows, and can be used to - deduce the local filename parameter if that is missing. + The application name. If this is empty, the class will normally use + wxApp::GetAppName() to set it. The application name is used in the + registry key on Windows, and can be used to deduce the local + filename parameter if that is missing. @param vendorName - The vendor name. If this is empty, it is assumed that - no vendor name is wanted, if this is optional for the current config class. - The vendor name is appended to the application name for wxRegConfig. + The vendor name. If this is empty, it is assumed that no vendor + name is wanted, if this is optional for the current config class. + The vendor name is appended to the application name for + wxRegConfig. @param localFilename - Some config classes require a local filename. If this - is not present, but required, the application name will be used instead. + Some config classes require a local filename. If this is not + present, but required, the application name will be used instead. @param globalFilename - Some config classes require a global filename. If - this is not present, but required, the application name will be used - instead. + Some config classes require a global filename. If this is not + present, but required, the application name will be used instead. @param style - Can be one of wxCONFIG_USE_LOCAL_FILE and - wxCONFIG_USE_GLOBAL_FILE. The style interpretation depends on the config - class and is ignored by some implementations. For wxFileConfig, these styles - determine whether a local or global config file is created or used: if - wxCONFIG_USE_GLOBAL_FILE is used, then settings are read from the global - config file and if wxCONFIG_USE_LOCAL_FILE is used, settings are read from - and written to local config file (if they are both set, global file is read - first, then local file, overwriting global settings). If the - flag is present but the parameter is empty, the parameter will be set to a - default. If the parameter is present but the style flag not, the relevant - flag - will be added to the style. For wxRegConfig, thie GLOBAL flag refers to HKLM - key while LOCAL one is for the usual HKCU one. - For wxFileConfig you can also add wxCONFIG_USE_RELATIVE_PATH by logically - or'ing it to either of the _FILE options to tell wxFileConfig to use - relative - instead of absolute paths. - On non-VMS Unix systems, the default local configuration file is ~/.appname. - However, this path may be also used as user data directory - (see wxStandardPaths::GetUserDataDir) if - the application has several data files. In this case wxCONFIG_USE_SUBDIR - flag, which changes the default local configuration file to - ~/.appname/appname - should be used. Notice that this flag is ignored if localFilename is - provided. - @wxsince{2.8.2} - For wxFileConfig, you can also add wxCONFIG_USE_NO_ESCAPE_CHARACTERS which - will turn off character escaping for the values of entries stored in the - config - file: for example a foo key with some backslash characters will be stored - as foo=C:\mydir instead of the usual storage of - foo=C:\\mydir. - The wxCONFIG_USE_NO_ESCAPE_CHARACTERS style can be helpful if your config - file must be read or written to by a non-wxWidgets program (which might not - understand the escape characters). Note, however, that if - wxCONFIG_USE_NO_ESCAPE_CHARACTERS style is used, it is is now - your application's responsibility to ensure that there is no newline or - other illegal characters in a value, before writing that value to the file. + Can be one of wxCONFIG_USE_LOCAL_FILE and wxCONFIG_USE_GLOBAL_FILE. + The style interpretation depends on the config class and is ignored + by some implementations. For wxFileConfig, these styles determine + whether a local or global config file is created or used: if + wxCONFIG_USE_GLOBAL_FILE is used, then settings are read from the + global config file and if wxCONFIG_USE_LOCAL_FILE is used, settings + are read from and written to local config file (if they are both + set, global file is read first, then local file, overwriting global + settings). If the flag is present but the parameter is empty, the + parameter will be set to a default. If the parameter is present but + the style flag not, the relevant flag will be added to the style. + For wxRegConfig, thie GLOBAL flag refers to HKLM key while LOCAL + one is for the usual HKCU one. + @n For wxFileConfig you can also add wxCONFIG_USE_RELATIVE_PATH by + logically or'ing it to either of the _FILE options to tell + wxFileConfig to use relative instead of absolute paths. + @n On non-VMS Unix systems, the default local configuration file is + "~/.appname". However, this path may be also used as user data + directory (see wxStandardPaths::GetUserDataDir()) if the + application has several data files. In this case + wxCONFIG_USE_SUBDIR flag, which changes the default local + configuration file to "~/.appname/appname" should be used. Notice + that this flag is ignored if localFilename is provided. + wxCONFIG_USE_SUBDIR is new since wxWidgets version 2.8.2. + @n For wxFileConfig, you can also add + wxCONFIG_USE_NO_ESCAPE_CHARACTERS which will turn off character + escaping for the values of entries stored in the config file: for + example a foo key with some backslash characters will be stored as + "foo=C:\mydir" instead of the usual storage of "foo=C:\\mydir". + @n The wxCONFIG_USE_NO_ESCAPE_CHARACTERS style can be helpful if your + config file must be read or written to by a non-wxWidgets program + (which might not understand the escape characters). Note, however, + that if wxCONFIG_USE_NO_ESCAPE_CHARACTERS style is used, it is is + now your application's responsibility to ensure that there is no + newline or other illegal characters in a value, before writing that + value to the file. @param conv - This parameter is only used by wxFileConfig when compiled - in Unicode mode. It specifies the encoding in which the configuration file - is written. - + This parameter is only used by wxFileConfig when compiled in + Unicode mode. It specifies the encoding in which the configuration + file is written. + @remarks By default, environment variable expansion is on and recording defaults is off. */ @@ -109,472 +330,451 @@ public: const wxString& vendorName = wxEmptyString, const wxString& localFilename = wxEmptyString, const wxString& globalFilename = wxEmptyString, - long style = 0); + long style = 0, + const wxMBConv& conv = wxConvAuto()); /** Empty but ensures that dtor of all derived classes is virtual. */ ~wxConfigBase(); - /** - @ref ctor() wxConfigBase - - @ref dtor() ~wxConfigBase - */ - - - /** - Create a new config object: this function will create the "best" - implementation of wxConfig available for the current platform, see comments - near the definition of wxCONFIG_WIN32_NATIVE for details. It returns the - created object and also sets it as the current one. - */ - static wxConfigBase* Create(); - - /** - The functions in this section delete entries and/or groups of entries from the - config file. @e DeleteAll() is especially useful if you want to erase all - traces of your program presence: for example, when you uninstall it. - DeleteEntry() - - DeleteGroup() - - DeleteAll() - */ - - - /** - Delete the whole underlying object (disk file, registry key, ...). Primarly - for use by uninstallation routine. - */ - bool DeleteAll(); /** - Deletes the specified entry and the group it belongs to if it was the last key - in it and the second parameter is @true. - */ - bool DeleteEntry(const wxString& key, - bool bDeleteGroupIfEmpty = true); + @name Path Management - /** - Delete the group (with all subgroups). If the current path is under the group - being deleted it is changed to its deepest still existing component. E.g. if - the current path is @c /A/B/C/D and the group @c C is deleted the - path becomes @c /A/B. + See @ref configbase_paths */ - bool DeleteGroup(const wxString& key); + //@{ /** - Calling this function will prevent @e Get() from automatically creating a - new config object if the current one is @NULL. It might be useful to call it - near the program end to prevent "accidental" creation of a new config object. + Retrieve the current path (always as absolute path). */ - void DontCreateOnDemand(); + const wxString GetPath() const; /** - The functions in this section allow to enumerate all entries and groups in the - config file. All functions here return @false when there are no more items. - You must pass the same index to GetNext and GetFirst (don't modify it). - Please note that it is @b not the index of the current item (you will have - some great surprises with wxRegConfig if you assume this) and you shouldn't - even look at it: it is just a "cookie" which stores the state of the - enumeration. It can't be stored inside the class because it would prevent you - from running several enumerations simultaneously, that's why you must pass it - explicitly. - Having said all this, enumerating the config entries/groups is very simple: - - There are also functions to get the number of entries/subgroups without - actually enumerating them, but you will probably never need them. - GetFirstGroup() - - GetNextGroup() - - GetFirstEntry() - - GetNextEntry() - - GetNumberOfEntries() - - GetNumberOfGroups() + Set current path: if the first character is '/', it is the absolute + path, otherwise it is a relative path. '..' is supported. If @a strPath + doesn't exist it is created. */ + void SetPath(const wxString& strPath); + //@} - /** - returns @true if either a group or an entry with a given name exists - */ - bool Exists(wxString& strName) const; - - /** - permanently writes all changes (otherwise, they're only written from object's - destructor) - */ - bool Flush(bool bCurrentOnly = false); /** - Get the current config object. If there is no current object and - @a CreateOnDemand is @true, creates one - (using @e Create) unless DontCreateOnDemand was called previously. - */ - static wxConfigBase* Get(bool CreateOnDemand = true); + @name Enumeration - /** - Returns the application name. + See @ref configbase_enumeration */ - wxString GetAppName() const; - - /** - Returns the type of the given entry or @e Unknown if the entry doesn't - exist. This function should be used to decide which version of Read() should - be used because some of wxConfig implementations will complain about type - mismatch otherwise: e.g., an attempt to read a string value from an integer - key with wxRegConfig will fail. - The result is an element of enum EntryType: - */ - enum wxConfigBase::EntryType GetEntryType(const wxString& name) const; + //@{ /** Gets the first entry. + + @beginWxPythonOnly + The wxPython version of this method returns a 3-tuple consisting of the + continue flag, the value string, and the index for the next call. + @endWxPythonOnly */ bool GetFirstEntry(wxString& str, long& index) const; /** Gets the first group. + + @beginWxPythonOnly + The wxPython version of this method returns a 3-tuple consisting of the + continue flag, the value string, and the index for the next call. + @endWxPythonOnly */ bool GetFirstGroup(wxString& str, long& index) const; /** Gets the next entry. + + @beginWxPythonOnly + The wxPython version of this method returns a 3-tuple consisting of the + continue flag, the value string, and the index for the next call. + @endWxPythonOnly */ bool GetNextEntry(wxString& str, long& index) const; /** Gets the next group. + + @beginWxPythonOnly + The wxPython version of this method returns a 3-tuple consisting of the + continue flag, the value string, and the index for the next call. + @endWxPythonOnly */ bool GetNextGroup(wxString& str, long& index) const; /** - + Get number of entries in the current group. */ uint GetNumberOfEntries(bool bRecursive = false) const; /** - Get number of entries/subgroups in the current group, with or without its - subgroups. + Get number of entries/subgroups in the current group, with or without + its subgroups. */ uint GetNumberOfGroups(bool bRecursive = false) const; + //@} + + + enum EntryType + { + Type_Unknown, + Type_String, + Type_Boolean, + Type_Integer, + Type_Float + }; + /** - Retrieve the current path (always as absolute path). + @name Tests of Existence */ - const wxString GetPath() const; + //@{ /** - Returns the vendor name. + @return @true if either a group or an entry with a given name exists. */ - wxString GetVendorName() const; + bool Exists(wxString& strName) const; + + /** + Returns the type of the given entry or @e Unknown if the entry doesn't + exist. This function should be used to decide which version of Read() + should be used because some of wxConfig implementations will complain + about type mismatch otherwise: e.g., an attempt to read a string value + from an integer key with wxRegConfig will fail. + */ + wxConfigBase::EntryType GetEntryType(const wxString& name) const; /** - returns @true if the entry by this name exists + @return @true if the entry by this name exists. */ bool HasEntry(wxString& strName) const; /** - returns @true if the group by this name exists + @return @true if the group by this name exists. */ bool HasGroup(const wxString& strName) const; + //@} + + /** - Returns @true if we are expanding environment variables in key values. + @name Miscellaneous Functions */ - bool IsExpandingEnvVars() const; + //@{ /** - Returns @true if we are writing defaults back to the config file. + Returns the application name. */ - bool IsRecordingDefaults() const; + wxString GetAppName() const; /** - These function are the core of wxConfigBase class: they allow you to read and - write config file data. All @e Read function take a default value which - will be returned if the specified key is not found in the config file. - Currently, supported types of data are: - wxString, @e long, @e double, @e bool, - wxColour and any other types, - for which functions wxToString() - and wxFromString() are defined. - Try not to read long values into string variables and vice versa: although it - just might work with wxFileConfig, you will get a system error with - wxRegConfig because in the Windows registry the different types of entries are - indeed used. - Final remark: the @e szKey parameter for all these functions can contain an - arbitrary path (either relative or absolute), not just the key name. - Read() - - Write() - - Flush() - */ - - - /** - GetAppName() - - GetVendorName() - - wxFileConfig::SetUmask - */ - - - /** - Some aspects of wxConfigBase behaviour can be changed during run-time. The - first of them is the expansion of environment variables in the string values - read from the config file: for example, if you have the following in your - config file: - - the call to @c config-Read("UserData") will return something like - @c "/home/zeitlin/data" if you're lucky enough to run a Linux system ;-) - Although this feature is very useful, it may be annoying if you read a value - which containts '$' or '%' symbols (% is used for environment variables - expansion under Windows) which are not used for environment variable - expansion. In this situation you may call SetExpandEnvVars(@false) just before - reading this value and SetExpandEnvVars(@true) just after. Another solution - would be to prefix the offending symbols with a backslash. - The following functions control this option: - IsExpandingEnvVars() - - SetExpandEnvVars() - - SetRecordDefaults() - - IsRecordingDefaults() - */ - - - /** - As explained in @ref overview_wxconfigoverview "config overview", the config - classes - support a file system-like hierarchy of keys (files) and groups (directories). - As in the file system case, to specify a key in the config class you must use - a path to it. Config classes also support the notion of the current group, - which makes it possible to use the relative paths. To clarify all this, here - is an example (it is only for the sake of demonstration, it doesn't do anything - sensible!): - - @e Warning: it is probably a good idea to always restore the path to its - old value on function exit: - - because otherwise the assert in the following example will surely fail - (we suppose here that @e foo() function is the same as above except that it - doesn't save and restore the path): - - Finally, the path separator in wxConfigBase and derived classes is always '/', - regardless of the platform (i.e. it is @b not '\\' under Windows). - SetPath() - - GetPath() + Returns the vendor name. */ + wxString GetVendorName() const; + + //@} + + /** + @name Key Access + See @ref configbase_keyaccess + */ //@{ + + /** + Permanently writes all changes (otherwise, they're only written from + object's destructor). + */ + bool Flush(bool bCurrentOnly = false); + /** - Reads a value of type T, for which function - wxFromString() is defined, - returning @true if the value was found. - If the value was not found, @a defaultVal is used instead. - bool Read(const wxStringkey, T* value) const; - - - @b Read(key, default="") - - Returns a string - - @b ReadInt(key, default=0) - - Returns an integer - - @b ReadFloat(key, default=0.0) - - Returns a floating point number - - @b ReadBool(key, default=0) - - Returns a boolean + Read a string from the key, returning @true if the value was read. If + the key was not found, @a str is not changed. */ bool Read(const wxString& key, wxString* str) const; + /** + Read a string from the key. The default value is returned if the key + was not found. + + @return @true if value was really read, @false if the default was used. + */ const bool Read(const wxString& key, wxString* str, - const wxString& defaultVal) const; - const wxString Read(const wxString& key, - const - wxString& defaultVal) const; + const wxString& defaultVal) const; + /** + Another version of Read(), returning the string value directly. + */ + const wxString Read(const wxString& key, + const wxString& defaultVal) const; + /** + Reads a long value, returning @true if the value was found. If the + value was not found, @a l is not changed. + */ const bool Read(const wxString& key, long* l) const; + /** + Reads a long value, returning @true if the value was found. If the + value was not found, @a defaultVal is used instead. + */ const bool Read(const wxString& key, long* l, long defaultVal) const; + /** + Reads a double value, returning @true if the value was found. If the + value was not found, @a d is not changed. + */ const bool Read(const wxString& key, double* d) const; + /** + Reads a double value, returning @true if the value was found. If the + value was not found, @a defaultVal is used instead. + */ const bool Read(const wxString& key, double* d, - double defaultVal) const; + double defaultVal) const; + /** + Reads a bool value, returning @true if the value was found. If the + value was not found, @a b is not changed. + */ const bool Read(const wxString& key, bool* b) const; + /** + Reads a bool value, returning @true if the value was found. If the + value was not found, @a defaultVal is used instead. + */ const bool Read(const wxString& key, bool* d, - bool defaultVal) const; + bool defaultVal) const; + /** + Reads a binary block, returning @true if the value was found. If the + value was not found, @a buf is not changed. + */ const bool Read(const wxString& key, wxMemoryBuffer* buf) const; + /** + Reads a value of type T, for which function wxFromString() is defined, + returning @true if the value was found. If the value was not found, + @a value is not changed. + */ const bool Read(const wxString& key, T* value) const; + /** + Reads a value of type T, for which function wxFromString() is defined, + returning @true if the value was found. If the value was not found, + @a defaultVal is used instead. + */ const bool Read(const wxString& key, T* value, - T const& defaultVal) const; - //@} + const T& defaultVal) const; /** - Reads a bool value from the key and returns it. @a defaultVal is returned - if the key is not found. + Reads a bool value from the key and returns it. @a defaultVal is + returned if the key is not found. */ long ReadBool(const wxString& key, bool defaultVal) const; /** - Reads a double value from the key and returns it. @a defaultVal is returned - if the key is not found. + Reads a double value from the key and returns it. @a defaultVal is + returned if the key is not found. */ long ReadDouble(const wxString& key, double defaultVal) const; /** - Reads a long value from the key and returns it. @a defaultVal is returned - if the key is not found. + Reads a long value from the key and returns it. @a defaultVal is + returned if the key is not found. */ long ReadLong(const wxString& key, long defaultVal) const; /** - Reads a value of type T, for which function - wxFromString() is defined, from the key and returns it. - @a defaultVal is returned if the key is not found. + Reads a value of type T (for which the function wxFromString() must be + defined) from the key and returns it. @a defaultVal is returned if the + key is not found. */ T ReadObject(const wxString& key, T const& defaultVal) const; /** - The functions in this section allow to rename entries or subgroups of the - current group. They will return @false on error. typically because either the - entry/group with the original name doesn't exist, because the entry/group with - the new name already exists or because the function is not supported in this - wxConfig implementation. - RenameEntry() - - RenameGroup() + Writes the wxString value to the config file and returns @true on + success. + */ + bool Write(const wxString& key, const wxString& value); + /** + Writes the long value to the config file and returns @true on success. + */ + bool Write(const wxString& key, long value); + /** + Writes the double value to the config file and returns @true on + success. + */ + bool Write(const wxString& key, double value); + /** + Writes the bool value to the config file and returns @true on success. */ + bool Write(const wxString& key, bool value); + /** + Writes the wxMemoryBuffer value to the config file and returns @true on + success. + */ + bool Write(const wxString& key, const wxMemoryBuffer& buf); + /** + Writes the specified value to the config file and returns @true on + success. The function wxToString() must be defined for type @e T. + */ + bool Write(const wxString& key, T const& buf); + + //@} /** - Renames an entry in the current group. The entries names (both the old and - the new one) shouldn't contain backslashes, i.e. only simple names and not - arbitrary paths are accepted by this function. - Returns @false if @a oldName doesn't exist or if @a newName already - exists. + @name Rename Entries/Groups + + These functions allow renaming entries or subgroups of the current + group. They will return @false on error, typically because either the + entry/group with the original name doesn't exist, because the + entry/group with the new name already exists or because the function is + not supported in this wxConfig implementation. */ - bool RenameEntry(const wxString& oldName, - const wxString& newName); + //@{ /** - Renames a subgroup of the current group. The subgroup names (both the old and - the new one) shouldn't contain backslashes, i.e. only simple names and not - arbitrary paths are accepted by this function. - Returns @false if @a oldName doesn't exist or if @a newName already - exists. + Renames an entry in the current group. The entries names (both the old + and the new one) shouldn't contain backslashes, i.e. only simple names + and not arbitrary paths are accepted by this function. + + @return @false if @a oldName doesn't exist or if @a newName already + exists. */ - bool RenameGroup(const wxString& oldName, - const wxString& newName); + bool RenameEntry(const wxString& oldName, const wxString& newName); /** - Sets the config object as the current one, returns the pointer to the previous - current object (both the parameter and returned value may be @NULL) + Renames a subgroup of the current group. The subgroup names (both the + old and the new one) shouldn't contain backslashes, i.e. only simple + names and not arbitrary paths are accepted by this function. + + @return @false if @a oldName doesn't exist or if @a newName already + exists. */ - static wxConfigBase* Set(wxConfigBase* pConfig); + bool RenameGroup(const wxString& oldName, const wxString& newName); + + //@} + /** - Determine whether we wish to expand environment variables in key values. + @name Delete Entries/Groups + + These functions delete entries and/or groups of entries from the config + file. DeleteAll() is especially useful if you want to erase all traces + of your program presence: for example, when you uninstall it. */ - void SetExpandEnvVars(bool bDoIt = true); + //@{ /** - Set current path: if the first character is '/', it is the absolute path, - otherwise it is a relative path. '..' is supported. If strPath doesn't - exist it is created. + Delete the whole underlying object (disk file, registry key, ...). + Primarly for use by uninstallation routine. */ - void SetPath(const wxString& strPath); + bool DeleteAll(); /** - Sets whether defaults are recorded to the config file whenever an attempt to - read the value which is not present in it is done. - If on (default is off) all default values for the settings used by the program - are written back to the config file. This allows the user to see what config - options may be changed and is probably useful only for wxFileConfig. + Deletes the specified entry and the group it belongs to if it was the + last key in it and the second parameter is @true. */ - void SetRecordDefaults(bool bDoIt = true); + bool DeleteEntry(const wxString& key, + bool bDeleteGroupIfEmpty = true); /** - These functions deal with the "default" config object. Although its usage is - not at all mandatory it may be convenient to use a global config object - instead of creating and deleting the local config objects each time you need - one (especially because creating a wxFileConfig object might be a time - consuming operation). In this case, you may create this global config object - in the very start of the program and @e Set() it as the default. Then, from - anywhere in your program, you may access it using the @e Get() function. - This global wxConfig object will be deleted by wxWidgets automatically if it - exists. Note that this implies that if you do delete this object yourself - (usually in wxApp::OnExit) you must use @e Set(@NULL) - to prevent wxWidgets from deleting it the second time. - As it happens, you may even further simplify the procedure described above: - you may forget about calling @e Set(). When @e Get() is called and there - is no current object, it will create one using @e Create() function. To - disable this behaviour @e DontCreateOnDemand() is provided. - @b Note: You should use either @e Set() or @e Get() because wxWidgets - library itself would take advantage of it and could save various information - in it. For example wxFontMapper or Unix version - of wxFileDialog have the ability to use wxConfig class. - Set() - - Get() - - Create() - - DontCreateOnDemand() - */ - - - /** - HasGroup() - - HasEntry() - - Exists() - - GetEntryType() + Delete the group (with all subgroups). If the current path is under the + group being deleted it is changed to its deepest still existing + component. E.g. if the current path is @c "/A/B/C/D" and the group @c C + is deleted, the path becomes @c "/A/B". */ + bool DeleteGroup(const wxString& key); + + //@} + + + /** + @name Options + Some aspects of wxConfigBase behaviour can be changed during run-time. + The first of them is the expansion of environment variables in the + string values read from the config file: for example, if you have the + following in your config file: + @code + # config file for my program + UserData = $HOME/data + + # the following syntax is valud only under Windows + UserData = %windir%\\data.dat + @endcode + + The call to Read("UserData") will return something like + @c "/home/zeitlin/data" on linux for example. + + Although this feature is very useful, it may be annoying if you read a + value which containts '$' or '%' symbols (% is used for environment + variables expansion under Windows) which are not used for environment + variable expansion. In this situation you may call + SetExpandEnvVars(@false) just before reading this value and + SetExpandEnvVars(@true) just after. Another solution would be to prefix + the offending symbols with a backslash. + */ //@{ + /** - These functions write the specified value to the config file and return @true - on success. In the last one, function wxToString() must be - defined for type @e T. - - - @b Write(key, value) - - Writes a string - - @b WriteInt(key, value) - - Writes an integer - - @b WriteFloat(key, value) - - Writes a floating point number - - @b WriteBool(key, value) - - Writes a boolean + Returns @true if we are expanding environment variables in key values. */ - bool Write(const wxString& key, const wxString& value); - bool Write(const wxString& key, long value); - bool Write(const wxString& key, double value); - bool Write(const wxString& key, bool value); - bool Write(const wxString& key, const wxMemoryBuffer& buf); - bool Write(const wxString& key, const T& buf); + bool IsExpandingEnvVars() const; + + /** + Returns @true if we are writing defaults back to the config file. + */ + bool IsRecordingDefaults() const; + + /** + Determine whether we wish to expand environment variables in key + values. + */ + void SetExpandEnvVars(bool bDoIt = true); + + /** + Sets whether defaults are recorded to the config file whenever an + attempt to read the value which is not present in it is done. + + If on (default is off) all default values for the settings used by the + program are written back to the config file. This allows the user to + see what config options may be changed and is probably useful only for + wxFileConfig. + */ + void SetRecordDefaults(bool bDoIt = true); + //@} + + + /** + Create a new config object: this function will create the "best" + implementation of wxConfig available for the current platform, see + comments near the definition of wxCONFIG_WIN32_NATIVE for details. It + returns the created object and also sets it as the current one. + */ + static wxConfigBase* Create(); + + /** + Calling this function will prevent @e Get() from automatically creating + a new config object if the current one is @NULL. It might be useful to + call it near the program end to prevent "accidental" creation of a new + config object. + */ + static void DontCreateOnDemand(); + + /** + Get the current config object. If there is no current object and + @a CreateOnDemand is @true, this creates one (using Create()) unless + DontCreateOnDemand() was called previously. + */ + static wxConfigBase* Get(bool CreateOnDemand = true); + + /** + Sets the config object as the current one, returns the pointer to the + previous current object (both the parameter and returned value may be + @NULL). + */ + static wxConfigBase* Set(wxConfigBase* pConfig); };