From: Vadim Zeitlin <vadim@wxwidgets.org> Date: Mon, 17 Aug 1998 22:45:47 +0000 (+0000) Subject: added wxConfigBase documentation X-Git-Url: https://git.saurik.com/wxWidgets.git/commitdiff_plain/c4afa2cbfd9dba4ffbbe53ffc70d06b89bf4c619 added wxConfigBase documentation git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@583 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775 --- diff --git a/docs/latex/wx/classes.tex b/docs/latex/wx/classes.tex index 4b1eda6bc6..1cd0dc855e 100644 --- a/docs/latex/wx/classes.tex +++ b/docs/latex/wx/classes.tex @@ -46,6 +46,7 @@ $$\image{14cm;0cm}{wxclass.ps}$$ \input cmdevent.tex \input cmdproc.tex \input conditn.tex +\input config.tex \input control.tex \input cursor.tex \input database.tex @@ -96,6 +97,7 @@ $$\image{14cm;0cm}{wxclass.ps}$$ \input listbox.tex \input listctrl.tex \input listevt.tex +% \input log.tex \input mask.tex \input mdi.tex \input menu.tex diff --git a/docs/latex/wx/config.tex b/docs/latex/wx/config.tex new file mode 100644 index 0000000000..0fcdd00f62 --- /dev/null +++ b/docs/latex/wx/config.tex @@ -0,0 +1,411 @@ +\section{\class{wxConfigBase}}\label{wxconfigbase} + +wxConfigBase class defines the basic interface of all config classes. It can +not be used by itself (it's an abstract base class) and you'll always use one +of it's derivations: \helpref{wxIniConfig}{wxiniconfig}, +\helpref{wxFileConfig}{wxfileconfig}, \helpref{wxRegConfig}{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, wxWindows provides a typedef \helpref{wxConfig}{wxconfig} +which is mapped onto the native wxConfigBase implementation on the given +platform: i.e. wxRegConfig under Win32, wxIniConfig under Win16 and +wxFileConfig otherwise. + +See \helpref{config overview}{configoverview} for the descriptions of all +features of this class. + +\wxheading{Derived from} + +No base class + +\wxheading{Example} + +Here is how you would typically use this class: + +\begin{verbatim} + // using wxConfig instead of writing wxFileConfig or wxRegConfig enhances + // portability of the code + wxConfig *config = new wxConfig("MyAppName"); + + wxString str; + if ( config->Read(&str, "LastPrompt") ) { + // last prompt was found in the config file/registry and it's 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->Read("/LastRun/CalculatedValues/MaxValue", -1); + ... + ... + ... + // 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; +\end{verbatim} + +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, it's 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. + +NB: 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 it's data. + +\wxheading{See also} + +\helpref{wxIniConfig}{wxiniconfig}, \helpref{wxFileConfig}{wxfileconfig}, +\helpref{wxRegConfig}{wxregconfig} + +\latexignore{\rtfignore{\wxheading{Members}}} + +\membersection{static functions} + +These function deal with the "default" config object. Although it's 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 {\it Set()} it as the default. Then, from +anywhere in your program, you may access it using the {\it Get()} function. Of +course, you should delete it on the program termination (otherwise, not only a +memory leak will result, but even more importantly the changes won't be +written back!). + +As it happens, you may even further simplify the procedure described above: +you may forget about calling {\it Set()}. When {\it Get()} is called and there +is no current object, it will create one using {\it Create()} function. To +disable this behaviour {\it DontCreateOnDemand()} is provided. + +\func{wxConfigBase *}{Set}{\param{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 NULL) + +\func{wxConfigBase *}{Get}{\void} + +Get the current config object. If there is no current object, creates one +(using {\it Create}) unless DontCreateOnDemand was called previously. + +\func{wxConfigBase *}{Create}{\void} + +Create a new config object: this function will create the "best" +implementation of wxConfig available for the current platform, see +comments near definition wxCONFIG\_WIN32\_NATIVE for details. It returns +the created object and also sets it as the current one. + +\func{void}{DontCreateOnDemand}{\void} + +Calling this function will prevent {\it Get()} from automatically creating a +new config object if the current one is NULL. It might be useful to call it +near the program end to prevent new config object "accidental" creation. + +\membersection{ctor and dtor} + +\func{}{wxConfigBase}{\void} + +This is the default and only constructor of wxConfigBase class. It initializes +it options: by default, environment variable expansion is on and recording +defaults is off. + +\func{}{\destruct{wxConfigBase}}{\void} + +Empty but ensures that dtor of all derived classes is virtual. + +\membersection{path management} + +As explained in \helpref{config overview}{configoverview}, 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's only for the sake of demonstration, it doesn't do anything +sensible!): + +\begin{verbatim} + 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->Read("Subgroup/SubgroupEntry", 0l) == 3 ); + + // use absolute path: it's allowed, too + wxASSERT( conf->Read("/RootEntry", 0l) == 1 ); +\end{verbatim} + +{\it Warning}: it's probably a good idea to always restore the path to it's +old value on function exit: +\begin{verbatim} + void foo(wxConfigBase *config) + { + wxString strOldPath = config->GetPath(); + + config->SetPath("/Foo/Data"); + ... + + config->SetPath(strOldPath); + } +\end{verbatim} + +because otherwise the assert in the following example will surely fail +(we suppose here that {\it foo()} function is the same as above except that it +doesn't save and restore the path): + +\begin{verbatim} + void bar(wxConfigBase *config) + { + config->Write("Test", 17); + + foo(config); + + // we're reading "/Foo/Data/Test" here! -1 will probably be returned... + wxASSERT( config->Read("Test", -1) == 17 ); + } +\end{verbatim} + +Finally, the path separator in wxConfigBase and derived classes is always '/', +regardless of the platform (i.e. it's {\bf not} '\\' under Windows). + +\func{void}{SetPath}{\param{const wxString& }{strPath}} + +Set current path: if the first character is '/', it's the absolute path, +otherwise it's a relative path. '..' is supported. If the strPath +doesn't exist it is created. + +\func{const wxString& }{GetPath}{\void} const + +Retrieve the current path (always as absolute path). + +\membersection{enumeration} + +The functions in this section allow 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 lIndex to GetNext and GetFirst (don't modify it). +Please note that it's {\bf not} the index of the current item (you will have +some great surprizes with wxRegConfig if you assume this) and you shouldn't +even look at it: it's 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: + +\begin{verbatim} + 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... + +\end{verbatim} + +There are also functions to get th number of entries/subgroups without +actually enumerating them, but you will probably never need them. + +\func{bool }{GetFirstGroup}{\param{wxString& }{str}, \param{long&}{lIndex}} const + +\func{bool }{GetNextGroup}{\param{wxString& }{str}, \param{long&}{lIndex}} const + +\func{bool }{GetFirstEntry}{\param{wxString& }{str}, \param{long&}{lIndex}} const + +\func{bool }{GetNextEntry}{\param{wxString& }{str}, \param{long&}{lIndex}} const + +See the example above. + +\func{uint }{GetNumberOfEntries}{\param{bool }{bRecursive = FALSE}} const + +\func{uint }{GetNumberOfGroups}{\param{bool }{bRecursive = FALSE}} const + +Get number of entries/subgroups in the current group, with or without +it's subgroups. + +\membersection{tests of existence} + +\func{bool }{HasGroup}{\param{const wxString& }{strName}} const + +returns TRUE if the group by this name exists + +\func{bool }{HasEntryconst }{\param{wxString& }{strName}} const + +returns TRUE if the entry by this name exists + +\func{bool }{Existsconst }{\param{wxString& }{strName}} const + +returns TRUE if either a group or an entry with a given name exists + +\membersection{key access} + +These function are the core of wxConfigBase class: they allow you to read and +write config file data. All {\it Read} function take a default value which +will be returned if the specified key is not found in the config file. + +Currently, only two types of data are supported: string and long (but it might +change in the near future). To work with other types: for {\it int} or {\it +bool} you can work with function taking/returning {\it long} and just use the +casts. Better yet, just use {\it long} for all variables which you're going to +save in the config file: chances are that \verb{sizeof(bool) == sizeof(int) == +sizeof(long)} anyhow on your system. For {\it float}, {\it double} and, in +general, any other type you'd have to translate them to/from string +representation and use string functions. + +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 {\it szKey} parameter for all these functions can contain an +arbitrary path (either relative or absolute), not just the key name. + +\func{bool }{Read}{\param{wxString *}{pStr}, \param{const char *}{szKey}, \param{const char *}{szDefault = NULL}} const + +Read a string from the key: returns TRUE if value was really read, FALSE if +default was used (the default value is returned if the key wasn't found) + +\func{const char *}{Read }{\param{const char *}{szKey}, \param{const char *}{szDefault = NULL}} const + +Another version of {\it Read()} using static buffer. + +NB: although this function seems more convenient, you should only use it if +you know what you're doing! As it uses a static buffer, it means it will be +overwritten after each call to this function! If you do use it, you should +save the returned value to a wxString as soon as possible. + +\func{long }{Read}{\param{const char *}{szKey}, \param{long}{lDefault}} const + +Read a long value from the key and return it (lDefault is returned if key not +found). + +NB: writing +\begin{verbatim} + conf->Read("key", 0); +\end{verbatim} +won't work because the call is ambiguous: compiler can not choose between 2 +{\it Read} functions. Instead, just write +\begin{verbatim} + conf->Read("key", 0l); +\end{verbatim} + +\func{bool }{Read }{\param{long *}{pl}, \param{const char *}{szKey}, \param{long}{lDefault = 0}} const + +Another function for reading long values, it returns TRUE if the key was +really read from config file and FALSE if the default value was used. + +\func{bool}{Write}{\param{const char *}{szKey}, \param{const char *}{szValue}} +\func{bool}{Write}{\param{const char *}{szKey}, \param{long}{lValue}} + +Both of these functions write the specified value to the config file and +return true on success. + +\func{bool }{Flush}{\param{bool }{bCurrentOnly = FALSE}} + +permanently writes all changes (otherwise, they're only written from object's +destructor) + +\membersection{delete entries/groups} + +The functions in this section delete entries and/or groups of entries from the +config file. {\it DeleteAll()} is especially useful if you want to erase all +traces of your program presence: for example, when you uninstall it. + +\func{bool}{DeleteEntry}{\param{const char *}{szKey}, \param{bool}{bDeleteGroupIfEmpty = 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. + +\func{bool }{DeleteGroup}{\param{const char *}{szKey}} + +Delete the group (with all subgroups) + +\func{bool }{DeleteAll}{\void} + +Delete the whole underlying object (disk file, registry key, ...). Primarly +for use by desinstallation routine. + +\membersection{options} + +Some aspects of wxConfigBase behaviour can be changed during run-time. The +first of them is the expansion of environment variables in the string values +read from the config file: for example, if you have the following in your +config file: + +\begin{verbatim} + # config file for my program + UserData = $HOME/data + + # the following syntax is valud only under Windows + UserData = %windir%\\data.dat +\end{verbatim} + +the call to \verb{config->Read("UserData")} will return something like +\verb{"/home/zeitlin/data"} if you're lucky enough to run a Linux system ;-) + +Although this feature is very useful, it may be annoying if you read a value +which containts '\$' or '\%' symbols (\% is used for environment variables +expansion under Windows) which are not used for environment variable +expansion. In this situation you may call SetExpandEnvVars(FALSE) just before +reading this value and SetExpandEnvVars(TRUE) just after. Another solution +would be to prefix the offending symbols with a backslash. + +Following functions control this option: + +\func{bool }{IsExpandingEnvVars}{\void} const + +\func{void }{SetExpandEnvVars }{\param{bool }{bDoIt = TRUE}} + +The second option is recording of the default values: if it's on (default +is off) all default values are written back to the config file. This allows +the user to see what config options may be changed and is probably useful only +for wxFileConfig. + +Following functions control this option: + +\func{void }{SetRecordDefaults }{\param{bool }{bDoIt = TRUE}} + +\func{bool }{IsRecordingDefaults }{\void} const