// Name: config.h
// 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.
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.
+ with the registry under Windows or text-based config files under Unix.
+ 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 Windows and wxFileConfig otherwise.
See @ref overview_config for a description of all features of this class.
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}
+ @category{cfg}
+
+ @see wxConfigPathChanger
*/
class wxConfigBase : public wxObject
{
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
+ Can be one of @c wxCONFIG_USE_LOCAL_FILE and @c wxCONFIG_USE_GLOBAL_FILE.
+ @n 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
+ @c wxCONFIG_USE_GLOBAL_FILE is used, then settings are read from the
+ global config file and if @c 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
+ For wxRegConfig, the GLOBAL flag refers to the @c HKLM key while LOCAL
+ one is for the usual @c HKCU one.
+ @n For wxFileConfig you can also add @c 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
+ @c 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.
+ that this flag is ignored if @a localFilename is provided.
+ @c 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
+ @c 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
+ @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 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).
+ @endWxPerlOnly
*/
virtual bool GetFirstEntry(wxString& str, long& index) const = 0;
/**
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).
+ @endWxPerlOnly
*/
virtual bool GetFirstGroup(wxString& str, long& index) const = 0;
/**
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,
+ index_for_getnextentry).
+ @endWxPerlOnly
*/
virtual bool GetNextEntry(wxString& str, long& index) const = 0;
/**
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,
+ index_for_getnextentry).
+ @endWxPerlOnly
*/
virtual bool GetNextGroup(wxString& str, long& index) const = 0;
/**
Read a string from the key, returning @true if the value was read. If
the key was not found, @a str is not changed.
+
+ @beginWxPerlOnly
+ Not supported by wxPerl.
+ @endWxPerlOnly
*/
bool Read(const wxString& key, wxString* str) const;
/**
was not found.
@return @true if value was really read, @false if the default was used.
+
+ @beginWxPerlOnly
+ Not supported by wxPerl.
+ @endWxPerlOnly
*/
bool Read(const wxString& key, wxString* str,
const wxString& defaultVal) const;
/**
Another version of Read(), returning the string value directly.
+
+ @beginWxPerlOnly
+ In wxPerl, this can be called as:
+ - Read(key): returns the empty string if no key is found
+ - Read(key, default): returns the default value if no key is found
+ @endWxPerlOnly
*/
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.
+
+ @beginWxPerlOnly
+ Not supported by wxPerl.
+ @endWxPerlOnly
*/
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.
+
+ @beginWxPerlOnly
+ In wxPerl, this can be called as:
+ - ReadInt(key): returns the 0 if no key is found
+ - ReadInt(key, default): returns the default value if no key is found
+ @endWxPerlOnly
*/
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.
+
+ @beginWxPerlOnly
+ Not supported by wxPerl.
+ @endWxPerlOnly
*/
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.
+
+ @beginWxPerlOnly
+ In wxPerl, this can be called as:
+ - ReadFloat(key): returns the 0.0 if no key is found
+ - ReadFloat(key, default): returns the default value if no key is found
+ @endWxPerlOnly
*/
bool Read(const wxString& key, double* d,
double defaultVal) const;
+
/**
- Reads a bool value, returning @true if the value was found. If the
+ Reads a float value, returning @true if the value was found.
+
+ 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.
+
+ @since 2.9.1
+
+ @beginWxPerlOnly
+ 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 boolean value, returning @true if the value was found. If the
value was not found, @a b is not changed.
+
+ @since 2.9.1
+
+ @beginWxPerlOnly
+ Not supported by wxPerl.
+ @endWxPerlOnly
*/
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
+ In wxPerl, this can be called as:
+ - ReadBool(key): returns false if no key is found
+ - ReadBool(key, default): returns the default value if no key is found
+ @endWxPerlOnly
*/
bool Read(const wxString& key, bool* d,
bool defaultVal) const;
/**
Writes the double value to the config file and returns @true on
success.
+
+ Notice that if floating point numbers are saved as strings (as is the
+ case with the configuration files used by wxFileConfig), this function
+ uses the C locale for writing out the number, i.e. it will always use a
+ period as the decimal separator, irrespectively of the current locale.
+ This behaviour is new since wxWidgets 2.9.1 as the current locale was
+ used before, but the change should be transparent because both C and
+ current locales are tried when reading the numbers back.
*/
bool Write(const wxString& key, double value);
/**
/**
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;
# config file for my program
UserData = $HOME/data
- # the following syntax is valud only under Windows
+ # the following syntax is valid only under Windows
UserData = %windir%\\data.dat
@endcode
/**
- 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