+ wxConfigBase defines the basic interface of all config classes. It can not
+ be used by itself (it is an abstract base class) and you will always use
+ one of its derivations: wxFileConfig, wxRegConfig or any other.
+
+ However, usually you don't even need to know the precise nature of the
+ class you're working with but you would just use the wxConfigBase methods.
+ This allows you to write the same code regardless of whether you're working
+ with the registry under Win32 or text-based config files under Unix (or
+ even Windows 3.1 .INI files if you're really unlucky). To make writing the
+ portable code even easier, wxWidgets provides a typedef wxConfig which is
+ mapped onto the native wxConfigBase implementation on the given platform:
+ i.e. wxRegConfig under Win32 and wxFileConfig otherwise.
+
+ See @ref overview_config for a description of all features of this class.
+
+ It is highly recommended to use static functions Get() and/or Set(), so
+ please have a look at them.
+
+ Related Include Files:
+
+ @li @c <wx/config.h> - Let wxWidgets choose a wxConfig class for your
+ platform.
+ @li @c <wx/confbase.h> - Base config class.
+ @li @c <wx/fileconf.h> - wxFileConfig class.
+ @li @c <wx/msw/regconf.h> - wxRegConfig class, see also wxRegKey.
+
+
+ @section configbase_example Example
+
+ Here is how you would typically use this class:
+
+ @code
+ // using wxConfig instead of writing wxFileConfig or wxRegConfig enhances
+ // portability of the code
+ wxConfig *config = new wxConfig("MyAppName");
+
+ wxString str;
+ if ( config->Read("LastPrompt", &str) ) {
+ // last prompt was found in the config file/registry and its value is
+ // now in str
+ // ...
+ }
+ else {
+ // no last prompt...
+ }
+
+ // another example: using default values and the full path instead of just
+ // key name: if the key is not found , the value 17 is returned
+ long value = config->ReadLong("/LastRun/CalculatedValues/MaxValue", 17);
+
+ // at the end of the program we would save everything back
+ config->Write("LastPrompt", str);
+ config->Write("/LastRun/CalculatedValues/MaxValue", value);
+
+ // the changes will be written back automatically
+ delete config;
+ @endcode
+
+ This basic example, of course, doesn't show all wxConfig features, such as
+ enumerating, testing for existence and deleting the entries and groups of
+ entries in the config file, its abilities to automatically store the
+ default values or expand the environment variables on the fly. However, the
+ main idea is that using this class is easy and that it should normally do
+ what you expect it to.
+
+ @note In the documentation of this class, the words "config file" also mean
+ "registry hive" for wxRegConfig and, generally speaking, might mean
+ any physical storage where a wxConfigBase-derived class stores its
+ data.
+
+
+ @section configbase_static Static Functions
+
+ The static functions provided deal with the "default" config object.
+ Although its usage is not at all mandatory it may be convenient to use a
+ global config object instead of creating and deleting the local config
+ objects each time you need one (especially because creating a wxFileConfig
+ object might be a time consuming operation). In this case, you may create
+ this global config object in the very start of the program and Set() it as
+ the default. Then, from anywhere in your program, you may access it using
+ the Get() function. This global wxConfig object will be deleted by
+ wxWidgets automatically if it exists. Note that this implies that if you do
+ delete this object yourself (usually in wxApp::OnExit()) you must use
+ Set(@NULL) to prevent wxWidgets from deleting it the second time.
+
+ As it happens, you may even further simplify the procedure described above:
+ you may forget about calling Set(). When Get() is called and there is no
+ current object, it will create one using Create() function. To disable this
+ behaviour DontCreateOnDemand() is provided.
+
+ @note You should use either Set() or Get() because wxWidgets library itself
+ would take advantage of it and could save various information in it.
+ For example wxFontMapper or Unix version of wxFileDialog have the
+ ability to use wxConfig class.
+
+
+ @section configbase_paths Path Management
+
+ As explained in the @ref overview_config "config overview", the config
+ classes support a file system-like hierarchy of keys (files) and groups
+ (directories). As in the file system case, to specify a key in the config
+ class you must use a path to it. Config classes also support the notion of
+ the current group, which makes it possible to use the relative paths. To
+ clarify all this, here is an example (it is only for the sake of
+ demonstration, it doesn't do anything sensible!):
+
+ @code
+ wxConfig *config = new wxConfig("FooBarApp");
+
+ // right now the current path is '/'
+ conf->Write("RootEntry", 1);
+
+ // go to some other place: if the group(s) don't exist, they will be created
+ conf->SetPath("/Group/Subgroup");
+
+ // create an entry in subgroup
+ conf->Write("SubgroupEntry", 3);
+
+ // '..' is understood
+ conf->Write("../GroupEntry", 2);
+ conf->SetPath("..");
+
+ wxASSERT( conf->ReadLong("Subgroup/SubgroupEntry", 0) == 3 );
+
+ // use absolute path: it is allowed, too
+ wxASSERT( conf->ReadLong("/RootEntry", 0) == 1 );
+ @endcode
+
+ It is highly recommended that you restore the path to its old value on
+ function exit:
+
+ @code
+ void foo(wxConfigBase *config)
+ {
+ wxString strOldPath = config->GetPath();
+
+ config->SetPath("/Foo/Data");
+ // ...
+
+ config->SetPath(strOldPath);
+ }
+ @endcode
+
+ Otherwise the assert in the following example will surely fail (we suppose
+ here that the foo() function is the same as above except that it doesn’t
+ save and restore the path):
+
+ @code
+ void bar(wxConfigBase *config)
+ {
+ config->Write("Test", 17);
+
+ foo(config);
+
+ // we're reading "/Foo/Data/Test" here! -1 will probably be returned...
+ wxASSERT( config->ReadLong("Test", -1) == 17 );
+ }
+ @endcode
+
+ Finally, the path separator in wxConfigBase and derived classes is always
+ "/", regardless of the platform (i.e. it is not "\\" under Windows).
+
+
+ @section configbase_enumeration Enumeration
+
+ The enumeration functions allow you to enumerate all entries and groups in
+ the config file. All functions here return @false when there are no more
+ items.
+
+ You must pass the same index to GetNext() and GetFirst() (don't modify it).
+ Please note that it is not the index of the current item (you will have
+ some great surprises with wxRegConfig if you assume this) and you shouldn't
+ even look at it: it is just a "cookie" which stores the state of the
+ enumeration. It can't be stored inside the class because it would prevent
+ you from running several enumerations simultaneously, that's why you must
+ pass it explicitly.
+
+ Having said all this, enumerating the config entries/groups is very simple:
+
+ @code
+ wxConfigBase *config = ...;
+ wxArrayString aNames;
+
+ // enumeration variables
+ wxString str;
+ long dummy;
+
+ // first enum all entries
+ bool bCont = config->GetFirstEntry(str, dummy);
+ while ( bCont ) {
+ aNames.Add(str);
+
+ bCont = GetConfig()->GetNextEntry(str, dummy);
+ }
+
+ // ... we have all entry names in aNames...
+
+ // now all groups...
+ bCont = GetConfig()->GetFirstGroup(str, dummy);
+ while ( bCont ) {
+ aNames.Add(str);
+
+ bCont = GetConfig()->GetNextGroup(str, dummy);
+ }
+
+ // ... we have all group (and entry) names in aNames...
+ @endcode
+
+ There are also functions to get the number of entries/subgroups without
+ actually enumerating them, but you will probably never need them.
+
+
+ @section configbase_keyaccess Key Access
+
+ The key access functions are the core of wxConfigBase class: they allow you
+ to read and write config file data. All Read() functions take a default
+ value which will be returned if the specified key is not found in the
+ config file.
+
+ Currently, supported types of data are: wxString, @c long, @c double,
+ @c bool, wxColour and any other types for which the functions
+ wxToString() and wxFromString() are defined.
+
+ Try not to read long values into string variables and vice versa:
+ although it just might work with wxFileConfig, you will get a system
+ error with wxRegConfig because in the Windows registry the different
+ types of entries are indeed used.
+
+ Final remark: the @a szKey parameter for all these functions can
+ contain an arbitrary path (either relative or absolute), not just the
+ key name.
+
+ @beginWxPythonOnly
+ In place of a single overloaded method name, wxPython implements the
+ following methods:
+ - Read(key, default="") - Returns a string.
+ - ReadInt(key, default=0) - Returns an integer.
+ - ReadFloat(key, default=0.0) - Returns a floating point number.
+ - ReadBool(key, default=0) - Returns a boolean.
+ - Write(key, value) - Writes a string.
+ - WriteInt(key, value) - Writes an int.
+ - WriteFloat(key, value) - Writes a floating point number.
+ @endWxPythonOnly
+
projects / wxWidgets.git / blobdiff