]> git.saurik.com Git - wxWidgets.git/blame - docs/latex/wx/config.tex
added missing libraries to the requirements list
[wxWidgets.git] / docs / latex / wx / config.tex
CommitLineData
c4afa2cb
VZ
1\section{\class{wxConfigBase}}\label{wxconfigbase}
2
3wxConfigBase class defines the basic interface of all config classes. It can
f6bcfd97 4not be used by itself (it is an abstract base class) and you will always use one
7ad56d27 5of its derivations: \helpref{wxFileConfig}{wxfileconfig},
a121d720 6wxRegConfig or any other.
c4afa2cb
VZ
7
8However, usually you don't even need to know the precise nature of the class
9you're working with but you would just use the wxConfigBase methods. This
10allows you to write the same code regardless of whether you're working with
11the registry under Win32 or text-based config files under Unix (or even
12Windows 3.1 .INI files if you're really unlucky). To make writing the portable
fc2171bd 13code even easier, wxWidgets provides a typedef wxConfig
c4afa2cb 14which is mapped onto the native wxConfigBase implementation on the given
7ad56d27 15platform: i.e. wxRegConfig under Win32 and
c4afa2cb
VZ
16wxFileConfig otherwise.
17
5f3cd8a2
VZ
18See \helpref{config overview}{wxconfigoverview} for the descriptions of all
19features of this class.
c4afa2cb 20
eee786e9
VS
21It is highly recommended to use static functions {\it Get()} and/or {\it Set()},
22so please have a \helpref{look at them.}{wxconfigstaticfunctions}
23
c4afa2cb
VZ
24\wxheading{Derived from}
25
c4ec0ce8 26\helpref{wxObject}{wxobject}
c4afa2cb 27
954b8ae6
JS
28\wxheading{Include files}
29
fc2171bd 30<wx/config.h> (to let wxWidgets choose a wxConfig class for your platform)\\
954b8ae6 31<wx/confbase.h> (base config class)\\
2f930c85 32<wx/fileconf.h> (wxFileConfig class)\\
7ad56d27 33<wx/msw/regconf.h> (wxRegConfig class)
954b8ae6 34
c4afa2cb
VZ
35\wxheading{Example}
36
37Here is how you would typically use this class:
38
39\begin{verbatim}
40 // using wxConfig instead of writing wxFileConfig or wxRegConfig enhances
41 // portability of the code
42 wxConfig *config = new wxConfig("MyAppName");
43
44 wxString str;
052ae0e5 45 if ( config->Read("LastPrompt", &str) ) {
b8de493f 46 // last prompt was found in the config file/registry and its value is now
c4afa2cb
VZ
47 // in str
48 ...
49 }
50 else {
51 // no last prompt...
52 }
53
54 // another example: using default values and the full path instead of just
55 // key name: if the key is not found , the value 17 is returned
873fb06d 56 long value = config->Read("/LastRun/CalculatedValues/MaxValue", 17);
c4afa2cb
VZ
57 ...
58 ...
59 ...
60 // at the end of the program we would save everything back
61 config->Write("LastPrompt", str);
62 config->Write("/LastRun/CalculatedValues/MaxValue", value);
63
64 // the changes will be written back automatically
65 delete config;
66\end{verbatim}
67
68This basic example, of course, doesn't show all wxConfig features, such as
69enumerating, testing for existence and deleting the entries and groups of
b8de493f 70entries in the config file, its abilities to automatically store the default
c4afa2cb
VZ
71values or expand the environment variables on the fly. However, the main idea
72is that using this class is easy and that it should normally do what you
73expect it to.
74
75NB: in the documentation of this class, the words "config file" also mean
76"registry hive" for wxRegConfig and, generally speaking, might mean any
b8de493f 77physical storage where a wxConfigBase-derived class stores its data.
c4afa2cb 78
b8de493f 79\latexignore{\rtfignore{\wxheading{Function groups}}}
c4afa2cb 80
a121d720 81
eee786e9 82\membersection{Static functions}\label{wxconfigstaticfunctions}
c4afa2cb 83
052ae0e5 84These functions deal with the "default" config object. Although its usage is
c4afa2cb
VZ
85not at all mandatory it may be convenient to use a global config object
86instead of creating and deleting the local config objects each time you need
87one (especially because creating a wxFileConfig object might be a time
88consuming operation). In this case, you may create this global config object
89in the very start of the program and {\it Set()} it as the default. Then, from
b52ea5c5 90anywhere in your program, you may access it using the {\it Get()} function.
74970435
VZ
91This global wxConfig object will be deleted by wxWidgets automatically if it
92exists. Note that this implies that if you do delete this object yourself
93(usually in \helpref{wxApp::OnExit}{wxapponexit}) you must use {\it Set(NULL)}
94to prevent wxWidgets from deleting it the second time.
c4afa2cb
VZ
95
96As it happens, you may even further simplify the procedure described above:
97you may forget about calling {\it Set()}. When {\it Get()} is called and there
98is no current object, it will create one using {\it Create()} function. To
99disable this behaviour {\it DontCreateOnDemand()} is provided.
100
fc2171bd 101{\bf Note:} You should use either {\it Set()} or {\it Get()} because wxWidgets
eee786e9
VS
102library itself would take advantage of it and could save various information
103in it. For example \helpref{wxFontMapper}{wxfontmapper} or Unix version
43e8916f 104of \helpref{wxFileDialog}{wxfiledialog} have the ability to use wxConfig class.
eee786e9 105
b8de493f
JS
106\helpref{Set}{wxconfigbaseset}\\
107\helpref{Get}{wxconfigbaseget}\\
108\helpref{Create}{wxconfigbasecreate}\\
109\helpref{DontCreateOnDemand}{wxconfigbasedontcreateondemand}
c4afa2cb 110
a121d720 111
f510b7b2 112\membersection{Constructor and destructor}\label{congigconstructordestructor}
c4afa2cb 113
b8de493f
JS
114\helpref{wxConfigBase}{wxconfigbasector}\\
115\helpref{\destruct{wxConfigBase}}{wxconfigbasedtor}
c4afa2cb 116
a121d720 117
f510b7b2 118\membersection{Path management}\label{configpathmanagement}
c4afa2cb 119
5f3cd8a2
VZ
120As explained in \helpref{config overview}{wxconfigoverview}, the config classes
121support a file system-like hierarchy of keys (files) and groups (directories).
c4afa2cb
VZ
122As in the file system case, to specify a key in the config class you must use
123a path to it. Config classes also support the notion of the current group,
124which makes it possible to use the relative paths. To clarify all this, here
f6bcfd97 125is an example (it is only for the sake of demonstration, it doesn't do anything
c4afa2cb
VZ
126sensible!):
127
128\begin{verbatim}
129 wxConfig *config = new wxConfig("FooBarApp");
130
131 // right now the current path is '/'
132 conf->Write("RootEntry", 1);
133
134 // go to some other place: if the group(s) don't exist, they will be created
135 conf->SetPath("/Group/Subgroup");
136
137 // create an entry in subgroup
138 conf->Write("SubgroupEntry", 3);
21f280f4 139
c4afa2cb
VZ
140 // '..' is understood
141 conf->Write("../GroupEntry", 2);
142 conf->SetPath("..");
143
144 wxASSERT( conf->Read("Subgroup/SubgroupEntry", 0l) == 3 );
145
f6bcfd97 146 // use absolute path: it is allowed, too
c4afa2cb
VZ
147 wxASSERT( conf->Read("/RootEntry", 0l) == 1 );
148\end{verbatim}
149
f6bcfd97 150{\it Warning}: it is probably a good idea to always restore the path to its
c4afa2cb 151old value on function exit:
b8de493f 152
c4afa2cb
VZ
153\begin{verbatim}
154 void foo(wxConfigBase *config)
155 {
156 wxString strOldPath = config->GetPath();
157
158 config->SetPath("/Foo/Data");
159 ...
160
161 config->SetPath(strOldPath);
162 }
163\end{verbatim}
164
165because otherwise the assert in the following example will surely fail
166(we suppose here that {\it foo()} function is the same as above except that it
167doesn't save and restore the path):
168
169\begin{verbatim}
170 void bar(wxConfigBase *config)
171 {
172 config->Write("Test", 17);
21f280f4 173
c4afa2cb
VZ
174 foo(config);
175
176 // we're reading "/Foo/Data/Test" here! -1 will probably be returned...
177 wxASSERT( config->Read("Test", -1) == 17 );
178 }
179\end{verbatim}
180
181Finally, the path separator in wxConfigBase and derived classes is always '/',
f6bcfd97 182regardless of the platform (i.e. it is {\bf not} '$\backslash\backslash$' under Windows).
c4afa2cb 183
b8de493f
JS
184\helpref{SetPath}{wxconfigbasesetpath}\\
185\helpref{GetPath}{wxconfigbasegetpath}
c4afa2cb 186
a121d720 187
f510b7b2 188\membersection{Enumeration}\label{configenumeration}
c4afa2cb
VZ
189
190The functions in this section allow to enumerate all entries and groups in the
43e8916f 191config file. All functions here return \false when there are no more items.
c4afa2cb 192
b8de493f 193You must pass the same index to GetNext and GetFirst (don't modify it).
f6bcfd97 194Please note that it is {\bf not} the index of the current item (you will have
2edb0bde 195some great surprises with wxRegConfig if you assume this) and you shouldn't
f6bcfd97 196even look at it: it is just a "cookie" which stores the state of the
c4afa2cb
VZ
197enumeration. It can't be stored inside the class because it would prevent you
198from running several enumerations simultaneously, that's why you must pass it
199explicitly.
200
201Having said all this, enumerating the config entries/groups is very simple:
202
203\begin{verbatim}
aefcdeee 204 wxConfigBase *config = ...;
c4afa2cb
VZ
205 wxArrayString aNames;
206
207 // enumeration variables
208 wxString str;
209 long dummy;
210
211 // first enum all entries
212 bool bCont = config->GetFirstEntry(str, dummy);
213 while ( bCont ) {
214 aNames.Add(str);
215
216 bCont = GetConfig()->GetNextEntry(str, dummy);
217 }
218
219 ... we have all entry names in aNames...
220
221 // now all groups...
222 bCont = GetConfig()->GetFirstGroup(str, dummy);
223 while ( bCont ) {
224 aNames.Add(str);
225
226 bCont = GetConfig()->GetNextGroup(str, dummy);
227 }
228
229 ... we have all group (and entry) names in aNames...
230
231\end{verbatim}
232
b8de493f 233There are also functions to get the number of entries/subgroups without
c4afa2cb
VZ
234actually enumerating them, but you will probably never need them.
235
b8de493f
JS
236\helpref{GetFirstGroup}{wxconfigbasegetfirstgroup}\\
237\helpref{GetNextGroup}{wxconfigbasegetnextgroup}\\
238\helpref{GetFirstEntry}{wxconfigbasegetfirstentry}\\
239\helpref{GetNextEntry}{wxconfigbasegetnextentry}\\
240\helpref{GetNumberOfEntries}{wxconfigbasegetnumberofentries}\\
241\helpref{GetNumberOfGroups}{wxconfigbasegetnumberofgroups}
c4afa2cb 242
a121d720 243
f510b7b2 244\membersection{Tests of existence}\label{configtestsofexistence}
c4afa2cb 245
b8de493f
JS
246\helpref{HasGroup}{wxconfigbasehasgroup}\\
247\helpref{HasEntry}{wxconfigbasehasentry}\\
19d40bab
VZ
248\helpref{Exists}{wxconfigbaseexists}\\
249\helpref{GetEntryType}{wxconfigbasegetentrytype}
c4afa2cb 250
a121d720 251
f510b7b2 252\membersection{Miscellaneous functions}\label{configmiscellaneous}
052ae0e5 253
052ae0e5 254\helpref{GetAppName}{wxconfigbasegetappname}\\
f6bcfd97
BP
255\helpref{GetVendorName}{wxconfigbasegetvendorname}\\
256\helpref{SetUmask}{wxfileconfigsetumask}
052ae0e5 257
a121d720 258
f510b7b2 259\membersection{Key access}\label{configkeyaccess}
c4afa2cb
VZ
260
261These function are the core of wxConfigBase class: they allow you to read and
262write config file data. All {\it Read} function take a default value which
263will be returned if the specified key is not found in the config file.
264
265Currently, only two types of data are supported: string and long (but it might
266change in the near future). To work with other types: for {\it int} or {\it
267bool} you can work with function taking/returning {\it long} and just use the
268casts. Better yet, just use {\it long} for all variables which you're going to
7af3ca16 269save 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
c4afa2cb
VZ
270general, any other type you'd have to translate them to/from string
271representation and use string functions.
272
273Try not to read long values into string variables and vice versa: although it
274just might work with wxFileConfig, you will get a system error with
275wxRegConfig because in the Windows registry the different types of entries are
276indeed used.
277
278Final remark: the {\it szKey} parameter for all these functions can contain an
279arbitrary path (either relative or absolute), not just the key name.
280
b8de493f
JS
281\helpref{Read}{wxconfigbaseread}\\
282\helpref{Write}{wxconfigbasewrite}\\
283\helpref{Flush}{wxconfigbaseflush}
284
a121d720 285
f510b7b2 286\membersection{Rename entries/groups}\label{configrenaming}
5d1902d6
VZ
287
288The functions in this section allow to rename entries or subgroups of the
43e8916f 289current group. They will return \false on error. typically because either the
5d1902d6
VZ
290entry/group with the original name doesn't exist, because the entry/group with
291the new name already exists or because the function is not supported in this
292wxConfig implementation.
293
294\helpref{RenameEntry}{wxconfigbaserenameentry}\\
295\helpref{RenameGroup}{wxconfigbaserenamegroup}
296
a121d720 297
f510b7b2 298\membersection{Delete entries/groups}\label{configdeleting}
b8de493f
JS
299
300The functions in this section delete entries and/or groups of entries from the
301config file. {\it DeleteAll()} is especially useful if you want to erase all
302traces of your program presence: for example, when you uninstall it.
303
304\helpref{DeleteEntry}{wxconfigbasedeleteentry}\\
305\helpref{DeleteGroup}{wxconfigbasedeletegroup}\\
306\helpref{DeleteAll}{wxconfigbasedeleteall}
307
a121d720 308
f510b7b2 309\membersection{Options}\label{configoptions}
b8de493f
JS
310
311Some aspects of wxConfigBase behaviour can be changed during run-time. The
312first of them is the expansion of environment variables in the string values
313read from the config file: for example, if you have the following in your
314config file:
315
316\begin{verbatim}
317 # config file for my program
318 UserData = $HOME/data
319
320 # the following syntax is valud only under Windows
321 UserData = %windir%\\data.dat
322\end{verbatim}
9722642d 323% $ % help EMACS syntax highlighting...
7af3ca16
VZ
324the call to {\tt config->Read("UserData")} will return something like
325{\tt "/home/zeitlin/data"} if you're lucky enough to run a Linux system ;-)
b8de493f
JS
326
327Although this feature is very useful, it may be annoying if you read a value
328which containts '\$' or '\%' symbols (\% is used for environment variables
329expansion under Windows) which are not used for environment variable
cc81d32f
VS
330expansion. In this situation you may call SetExpandEnvVars(false) just before
331reading this value and SetExpandEnvVars(true) just after. Another solution
b8de493f
JS
332would be to prefix the offending symbols with a backslash.
333
334The following functions control this option:
335
336\helpref{IsExpandingEnvVars}{wxconfigbaseisexpandingenvvars}\\
f6bcfd97 337\helpref{SetExpandEnvVars}{wxconfigbasesetexpandenvvars}\\
b8de493f
JS
338\helpref{SetRecordDefaults}{wxconfigbasesetrecorddefaults}\\
339\helpref{IsRecordingDefaults}{wxconfigbaseisrecordingdefaults}
340
341%%%%% MEMBERS HERE %%%%%
342\helponly{\insertatlevel{2}{
343
344\wxheading{Members}
345
346}}
347
a121d720 348
052ae0e5 349\membersection{wxConfigBase::wxConfigBase}\label{wxconfigbasector}
b8de493f 350
052ae0e5
JS
351\func{}{wxConfigBase}{\param{const wxString\& }{appName = wxEmptyString},
352 \param{const wxString\& }{vendorName = wxEmptyString},
353 \param{const wxString\& }{localFilename = wxEmptyString},
354 \param{const wxString\& }{globalFilename = wxEmptyString},
4561e95d 355 \param{long}{ style = 0},
5487ff0f 356 \param{const wxMBConv\&}{ conv = wxConvAuto()}}
b8de493f 357
5f3cd8a2
VZ
358This is the default and only constructor of the wxConfigBase class, and
359derived classes.
b8de493f 360
052ae0e5 361\wxheading{Parameters}
b8de493f 362
5f3cd8a2
VZ
363\docparam{appName}{The application name. If this is empty, the class will
364normally use \helpref{wxApp::GetAppName}{wxappgetappname} to set it. The
365application name is used in the registry key on Windows, and can be used to
366deduce the local filename parameter if that is missing.}
b8de493f 367
052ae0e5
JS
368\docparam{vendorName}{The vendor name. If this is empty, it is assumed that
369no vendor name is wanted, if this is optional for the current config class.
370The vendor name is appended to the application name for wxRegConfig.}
b8de493f 371
5f3cd8a2
VZ
372\docparam{localFilename}{Some config classes require a local filename. If this
373is not present, but required, the application name will be used instead.}
b8de493f 374
5f3cd8a2
VZ
375\docparam{globalFilename}{Some config classes require a global filename. If
376this is not present, but required, the application name will be used instead.}
b8de493f 377
5f3cd8a2
VZ
378\docparam{style}{Can be one of wxCONFIG\_USE\_LOCAL\_FILE and
379wxCONFIG\_USE\_GLOBAL\_FILE. The style interpretation depends on the config
04af2f5c 380class and is ignored by some implementations. For wxFileConfig, these styles
5e1fd3eb
VS
381determine whether a local or global config file is created or used: if
382wxCONFIG\_USE\_GLOBAL\_FILE is used, then settings are read from the global
383config file and if wxCONFIG\_USE\_LOCAL\_FILE is used, settings are read from
384and written to local config file (if they are both set, global file is read
385first, then local file, overwriting global settings). If the
04af2f5c
VZ
386flag is present but the parameter is empty, the parameter will be set to a
387default. If the parameter is present but the style flag not, the relevant flag
388will be added to the style. For wxRegConfig, thie GLOBAL flag refers to HKLM
389key while LOCAL one is for the usual HKCU one.
390
391For wxFileConfig you can also add wxCONFIG\_USE\_RELATIVE\_PATH by logically
392or'ing it to either of the \_FILE options to tell wxFileConfig to use relative
393instead of absolute paths.
394
395On non-VMS Unix systems, the default local configuration file is \tt{~/.appname}.
396However, this path may be also used as user data directory
397(see \helpref{wxStandardPaths::GetUserDataDir}{wxstandardpathsgetuserdatadir}) if
398the application has several data files. In this case wxCONFIG\_USE\_SUBDIR
399flag, which changes the default local configuration file to \tt{~/.appname/appname}
466e87bd
VZ
400should be used. Notice that this flag is ignored if \textit{localFilename} is
401provided. \newsince{2.8.2}
04af2f5c
VZ
402
403For wxFileConfig, you can also add wxCONFIG\_USE\_NO\_ESCAPE\_CHARACTERS which
404will turn off character escaping for the values of entries stored in the config
405file: for example a {\it foo} key with some backslash characters will be stored
406as {\tt foo=C:$\backslash$mydir} instead of the usual storage of {\tt
407foo=C:$\backslash\backslash$mydir}.
2b5f62a0 408
8dce54c9 409The wxCONFIG\_USE\_NO\_ESCAPE\_CHARACTERS style can be helpful if your config
fc2171bd 410file must be read or written to by a non-wxWidgets program (which might not
8dce54c9
VZ
411understand the escape characters). Note, however, that if
412wxCONFIG\_USE\_NO\_ESCAPE\_CHARACTERS style is used, it is is now
413your application's responsibility to ensure that there is no newline or
414other illegal characters in a value, before writing that value to the file.}
b8de493f 415
b867ed68 416\docparam{conv}{This parameter is only used by wxFileConfig when compiled
3980000c 417in Unicode mode. It specifies the encoding in which the configuration file
b867ed68
VS
418is written.}
419
420
052ae0e5 421\wxheading{Remarks}
b8de493f 422
5f3cd8a2
VZ
423By default, environment variable expansion is on and recording defaults is
424off.
b8de493f 425
a121d720 426
052ae0e5 427\membersection{wxConfigBase::\destruct{wxConfigBase}}\label{wxconfigbasedtor}
b8de493f 428
052ae0e5 429\func{}{\destruct{wxConfigBase}}{\void}
b8de493f 430
052ae0e5 431Empty but ensures that dtor of all derived classes is virtual.
b8de493f 432
a121d720 433
b8de493f
JS
434\membersection{wxConfigBase::Create}\label{wxconfigbasecreate}
435
052ae0e5 436\func{static wxConfigBase *}{Create}{\void}
b8de493f
JS
437
438Create a new config object: this function will create the "best"
5f3cd8a2
VZ
439implementation of wxConfig available for the current platform, see comments
440near the definition of wxCONFIG\_WIN32\_NATIVE for details. It returns the
441created object and also sets it as the current one.
b8de493f 442
a121d720 443
b8de493f
JS
444\membersection{wxConfigBase::DontCreateOnDemand}\label{wxconfigbasedontcreateondemand}
445
446\func{void}{DontCreateOnDemand}{\void}
447
448Calling this function will prevent {\it Get()} from automatically creating a
449new config object if the current one is NULL. It might be useful to call it
43e8916f 450near the program end to prevent "accidental" creation of a new config object.
b8de493f 451
a121d720 452
052ae0e5 453\membersection{wxConfigBase::DeleteAll}\label{wxconfigbasedeleteall}
b8de493f 454
052ae0e5 455\func{bool}{DeleteAll}{\void}
b8de493f 456
052ae0e5 457Delete the whole underlying object (disk file, registry key, ...). Primarly
43e8916f 458for use by uninstallation routine.
b8de493f 459
a121d720 460
052ae0e5 461\membersection{wxConfigBase::DeleteEntry}\label{wxconfigbasedeleteentry}
b8de493f 462
cc81d32f 463\func{bool}{DeleteEntry}{\param{const wxString\& }{ key}, \param{bool}{ bDeleteGroupIfEmpty = true}}
b8de493f 464
5f3cd8a2
VZ
465Deletes the specified entry and the group it belongs to if it was the last key
466in it and the second parameter is true.
b8de493f 467
a121d720 468
052ae0e5 469\membersection{wxConfigBase::DeleteGroup}\label{wxconfigbasedeletegroup}
b8de493f 470
052ae0e5 471\func{bool}{DeleteGroup}{\param{const wxString\& }{ key}}
b8de493f 472
41f30152
VZ
473Delete the group (with all subgroups). If the current path is under the group
474being deleted it is changed to its deepest still existing component. E.g. if
475the current path is \texttt{/A/B/C/D} and the group \texttt{C} is deleted the
476path becomes \texttt{/A/B}.
052ae0e5 477
a121d720 478
052ae0e5
JS
479\membersection{wxConfigBase::Exists}\label{wxconfigbaseexists}
480
481\constfunc{bool}{Exists}{\param{wxString\& }{strName}}
482
43e8916f 483returns \true if either a group or an entry with a given name exists
052ae0e5 484
a121d720 485
052ae0e5
JS
486\membersection{wxConfigBase::Flush}\label{wxconfigbaseflush}
487
cc81d32f 488\func{bool}{Flush}{\param{bool }{bCurrentOnly = false}}
052ae0e5
JS
489
490permanently writes all changes (otherwise, they're only written from object's
491destructor)
492
a121d720 493
052ae0e5
JS
494\membersection{wxConfigBase::Get}\label{wxconfigbaseget}
495
cc81d32f 496\func{static wxConfigBase *}{Get}{\param{bool }{CreateOnDemand = true}}
052ae0e5 497
eee786e9 498Get the current config object. If there is no current object and
cc81d32f 499{\it CreateOnDemand} is true, creates one
052ae0e5
JS
500(using {\it Create}) unless DontCreateOnDemand was called previously.
501
a121d720 502
052ae0e5
JS
503\membersection{wxConfigBase::GetAppName}\label{wxconfigbasegetappname}
504
505\constfunc{wxString}{GetAppName}{\void}
506
507Returns the application name.
508
a121d720 509
19d40bab
VZ
510\membersection{wxConfigBase::GetEntryType}\label{wxconfigbasegetentrytype}
511
512\constfunc{enum wxConfigBase::EntryType}{GetEntryType}{\param{const wxString\& }{name}}
513
514Returns the type of the given entry or {\it Unknown} if the entry doesn't
515exist. This function should be used to decide which version of Read() should
516be used because some of wxConfig implementations will complain about type
517mismatch otherwise: e.g., an attempt to read a string value from an integer
6776a0b2 518key with wxRegConfig will fail.
19d40bab
VZ
519
520The result is an element of enum EntryType:
521
522\begin{verbatim}
523 enum EntryType
524 {
43e8916f
MW
525 Type_Unknown,
526 Type_String,
527 Type_Boolean,
528 Type_Integer,
529 Type_Float
19d40bab
VZ
530 };
531\end{verbatim}
532
a121d720 533
052ae0e5
JS
534\membersection{wxConfigBase::GetFirstGroup}\label{wxconfigbasegetfirstgroup}
535
f6bcfd97 536\constfunc{bool}{GetFirstGroup}{\param{wxString\& }{str}, \param{long\&}{ index}}
052ae0e5
JS
537
538Gets the first group.
539
21f280f4
RD
540\pythonnote{The wxPython version of this method returns a 3-tuple
541consisting of the continue flag, the value string, and the index for
542the next call.}
543
9722642d
MB
544\perlnote{In wxPerl this method takes no arguments and returns a 3-element
545list {\tt ( continue, str, index )}.}
546
a121d720 547
052ae0e5
JS
548\membersection{wxConfigBase::GetFirstEntry}\label{wxconfigbasegetfirstentry}
549
f6bcfd97 550\constfunc{bool}{GetFirstEntry}{\param{wxString\& }{str}, \param{long\&}{ index}}
052ae0e5
JS
551
552Gets the first entry.
553
21f280f4
RD
554\pythonnote{The wxPython version of this method returns a 3-tuple
555consisting of the continue flag, the value string, and the index for
556the next call.}
557
9722642d
MB
558\perlnote{In wxPerl this method takes no arguments and returns a 3-element
559list {\tt ( continue, str, index )}.}
560
a121d720 561
052ae0e5
JS
562\membersection{wxConfigBase::GetNextGroup}\label{wxconfigbasegetnextgroup}
563
f6bcfd97 564\constfunc{bool}{GetNextGroup}{\param{wxString\& }{str}, \param{long\&}{ index}}
052ae0e5
JS
565
566Gets the next group.
567
21f280f4
RD
568\pythonnote{The wxPython version of this method returns a 3-tuple
569consisting of the continue flag, the value string, and the index for
570the next call.}
571
9722642d
MB
572\perlnote{In wxPerl this method only takes the {\tt index} parameter
573and returns a 3-element list {\tt ( continue, str, index )}.}
574
a121d720 575
052ae0e5
JS
576\membersection{wxConfigBase::GetNextEntry}\label{wxconfigbasegetnextentry}
577
f6bcfd97 578\constfunc{bool}{GetNextEntry}{\param{wxString\& }{str}, \param{long\&}{ index}}
052ae0e5
JS
579
580Gets the next entry.
581
21f280f4
RD
582\pythonnote{The wxPython version of this method returns a 3-tuple
583consisting of the continue flag, the value string, and the index for
584the next call.}
585
9722642d
MB
586\perlnote{In wxPerl this method only takes the {\tt index} parameter
587and returns a 3-element list {\tt ( continue, str, index )}.}
588
a121d720 589
052ae0e5
JS
590\membersection{wxConfigBase::GetNumberOfEntries}\label{wxconfigbasegetnumberofentries}
591
cc81d32f 592\constfunc{uint }{GetNumberOfEntries}{\param{bool }{bRecursive = false}}
052ae0e5 593
a121d720 594
052ae0e5
JS
595\membersection{wxConfigBase::GetNumberOfGroups}\label{wxconfigbasegetnumberofgroups}
596
cc81d32f 597\constfunc{uint}{GetNumberOfGroups}{\param{bool }{bRecursive = false}}
052ae0e5 598
5f3cd8a2
VZ
599Get number of entries/subgroups in the current group, with or without its
600subgroups.
b8de493f 601
a121d720 602
b8de493f
JS
603\membersection{wxConfigBase::GetPath}\label{wxconfigbasegetpath}
604
052ae0e5 605\constfunc{const wxString\&}{GetPath}{\void}
b8de493f
JS
606
607Retrieve the current path (always as absolute path).
608
a121d720 609
052ae0e5 610\membersection{wxConfigBase::GetVendorName}\label{wxconfigbasegetvendorname}
b8de493f 611
052ae0e5 612\constfunc{wxString}{GetVendorName}{\void}
b8de493f 613
052ae0e5 614Returns the vendor name.
b8de493f 615
a121d720 616
b8de493f
JS
617\membersection{wxConfigBase::HasEntry}\label{wxconfigbasehasentry}
618
619\constfunc{bool}{HasEntry}{\param{wxString\& }{strName}}
620
43e8916f 621returns \true if the entry by this name exists
b8de493f 622
a121d720 623
052ae0e5 624\membersection{wxConfigBase::HasGroup}\label{wxconfigbasehasgroup}
b8de493f 625
052ae0e5 626\constfunc{bool}{HasGroup}{\param{const wxString\& }{strName}}
b8de493f 627
43e8916f 628returns \true if the group by this name exists
052ae0e5 629
a121d720 630
052ae0e5
JS
631\membersection{wxConfigBase::IsExpandingEnvVars}\label{wxconfigbaseisexpandingenvvars}
632
633\constfunc{bool}{IsExpandingEnvVars}{\void}
634
43e8916f 635Returns \true if we are expanding environment variables in key values.
052ae0e5 636
a121d720 637
052ae0e5
JS
638\membersection{wxConfigBase::IsRecordingDefaults}\label{wxconfigbaseisrecordingdefaults}
639
f6bcfd97 640\constfunc{bool}{IsRecordingDefaults}{\void}
052ae0e5 641
43e8916f 642Returns \true if we are writing defaults back to the config file.
b8de493f 643
a121d720 644
b8de493f
JS
645\membersection{wxConfigBase::Read}\label{wxconfigbaseread}
646
f6bcfd97 647\constfunc{bool}{Read}{\param{const wxString\& }{key}, \param{wxString*}{ str}}
052ae0e5 648
43e8916f 649Read a string from the key, returning \true if the value was read. If the key
5f3cd8a2 650was not found, {\it str} is not changed.
052ae0e5 651
f6bcfd97 652\constfunc{bool}{Read}{\param{const wxString\& }{key}, \param{wxString*}{ str}, \param{const wxString\& }{defaultVal}}
052ae0e5 653
5f3cd8a2
VZ
654Read a string from the key. The default value is returned if the key was not
655found.
c4afa2cb 656
43e8916f 657Returns \true if value was really read, \false if the default was used.
c4afa2cb 658
5f3cd8a2
VZ
659\constfunc{wxString}{Read}{\param{const wxString\& }{key}, \param{const
660wxString\& }{defaultVal}}
c4afa2cb 661
052ae0e5 662Another version of {\it Read()}, returning the string value directly.
c4afa2cb 663
052ae0e5 664\constfunc{bool}{Read}{\param{const wxString\& }{ key}, \param{long*}{ l}}
c4afa2cb 665
43e8916f 666Reads a long value, returning \true if the value was found. If the value was
5f3cd8a2 667not found, {\it l} is not changed.
c4afa2cb 668
5f3cd8a2
VZ
669\constfunc{bool}{Read}{\param{const wxString\& }{ key}, \param{long*}{ l},
670\param{long}{ defaultVal}}
052ae0e5 671
43e8916f 672Reads a long value, returning \true if the value was found. If the value was
5f3cd8a2 673not found, {\it defaultVal} is used instead.
052ae0e5 674
f6bcfd97 675\constfunc{long }{Read}{\param{const wxString\& }{key}, \param{long}{ defaultVal}}
052ae0e5 676
5f3cd8a2
VZ
677Reads a long value from the key and returns it. {\it defaultVal} is returned
678if the key is not found.
c4afa2cb
VZ
679
680NB: writing
052ae0e5 681
6aa358ae
GT
682{\small
683\begin{verbatim}
684 conf->Read("key", 0);
685\end{verbatim}
686}
052ae0e5 687
5f3cd8a2
VZ
688won't work because the call is ambiguous: compiler can not choose between two
689{\it Read} functions. Instead, write:
052ae0e5 690
6aa358ae
GT
691{\small
692\begin{verbatim}
693 conf->Read("key", 0l);
694\end{verbatim}
695}
c4afa2cb 696
052ae0e5 697\constfunc{bool}{Read}{\param{const wxString\& }{ key}, \param{double*}{ d}}
c4afa2cb 698
43e8916f 699Reads a double value, returning \true if the value was found. If the value was
5f3cd8a2 700not found, {\it d} is not changed.
c4afa2cb 701
5f3cd8a2 702\constfunc{bool}{Read}{\param{const wxString\& }{ key}, \param{double*}{ d},
0d57be45 703 \param{double}{ defaultVal}}
b8de493f 704
43e8916f 705Reads a double value, returning \true if the value was found. If the value was
5f3cd8a2 706not found, {\it defaultVal} is used instead.
b8de493f 707
052ae0e5 708\constfunc{bool}{Read}{\param{const wxString\& }{ key}, \param{bool*}{ b}}
c4afa2cb 709
43e8916f 710Reads a bool value, returning \true if the value was found. If the value was
5f3cd8a2 711not found, {\it b} is not changed.
b8de493f 712
5f3cd8a2
VZ
713\constfunc{bool}{Read}{\param{const wxString\& }{ key}, \param{bool*}{ d},
714\param{bool}{ defaultVal}}
c4afa2cb 715
43e8916f 716Reads a bool value, returning \true if the value was found. If the value was
5f3cd8a2 717not found, {\it defaultVal} is used instead.
c4afa2cb 718
5814e8ba
VZ
719\constfunc{bool}{Read}{\param{const wxString\& }{ key}, \param{wxMemoryBuffer*}{ buf}}
720
721Reads a binary block, returning \true if the value was found. If the value was
722not found, {\it buf} is not changed.
723
21f280f4
RD
724\pythonnote{In place of a single overloaded method name, wxPython
725implements the following methods:\par
726\indented{2cm}{\begin{twocollist}
c9110876
VS
727\twocolitem{{\bf Read(key, default="")}}{Returns a string.}
728\twocolitem{{\bf ReadInt(key, default=0)}}{Returns an int.}
729\twocolitem{{\bf ReadFloat(key, default=0.0)}}{Returns a floating point number.}
21f280f4
RD
730\end{twocollist}}
731}
732
9722642d
MB
733\perlnote{In place of a single overloaded method, wxPerl uses:\par
734\indented{2cm}{\begin{twocollist}
735\twocolitem{{\bf Read(key, default="")}}{Returns a string}
736\twocolitem{{\bf ReadInt(key, default=0)}}{Returns an integer}
737\twocolitem{{\bf ReadFloat(key, default=0.0)}}{Returns a floating point number}
738\twocolitem{{\bf ReadBool(key, default=0)}}{Returns a boolean}
739\end{twocollist}
740}}
741
a121d720 742
5d1902d6
VZ
743\membersection{wxConfigBase::RenameEntry}\label{wxconfigbaserenameentry}
744
745\func{bool}{RenameEntry}{\param{const wxString\& }{ oldName}, \param{const wxString\& }{ newName}}
746
747Renames an entry in the current group. The entries names (both the old and
748the new one) shouldn't contain backslashes, i.e. only simple names and not
749arbitrary paths are accepted by this function.
750
43e8916f 751Returns \false if {\it oldName} doesn't exist or if {\it newName} already
5d1902d6
VZ
752exists.
753
a121d720 754
5d1902d6
VZ
755\membersection{wxConfigBase::RenameGroup}\label{wxconfigbaserenamegroup}
756
757\func{bool}{RenameGroup}{\param{const wxString\& }{ oldName}, \param{const wxString\& }{ newName}}
758
759Renames a subgroup of the current group. The subgroup names (both the old and
760the new one) shouldn't contain backslashes, i.e. only simple names and not
761arbitrary paths are accepted by this function.
762
43e8916f 763Returns \false if {\it oldName} doesn't exist or if {\it newName} already
5d1902d6
VZ
764exists.
765
a121d720 766
052ae0e5 767\membersection{wxConfigBase::Set}\label{wxconfigbaseset}
c4afa2cb 768
142b3bc2 769\func{static wxConfigBase *}{Set}{\param{wxConfigBase *}{pConfig}}
c4afa2cb 770
052ae0e5
JS
771Sets the config object as the current one, returns the pointer to the previous
772current object (both the parameter and returned value may be NULL)
c4afa2cb 773
a121d720 774
f6bcfd97 775\membersection{wxConfigBase::SetExpandEnvVars}\label{wxconfigbasesetexpandenvvars}
c4afa2cb 776
cc81d32f 777\func{void}{SetExpandEnvVars }{\param{bool }{bDoIt = true}}
b8de493f 778
052ae0e5 779Determine whether we wish to expand environment variables in key values.
c4afa2cb 780
a121d720 781
052ae0e5 782\membersection{wxConfigBase::SetPath}\label{wxconfigbasesetpath}
c4afa2cb 783
052ae0e5 784\func{void}{SetPath}{\param{const wxString\& }{strPath}}
c4afa2cb 785
f6bcfd97 786Set current path: if the first character is '/', it is the absolute path,
43e8916f 787otherwise it is a relative path. '..' is supported. If strPath doesn't
5f3cd8a2 788exist it is created.
c4afa2cb 789
a121d720 790
052ae0e5 791\membersection{wxConfigBase::SetRecordDefaults}\label{wxconfigbasesetrecorddefaults}
c4afa2cb 792
cc81d32f 793\func{void}{SetRecordDefaults}{\param{bool }{bDoIt = true}}
052ae0e5 794
cb3b65d4 795Sets whether defaults are recorded to the config file whenever an attempt to
43e8916f 796read the value which is not present in it is done.
c4afa2cb 797
cb3b65d4
VZ
798If on (default is off) all default values for the settings used by the program
799are written back to the config file. This allows the user to see what config
800options may be changed and is probably useful only for wxFileConfig.
c4afa2cb 801
f6bcfd97 802
052ae0e5
JS
803\membersection{wxConfigBase::Write}\label{wxconfigbasewrite}
804
5f3cd8a2
VZ
805\func{bool}{Write}{\param{const wxString\& }{ key}, \param{const wxString\& }{
806value}}
052ae0e5
JS
807
808\func{bool}{Write}{\param{const wxString\& }{ key}, \param{long}{ value}}
809
810\func{bool}{Write}{\param{const wxString\& }{ key}, \param{double}{ value}}
811
812\func{bool}{Write}{\param{const wxString\& }{ key}, \param{bool}{ value}}
813
5814e8ba
VZ
814\func{bool}{Write}{\param{const wxString\& }{ key}, \param{const wxMemoryBuffer\&}{ buf}}
815
43e8916f 816These functions write the specified value to the config file and return \true on success.
c4afa2cb 817
21f280f4
RD
818\pythonnote{In place of a single overloaded method name, wxPython
819implements the following methods:\par
820\indented{2cm}{\begin{twocollist}
c9110876
VS
821\twocolitem{{\bf Write(key, value)}}{Writes a string.}
822\twocolitem{{\bf WriteInt(key, value)}}{Writes an int.}
823\twocolitem{{\bf WriteFloat(key, value)}}{Writes a floating point number.}
21f280f4
RD
824\end{twocollist}}
825}
826
9722642d
MB
827\perlnote{In place of a single overloaded method, wxPerl uses:\par
828\indented{2cm}{\begin{twocollist}
829\twocolitem{{\bf Write(key, value)}}{Writes a string}
830\twocolitem{{\bf WriteInt(key, value)}}{Writes an integer}
831\twocolitem{{\bf WriteFloat(key, value)}}{Writes a floating point number}
832\twocolitem{{\bf WriteBool(key, value)}}{Writes a boolean}
833\end{twocollist}
834}}
dceb1c09 835