X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/749704355bd9ca68cfe629aa59af8fabb7dce0ff..2706e543a6923d8e743c6ec21fcfe898a52aec88:/docs/latex/wx/config.tex diff --git a/docs/latex/wx/config.tex b/docs/latex/wx/config.tex index b2969399f7..83c1e01824 100644 --- a/docs/latex/wx/config.tex +++ b/docs/latex/wx/config.tex @@ -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} @@ -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 - 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(".."); - wxASSERT( conf->Read("Subgroup/SubgroupEntry", 0l) == 3 ); + wxASSERT( conf->ReadLong("Subgroup/SubgroupEntry", 0) == 3 ); // 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 @@ -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... - wxASSERT( config->Read("Test", -1) == 17 ); + wxASSERT( config->ReadLong("Test", -1) == 17 ); } \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. -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 @@ -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{wxMBConv\&}{ conv = wxConvUTF8}} + \param{const wxMBConv\&}{ conv = wxConvAuto()}} This is the default and only constructor of the wxConfigBase class, and derived classes. @@ -377,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 @@ -454,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} @@ -653,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. -\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 @@ -697,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. +\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} @@ -716,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}} @@ -787,7 +837,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