added wxConfigBase documentation

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@583 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

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

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