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 \membersection{wxRegKey::wxRegKey}\label{wxregkeyctor}
  81
  82 \func{}{wxRegKey}{\void}
  83
  84 The Constructor to set to HKCR
  85
  86 \func{}{wxRegKey}{\param{const wxString\&}{ strKey}}
  87
  88 The constructor to set the full name of the key.
  89
  90 \func{}{wxRegKey}{\param{const wxRegKey\&}{ keyParent}, \param{const wxString\&}{ strKey}}
  91
  92 The constructor to set the full name of the key under a previously created parent.
  93
  94 \membersection{wxRegKey::Close}\label{wxregkeyclose}
  95
  96 \func{void}{Close}{\void}
  97
  98 Closes the key.
  99
 100 \membersection{wxRegKey::Create}\label{wxregkeycreate}
 101
 102 \func{bool}{Create}{\param{bool }{bOkIfExists = true}}
 103
 104 Creates the key. Will fail if the key already exists and {\it bOkIfExists} is false.
 105
 106 \membersection{wxRegKey::DeleteSelf}\label{wxregkeydeleteself}
 107
 108 \func{void}{DeleteSelf}{\void}
 109
 110 Deletes this key and all of its subkeys and values recursively.
 111
 112 \membersection{wxRegKey::DeleteKey}\label{wxregkeydeletekey}
 113
 114 \func{void}{DeleteKey}{\param{const wxChar *}{szKey}}
 115
 116 Deletes the subkey with all of its subkeys/values recursively.
 117
 118 \membersection{wxRegKey::DeleteValue}\label{wxregkeydeletevalue}
 119
 120 \func{void}{DeleteValue}{\param{const wxChar *}{szKey}}
 121
 122 Deletes the named value.
 123
 124 \membersection{wxRegKey::Exists}\label{wxregkeyexists}
 125
 126 \constfunc{static bool}{Exists}{\void}
 127
 128 Returns true if the key exists.
 129
 130 \membersection{wxRegKey::GetName}\label{wxregkeygetname}
 131
 132 \constfunc{wxString}{GetName}{\param{bool }{bShortPrefix = true}}
 133
 134 Gets the name of the registry key.
 135
 136 \membersection{wxRegKey::GetFirstKey}\label{wxregkeygetfirstkey}
 137
 138 \func{bool}{GetKeyValue}{\param{wxString\&}{ strKeyName}, \param{long\&}{ lIndex}}
 139
 140 Gets the first key.
 141
 142 \membersection{wxRegKey::GetFirstValue}\label{wxregkeygetfirstvalue}
 143
 144 \func{bool}{GetFirstValue}{\param{wxString\&}{ strValueName}, \param{long\&}{ lIndex}}
 145
 146 Gets the first value of this key.
 147
 148 \membersection{wxRegKey::GetKeyInfo}\label{wxregkeygetkeyinfo}
 149
 150 \constfunc{bool}{Exists}{\param{size\_t *}{pnSubKeys}, \param{size\_t *}{pnValues}, \param{size\_t *}{pnMaxValueLen}}
 151
 152 Gets information about the key.
 153
 154 \wxheading{Parameters}
 155
 156 \docparam{pnSubKeys}{The number of subkeys.}
 157
 158 \docparam{pnMaxKeyLen}{The maximum length of the subkey name.}
 159
 160 \docparam{pnValues}{The number of values.}
 161
 162 \membersection{wxRegKey::GetNextKey}\label{wxregkeygetnextkey}
 163
 164 \constfunc{bool}{GetNextKey}{\param{wxString\&}{ strKeyName}, \param{long\&}{ lIndex}}
 165
 166 Gets the next key.
 167
 168 \membersection{wxRegKey::GetNextValue}\label{wxregkeygetnextvalue}
 169
 170 \constfunc{bool}{GetNextValue}{\param{wxString\&}{ strValueName}, \param{long\&}{ lIndex}}
 171
 172 Gets the next key value for this key.
 173
 174 \membersection{wxRegKey::HasValue}\label{wxregkeyhasvalue}
 175
 176 \constfunc{bool}{HasValue}{\param{const wxChar *}{szValue}}
 177
 178 Returns true if the value exists.
 179
 180 \membersection{wxRegKey::HasValues}\label{wxregkeyhasvalues}
 181
 182 \constfunc{bool}{HasValues}{\void}
 183
 184 Returns true if any values exist.
 185
 186 \membersection{wxRegKey::HasSubKey}\label{wxregkeyhassubkey}
 187
 188 \constfunc{bool}{HasSubKey}{\param{const wxChar *}{szKey}}
 189
 190 Returns true if given subkey exists.
 191
 192 \membersection{wxRegKey::HasSubKeys}\label{wxregkeyhassubkeys}
 193
 194 \constfunc{bool}{HasSubKeys}{\void}
 195
 196 Returns true if any subkeys exist.
 197
 198 \membersection{wxRegKey::IsEmpty}\label{wxregkeyisempty}
 199
 200 \constfunc{bool}{IsEmpty}{\void}
 201
 202 Returns true if this key is empty, nothing under this key.
 203
 204 \membersection{wxRegKey::IsOpened}\label{wxregkeyisopened}
 205
 206 \constfunc{bool}{IsOpened}{\void}
 207
 208 Returns true if the key is opened.
 209
 210 \membersection{wxRegKey::Open}\label{wxregkeyopen}
 211
 212 \func{bool}{Open}{\void}
 213
 214 Explicitly opens the key to be opened.
 215
 216 \membersection{wxRegKey::QueryValue}\label{wxregkeyqueryvalue}
 217
 218 \constfunc{bool}{QueryValue}{\param{const wxChar *}{szValue}, \param{wxString\&}{ strValue}}
 219
 220 Retrieves the string value.
 221
 222 \constfunc{bool}{QueryValue}{\param{const wxChar *}{szValue}, \param{long *}{plValue}}
 223
 224 Retrieves the numeric value.
 225
 226 \membersection{wxRegKey::Rename}\label{wxregkeyrename}
 227
 228 \func{bool}{Rename}{\param{const wxChar *}{ szNewName}}
 229
 230 Renames the key.
 231
 232 \membersection{wxRegKey::RenameValue}\label{wxregkeyrenamevalue}
 233
 234 \func{bool}{RenameValue}{\param{const wxChar *}{szValueOld}, \param{const wxChar *}{szValueNew}}
 235
 236 Renames a value.
 237
 238 \membersection{wxRegKey::SetValue}\label{wxregkeysetvalue}
 239
 240 \func{bool}{SetValue}{\param{const wxChar *}{szValue}, \param{long}{ lValue}}
 241
 242 Sets the numeric value.
 243