wx.Config Class Reference

Inheritance diagram for wx.Config:

List of all members.

Public Types
enum	EntryType
Public Member Functions
	Config (wxString appName, wxString vendorName, wxString localName, wxString globalName, ConfigStyle style)
	Config (string appName, string vendorName, string localName, string globalName, ConfigStyle style)
	Config (IntPtr wxObject)
bool	DeleteAll ()
bool	DeleteEntry (string key, bool bDeleteGroupIfEmpty)
bool	DeleteGroup (string key)
void	DontCreateOnDemand ()
bool	Exists (string strName)
bool	Flush (bool bCurrentOnly)
bool	Flush ()
EntryType	GetEntryType (string name)
bool	GetFirstEntry (ref string str, ref int lIndex)
bool	GetFirstGroup (ref string str, ref int lIndex)
bool	GetNextEntry (ref string str, ref int lIndex)
bool	GetNextGroup (ref string str, ref int lIndex)
int	GetNumberOfEntries (bool bRecursive)
int	GetNumberOfGroups (bool bRecursive)
bool	HasEntry (string strName)
bool	HasGroup (string strName)
Font	Read (string key, Font defVal)
Colour	Read (string key, Colour defVal)
bool	Read (string key, bool defVal)
int	Read (string key, int defVal)
string	Read (string key, string defVal)
bool	Read (string key, System.Xml.Serialization.IXmlSerializable readThis)
bool	ReadBool (string key, ref bool val, bool defVal)
bool	ReadBool (string key, ref bool val)
bool	ReadColour (string key, ref Colour val, Colour defVal)
bool	ReadDouble (string key, ref double val, double defVal)
bool	ReadDouble (string key, ref double val)
bool	ReadFont (string key, ref Font val, Font defVal)
bool	ReadFont (string key, ref Font val)
bool	ReadInt (string key, ref int pl, int defVal)
bool	ReadInt (string key, ref int pl)
bool	ReadString (string key, ref string str, string defVal)
bool	ReadString (string key, ref string str)
bool	RenameEntry (string oldName, string newName)
bool	RenameGroup (string oldName, string newName)
string	WithEnvVarsExpanded (string str)
bool	Write (string key, System.Xml.Serialization.IXmlSerializable val)
bool	Write (string key, Colour val)
bool	Write (string key, Font val)
bool	Write (string key, bool val)
bool	Write (string key, double val)
bool	Write (string key, uint val)
bool	Write (string key, int val)
bool	Write (string key, string val)
Static Public Member Functions
static Config	Create ()
static Config	Get ()
static Config	Get (bool createOnDemand)
static Config	Set (Config config)
Protected Member Functions
override void	CallDTor ()
Properties
string	AppName [get, set]
static Config	Default [get, set]
bool	ExpandEnvVars [get, set]
string	Path [get, set]
bool	RecordDefaults [get, set]
ConfigStyle	Style [get, set]
string	VendorName [get, set]

---

Detailed Description

This is the class for writing and reading configuration parameters via wxWidgets wxConfigBase implementations.

The idea of wxWidgets configuration class is to provide an interface that allows applications to manage configuration data without regard to the mathod of storing the information. Configurations may either be stored in a global or local file, or into the registry database. The syntax of the files is according to the good old Ini-files as common to 16-Bit Windows.

This interface might be extended in the future to provide some additional styles that implement the standard way of configuring .NET applications (XML file myApp.exe.config for application myApp.exe read by class System.Configuration.Configuration).

Although wxConfig is not derived from wxObject, this class is derived from wx.Object since the main concern of wx.Object is to manage pointers to C++ objects. Use Config.Get() to get an instance.

The original C++ implementation uses Method Read with many, many signatures. Since this may lead to some confusion (at least I have been confused on using this class), this class implements Read functionality in two flavours: Returning the value or a default as method result and loading a reference with the value from the configuration if this has been found. Methods of the first flavour still are called Read whereas methods of the second flavour contain the data type as part of their name like wx.Config.ReadInt().

In the past, both flavours were named simply Read. Hence, programmers that missed to use the small C# keyword ref accidentally turned an intended call of flavour 2 into one of flavour 1.

A few things have been added to this class going beyond the functions in wxWidgets: WriteProperties() and ReadProperties() will write and read public properties and fields using reflection.

Problems: There is some evidence that reading strings for non-existing keys using a default value might lead to memory corruption at least in some cases.

---

Member Enumeration Documentation

enum wx::Config::EntryType

An enumeration representing the data type of an atomic field.

Enumerator:

Unknown
String
Boolean
Integer
Float

---

Constructor & Destructor Documentation

wx.Config.Config

(

IntPtr

wxObject

)

wx.Config.Config	(	string	appName,
		string	vendorName,
		string	localName,
		string	globalName,
		ConfigStyle	style
	)

Use this CTor and call Set() to create a configuration of a particular style.

Parameters:

	appName	The application name. If this is empty, the class will normally use wx.App.GetAppName to set it. The application name is used in the registry key on Windows, and can be used to deduce the local filename parameter if that is missing.
	vendorName	The vendor name. If this is empty, it is assumed that no vendor name is wanted, if this is optional for the current config class. The vendor name is appended to the application name for wxRegConfig.
	localName	Some config classes require a local filename. If this is not present, but required, the application's name will be used instead.
	globalName	Some config classes require a global filename. If this is not present, but required, the application's name will be used instead.
	style	Can be one of USE_LOCAL_FILE and USE_GLOBAL_FILE. The style interpretation depends on the config class and is ignored by some. For wxFileConfig, these styles determine whether a local or global config file is created or used. 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 wxFileConfig you can also add USE_RELATIVE_PATH by logically or'ing it to either of the _FILE options to tell wxFileConfig to use relative instead of absolute paths. For wxFileConfig, you can also add USE_NO_ESCAPE_CHARACTERS which will turn off character escaping for the values of entries stored in the config file.

wx.Config.Config	(	wxString	appName,
		wxString	vendorName,
		wxString	localName,
		wxString	globalName,
		ConfigStyle	style
	)

---

Member Function Documentation

override void wx.Config.CallDTor

(

)

[protected, virtual]

This will be called by Dispose() to delete the C++ object. Overload this if you have to use another DTor.

Reimplemented from wx.Object.

static Config wx.Config.Create

(

)

[static]

Create a new configuration according to properties of the application. On Windows, the configuration will preferably recorded in the registry database within the HKEY_CURRENT_USER section using the vendor's name and the application's name to create subkeys. However, this depends on whether wxUSE_CONFIG_NATIVE has been defined on compiling wxWidgets or not. In most other cases, this will use a file of the application name in the current working directory. Refer also to wx.App.AppName and wx.App.VendorName.

bool wx.Config.DeleteAll

(

)

bool wx.Config.DeleteEntry	(	string	key,
		bool	bDeleteGroupIfEmpty
	)

bool wx.Config.DeleteGroup

(

string

key

)

void wx.Config.DontCreateOnDemand

(

)

bool wx.Config.Exists

(

string

strName

)

returns true if either a group or an entry with a given name exists

Parameters:

strName

name of an entry or a group

bool wx.Config.Flush

(

bool

bCurrentOnly

)

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

bool wx.Config.Flush

(

)

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

static Config wx.Config.Get

(

)

[static]

Equivalent to wx.Config.Get(true).

static Config wx.Config.Get

(

bool

createOnDemand

)

[static]

This will get the current configuration of the application. If the argument is true, this method will wx.Config.Create() a new configuration is required.

EntryType wx.Config.GetEntryType

(

string

name

)

bool wx.Config.GetFirstEntry	(	ref string	str,
		ref int	lIndex
	)

bool wx.Config.GetFirstGroup	(	ref string	str,
		ref int	lIndex
	)

bool wx.Config.GetNextEntry	(	ref string	str,
		ref int	lIndex
	)

bool wx.Config.GetNextGroup	(	ref string	str,
		ref int	lIndex
	)

int wx.Config.GetNumberOfEntries

(

bool

bRecursive

)

int wx.Config.GetNumberOfGroups

(

bool

bRecursive

)

bool wx.Config.HasEntry

(

string

strName

)

bool wx.Config.HasGroup

(

string

strName

)

Font wx.Config.Read	(	string	key,
		Font	defVal
	)

Colour wx.Config.Read	(	string	key,
		Colour	defVal
	)

bool wx.Config.Read	(	string	key,
		bool	defVal
	)

int wx.Config.Read	(	string	key,
		int	defVal
	)

string wx.Config.Read	(	string	key,
		string	defVal
	)

bool wx.Config.Read	(	string	key,
		System.Xml.Serialization.IXmlSerializable	readThis
	)

bool wx.Config.ReadBool	(	string	key,
		ref bool	val,
		bool	defVal
	)

Read a value from the key, returning true if the value was read. Assigns a default value if the key was not found.

Parameters:

	key	the key
	val	the value to be read
	defVal	this will be assigned if the key has not been found

Returns:

true if value has been found and set

bool wx.Config.ReadBool	(	string	key,
		ref bool	val
	)

Read a value from the key, returning true if the value was read. If the key was not found, the value will not be changed.

Parameters:

	key	the key
	val	the value to be read

Returns:

true if value has been found and set

bool wx.Config.ReadColour	(	string	key,
		ref Colour	val,
		Colour	defVal
	)

Read a value from the key, returning true if the value was read. Assigns a default value if the key was not found.

Parameters:

	key	the key
	val	the value to be read
	defVal	this will be assigned if the key has not been found

Returns:

true if value has been found and set

bool wx.Config.ReadDouble	(	string	key,
		ref double	val,
		double	defVal
	)

Read a value from the key, returning true if the value was read. Assigns a default value if the key was not found.

Parameters:

	key	the key
	val	the value to be read
	defVal	this will be assigned if the key has not been found

Returns:

true if value has been found and set

bool wx.Config.ReadDouble	(	string	key,
		ref double	val
	)

Read a value from the key, returning true if the value was read. If the key was not found, the value will not be changed.

Parameters:

	key	the key
	val	the value to be read

Returns:

true if value has been found and set

bool wx.Config.ReadFont	(	string	key,
		ref Font	val,
		Font	defVal
	)

Read a value from the key, returning true if the value was read. Assigns a default value if the key was not found.

Parameters:

	key	the key
	val	the value to be read
	defVal	this will be assigned if the key has not been found

Returns:

true if value has been found and set

bool wx.Config.ReadFont	(	string	key,
		ref Font	val
	)

Read a value from the key, returning true if the value was read. If the key was not found, the value will not be changed.

Parameters:

	key	the key
	val	the value to be read

Returns:

true if value has been found and set

bool wx.Config.ReadInt	(	string	key,
		ref int	pl,
		int	defVal
	)

Read a value from the key, returning true if the value was read. Assigns a default value if the key was not found.

Parameters:

	key	the key
	pl	the value to be read
	defVal	this will be assigned if the key has not been found

Returns:

true if value has been found and set

bool wx.Config.ReadInt	(	string	key,
		ref int	pl
	)

Read a value from the key, returning true if the value was read. If the key was not found, the value will not be changed.

Parameters:

	key	the key
	pl	the value to be read

Returns:

true if value has been found and set

bool wx.Config.ReadString	(	string	key,
		ref string	str,
		string	defVal
	)

Read a value from the key, returning true if the value was read. Assigns a default value if the key was not found.

Parameters:

	key	the key
	str	the value to be read
	defVal	this will be assigned if the key has not been found

Returns:

true if value has been found and set

bool wx.Config.ReadString	(	string	key,
		ref string	str
	)

Read a value from the key, returning true if the value was read. If the key was not found, the value will not be changed.

Parameters:

	key	the key
	str	the value to be read

Returns:

true if value has been found and set

bool wx.Config.RenameEntry	(	string	oldName,
		string	newName
	)

bool wx.Config.RenameGroup	(	string	oldName,
		string	newName
	)

static Config wx.Config.Set

(

Config

config

)

[static]

This method will set the argument as the current configuration returning the old instance of Config that has been the current configuration before calling this.

string wx.Config.WithEnvVarsExpanded

(

string

str

)

This is the equivalent to wxConfigEnvVarsExpanded(). This has to be renamed since EnvVarsExpanded is required as name of the property for automatic expansion.

bool wx.Config.Write	(	string	key,
		System.Xml.Serialization.IXmlSerializable	val
	)

This will write a serializable object identified by key.

bool wx.Config.Write	(	string	key,
		Colour	val
	)

bool wx.Config.Write	(	string	key,
		Font	val
	)

bool wx.Config.Write	(	string	key,
		bool	val
	)

bool wx.Config.Write	(	string	key,
		double	val
	)

bool wx.Config.Write	(	string	key,
		uint	val
	)

bool wx.Config.Write	(	string	key,
		int	val
	)

bool wx.Config.Write	(	string	key,
		string	val
	)

---

Property Documentation

string wx.Config.AppName [get, set]

Config wx.Config.Default [static, get, set]

bool wx.Config.ExpandEnvVars [get, set]

This read/write property defines automatic expansion of environment variables. Use WithEnvVarsExpanded() to read a string with expanded environment variables.

string wx.Config.Path [get, set]

Get or set the current path in the configuration: On reading the path: Path information is always absolute on reading. On setting the 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.

bool wx.Config.RecordDefaults [get, set]

ConfigStyle wx.Config.Style [get, set]

string wx.Config.VendorName [get, set]

---