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}{Exists}{\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
 178 \membersection{wxRegKey::GetNextKey}\label{wxregkeygetnextkey}
 179
 180 \constfunc{bool}{GetNextKey}{\param{wxString\&}{ strKeyName}, \param{long\&}{ lIndex}}
 181
 182 Gets the next key.
 183
 184
 185 \membersection{wxRegKey::GetNextValue}\label{wxregkeygetnextvalue}
 186
 187 \constfunc{bool}{GetNextValue}{\param{wxString\&}{ strValueName}, \param{long\&}{ lIndex}}
 188
 189 Gets the next key value for this key.
 190
 191
 192 \membersection{wxRegKey::HasValue}\label{wxregkeyhasvalue}
 193
 194 \constfunc{bool}{HasValue}{\param{const wxChar *}{szValue}}
 195
 196 Returns true if the value exists.
 197
 198
 199 \membersection{wxRegKey::HasValues}\label{wxregkeyhasvalues}
 200
 201 \constfunc{bool}{HasValues}{\void}
 202
 203 Returns true if any values exist.
 204
 205
 206 \membersection{wxRegKey::HasSubKey}\label{wxregkeyhassubkey}
 207
 208 \constfunc{bool}{HasSubKey}{\param{const wxChar *}{szKey}}
 209
 210 Returns true if given subkey exists.
 211
 212
 213 \membersection{wxRegKey::HasSubKeys}\label{wxregkeyhassubkeys}
 214
 215 \constfunc{bool}{HasSubKeys}{\void}
 216
 217 Returns true if any subkeys exist.
 218
 219
 220 \membersection{wxRegKey::IsEmpty}\label{wxregkeyisempty}
 221
 222 \constfunc{bool}{IsEmpty}{\void}
 223
 224 Returns true if this key is empty, nothing under this key.
 225
 226
 227 \membersection{wxRegKey::IsOpened}\label{wxregkeyisopened}
 228
 229 \constfunc{bool}{IsOpened}{\void}
 230
 231 Returns true if the key is opened.
 232
 233
 234 \membersection{wxRegKey::Open}\label{wxregkeyopen}
 235
 236 \func{bool}{Open}{\param{AccessMode }{mode = Write}}
 237
 238 Explicitly opens the key. This method also allows the key to be opened in
 239 read-only mode by passing \texttt{wxRegKey::Read} instead of default
 240 \texttt{wxRegKey::Write} parameter.
 241
 242
 243 \membersection{wxRegKey::QueryValue}\label{wxregkeyqueryvalue}
 244
 245 \constfunc{bool}{QueryValue}{\param{const wxChar *}{szValue}, \param{wxString\&}{ strValue}}
 246
 247 Retrieves the string value.
 248
 249 \constfunc{bool}{QueryValue}{\param{const wxChar *}{szValue}, \param{long *}{plValue}}
 250
 251 Retrieves the numeric value.
 252
 253
 254 \membersection{wxRegKey::Rename}\label{wxregkeyrename}
 255
 256 \func{bool}{Rename}{\param{const wxChar *}{ szNewName}}
 257
 258 Renames the key.
 259
 260
 261 \membersection{wxRegKey::RenameValue}\label{wxregkeyrenamevalue}
 262
 263 \func{bool}{RenameValue}{\param{const wxChar *}{szValueOld}, \param{const wxChar *}{szValueNew}}
 264
 265 Renames a value.
 266
 267
 268 \membersection{wxRegKey::SetValue}\label{wxregkeysetvalue}
 269
 270 \func{bool}{SetValue}{\param{const wxChar *}{szValue}, \param{long}{ lValue}}
 271
 272 \func{bool}{SetValue}{\param{const wxChar *}{szValue}, \param{const wxString\&}{ strValue}}
 273
 274 \func{bool}{SetValue}{\param{const wxChar *}{szValue}, \param{const wxMemoryBuffer\&}{ buf}}
 275
 276 Sets the given \arg{szValue} which must be numeric, string or binary depending
 277 on the overload used. If the value doesn't exist, it is created.
 278