]> git.saurik.com Git - wxWidgets.git/blobdiff - docs/latex/wx/config.tex
many wxItemContainer-related changes:
[wxWidgets.git] / docs / latex / wx / config.tex
index a9c58e4168f3f8c1266f790b03cc04afaabee2f2..61c2136e6ad62059e227674075e8fed1f7f5c77d 100644 (file)
@@ -23,7 +23,7 @@ so please have a \helpref{look at them.}{wxconfigstaticfunctions}
 
 \wxheading{Derived from}
 
-No base class
+\helpref{wxObject}{wxobject}
 
 \wxheading{Include files}
 
@@ -88,8 +88,10 @@ 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.
-Note that you must delete this object (usually in \helpref{wxApp::OnExit}{wxapponexit}) 
-in order to avoid memory leaks, wxWidgets won't do it automatically.
+This global wxConfig object will be deleted by wxWidgets automatically if it
+exists. Note that this implies that if you do delete this object yourself
+(usually in \helpref{wxApp::OnExit}{wxapponexit}) you must use {\it Set(NULL)}
+to prevent wxWidgets from deleting it the second time.
 
 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
@@ -260,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.
 
-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
@@ -351,7 +351,7 @@ The following functions control this option:
  \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.
@@ -375,18 +375,34 @@ 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. For wxFileConfig, these styles determine whether
-a local or global config file is created or used. 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 wxFileConfig you can also add wxCONFIG\_USE\_RELATIVE\_PATH 
-by logically or'ing it to either of the \_FILE options to tell wxFileConfig to 
-use relative instead of absolute paths.  For wxFileConfig, you can also 
-add wxCONFIG\_USE\_NO\_ESCAPE\_CHARACTERS which will turn off character 
-escaping for the values of entries stored in the config file: for example 
-a {\it foo} key with some backslash characters will be stored as {\tt foo=C:$\backslash$mydir} instead
-of the usual storage of {\tt foo=C:$\backslash\backslash$mydir}.
-For wxRegConfig, this flag refers to HKLM, and provides read-only access.
+class and is ignored by some implementations. For wxFileConfig, these styles
+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
+key while LOCAL one is for the usual HKCU one.
+
+For wxFileConfig you can also add wxCONFIG\_USE\_RELATIVE\_PATH by logically
+or'ing it to either of the \_FILE options to tell wxFileConfig to use relative
+instead of absolute paths.
+
+On non-VMS Unix systems, the default local configuration file is \tt{~/.appname}.
+However, this path may be also used as user data directory
+(see \helpref{wxStandardPaths::GetUserDataDir}{wxstandardpathsgetuserdatadir}) if
+the application has several data files. In this case wxCONFIG\_USE\_SUBDIR
+flag, which changes the default local configuration file to \tt{~/.appname/appname}
+should be used. Notice that this flag is ignored if \textit{localFilename} is
+provided. \newsince{2.8.2}
+
+For wxFileConfig, you can also add wxCONFIG\_USE\_NO\_ESCAPE\_CHARACTERS which
+will turn off character escaping for the values of entries stored in the config
+file: for example a {\it foo} key with some backslash characters will be stored
+as {\tt foo=C:$\backslash$mydir} instead of the usual storage of {\tt
+foo=C:$\backslash\backslash$mydir}.
 
 The wxCONFIG\_USE\_NO\_ESCAPE\_CHARACTERS style can be helpful if your config 
 file must be read or written to by a non-wxWidgets program (which might not 
@@ -452,7 +468,10 @@ in it and the second parameter is true.
 
 \func{bool}{DeleteGroup}{\param{const wxString\& }{ key}}
 
-Delete the group (with all subgroups)
+Delete the group (with all subgroups). If the current path is under the group
+being deleted it is changed to its deepest still existing component. E.g. if
+the current path is \texttt{/A/B/C/D} and the group \texttt{C} is deleted the
+path becomes \texttt{/A/B}.
 
 
 \membersection{wxConfigBase::Exists}\label{wxconfigbaseexists}
@@ -695,6 +714,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.
 
+\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}
@@ -785,7 +826,13 @@ 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