// 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.
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
{
@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.
/**
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;
/**
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).
/**
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).
/**
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,
/**
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,
/**
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.
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
*/
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
/**
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;
/**
- 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();
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();
+};
+
projects / wxWidgets.git / blobdiff