/////////////////////////////////////////////////////////////////////////////
// Name: config.h
-// Purpose: documentation for wxConfigBase class
+// Purpose: interface of wxConfigBase
// Author: wxWidgets team
// RCS-ID: $Id$
// Licence: wxWindows license
)
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
flag, which changes the default local configuration file to
~/.appname/appname
should be used. Notice that this flag is ignored if localFilename is
- provided. This function is new since wxWidgets version 2.8.2
+ 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
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.
*/
/**
@ref ctor() wxConfigBase
-
+
@ref dtor() ~wxConfigBase
*/
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()
*/
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()
*/
/**
returns @true if either a group or an entry with a given name exists
*/
- bool Exists(wxString& strName);
+ bool Exists(wxString& strName) const;
/**
permanently writes all changes (otherwise, they're only written from object's
/**
Returns the application name.
*/
- wxString GetAppName();
+ wxString GetAppName() const;
/**
Returns the type of the given entry or @e Unknown if the entry doesn't
key with wxRegConfig will fail.
The result is an element of enum EntryType:
*/
- enum wxConfigBase::EntryType GetEntryType(const wxString& name);
+ enum wxConfigBase::EntryType GetEntryType(const wxString& name) const;
/**
Gets the first entry.
*/
- bool GetFirstEntry(wxString& str, long& index);
+ bool GetFirstEntry(wxString& str, long& index) const;
/**
Gets the first group.
*/
- bool GetFirstGroup(wxString& str, long& index);
+ bool GetFirstGroup(wxString& str, long& index) const;
/**
Gets the next entry.
*/
- bool GetNextEntry(wxString& str, long& index);
+ bool GetNextEntry(wxString& str, long& index) const;
/**
Gets the next group.
*/
- bool GetNextGroup(wxString& str, long& index);
+ bool GetNextGroup(wxString& str, long& index) const;
/**
-
+
*/
- uint GetNumberOfEntries(bool bRecursive = false);
+ uint GetNumberOfEntries(bool bRecursive = false) const;
/**
Get number of entries/subgroups in the current group, with or without its
subgroups.
*/
- uint GetNumberOfGroups(bool bRecursive = false);
+ uint GetNumberOfGroups(bool bRecursive = false) const;
/**
Retrieve the current path (always as absolute path).
*/
- const wxString GetPath();
+ const wxString GetPath() const;
/**
Returns the vendor name.
*/
- wxString GetVendorName();
+ wxString GetVendorName() const;
/**
returns @true if the entry by this name exists
*/
- bool HasEntry(wxString& strName);
+ bool HasEntry(wxString& strName) const;
/**
returns @true if the group by this name exists
*/
- bool HasGroup(const wxString& strName);
+ bool HasGroup(const wxString& strName) const;
/**
Returns @true if we are expanding environment variables in key values.
*/
- bool IsExpandingEnvVars();
+ bool IsExpandingEnvVars() const;
/**
Returns @true if we are writing defaults back to the config file.
*/
- bool IsRecordingDefaults();
+ bool IsRecordingDefaults() const;
/**
These function are the core of wxConfigBase class: they allow you to read and
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.
+ 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
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
*/
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
would be to prefix the offending symbols with a backslash.
The following functions control this option:
IsExpandingEnvVars()
-
+
SetExpandEnvVars()
-
+
SetRecordDefaults()
-
+
IsRecordingDefaults()
*/
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()
*/
//@{
/**
Reads a value of type T, for which function
- wxFromString is defined,
+ 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
*/
- bool Read(const wxString& key, wxString* str);
- bool Read(const wxString& key, wxString* str,
- const wxString& defaultVal);
- wxString Read(const wxString& key,
- const
- wxString& defaultVal);
- bool Read(const wxString& key, long* l);
- bool Read(const wxString& key, long* l, long defaultVal);
- bool Read(const wxString& key, double* d);
- bool Read(const wxString& key, double* d, double defaultVal);
- bool Read(const wxString& key, bool* b);
- bool Read(const wxString& key, bool* d, bool defaultVal);
- bool Read(const wxString& key, wxMemoryBuffer* buf);
- bool Read(const wxString& key, T* value);
- bool Read(const wxString& key, T* value,
- T const& defaultVal);
+ bool Read(const wxString& key, wxString* str) const;
+ const bool Read(const wxString& key, wxString* str,
+ const wxString& defaultVal) const;
+ const wxString Read(const wxString& key,
+ const
+ wxString& defaultVal) const;
+ const bool Read(const wxString& key, long* l) const;
+ const bool Read(const wxString& key, long* l,
+ long defaultVal) const;
+ const bool Read(const wxString& key, double* d) const;
+ const bool Read(const wxString& key, double* d,
+ double defaultVal) const;
+ const bool Read(const wxString& key, bool* b) const;
+ const bool Read(const wxString& key, bool* d,
+ bool defaultVal) const;
+ const bool Read(const wxString& key, wxMemoryBuffer* buf) const;
+ const bool Read(const wxString& key, T* value) const;
+ const bool Read(const wxString& key, T* value,
+ T const& defaultVal) const;
//@}
/**
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);
+ 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.
*/
- long ReadDouble(const wxString& key, double defaultVal);
+ 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.
*/
- long ReadLong(const wxString& key, long defaultVal);
+ 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.
+ wxFromString() is 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);
+ T ReadObject(const wxString& key, T const& defaultVal) const;
/**
The functions in this section allow to rename entries or subgroups of the
the new name already exists or because the function is not supported in this
wxConfig implementation.
RenameEntry()
-
+
RenameGroup()
*/
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()
*/
//@{
/**
These functions write the specified value to the config file and return @true
- on success. In the last one, function wxToString must be
+ 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
*/
bool Write(const wxString& key, const wxString& value);
bool Write(const wxString& key, const T& buf);
//@}
};
+
projects / wxWidgets.git / blobdiff