X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/df693ed65cb3897397de903ddfc0318635eb5bd2..50d4763f1710f6e45ac6af7112d1ce9effe93bc4:/interface/wx/config.h diff --git a/interface/wx/config.h b/interface/wx/config.h index 65a6c1d1a8..9fcd26670d 100644 --- a/interface/wx/config.h +++ b/interface/wx/config.h @@ -3,13 +3,13 @@ // Purpose: interface of wxConfigBase // Author: wxWidgets team // RCS-ID: $Id$ -// Licence: wxWindows license +// Licence: wxWindows licence ///////////////////////////////////////////////////////////////////////////// /** @class wxConfigBase - wxConfigBase defines the basic interface of all config classes. It can not + wxConfigBase defines the basic interface of all config classes. It cannot be used by itself (it is an abstract base class) and you will always use one of its derivations: wxFileConfig, wxRegConfig or any other. @@ -255,6 +255,8 @@ @library{wxbase} @category{cfg} + + @see wxConfigPathChanger */ class wxConfigBase : public wxObject { @@ -312,7 +314,7 @@ public: @n The @c 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 @c wxCONFIG_USE_NO_ESCAPE_CHARACTERS style is used, it is is + that if @c wxCONFIG_USE_NO_ESCAPE_CHARACTERS style is used, it 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. @@ -352,7 +354,9 @@ public: /** 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. + doesn't exist, it is created. + + @see wxConfigPathChanger */ virtual void SetPath(const wxString& strPath) = 0; @@ -592,8 +596,7 @@ public: /** Reads a float value, returning @true if the value was found. - With the second overload, if the value was not found, @a defaultVal is - used instead. + If the value was not found, @a f is not changed. Notice that the value is read as a double but must be in a valid range for floats for the function to return @true. @@ -604,13 +607,25 @@ public: Not supported by wxPerl. @endWxPerlOnly */ - //@{ bool Read(const wxString& key, float* f) const; + /** + Reads a float value, returning @true if the value was found. + + If the value was not found, @a defaultVal is used instead. + + Notice that the value is read as a double but must be in a valid range + for floats for the function to return @true. + + @since 2.9.1 + + @beginWxPerlOnly + Not supported by wxPerl. + @endWxPerlOnly + */ bool Read(const wxString& key, float* f, float defaultVal) const; - //@} /** - Reads a float value, returning @true if the value was found. If the + Reads a boolean value, returning @true if the value was found. If the value was not found, @a b is not changed. @since 2.9.1 @@ -621,7 +636,7 @@ public: */ bool Read(const wxString& key, bool* b) const; /** - Reads a bool value, returning @true if the value was found. If the + Reads a boolean value, returning @true if the value was found. If the value was not found, @a defaultVal is used instead. @beginWxPerlOnly @@ -763,7 +778,7 @@ public: /** Delete the whole underlying object (disk file, registry key, ...). - Primarly for use by uninstallation routine. + Primarily for use by uninstallation routine. */ virtual bool DeleteAll() = 0; @@ -845,10 +860,26 @@ public: /** - 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. + Create a new config object and sets it as the current one. + + This function will create the most appropriate implementation of + wxConfig available for the current platform. By default this means that + the system registry will be used for storing the configuration + information under MSW and a file under the user home directory (see + wxStandardPaths::GetUserConfigDir()) elsewhere. + + If you prefer to use the configuration files everywhere, you can define + @c wxUSE_CONFIG_NATIVE to 0 when compiling wxWidgets. Or you can simply + always create wxFileConfig explicitly. + + Finally, if you want to create a custom wxConfig subclass you may + change this function behaviour by overriding wxAppTraits::CreateConfig() + to create it. An example when this could be useful could be an + application which could be installed either normally (in which case the + default behaviour of using wxRegConfig is appropriate) or in a + "portable" way in which case a wxFileConfig with a file in the program + directory would be used and the choice would be done in CreateConfig() + at run-time. */ static wxConfigBase* Create(); @@ -875,3 +906,79 @@ public: static wxConfigBase* Set(wxConfigBase* pConfig); }; + +/** + @class wxConfigPathChanger + + A handy little class which changes the current path in a wxConfig object and restores it in dtor. + Declaring a local variable of this type, it's possible to work in a specific directory + and ensure that the path is automatically restored when the function returns. + + For example: + @code + // this function loads somes settings from the given wxConfig object; + // the path selected inside it is left unchanged + bool LoadMySettings(wxConfigBase* cfg) + { + wxConfigPathChanger changer(cfg, "/Foo/Data/SomeString"); + wxString str; + if ( !config->Read("SomeString", &str) ) { + wxLogError("Couldn't read SomeString!"); + return false; + // NOTE: without wxConfigPathChanger it would be easy to forget to + // set the old path back into the wxConfig object before this return! + } + + // do something useful with SomeString... + + return true; // again: wxConfigPathChanger dtor will restore the original wxConfig path + } + @endcode + + @library{wxbase} + @category{cfg} +*/ +class WXDLLIMPEXP_BASE wxConfigPathChanger +{ +public: + + /** + Changes the path of the given wxConfigBase object so that the key @a strEntry is accessible + (for read or write). + + In other words, the ctor uses wxConfigBase::SetPath() with everything which precedes the + last slash of @a strEntry, so that: + @code + wxConfigPathChanger(wxConfigBase::Get(), "/MyProgram/SomeKeyName"); + @endcode + has the same effect of: + @code + wxConfigPathChanger(wxConfigBase::Get(), "/MyProgram/"); + @endcode + */ + wxConfigPathChanger(const wxConfigBase *pContainer, const wxString& strEntry); + + /** + Restores the path selected, inside the wxConfig object passed to the ctor, to the path which was + selected when the wxConfigPathChanger ctor was called. + */ + ~wxConfigPathChanger(); + + /** + Returns the name of the key which was passed to the ctor. + The "name" is just anything which follows the last slash of the string given to the ctor. + */ + const wxString& Name() const; + + /** + This method must be called if the original path inside the wxConfig object + (i.e. the current path at the moment of creation of this wxConfigPathChanger object) + could have been deleted, thus preventing wxConfigPathChanger from restoring the not + existing (any more) path. + + If the original path doesn't exist any more, the path will be restored to + the deepest still existing component of the old path. + */ + void UpdateIfDeleted(); +}; +