Version: 3.1.0
wxFileConfig Class Reference

#include <wx/fileconf.h>

+ Inheritance diagram for wxFileConfig:

Detailed Description

wxFileConfig implements wxConfigBase interface for storing and retrieving configuration information using plain text files.

The files have a simple format reminiscent of Windows INI files with lines of the form "key = value" defining the keys and lines of special form "[group]" indicating the start of each group.

This class is used by default for wxConfig on Unix platforms but may also be used explicitly if you want to use files and not the registry even under Windows.

Library:  wxBase
Category:  Application and System configuration
See Also
wxFileConfig::Save

Public Member Functions

 wxFileConfig (const wxString &appName=wxEmptyString, const wxString &vendorName=wxEmptyString, const wxString &localFilename=wxEmptyString, const wxString &globalFilename=wxEmptyString, long style=wxCONFIG_USE_LOCAL_FILE|wxCONFIG_USE_GLOBAL_FILE, const wxMBConv &conv=wxConvAuto())
 Constructor allowing to choose the file names to use.
 
 wxFileConfig (wxInputStream &is, const wxMBConv &conv=wxConvAuto())
 Read the config data from the specified stream instead of the associated file, as usual.
 
virtual bool Save (wxOutputStream &os, const wxMBConv &conv=wxConvAuto())
 Saves all config data to the given stream, returns true if data was saved successfully or false on error.
 
void SetUmask (int mode)
 Allows to set the mode to be used for the config file creation.
 
virtual void SetPath (const wxString &strPath)
 Set current path: if the first character is '/', it is the absolute path, otherwise it is a relative path.
 
virtual const wxStringGetPath () const
 Retrieve the current path (always as absolute path).
 
virtual bool GetFirstGroup (wxString &str, long &lIndex) const
 Gets the first group.
 
virtual bool GetNextGroup (wxString &str, long &lIndex) const
 Gets the next group.
 
virtual bool GetFirstEntry (wxString &str, long &lIndex) const
 Gets the first entry.
 
virtual bool GetNextEntry (wxString &str, long &lIndex) const
 Gets the next entry.
 
virtual size_t GetNumberOfEntries (bool bRecursive=false) const
 Get number of entries in the current group.
 
virtual size_t GetNumberOfGroups (bool bRecursive=false) const
 Get number of entries/subgroups in the current group, with or without its subgroups.
 
virtual bool HasGroup (const wxString &strName) const
 
virtual bool HasEntry (const wxString &strName) const
 
virtual bool Flush (bool bCurrentOnly=false)
 Permanently writes all changes (otherwise, they're only written from object's destructor).
 
virtual bool RenameEntry (const wxString &oldName, const wxString &newName)
 Renames an entry in the current group.
 
virtual bool RenameGroup (const wxString &oldName, const wxString &newName)
 Renames a subgroup of the current group.
 
virtual bool DeleteEntry (const wxString &key, bool bGroupIfEmptyAlso=true)
 Deletes the specified entry and the group it belongs to if it was the last key in it and the second parameter is true.
 
virtual bool DeleteGroup (const wxString &szKey)
 Delete the group (with all subgroups).
 
virtual bool DeleteAll ()
 Delete the whole underlying object (disk file, registry key, ...).
 
- Public Member Functions inherited from wxConfigBase
 wxConfigBase (const wxString &appName=wxEmptyString, const wxString &vendorName=wxEmptyString, const wxString &localFilename=wxEmptyString, const wxString &globalFilename=wxEmptyString, long style=0, const wxMBConv &conv=wxConvAuto())
 This is the default and only constructor of the wxConfigBase class, and derived classes.
 
virtual ~wxConfigBase ()
 Empty but ensures that dtor of all derived classes is virtual.
 
bool Exists (const wxString &strName) const
 
virtual wxConfigBase::EntryType GetEntryType (const wxString &name) const
 Returns the type of the given entry or Unknown if the entry doesn't exist.
 
wxString GetAppName () const
 Returns the application name.
 
wxString GetVendorName () const
 Returns the vendor name.
 
bool Read (const wxString &key, wxString *str) const
 Read a string from the key, returning true if the value was read.
 
bool Read (const wxString &key, wxString *str, const wxString &defaultVal) const
 Read a string from the key.
 
const wxString Read (const wxString &key, const wxString &defaultVal) const
 Another version of Read(), returning the string value directly.
 
bool Read (const wxString &key, long *l) const
 Reads a long value, returning true if the value was found.
 
bool Read (const wxString &key, long *l, long defaultVal) const
 Reads a long value, returning true if the value was found.
 
bool Read (const wxString &key, double *d) const
 Reads a double value, returning true if the value was found.
 
bool Read (const wxString &key, double *d, double defaultVal) const
 Reads a double value, returning true if the value was found.
 
bool Read (const wxString &key, float *f) const
 Reads a float value, returning true if the value was found.
 
bool Read (const wxString &key, float *f, float defaultVal) const
 Reads a float value, returning true if the value was found.
 
bool Read (const wxString &key, bool *b) const
 Reads a boolean value, returning true if the value was found.
 
bool Read (const wxString &key, bool *d, bool defaultVal) const
 Reads a boolean value, returning true if the value was found.
 
bool Read (const wxString &key, wxMemoryBuffer *buf) const
 Reads a binary block, returning true if the value was found.
 
bool Read (const wxString &key, T *value) const
 Reads a value of type T, for which function wxFromString() is defined, returning true if the value was found.
 
bool Read (const wxString &key, T *value, const T &defaultVal) const
 Reads a value of type T, for which function wxFromString() is defined, returning true if the value was found.
 
bool ReadBool (const wxString &key, bool defaultVal) const
 Reads a bool value from the key and returns it.
 
double ReadDouble (const wxString &key, double defaultVal) const
 Reads a double value from the key and returns it.
 
long ReadLong (const wxString &key, long defaultVal) const
 Reads a long value from the key and returns it.
 
ReadObject (const wxString &key, T const &defaultVal) const
 Reads a value of type T (for which the function wxFromString() must be defined) from the key and returns it.
 
bool Write (const wxString &key, const wxString &value)
 Writes the wxString value to the config file and returns true on success.
 
bool Write (const wxString &key, long value)
 Writes the long value to the config file and returns true on success.
 
bool Write (const wxString &key, double value)
 Writes the double value to the config file and returns true on success.
 
bool Write (const wxString &key, bool value)
 Writes the bool value to the config file and returns true on success.
 
bool Write (const wxString &key, const wxMemoryBuffer &buf)
 Writes the wxMemoryBuffer value to the config file and returns true on success.
 
bool Write (const wxString &key, T const &buf)
 Writes the specified value to the config file and returns true on success.
 
bool IsExpandingEnvVars () const
 Returns true if we are expanding environment variables in key values.
 
bool IsRecordingDefaults () const
 Returns true if we are writing defaults back to the config file.
 
void SetExpandEnvVars (bool bDoIt=true)
 Determine whether we wish to expand environment variables in key values.
 
void SetRecordDefaults (bool bDoIt=true)
 Sets whether defaults are recorded to the config file whenever an attempt to read the value which is not present in it is done.
 
- Public Member Functions inherited from wxObject
 wxObject ()
 Default ctor; initializes to NULL the internal reference data.
 
 wxObject (const wxObject &other)
 Copy ctor.
 
virtual ~wxObject ()
 Destructor.
 
virtual wxClassInfoGetClassInfo () const
 This virtual function is redefined for every class that requires run-time type information, when using the wxDECLARE_CLASS macro (or similar).
 
wxObjectRefDataGetRefData () const
 Returns the wxObject::m_refData pointer, i.e. the data referenced by this object.
 
bool IsKindOf (const wxClassInfo *info) const
 Determines whether this class is a subclass of (or the same class as) the given class.
 
bool IsSameAs (const wxObject &obj) const
 Returns true if this object has the same data pointer as obj.
 
void Ref (const wxObject &clone)
 Makes this object refer to the data in clone.
 
void SetRefData (wxObjectRefData *data)
 Sets the wxObject::m_refData pointer.
 
void UnRef ()
 Decrements the reference count in the associated data, and if it is zero, deletes the data.
 
void UnShare ()
 This is the same of AllocExclusive() but this method is public.
 
void operator delete (void *buf)
 The delete operator is defined for debugging versions of the library only, when the identifier WXDEBUG is defined.
 
void * operator new (size_t size, const wxString &filename=NULL, int lineNum=0)
 The new operator is defined for debugging versions of the library only, when the identifier WXDEBUG is defined.
 

Static Public Member Functions

static wxFileName GetGlobalFile (const wxString &basename)
 Return the full path to the file which would be used by wxFileConfig as global, system-wide, file if it were constructed with basename as "global filename" parameter in the constructor.
 
static wxFileName GetLocalFile (const wxString &basename, int style=0)
 Return the full path to the file which would be used by wxFileConfig as local, user-specific, file if it were constructed with basename as "local filename" parameter in the constructor.
 
static wxString GetGlobalFileName (const wxString &szFile)
 
static wxString GetLocalFileName (const wxString &szFile, int style=0)
 
- Static Public Member Functions inherited from wxConfigBase
static wxConfigBaseCreate ()
 Create a new config object and sets it as the current one.
 
static void DontCreateOnDemand ()
 Calling this function will prevent Get() from automatically creating a new config object if the current one is NULL.
 
static wxConfigBaseGet (bool CreateOnDemand=true)
 Get the current config object.
 
static wxConfigBaseSet (wxConfigBase *pConfig)
 Sets the config object as the current one, returns the pointer to the previous current object (both the parameter and returned value may be NULL).
 

Additional Inherited Members

- Public Types inherited from wxConfigBase
enum  EntryType {
  Type_Unknown,
  Type_String,
  Type_Boolean,
  Type_Integer,
  Type_Float
}
 
- Protected Member Functions inherited from wxObject
void AllocExclusive ()
 Ensure that this object's data is not shared with any other object.
 
virtual wxObjectRefDataCreateRefData () const
 Creates a new instance of the wxObjectRefData-derived class specific to this object and returns it.
 
virtual wxObjectRefDataCloneRefData (const wxObjectRefData *data) const
 Creates a new instance of the wxObjectRefData-derived class specific to this object and initializes it copying data.
 
- Protected Attributes inherited from wxObject
wxObjectRefDatam_refData
 Pointer to an object which is the object's reference-counted data.
 

Constructor & Destructor Documentation

wxFileConfig::wxFileConfig ( const wxString appName = wxEmptyString,
const wxString vendorName = wxEmptyString,
const wxString localFilename = wxEmptyString,
const wxString globalFilename = wxEmptyString,
long  style = wxCONFIG_USE_LOCAL_FILE|wxCONFIG_USE_GLOBAL_FILE,
const wxMBConv conv = wxConvAuto() 
)

Constructor allowing to choose the file names to use.

If localFilename and/or globalFilename are explicitly specified, they are used as the names of the user and system-wide configuration files (the latter is only read by the program while the former is read from and written to). Otherwise the behaviour depends on style parameter. If it includes wxCONFIG_USE_LOCAL_FILE, then the local file name is constructed from the information in appName and vendorName arguments in a system-dependent way. If wxCONFIG_USE_GLOBAL_FILE is not specified at all (and globalFilename is empty) then the system-wide file is not used at all. Otherwise its name and path are also constructed in the way appropriate for the current platform from the application and vendor names.

wxFileConfig::wxFileConfig ( wxInputStream is,
const wxMBConv conv = wxConvAuto() 
)

Read the config data from the specified stream instead of the associated file, as usual.

See Also
Save()

Member Function Documentation

virtual bool wxFileConfig::DeleteAll ( )
virtual

Delete the whole underlying object (disk file, registry key, ...).

Primarily for use by uninstallation routine.

Implements wxConfigBase.

virtual bool wxFileConfig::DeleteEntry ( const wxString key,
bool  bDeleteGroupIfEmpty = true 
)
virtual

Deletes the specified entry and the group it belongs to if it was the last key in it and the second parameter is true.

Implements wxConfigBase.

virtual bool wxFileConfig::DeleteGroup ( const wxString key)
virtual

Delete the group (with all subgroups).

If the current path is under the group being deleted it is changed to its deepest still existing component. E.g. if the current path is "/A/B/C/D" and the group C is deleted, the path becomes "/A/B".

Implements wxConfigBase.

virtual bool wxFileConfig::Flush ( bool  bCurrentOnly = false)
virtual

Permanently writes all changes (otherwise, they're only written from object's destructor).

Implements wxConfigBase.

virtual bool wxFileConfig::GetFirstEntry ( wxString str,
long &  index 
) const
virtual

Gets the first entry.

wxPerl Note: In wxPerl this method takes no parameters and returns a 3-element list (continue_flag, string, index_for_getnextentry).

Implements wxConfigBase.

virtual bool wxFileConfig::GetFirstGroup ( wxString str,
long &  index 
) const
virtual

Gets the first group.

wxPerl Note: In wxPerl this method takes no parameters and returns a 3-element list (continue_flag, string, index_for_getnextentry).

Implements wxConfigBase.

static wxFileName wxFileConfig::GetGlobalFile ( const wxString basename)
static

Return the full path to the file which would be used by wxFileConfig as global, system-wide, file if it were constructed with basename as "global filename" parameter in the constructor.

Notice that this function cannot be used if basename is already a full path name.

static wxString wxFileConfig::GetGlobalFileName ( const wxString szFile)
static
static wxFileName wxFileConfig::GetLocalFile ( const wxString basename,
int  style = 0 
)
static

Return the full path to the file which would be used by wxFileConfig as local, user-specific, file if it were constructed with basename as "local filename" parameter in the constructor.

style has the same meaning as in wxConfig constructor and can contain any combination of styles but only wxCONFIG_USE_SUBDIR bit is examined by this function.

Notice that this function cannot be used if basename is already a full path name.

static wxString wxFileConfig::GetLocalFileName ( const wxString szFile,
int  style = 0 
)
static
virtual bool wxFileConfig::GetNextEntry ( wxString str,
long &  index 
) const
virtual

Gets the next entry.

wxPerl Note: In wxPerl this method only takes the index parameter and returns a 3-element list (continue_flag, string, index_for_getnextentry).

Implements wxConfigBase.

virtual bool wxFileConfig::GetNextGroup ( wxString str,
long &  index 
) const
virtual

Gets the next group.

wxPerl Note: In wxPerl this method only takes the index parameter and returns a 3-element list (continue_flag, string, index_for_getnextentry).

Implements wxConfigBase.

virtual size_t wxFileConfig::GetNumberOfEntries ( bool  bRecursive = false) const
virtual

Get number of entries in the current group.

Implements wxConfigBase.

virtual size_t wxFileConfig::GetNumberOfGroups ( bool  bRecursive = false) const
virtual

Get number of entries/subgroups in the current group, with or without its subgroups.

Implements wxConfigBase.

virtual const wxString& wxFileConfig::GetPath ( ) const
virtual

Retrieve the current path (always as absolute path).

Implements wxConfigBase.

virtual bool wxFileConfig::HasEntry ( const wxString strName) const
virtual
Returns
true if the entry by this name exists.

Implements wxConfigBase.

virtual bool wxFileConfig::HasGroup ( const wxString strName) const
virtual
Returns
true if the group by this name exists.

Implements wxConfigBase.

virtual bool wxFileConfig::RenameEntry ( const wxString oldName,
const wxString newName 
)
virtual

Renames an entry in the current group.

The entries names (both the old and the new one) shouldn't contain backslashes, i.e. only simple names and not arbitrary paths are accepted by this function.

Returns
false if oldName doesn't exist or if newName already exists.

Implements wxConfigBase.

virtual bool wxFileConfig::RenameGroup ( const wxString oldName,
const wxString newName 
)
virtual

Renames a subgroup of the current group.

The subgroup names (both the old and the new one) shouldn't contain backslashes, i.e. only simple names and not arbitrary paths are accepted by this function.

Returns
false if oldName doesn't exist or if newName already exists.

Implements wxConfigBase.

virtual bool wxFileConfig::Save ( wxOutputStream os,
const wxMBConv conv = wxConvAuto() 
)
virtual

Saves all config data to the given stream, returns true if data was saved successfully or false on error.

Note the interaction of this function with the internal "dirty flag": the data is saved unconditionally, i.e. even if the object is not dirty. However after saving it successfully, the dirty flag is reset so no changes will be written back to the file this object is associated with until you change its contents again.

See Also
wxConfigBase::Flush
virtual void wxFileConfig::SetPath ( const wxString strPath)
virtual

Set current path: if the first character is '/', it is the absolute path, otherwise it is a relative path.

'..' is supported. If strPath doesn't exist, it is created.

See Also
wxConfigPathChanger

Implements wxConfigBase.

void wxFileConfig::SetUmask ( int  mode)

Allows to set the mode to be used for the config file creation.

For example, to create a config file which is not readable by other users (useful if it stores some sensitive information, such as passwords), you could use SetUmask(0077).

This function doesn't do anything on non-Unix platforms.

See Also
wxCHANGE_UMASK()