added wxConfigBase documentation

[wxWidgets.git] / docs / latex / wx / config.tex

\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