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

\section{wxConfig classes overview}\label{wxconfigoverview}

Classes: \helpref{wxConfig}{wxconfigbase}

This overview briefly describes what the config classes are and what they are
for. All the details about how to use them may be found in the description of
the \helpref{wxConfigBase}{wxconfigbase} class and the documentation of the
file, registry and INI file based implementations mentions all the
features/limitations specific to each one of these versions.

The config classes provide a way to store some application configuration
information. They were especially designed for this usage and, although may
probably be used for many other things as well, should be limited to it. It
means that this information should be:

\begin{enumerate}\itemsep=0pt
\item Typed, i.e. strings or numbers for the moment. You can not store
binary data, for example.
\item Small. For instance, it is not recommended to use the Windows
registry for amounts of data more than a couple of kilobytes.
\item Not performance critical, neither from speed nor from a memory
consumption point of view.
\end{enumerate}

On the other hand, the features provided make them very useful for storing all
kinds of small to medium volumes of hierarchically-organized, heterogeneous
data. In short, this is a place where you can conveniently stuff all your data
(numbers and strings) organizing it in a tree where you use the
filesystem-like paths to specify the location of a piece of data. In
particular, these classes were designed to be as easy to use as possible.

From another point of view, they provide an interface which hides the
differences between the Windows registry and the standard Unix text format
configuration files. Other (future) implementations of wxConfigBase might also
understand GTK resource files or their analogues on the KDE side.

In any case, each implementation of wxConfigBase does its best to
make the data look the same way everywhere. Due to limitations of the underlying 
physical storage, it may not implement 100\% of the base class functionality.

There are groups of entries and the entries themselves. Each entry contains either a string or a number
(or a boolean value; support for other types of data such as dates or
timestamps is planned) and is identified by the full path to it: something
like /MyApp/UserPreferences/Colors/Foreground. The previous elements in the
path are the group names, and each name may contain an arbitrary number of entries
and subgroups. The path components are {\bf always} separated with a slash,
even though some implementations use the backslash internally. Further
details (including how to read/write these entries) may be found in 
the documentation for \helpref{wxConfigBase}{wxconfigbase}.
Commit	Line	Data
20e05ffb	1	\section{wxConfig classes overview}\label{wxconfigoverview}
9ee2d31c	2
42ff6409	3	Classes: \helpref{wxConfig}{wxconfigbase}
9ee2d31c	4
631f1bfe	5	This overview briefly describes what the config classes are and what they are
9ee2d31c VZ	6	for. All the details about how to use them may be found in the description of
	7	the \helpref{wxConfigBase}{wxconfigbase} class and the documentation of the
	8	file, registry and INI file based implementations mentions all the
	9	features/limitations specific to each one of these versions.
	10
	11	The config classes provide a way to store some application configuration
	12	information. They were especially designed for this usage and, although may
	13	probably be used for many other things as well, should be limited to it. It
	14	means that this information should be:
9a05fd8d	15
f6bcfd97	16	\begin{enumerate}\itemsep=0pt
9a05fd8d	17	\item Typed, i.e. strings or numbers for the moment. You can not store
9ee2d31c	18	binary data, for example.
9a05fd8d	19	\item Small. For instance, it is not recommended to use the Windows
9ee2d31c	20	registry for amounts of data more than a couple of kilobytes.
9a05fd8d	21	\item Not performance critical, neither from speed nor from a memory
9ee2d31c	22	consumption point of view.
9a05fd8d	23	\end{enumerate}
9ee2d31c	24
631f1bfe	25	On the other hand, the features provided make them very useful for storing all
f6bcfd97	26	kinds of small to medium volumes of hierarchically-organized, heterogeneous
9ee2d31c VZ	27	data. In short, this is a place where you can conveniently stuff all your data
	28	(numbers and strings) organizing it in a tree where you use the
	29	filesystem-like paths to specify the location of a piece of data. In
	30	particular, these classes were designed to be as easy to use as possible.
	31
	32	From another point of view, they provide an interface which hides the
	33	differences between the Windows registry and the standard Unix text format
	34	configuration files. Other (future) implementations of wxConfigBase might also
9a05fd8d	35	understand GTK resource files or their analogues on the KDE side.
9ee2d31c	36
631f1bfe	37	In any case, each implementation of wxConfigBase does its best to
7ad56d27 RN	38	make the data look the same way everywhere. Due to limitations of the underlying
7ad56d27 RN	39	physical storage, it may not implement 100\% of the base class functionality.
631f1bfe JS	40
	41	There are groups of entries and the entries themselves. Each entry contains either a string or a number
	42	(or a boolean value; support for other types of data such as dates or
9ee2d31c VZ	43	timestamps is planned) and is identified by the full path to it: something
9ee2d31c VZ	44	like /MyApp/UserPreferences/Colors/Foreground. The previous elements in the
631f1bfe	45	path are the group names, and each name may contain an arbitrary number of entries
9ee2d31c	46	and subgroups. The path components are {\bf always} separated with a slash,
631f1bfe JS	47	even though some implementations use the backslash internally. Further
	48	details (including how to read/write these entries) may be found in
	49	the documentation for \helpref{wxConfigBase}{wxconfigbase}.
62448488	50