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

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.

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.

Detailed Description

Configuration Files Paths

Classes

Public Member Functions

Static Public Member Functions

Additional Inherited Members

Constructor & Destructor Documentation

◆ wxFileConfig() [1/2]

◆ wxFileConfig() [2/2]

Member Function Documentation

◆ DeleteAll()

◆ DeleteEntry()

◆ DeleteGroup()

◆ DisableAutoSave()

◆ EnableAutoSave()

◆ Flush()

◆ GetFirstEntry()

◆ GetFirstGroup()

◆ GetGlobalFile()

◆ GetGlobalFileName()

◆ GetLocalFile()

◆ GetLocalFileName()

◆ GetNextEntry()

◆ GetNextGroup()

◆ GetNumberOfEntries()

◆ GetNumberOfGroups()

◆ GetPath()

◆ HasEntry()

◆ HasGroup()

◆ MigrateLocalFile()

◆ RenameEntry()

◆ RenameGroup()

◆ Save()

◆ SetPath()

◆ SetUmask()