docs/latex/wx/regkey.tex

   1 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
   2 %% Name:        regkey.tex
   3 %% Purpose:     wxRegKey docs
   4 %% Author:      Ryan Norton <wxprojects@comcast.net>, C.C.Chakkaradeep
   5 %% Modified by:
   6 %% Created:     2/5/2005
   7 %% RCS-ID:      $Id$
   8 %% Copyright:   (c) Ryan Norton (C.C.Chakkaradeep?)
   9 %% License:     wxWindows license
  10 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  11
  12 \section{\class{wxRegKey}}\label{wxregkey}
  13
  14 wxRegKey is a class representing the Windows registry (it is only available
  15 under Windows). One can create, query and delete registry keys using this
  16 class.
  17
  18 The Windows registry is easy to understand. There are five registry keys,
  19 namely:
  20
  21 \begin{enumerate}\itemsep=0pt
  22 \item HKEY\_CLASSES\_ROOT (HKCR)
  23 \item HKEY\_CURRENT\_USER (HKCU)
  24 \item HKEY\_LOCAL\_MACHINE (HKLM)
  25 \item HKEY\_CURRENT\_CONFIG (HKCC)
  26 \item HKEY\_USERS (HKU)
  27 \end{enumerate}
  28
  29 After creating a key, it can hold a value. The values can be:
  30
  31 \begin{enumerate}\itemsep=0pt
  32 \item String Value
  33 \item Binary Value
  34 \item DWORD Value
  35 \item Multi String Value
  36 \item Expandable String Value
  37 \end{enumerate}
  38
  39 \wxheading{Derived from}
  40
  41 None
  42
  43 \wxheading{Include files}
  44
  45 <wx/msw/registry.h>
  46
  47 \wxheading{Library}
  48
  49 \helpref{wxBase}{librarieslist}
  50
  51 \wxheading{Example}
  52
  53 \begin{verbatim}
  54 wxRegKey *pRegKey = new wxRegKey("HKEY_LOCAL_MACHINE\\Software\\MyKey");
  55
  56 //will create the Key if it does not exist
  57 if( !pRegKey->Exists() )
  58     pRegKey->Create();
  59
  60 //will create a new value MYVALUE and set it to 12
  61 pRegKey->SetValue("MYVALUE",12);
  62
  63 //Query for the Value and Retrieve it
  64 long lMyVal;
  65 wxString strTemp;
  66 pRegKey->QueryValue("MYVALUE",&lMyVal);
  67 strTemp.Printf("%d",lMyVal);
  68 wxMessageBox(strTemp,"Registry Value",0,this);
  69
  70 //Retrive the number of SubKeys and enumerate them
  71 size_t nSubKeys;
  72 pRegKey->GetKeyInfo(&nSubKeys,NULL,NULL,NULL);
  73
  74 pRegKey->GetFirstKey(strTemp,1);
  75 for(int i=0;i<nSubKeys;i++)
  76 {
  77      wxMessageBox(strTemp,"SubKey Name",0,this);
  78      pRegKey->GetNextKey(strTemp,1);
  79 }
  80 \end{verbatim}
  81
  82 \latexignore{\rtfignore{\wxheading{Members}}}
  83
  84
  85 \membersection{wxRegKey::wxRegKey}\label{wxregkeyctor}
  86
  87 \func{}{wxRegKey}{\void}
  88
  89 The Constructor to set to HKCR
  90
  91 \func{}{wxRegKey}{\param{const wxString\&}{ strKey}}
  92
  93 The constructor to set the full name of the key.
  94
  95 \func{}{wxRegKey}{\param{const wxRegKey\&}{ keyParent}, \param{const wxString\&}{ strKey}}
  96
  97 The constructor to set the full name of the key under a previously created parent.
  98
  99
 100 \membersection{wxRegKey::Close}\label{wxregkeyclose}
 101
 102 \func{void}{Close}{\void}
 103
 104 Closes the key.
 105
 106
 107 \membersection{wxRegKey::Create}\label{wxregkeycreate}
 108
 109 \func{bool}{Create}{\param{bool }{bOkIfExists = true}}
 110
 111 Creates the key. Will fail if the key already exists and {\it bOkIfExists} is false.
 112
 113
 114 \membersection{wxRegKey::DeleteSelf}\label{wxregkeydeleteself}
 115
 116 \func{void}{DeleteSelf}{\void}
 117
 118 Deletes this key and all of its subkeys and values recursively.
 119
 120
 121 \membersection{wxRegKey::DeleteKey}\label{wxregkeydeletekey}
 122
 123 \func{void}{DeleteKey}{\param{const wxChar *}{szKey}}
 124
 125 Deletes the subkey with all of its subkeys/values recursively.
 126
 127
 128 \membersection{wxRegKey::DeleteValue}\label{wxregkeydeletevalue}
 129
 130 \func{void}{DeleteValue}{\param{const wxChar *}{szKey}}
 131
 132 Deletes the named value.
 133
 134
 135 \membersection{wxRegKey::Exists}\label{wxregkeyexists}
 136
 137 \constfunc{static bool}{Exists}{\void}
 138
 139 Returns true if the key exists.
 140
 141
 142 \membersection{wxRegKey::GetName}\label{wxregkeygetname}
 143
 144 \constfunc{wxString}{GetName}{\param{bool }{bShortPrefix = true}}
 145
 146 Gets the name of the registry key.
 147
 148
 149 \membersection{wxRegKey::GetFirstKey}\label{wxregkeygetfirstkey}
 150
 151 \func{bool}{GetFirstKey}{\param{wxString\&}{ strKeyName}, \param{long\&}{ lIndex}}
 152
 153 Gets the first key.
 154
 155
 156 \membersection{wxRegKey::GetFirstValue}\label{wxregkeygetfirstvalue}
 157
 158 \func{bool}{GetFirstValue}{\param{wxString\&}{ strValueName}, \param{long\&}{ lIndex}}
 159
 160 Gets the first value of this key.
 161
 162
 163 \membersection{wxRegKey::GetKeyInfo}\label{wxregkeygetkeyinfo}
 164
 165 \constfunc{bool}{GetKeyInfo}{\param{size\_t *}{pnSubKeys}, \param{size\_t *}{pnValues}, \param{size\_t *}{pnMaxValueLen}}
 166
 167 Gets information about the key.
 168
 169 \wxheading{Parameters}
 170
 171 \docparam{pnSubKeys}{The number of subkeys.}
 172
 173 \docparam{pnMaxKeyLen}{The maximum length of the subkey name.}
 174
 175 \docparam{pnValues}{The number of values.}
 176
 177 \docparam{pnMaxValueLen}{The maximum length of a value.}
 178
 179
 180 \membersection{wxRegKey::GetNextKey}\label{wxregkeygetnextkey}
 181
 182 \constfunc{bool}{GetNextKey}{\param{wxString\&}{ strKeyName}, \param{long\&}{ lIndex}}
 183
 184 Gets the next key.
 185
 186
 187 \membersection{wxRegKey::GetNextValue}\label{wxregkeygetnextvalue}
 188
 189 \constfunc{bool}{GetNextValue}{\param{wxString\&}{ strValueName}, \param{long\&}{ lIndex}}
 190
 191 Gets the next key value for this key.
 192
 193
 194 \membersection{wxRegKey::HasValue}\label{wxregkeyhasvalue}
 195
 196 \constfunc{bool}{HasValue}{\param{const wxChar *}{szValue}}
 197
 198 Returns true if the value exists.
 199
 200
 201 \membersection{wxRegKey::HasValues}\label{wxregkeyhasvalues}
 202
 203 \constfunc{bool}{HasValues}{\void}
 204
 205 Returns true if any values exist.
 206
 207
 208 \membersection{wxRegKey::HasSubKey}\label{wxregkeyhassubkey}
 209
 210 \constfunc{bool}{HasSubKey}{\param{const wxChar *}{szKey}}
 211
 212 Returns true if given subkey exists.
 213
 214
 215 \membersection{wxRegKey::HasSubKeys}\label{wxregkeyhassubkeys}
 216
 217 \constfunc{bool}{HasSubKeys}{\void}
 218
 219 Returns true if any subkeys exist.
 220
 221
 222 \membersection{wxRegKey::IsEmpty}\label{wxregkeyisempty}
 223
 224 \constfunc{bool}{IsEmpty}{\void}
 225
 226 Returns true if this key is empty, nothing under this key.
 227
 228
 229 \membersection{wxRegKey::IsOpened}\label{wxregkeyisopened}
 230
 231 \constfunc{bool}{IsOpened}{\void}
 232
 233 Returns true if the key is opened.
 234
 235
 236 \membersection{wxRegKey::Open}\label{wxregkeyopen}
 237
 238 \func{bool}{Open}{\param{AccessMode }{mode = Write}}
 239
 240 Explicitly opens the key. This method also allows the key to be opened in
 241 read-only mode by passing \texttt{wxRegKey::Read} instead of default
 242 \texttt{wxRegKey::Write} parameter.
 243
 244
 245 \membersection{wxRegKey::QueryValue}\label{wxregkeyqueryvalue}
 246
 247 \constfunc{bool}{QueryValue}{\param{const wxChar *}{szValue}, \param{wxString\&}{ strValue}}
 248
 249 Retrieves the string value.
 250
 251 \constfunc{bool}{QueryValue}{\param{const wxChar *}{szValue}, \param{long *}{plValue}}
 252
 253 Retrieves the numeric value.
 254
 255
 256 \membersection{wxRegKey::Rename}\label{wxregkeyrename}
 257
 258 \func{bool}{Rename}{\param{const wxChar *}{ szNewName}}
 259
 260 Renames the key.
 261
 262
 263 \membersection{wxRegKey::RenameValue}\label{wxregkeyrenamevalue}
 264
 265 \func{bool}{RenameValue}{\param{const wxChar *}{szValueOld}, \param{const wxChar *}{szValueNew}}
 266
 267 Renames a value.
 268
 269
 270 \membersection{wxRegKey::SetValue}\label{wxregkeysetvalue}
 271
 272 \func{bool}{SetValue}{\param{const wxChar *}{szValue}, \param{long}{ lValue}}
 273
 274 \func{bool}{SetValue}{\param{const wxChar *}{szValue}, \param{const wxString\&}{ strValue}}
 275
 276 \func{bool}{SetValue}{\param{const wxChar *}{szValue}, \param{const wxMemoryBuffer\&}{ buf}}
 277
 278 Sets the given \arg{szValue} which must be numeric, string or binary depending
 279 on the overload used. If the value doesn't exist, it is created.
 280