documentation for window ids allocation and wxIdManager (patch 1870570)

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

diff --git a/docs/latex/wx/config.tex b/docs/latex/wx/config.tex
index d7f6d8efcdb2b4e34cd66eb147ca64320233fcd4..83c1e018246dca37a99b3be997363f36a9a31785 100644 (file)
--- a/docs/latex/wx/config.tex
+++ b/docs/latex/wx/config.tex
@@ -53,7 +53,7 @@ Here is how you would typically use this class:
 
   // 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
 
   // 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", 17);
+  long value = config->ReadLong("/LastRun/CalculatedValues/MaxValue", 17);

   ...
   ...
   ...
   ...
   ...
   ...


@@ -141,10 +141,10 @@ sensible!):
   conf->Write("../GroupEntry", 2);
   conf->SetPath("..");
 
   conf->Write("../GroupEntry", 2);
   conf->SetPath("..");
 

-  wxASSERT( conf->Read("Subgroup/SubgroupEntry", 0l) == 3 );
+  wxASSERT( conf->ReadLong("Subgroup/SubgroupEntry", 0) == 3 );

 
   // use absolute path: it is allowed, too
 
   // use absolute path: it is allowed, too

-  wxASSERT( conf->Read("/RootEntry", 0l) == 1 );
+  wxASSERT( conf->ReadLong("/RootEntry", 0) == 1 );

 \end{verbatim}
 
 {\it Warning}: it is probably a good idea to always restore the path to its
 \end{verbatim}
 
 {\it Warning}: it is probably a good idea to always restore the path to its


@@ -174,7 +174,7 @@ doesn't save and restore the path):
     foo(config);
 
     // we're reading "/Foo/Data/Test" here! -1 will probably be returned...
     foo(config);
 
     // we're reading "/Foo/Data/Test" here! -1 will probably be returned...

-    wxASSERT( config->Read("Test", -1) == 17 );
+    wxASSERT( config->ReadLong("Test", -1) == 17 );

   }
 \end{verbatim}
 
   }
 \end{verbatim}
 


@@ -262,13 +262,11 @@ 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.
 
 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 {\tt 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.
+Currently, supported types of data are:
+\helpref{wxString}{wxstring}, {\it long}, {\it double}, {\it bool},
+\helpref{wxColour}{wxcolour} and any other types,
+for which functions \helpref{wxToString}{wxtostring}
+and \helpref{wxFromString}{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
 
 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


@@ -353,7 +351,7 @@ The following functions control this option:
  \param{const wxString\& }{localFilename = wxEmptyString},
  \param{const wxString\& }{globalFilename = wxEmptyString},
  \param{long}{ style = 0},
  \param{const wxString\& }{localFilename = wxEmptyString},
  \param{const wxString\& }{globalFilename = wxEmptyString},
  \param{long}{ style = 0},

- \param{wxMBConv\&}{ conv = wxConvUTF8}}
+ \param{const wxMBConv\&}{ conv = wxConvAuto()}}

 
 This is the default and only constructor of the wxConfigBase class, and
 derived classes.
 
 This is the default and only constructor of the wxConfigBase class, and
 derived classes.


@@ -378,7 +376,11 @@ this is not present, but required, the application name will be used instead.}
 \docparam{style}{Can be one of wxCONFIG\_USE\_LOCAL\_FILE and
 wxCONFIG\_USE\_GLOBAL\_FILE. The style interpretation depends on the config
 class and is ignored by some implementations. For wxFileConfig, these styles
 \docparam{style}{Can be one of wxCONFIG\_USE\_LOCAL\_FILE and
 wxCONFIG\_USE\_GLOBAL\_FILE. The style interpretation depends on the config
 class and is ignored by some implementations. For wxFileConfig, these styles

-determine whether a local or global config file is created or used. If the
+determine whether a local or global config file is created or used: if
+wxCONFIG\_USE\_GLOBAL\_FILE is used, then settings are read from the global
+config file and if wxCONFIG\_USE\_LOCAL\_FILE is used, settings are read from
+and written to local config file (if they are both set, global file is read
+first, then local file, overwriting global settings). If the

 flag is present but the parameter is empty, the parameter will be set to a
 default. If the parameter is present but the style flag not, the relevant flag
 will be added to the style. For wxRegConfig, thie GLOBAL flag refers to HKLM
 flag is present but the parameter is empty, the parameter will be set to a
 default. If the parameter is present but the style flag not, the relevant flag
 will be added to the style. For wxRegConfig, thie GLOBAL flag refers to HKLM


@@ -668,28 +670,6 @@ not found, {\it l} is not changed.
 Reads a long value, returning \true if the value was found. If the value was
 not found, {\it defaultVal} is used instead.
 
 Reads a long value, returning \true if the value was found. If the value was
 not found, {\it defaultVal} is used instead.
 

-\constfunc{long }{Read}{\param{const wxString\& }{key}, \param{long}{ defaultVal}}
-
-Reads a long value from the key and returns it. {\it defaultVal} is returned
-if the key is not found.
-
-NB: writing
-
-{\small
-\begin{verbatim}
-    conf->Read("key", 0);
-\end{verbatim}
-}
-
-won't work because the call is ambiguous: compiler can not choose between two
-{\it Read} functions. Instead, write:
-
-{\small
-\begin{verbatim}
-    conf->Read("key", 0l);
-\end{verbatim}
-}
-

 \constfunc{bool}{Read}{\param{const wxString\& }{ key}, \param{double*}{ d}}
 
 Reads a double value, returning \true if the value was found. If the value was
 \constfunc{bool}{Read}{\param{const wxString\& }{ key}, \param{double*}{ d}}
 
 Reads a double value, returning \true if the value was found. If the value was


@@ -712,6 +692,28 @@ not found, {\it b} is not changed.
 Reads a bool value, returning \true if the value was found. If the value was
 not found, {\it defaultVal} is used instead.
 
 Reads a bool value, returning \true if the value was found. If the value was
 not found, {\it defaultVal} is used instead.
 

+\constfunc{bool}{Read}{\param{const wxString\& }{ key}, \param{wxMemoryBuffer*}{ buf}}
+
+Reads a binary block, returning \true if the value was found. If the value was
+not found, {\it buf} is not changed.
+
+\constfunc{bool}{Read}{\param{const wxString\& }{ key}, \param{T*}{ value}}
+
+Reads a value of type T, for which function
+\helpref{wxFromString}{wxfromstring} is defined,
+returning \true if the value was found.
+If the value was not found, {\it value} is not changed.
+
+\constfunc{bool}{Read}{\param{const wxString\& }{ key}, \param{T*}{ value},
+                       \param{T const\& }{ defaultVal}}
+
+Reads a value of type T, for which function
+\helpref{wxFromString}{wxfromstring} is defined,
+returning \true if the value was found.
+If the value was not found, {\it defaultVal} is used instead.
+
+bool Read(const wxString& key, T* value) const;
+

 \pythonnote{In place of a single overloaded method name, wxPython
 implements the following methods:\par
 \indented{2cm}{\begin{twocollist}
 \pythonnote{In place of a single overloaded method name, wxPython
 implements the following methods:\par
 \indented{2cm}{\begin{twocollist}


@@ -731,6 +733,39 @@ implements the following methods:\par
 }}
 
 
 }}
 
 

+\membersection{wxConfigBase::ReadBool}\label{wxconfigbasereadbool}
+
+\constfunc{long }{ReadBool}{\param{const wxString\& }{key}, \param{bool}{ defaultVal}}
+
+Reads a bool value from the key and returns it. {\it defaultVal} is returned
+if the key is not found.
+
+
+\membersection{wxConfigBase::ReadDouble}\label{wxconfigbasereaddouble}
+
+\constfunc{long }{ReadDouble}{\param{const wxString\& }{key}, \param{double}{ defaultVal}}
+
+Reads a double value from the key and returns it. {\it defaultVal} is returned
+if the key is not found.
+
+
+\membersection{wxConfigBase::ReadLong}\label{wxconfigbasereadlong}
+
+\constfunc{long }{ReadLong}{\param{const wxString\& }{key}, \param{long}{ defaultVal}}
+
+Reads a long value from the key and returns it. {\it defaultVal} is returned
+if the key is not found.
+
+
+\membersection{wxConfigBase::ReadObject}\label{wxconfigbasereadobject}
+
+\constfunc{T }{ReadObject}{\param{const wxString\& }{key}, \param{T const&}{ defaultVal}}
+
+Reads a value of type T, for which function
+\helpref{wxFromString}{wxfromstring} is defined, from the key and returns it. 
+{\it defaultVal} is returned if the key is not found.
+
+

 \membersection{wxConfigBase::RenameEntry}\label{wxconfigbaserenameentry}
 
 \func{bool}{RenameEntry}{\param{const wxString\& }{ oldName}, \param{const wxString\& }{ newName}}
 \membersection{wxConfigBase::RenameEntry}\label{wxconfigbaserenameentry}
 
 \func{bool}{RenameEntry}{\param{const wxString\& }{ oldName}, \param{const wxString\& }{ newName}}


@@ -802,7 +837,13 @@ value}}
 
 \func{bool}{Write}{\param{const wxString\& }{ key}, \param{bool}{ value}}
 
 
 \func{bool}{Write}{\param{const wxString\& }{ key}, \param{bool}{ value}}
 

-These functions write the specified value to the config file and return \true on success.
+\func{bool}{Write}{\param{const wxString\& }{ key}, \param{const wxMemoryBuffer\&}{ buf}}
+
+\func{bool}{Write}{\param{const wxString\& }{ key}, \param{const T\&}{ buf}}
+
+These functions write the specified value to the config file and return \true
+on success. In the last one, function \helpref{wxToString}{wxtostring} must be
+defined for type {\it T}.

 
 \pythonnote{In place of a single overloaded method name, wxPython
 implements the following methods:\par
 
 \pythonnote{In place of a single overloaded method name, wxPython
 implements the following methods:\par