X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/df693ed65cb3897397de903ddfc0318635eb5bd2..d3fa4bc22e84e3ca4d88cc1772f2d414140a1017:/interface/wx/config.h diff --git a/interface/wx/config.h b/interface/wx/config.h index 65a6c1d1a8..a5c930c7d3 100644 --- a/interface/wx/config.h +++ b/interface/wx/config.h @@ -3,13 +3,25 @@ // Purpose: interface of wxConfigBase // Author: wxWidgets team // RCS-ID: $Id$ -// Licence: wxWindows license +// Licence: wxWindows licence ///////////////////////////////////////////////////////////////////////////// + +// Flags for constructor style parameter +enum +{ + wxCONFIG_USE_LOCAL_FILE = 1, + wxCONFIG_USE_GLOBAL_FILE = 2, + wxCONFIG_USE_RELATIVE_PATH = 4, + wxCONFIG_USE_NO_ESCAPE_CHARACTERS = 8, + wxCONFIG_USE_SUBDIR = 16 +}; + + /** @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. @@ -240,21 +252,10 @@ 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{cfg} + + @see wxConfigPathChanger */ class wxConfigBase : public wxObject { @@ -312,7 +313,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 +353,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; @@ -369,11 +372,6 @@ public: /** 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 - @beginWxPerlOnly In wxPerl this method takes no parameters and returns a 3-element list (continue_flag, string, index_for_getnextentry). @@ -384,11 +382,6 @@ public: /** 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 - @beginWxPerlOnly In wxPerl this method takes no parameters and returns a 3-element list (continue_flag, string, index_for_getnextentry). @@ -399,11 +392,6 @@ public: /** 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 - @beginWxPerlOnly In wxPerl this method only takes the @a index parameter and returns a 3-element list (continue_flag, string, @@ -415,11 +403,6 @@ public: /** 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 - @beginWxPerlOnly In wxPerl this method only takes the @a index parameter and returns a 3-element list (continue_flag, string, @@ -592,8 +575,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 +586,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 +615,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 +757,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 +839,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 +885,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 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(); +}; +