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{Example}
  48
  49 \begin{verbatim}
  50 wxRegKey *pRegKey = new wxRegKey("HKEY_LOCAL_MACHINE\\Software\\MyKey");
  51
  52 //will create the Key if it does not exist
  53 if( !pRegKey->Exists() )
  54     pRegKey->Create();
  55
  56 //will create a new value MYVALUE and set it to 12
  57 pRegKey->SetValue("MYVALUE",12);
  58
  59 //Query for the Value and Retrieve it
  60 long lMyVal;
  61 wxString strTemp;
  62 pRegKey->QueryValue("MYVALUE",&lMyVal);
  63 strTemp.Printf("%d",lMyVal);
  64 wxMessageBox(strTemp,"Registry Value",0,this);
  65
  66 //Retrive the number of SubKeys and enumerate them
  67 size_t nSubKeys;
  68 pRegKey->GetKeyInfo(&nSubKeys,NULL,NULL,NULL);
  69
  70 pRegKey->GetFirstKey(strTemp,1);
  71 for(int i=0;i<nSubKeys;i++)
  72 {
  73      wxMessageBox(strTemp,"SubKey Name",0,this);
  74      pRegKey->GetNextKey(strTemp,1);
  75 }
  76 \end{verbatim}
  77
  78 \latexignore{\rtfignore{\wxheading{Members}}}
  79
  80
  81 \membersection{wxRegKey::wxRegKey}\label{wxregkeyctor}
  82
  83 \func{}{wxRegKey}{\void}
  84
  85 The Constructor to set to HKCR
  86
  87 \func{}{wxRegKey}{\param{const wxString\&}{ strKey}}
  88
  89 The constructor to set the full name of the key.
  90
  91 \func{}{wxRegKey}{\param{const wxRegKey\&}{ keyParent}, \param{const wxString\&}{ strKey}}
  92
  93 The constructor to set the full name of the key under a previously created parent.
  94
  95
  96 \membersection{wxRegKey::Close}\label{wxregkeyclose}
  97
  98 \func{void}{Close}{\void}
  99
 100 Closes the key.
 101
 102
 103 \membersection{wxRegKey::Create}\label{wxregkeycreate}
 104
 105 \func{bool}{Create}{\param{bool }{bOkIfExists = true}}
 106
 107 Creates the key. Will fail if the key already exists and {\it bOkIfExists} is false.
 108
 109
 110 \membersection{wxRegKey::DeleteSelf}\label{wxregkeydeleteself}
 111
 112 \func{void}{DeleteSelf}{\void}
 113
 114 Deletes this key and all of its subkeys and values recursively.
 115
 116
 117 \membersection{wxRegKey::DeleteKey}\label{wxregkeydeletekey}
 118
 119 \func{void}{DeleteKey}{\param{const wxChar *}{szKey}}
 120
 121 Deletes the subkey with all of its subkeys/values recursively.
 122
 123
 124 \membersection{wxRegKey::DeleteValue}\label{wxregkeydeletevalue}
 125
 126 \func{void}{DeleteValue}{\param{const wxChar *}{szKey}}
 127
 128 Deletes the named value.
 129
 130
 131 \membersection{wxRegKey::Exists}\label{wxregkeyexists}
 132
 133 \constfunc{static bool}{Exists}{\void}
 134
 135 Returns true if the key exists.
 136
 137
 138 \membersection{wxRegKey::GetName}\label{wxregkeygetname}
 139
 140 \constfunc{wxString}{GetName}{\param{bool }{bShortPrefix = true}}
 141
 142 Gets the name of the registry key.
 143
 144
 145 \membersection{wxRegKey::GetFirstKey}\label{wxregkeygetfirstkey}
 146
 147 \func{bool}{GetFirstKey}{\param{wxString\&}{ strKeyName}, \param{long\&}{ lIndex}}
 148
 149 Gets the first key.
 150
 151
 152 \membersection{wxRegKey::GetFirstValue}\label{wxregkeygetfirstvalue}
 153
 154 \func{bool}{GetFirstValue}{\param{wxString\&}{ strValueName}, \param{long\&}{ lIndex}}
 155
 156 Gets the first value of this key.
 157
 158
 159 \membersection{wxRegKey::GetKeyInfo}\label{wxregkeygetkeyinfo}
 160
 161 \constfunc{bool}{Exists}{\param{size\_t *}{pnSubKeys}, \param{size\_t *}{pnValues}, \param{size\_t *}{pnMaxValueLen}}
 162
 163 Gets information about the key.
 164
 165 \wxheading{Parameters}
 166
 167 \docparam{pnSubKeys}{The number of subkeys.}
 168
 169 \docparam{pnMaxKeyLen}{The maximum length of the subkey name.}
 170
 171 \docparam{pnValues}{The number of values.}
 172
 173
 174 \membersection{wxRegKey::GetNextKey}\label{wxregkeygetnextkey}
 175
 176 \constfunc{bool}{GetNextKey}{\param{wxString\&}{ strKeyName}, \param{long\&}{ lIndex}}
 177
 178 Gets the next key.
 179
 180
 181 \membersection{wxRegKey::GetNextValue}\label{wxregkeygetnextvalue}
 182
 183 \constfunc{bool}{GetNextValue}{\param{wxString\&}{ strValueName}, \param{long\&}{ lIndex}}
 184
 185 Gets the next key value for this key.
 186
 187
 188 \membersection{wxRegKey::HasValue}\label{wxregkeyhasvalue}
 189
 190 \constfunc{bool}{HasValue}{\param{const wxChar *}{szValue}}
 191
 192 Returns true if the value exists.
 193
 194
 195 \membersection{wxRegKey::HasValues}\label{wxregkeyhasvalues}
 196
 197 \constfunc{bool}{HasValues}{\void}
 198
 199 Returns true if any values exist.
 200
 201
 202 \membersection{wxRegKey::HasSubKey}\label{wxregkeyhassubkey}
 203
 204 \constfunc{bool}{HasSubKey}{\param{const wxChar *}{szKey}}
 205
 206 Returns true if given subkey exists.
 207
 208
 209 \membersection{wxRegKey::HasSubKeys}\label{wxregkeyhassubkeys}
 210
 211 \constfunc{bool}{HasSubKeys}{\void}
 212
 213 Returns true if any subkeys exist.
 214
 215
 216 \membersection{wxRegKey::IsEmpty}\label{wxregkeyisempty}
 217
 218 \constfunc{bool}{IsEmpty}{\void}
 219
 220 Returns true if this key is empty, nothing under this key.
 221
 222
 223 \membersection{wxRegKey::IsOpened}\label{wxregkeyisopened}
 224
 225 \constfunc{bool}{IsOpened}{\void}
 226
 227 Returns true if the key is opened.
 228
 229
 230 \membersection{wxRegKey::Open}\label{wxregkeyopen}
 231
 232 \func{bool}{Open}{\param{AccessMode }{mode = Write}}
 233
 234 Explicitly opens the key. This method also allows the key to be opened in
 235 read-only mode by passing \texttt{wxRegKey::Read} instead of default
 236 \texttt{wxRegKey::Write} parameter.
 237
 238
 239 \membersection{wxRegKey::QueryValue}\label{wxregkeyqueryvalue}
 240
 241 \constfunc{bool}{QueryValue}{\param{const wxChar *}{szValue}, \param{wxString\&}{ strValue}}
 242
 243 Retrieves the string value.
 244
 245 \constfunc{bool}{QueryValue}{\param{const wxChar *}{szValue}, \param{long *}{plValue}}
 246
 247 Retrieves the numeric value.
 248
 249
 250 \membersection{wxRegKey::Rename}\label{wxregkeyrename}
 251
 252 \func{bool}{Rename}{\param{const wxChar *}{ szNewName}}
 253
 254 Renames the key.
 255
 256
 257 \membersection{wxRegKey::RenameValue}\label{wxregkeyrenamevalue}
 258
 259 \func{bool}{RenameValue}{\param{const wxChar *}{szValueOld}, \param{const wxChar *}{szValueNew}}
 260
 261 Renames a value.
 262
 263
 264 \membersection{wxRegKey::SetValue}\label{wxregkeysetvalue}
 265
 266 \func{bool}{SetValue}{\param{const wxChar *}{szValue}, \param{long}{ lValue}}
 267
 268 \func{bool}{SetValue}{\param{const wxChar *}{szValue}, \param{const wxString\&}{ strValue}}
 269
 270 \func{bool}{SetValue}{\param{const wxChar *}{szValue}, \param{const wxMemoryBuffer\&}{ buf}}
 271
 272 Sets the given \arg{szValue} which must be numeric, string or binary depending
 273 on the overload used. If the value doesn't exist, it is created.
 274