wx.Config Class Reference

Inheritance diagram for wx.Config:

wx.Object

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 DeleteEntry (string key)
bool DeleteGroup (string key)
void DontCreateOnDemand ()
bool Exists (string strName)
bool Flush (bool bCurrentOnly)
bool Flush ()
EntryType GetEntryType (string name)
System.Collections.Generic.IEnumerable
< string > 
GetEnumerableEntries ()
System.Collections.Generic.IEnumerable
< string > 
GetEnumerableGroups ()
System.Collections.Generic.IEnumerator
< string > 
GetEnumeratorOfEntries ()
System.Collections.Generic.IEnumerator
< string > 
GetEnumeratorOfGroups ()
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)
Point Read (string key, Point defVal)
Size Read (string key, Size defVal)
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 ReadPoint (string key, ref Point val)
bool ReadSize (string key, ref Size val)
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, Point pt)
bool Write (string key, Size size)
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 (ConfigStyle style)
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]

Classes

class  EntryEnumerator
class  GroupEnumerator


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 method 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 class only maintains (writes to) user specific configurations.

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

Delete the whole underlying object (disk file, registry key, ...). Primarly for use by uninstallation routine.

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

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

Parameters:
key The key of the entry to delete
bDeleteGroupIfEmpty If true the whole group will be deleted if this deleted the last entry

bool wx.Config.DeleteEntry ( string  key  ) 

Deletes the specified entry and the group it belongs to if it was the last key in it.

Parameters:
key The key of the entry to delete

bool wx.Config.DeleteGroup ( string  key  ) 

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.

Parameters:
key Designator of the group to be deleted

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  ) 

System.Collections.Generic.IEnumerable<string> wx.Config.GetEnumerableEntries (  ) 

Returns an enumerable collection of all contained groups. You may use this in foreach loops. Please keep care on the Path. The path shall always be the same on moving to the next entry.

System.Collections.Generic.IEnumerable<string> wx.Config.GetEnumerableGroups (  ) 

Returns an enumerable collection of all contained groups. You may use this in foreach loops. Please keep care on the Path. The path shall always be the same on moving to the next entry.

System.Collections.Generic.IEnumerator<string> wx.Config.GetEnumeratorOfEntries (  ) 

Returns an enumerator of all entries.

See also:
GetFirstEntry, GetNextEntry

System.Collections.Generic.IEnumerator<string> wx.Config.GetEnumeratorOfGroups (  ) 

Returns an enumerator of all groups.

See also:
GetFirstGroup, GetNextGroup

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

Gets the first entry in the configuration.

Parameters:
str Will be assigned with the name of the first entry.
lIndex This is an identifier for the enumeration.
Returns:
True on success.
See also:
GetEnumeratorOfEntries

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

Gets the first group in the configuration.

Parameters:
str Will be assigned with the name of the first group.
lIndex This is an identifier for the enumeration.
Returns:
True on success.
See also:
GetEnumeratorOfGroups

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

Gets the next entry in the configuration.

Parameters:
str Will be assigned with the name of the first entry.
lIndex This is an identifier for the enumeration.
Returns:
True on success.
See also:
GetEnumeratorOfEntries

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

Gets the next group in the configuration.

Parameters:
str Will be assigned with the name of the next group.
lIndex This is an identifier for the enumeration.
Returns:
True on success.
See also:
GetEnumeratorOfGroups

int wx.Config.GetNumberOfEntries ( bool  bRecursive  ) 

int wx.Config.GetNumberOfGroups ( bool  bRecursive  ) 

bool wx.Config.HasEntry ( string  strName  ) 

bool wx.Config.HasGroup ( string  strName  ) 

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

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

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.ReadPoint ( string  key,
ref Point  val 
)

Reads a point from this configuration using the specified key. The result is true on success. On success, the read value will be assigned to val. Otherwise, val will remain unchanged.

Parameters:
key The key that will be used to read the size
val The reference that will be used to return the result on success
Returns:
True on success.

bool wx.Config.ReadSize ( string  key,
ref Size  val 
)

Reads a size from this configuration using the specified key. The result is true on success. On success, the read value will be assigned to val. Otherwise, val will remain unchanged.

Parameters:
key The key that will be used to read the size
val The reference that will be used to return the result on success
Returns:
True on success.

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 ( ConfigStyle  style  )  [static]

Creates a new configuration using the provided style and returns the result. The new configuration will be the default instance returned by Get().

Parameters:
style A style describing the new instance.
Returns:

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,
Point  pt 
)

bool wx.Config.Write ( string  key,
Size  size 
)

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]

The name of the application.

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]

If true, all default values provided with Read() actions will be recorded.

ConfigStyle wx.Config.Style [get, set]

The style that has been used. You may also change this.

string wx.Config.VendorName [get, set]

The name of the vendor.


Manual of the wx.NET   (c) 2003-2011 the wx.NET project at   Get wx.NET at SourceForge.net. Fast, secure and Free Open Source software downloads