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