| 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}{GetKeyValue}{\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 | |