| Version: 3.3.1

Classes | Public Member Functions | Static Public Member Functions | List of all members
wxFileConfig Class Reference
Class List by Category » Application and System configuration

`#include <wx/fileconf.h>`

Inheritance diagram for wxFileConfig:
[legend]

## 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.

# Configuration Files Paths

The default path for local (or user) configuration file is `~/.appname`, i.e. it is stored directly in the user home directory. This default path is backwards-compatible but not recommended any more and it is advised to call wxStandardPaths::SetFileLayout() with wxStandardPaths::FileLayout_XDG parameter to change the default path to `~/.config/appname.conf`. MigrateLocalFile() may be helpful for moving the existing configuration file to the new location.

Alternatively, it is possible to specify wxCONFIG_USE_XDG flag in the style parameter of the constructor to use this XDG-compliant path without changing the global file layout.

And for the programs using multiple configuration files it is recommended to use both wxCONFIG_USE_XDG and wxCONFIG_USE_SUBDIR which change the default file path to `~/.config/appname/appname.conf` – and allow the program to store other files in the same `~/.config/appname` directory.

##

Library: wxBase
Category: Application and System configuration

See also
  wxFileConfig::Save

## Classes
struct | MigrationResult
| Contains return value of MigrateLocalFile(). More...

## 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. More...
| wxFileConfig (wxInputStream &is, const wxMBConv &conv=wxConvAuto())
| Read the config data from the specified stream instead of the associated file, as usual. More...
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. More...
void | EnableAutoSave ()
| Enables saving data to the disk file when this object is destroyed. More...
void | DisableAutoSave ()
| Prevent this object from saving data to the disk file when it is destroyed. More...
void | SetUmask (int mode)
| Allows setting the mode to be used for the config file creation. More...
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. More...
virtual const wxString & | GetPath () const
| Retrieve the current path (always as absolute path). More...
virtual bool | GetFirstGroup (wxString &str, long &lIndex) const
| Gets the first group. More...
virtual bool | GetNextGroup (wxString &str, long &lIndex) const
| Gets the next group. More...
virtual bool | GetFirstEntry (wxString &str, long &lIndex) const
| Gets the first entry. More...
virtual bool | GetNextEntry (wxString &str, long &lIndex) const
| Gets the next entry. More...
virtual size_t | GetNumberOfEntries (bool bRecursive=false) const
| Get number of entries in the current group. More...
virtual size_t | GetNumberOfGroups (bool bRecursive=false) const
| Get number of entries/subgroups in the current group, with or without its subgroups. More...
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). More...
virtual bool | RenameEntry (const wxString &oldName, const wxString &newName)
| Renames an entry in the current group. More...
virtual bool | RenameGroup (const wxString &oldName, const wxString &newName)
| Renames a subgroup of the current group. More...
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. More...
virtual bool | DeleteGroup (const wxString &szKey)
| Delete the group (with all subgroups). More...
virtual bool | DeleteAll ()
| Delete the whole underlying object (disk file, registry key, ...). More...
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. More...
virtual | ~wxConfigBase ()
| Empty but ensures that dtor of all derived classes is virtual. More...
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. More...
wxString | GetAppName () const
| Returns the application name. More...
wxString | GetVendorName () const
| Returns the vendor name. More...
bool | Read (const wxString &key, wxString *str) const
| Read a string from the key, returning true if the value was read. More...
bool | Read (const wxString &key, wxString *str, const wxString &defaultVal) const
| Read a string from the key. More...
const wxString | Read (const wxString &key, const wxString &defaultVal) const
| Another version of Read(), returning the string value directly. More...
bool | Read (const wxString &key, long *l) const
| Reads a long value, returning true if the value was found. More...
bool | Read (const wxString &key, long *l, long defaultVal) const
| Reads a long value, returning true if the value was found. More...
bool | Read (const wxString &key, wxLongLong_t *ll) const
| Reads a 64-bit long long value, returning true if the value was found. More...
bool | Read (const wxString &key, wxLongLong_t *ll, wxLongLong_t defaultVal) const
| Reads a 64-bit long long value, returning true if the value was found. More...
bool | Read (const wxString &key, size_t *value) const
| Reads a size_t value, returning true if the value was found. More...
bool | Read (const wxString &key, size_t *value, size_t defaultVal) const
| Reads a size_t value, returning true if the value was found. More...
bool | Read (const wxString &key, double *d) const
| Reads a double value, returning true if the value was found. More...
bool | Read (const wxString &key, double *d, double defaultVal) const
| Reads a double value, returning true if the value was found. More...
bool | Read (const wxString &key, float *f) const
| Reads a float value, returning true if the value was found. More...
bool | Read (const wxString &key, float *f, float defaultVal) const
| Reads a float value, returning true if the value was found. More...
bool | Read (const wxString &key, bool *b) const
| Reads a boolean value, returning true if the value was found. More...
bool | Read (const wxString &key, bool *d, bool defaultVal) const
| Reads a boolean value, returning true if the value was found. More...
bool | Read (const wxString &key, wxMemoryBuffer *buf) const
| Reads a binary block, returning true if the value was found. More...
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. More...
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. More...
bool | ReadBool (const wxString &key, bool defaultVal) const
| Reads a bool value from the key and returns it. More...
double | ReadDouble (const wxString &key, double defaultVal) const
| Reads a double value from the key and returns it. More...
long | ReadLong (const wxString &key, long defaultVal) const
| Reads a long value from the key and returns it. More...
wxLongLong_t | ReadLongLong (const wxString &key, wxLongLong_t defaultVal) const
| Reads a 64-bit long long value from the key and returns it. More...
T | 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. More...
bool | Write (const wxString &key, const wxString &value)
| Writes the wxString value to the config file and returns true on success. More...
bool | Write (const wxString &key, long value)
| Writes the long value to the config file and returns true on success. More...
bool | Write (const wxString &key, wxLongLong_t value)
| Writes the 64-bit long long value to the config file and returns true on success. More...
bool | Write (const wxString &key, double value)
| Writes the double value to the config file and returns true on success. More...
bool | Write (const wxString &key, bool value)
| Writes the bool value to the config file and returns true on success. More...
bool | Write (const wxString &key, const wxMemoryBuffer &buf)
| Writes the wxMemoryBuffer value to the config file and returns true on success. More...
bool | Write (const wxString &key, T const &buf)
| Writes the specified value to the config file and returns true on success. More...
bool | IsExpandingEnvVars () const
| Returns true if we are expanding environment variables in key values. More...
bool | IsRecordingDefaults () const
| Returns true if we are writing defaults back to the config file. More...
void | SetExpandEnvVars (bool bDoIt=true)
| Determine whether we wish to expand environment variables in key values. More...
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. More...
Public Member Functions inherited from wxObject
| wxObject ()
| Default ctor; initializes to nullptr the internal reference data. More...
| wxObject (const wxObject &other)
| Copy ctor. More...
virtual | ~wxObject ()
| Destructor. More...
virtual wxClassInfo * | GetClassInfo () const
| This virtual function is redefined for every class that requires run-time type information, when using the wxDECLARE_CLASS macro (or similar). More...
wxObjectRefData * | GetRefData () const
| Returns the wxObject::m_refData pointer, i.e. the data referenced by this object. More...
bool | IsKindOf (const wxClassInfo *info) const
| Determines whether this class is a subclass of (or the same class as) the given class. More...
bool | IsSameAs (const wxObject &obj) const
| Returns true if this object has the same data pointer as obj. More...
void | Ref (const wxObject &clone)
| Makes this object refer to the data in clone. More...
void | SetRefData (wxObjectRefData *data)
| Sets the wxObject::m_refData pointer. More...
void | UnRef ()
| Decrements the reference count in the associated data, and if it is zero, deletes the data. More...
void | UnShare ()
| This is the same of AllocExclusive() but this method is public. More...
void | operator delete (void *buf)
| The delete operator is defined for debugging versions of the library only, when the identifier `__WXDEBUG__` is defined. More...
void * | operator new (size_t size, const wxString &filename=nullptr, int lineNum=0)
| The new operator is defined for debugging versions of the library only, when the identifier `__WXDEBUG__` is defined. More...

## 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. More...
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. More...
static wxString | GetGlobalFileName (const wxString &szFile)
static wxString | GetLocalFileName (const wxString &szFile, int style=0)
static MigrationResult | MigrateLocalFile (const wxString &name, int newStyle, int oldStyle=wxCONFIG_USE_HOME)
| Move the existing configuration file to a new location. More...
Static Public Member Functions inherited from wxConfigBase
static wxConfigBase * | Create ()
| Create a new config object and sets it as the current one. More...
static void | DontCreateOnDemand ()
| Calling this function will prevent Get() from automatically creating a new config object if the current one is nullptr. More...
static wxConfigBase * | Get (bool CreateOnDemand=true)
| Get the current config object. More...
static wxConfigBase * | Set (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 nullptr). More...

## 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. More...
virtual wxObjectRefData * | CreateRefData () const
| Creates a new instance of the wxObjectRefData-derived class specific to this object and returns it. More...
virtual wxObjectRefData * | CloneRefData (const wxObjectRefData *data) const
| Creates a new instance of the wxObjectRefData-derived class specific to this object and initializes it copying data. More...
Protected Attributes inherited from wxObject
wxObjectRefData * | m_refData
| Pointer to an object which is the object's reference-counted data. More...

## Constructor & Destructor Documentation

## ◆ wxFileConfig() [1/2]

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() [2/2]

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

## ◆ DeleteAll()

virtual bool wxFileConfig::DeleteAll | ( |  | ) |
| virtual

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

Primarily for use by uninstallation routine.

Implements wxConfigBase.

## ◆ DeleteEntry()

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.

## ◆ DeleteGroup()

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.

## ◆ DisableAutoSave()

void wxFileConfig::DisableAutoSave | ( |  | ) |

Prevent this object from saving data to the disk file when it is destroyed.

By default, changes to this object are only saved permanently when Flush() is explicitly called or when it is destroyed. If this method is called, Flush() won't be called automatically from the destructor, meaning that any non-explicitly-flushed changes will be lost.

Since
  3.1.3

## ◆ EnableAutoSave()

void wxFileConfig::EnableAutoSave | ( |  | ) |

Enables saving data to the disk file when this object is destroyed.

This is the default behaviour and this function doesn't need to be called explicitly unless DisableAutoSave() had been previously called.

Since
  3.1.3

## ◆ Flush()

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

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

Implements wxConfigBase.

## ◆ GetFirstEntry()

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.

## ◆ GetFirstGroup()

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.

## ◆ GetGlobalFile()

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.

## ◆ GetGlobalFileName()

static wxString wxFileConfig::GetGlobalFileName | ( | const wxString & | szFile | ) |
| static

## ◆ GetLocalFile()

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, wxCONFIG_USE_XDG and wxCONFIG_USE_HOME are really used by this function.

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

## ◆ GetLocalFileName()

static wxString wxFileConfig::GetLocalFileName | ( | const wxString & | szFile,
|  | int | style = `0`
| ) |  |
| static

## ◆ GetNextEntry()

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.

## ◆ GetNextGroup()

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.

## ◆ GetNumberOfEntries()

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

Get number of entries in the current group.

Implements wxConfigBase.

## ◆ GetNumberOfGroups()

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.

## ◆ GetPath()

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

Retrieve the current path (always as absolute path).

Implements wxConfigBase.

## ◆ HasEntry()

virtual bool wxFileConfig::HasEntry | ( | const wxString & | strName | ) | const
| virtual

Returns
  true if the entry by this name exists.

Implements wxConfigBase.

## ◆ HasGroup()

virtual bool wxFileConfig::HasGroup | ( | const wxString & | strName | ) | const
| virtual

Returns
  true if the group by this name exists.

Implements wxConfigBase.

## ◆ MigrateLocalFile()

static MigrationResult wxFileConfig::MigrateLocalFile | ( | const wxString & | name,
|  | int | newStyle,
|  | int | oldStyle = `wxCONFIG_USE_HOME`
| ) |  |
| static

Move the existing configuration file to a new location.

This function is useful for moving legacy configuration files in `~/.appname` or `~/.appname/appname.conf` to the XDG-compliant location under `~/.config`. To do this, simply specify wxCONFIG_USE_XDG as part of newStyle.

The returned MigrationResult object describes what, if anything, was done: if its `oldPath` member is empty, it means that the file corresponding to oldStyle was not found and nothing was done. Otherwise, if its `error` member is empty, the old file was found and moved to `newPath`. And if `error` is not empty, it contains the user-readable error message describing why moving the file failed.

Typical example of using this function is shown in the widgets sample:

// Execute this early during the application startup, before the
// global wxConfig object is created.
const auto res = wxFileConfig::MigrateLocalFile("app", wxCONFIG_USE_XDG);
if ( !res.oldPath.empty() ) {
if ( res.error.empty() ) {
wxLogMessage("Config file was migrated from \"%s\" to \"%s\"",
res.oldPath, res.newPath);
} else {
wxLogWarning("Migrating old config failed: %s.", res.error);
}
}
// Prefer doing it only after successfully calling MigrateLocalFile(),
// otherwise, i.e. if it failed, the old config file wouldn't be used.
wxStandardPaths::Get().SetFileLayout(wxStandardPaths::FileLayout_XDG);
wxFileConfig::MigrateLocalFile
static MigrationResult MigrateLocalFile(const wxString &name, int newStyle, int oldStyle=wxCONFIG_USE_HOME)
Move the existing configuration file to a new location.
wxStandardPaths::Get
static wxStandardPaths & Get()
Returns reference to the unique global standard paths object.
wxStandardPaths::FileLayout_XDG
@ FileLayout_XDG
Use a XDG styled file layout.
Definition: stdpaths.h:178
wxStandardPaths::SetFileLayout
void SetFileLayout(FileLayout layout)
Sets the current file layout.
wxLogWarning
void wxLogWarning(const char *formatString,...)
For warnings - they are also normally shown to the user, but don't interrupt the program work.
wxLogMessage
void wxLogMessage(const char *formatString,...)
For all normal, informational messages.
wxCONFIG_USE_XDG
@ wxCONFIG_USE_XDG
Always use XDG-compliant file location on Unix systems.
Definition: config.h:48

Parameters

  name | Name of the configuration file.
  newStyle | Style which is used by the current version of the program, typically including wxCONFIG_USE_XDG and possibly also including wxCONFIG_USE_SUBDIR.
  oldStyle | Style which was used by the previous versions of the program, possibly including wxCONFIG_USE_SUBDIR and typically including wxCONFIG_USE_HOME.

Since
  3.3.0

## ◆ RenameEntry()

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.

## ◆ RenameGroup()

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.

## ◆ Save()

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

## ◆ SetPath()

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.

## ◆ SetUmask()

void wxFileConfig::SetUmask | ( | int | mode | ) |

Allows setting 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()