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: regkey.tex 45060 2007-03-26 09:42:43Z JS $
8%% Copyright:   (c) Ryan Norton (C.C.Chakkaradeep?)
9%% License:     wxWindows license
10%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
11
12\section{\class{wxRegKey}}\label{wxregkey}
13
14wxRegKey is a class representing the Windows registry (it is only available
15under Windows). One can create, query and delete registry keys using this
16class.
17
18The Windows registry is easy to understand. There are five registry keys,
19namely:
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
29After 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
41None
42
43\wxheading{Include files}
44
45<wx/msw/registry.h>
46
47\wxheading{Example}
48
49\begin{verbatim}
50wxRegKey *pRegKey = new wxRegKey("HKEY_LOCAL_MACHINE\\Software\\MyKey");
51
52//will create the Key if it does not exist
53if( !pRegKey->Exists() )
54    pRegKey->Create();
55
56//will create a new value MYVALUE and set it to 12
57pRegKey->SetValue("MYVALUE",12);
58
59//Query for the Value and Retrieve it
60long lMyVal;
61wxString strTemp;
62pRegKey->QueryValue("MYVALUE",&lMyVal); 
63strTemp.Printf("%d",lMyVal);
64wxMessageBox(strTemp,"Registry Value",0,this);
65
66//Retrive the number of SubKeys and enumerate them
67size_t nSubKeys;
68pRegKey->GetKeyInfo(&nSubKeys,NULL,NULL,NULL);
69
70pRegKey->GetFirstKey(strTemp,1);
71for(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
85The Constructor to set to HKCR
86
87\func{}{wxRegKey}{\param{const wxString\&}{ strKey}}
88
89The constructor to set the full name of the key.
90
91\func{}{wxRegKey}{\param{const wxRegKey\&}{ keyParent}, \param{const wxString\&}{ strKey}}
92
93The 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
100Closes the key.
101
102
103\membersection{wxRegKey::Create}\label{wxregkeycreate}
104
105\func{bool}{Create}{\param{bool }{bOkIfExists = true}}
106
107Creates 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
114Deletes 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
121Deletes 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
128Deletes the named value.
129
130
131\membersection{wxRegKey::Exists}\label{wxregkeyexists}
132
133\constfunc{static bool}{Exists}{\void}
134
135Returns true if the key exists.
136
137
138\membersection{wxRegKey::GetName}\label{wxregkeygetname}
139
140\constfunc{wxString}{GetName}{\param{bool }{bShortPrefix = true}}
141
142Gets 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
149Gets the first key.
150
151
152\membersection{wxRegKey::GetFirstValue}\label{wxregkeygetfirstvalue}
153
154\func{bool}{GetFirstValue}{\param{wxString\&}{ strValueName}, \param{long\&}{ lIndex}}
155
156Gets 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
163Gets 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
178Gets the next key.
179
180
181\membersection{wxRegKey::GetNextValue}\label{wxregkeygetnextvalue}
182
183\constfunc{bool}{GetNextValue}{\param{wxString\&}{ strValueName}, \param{long\&}{ lIndex}}
184
185Gets 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
192Returns true if the value exists.
193
194
195\membersection{wxRegKey::HasValues}\label{wxregkeyhasvalues}
196
197\constfunc{bool}{HasValues}{\void}
198
199Returns true if any values exist.
200
201
202\membersection{wxRegKey::HasSubKey}\label{wxregkeyhassubkey}
203
204\constfunc{bool}{HasSubKey}{\param{const wxChar *}{szKey}}
205
206Returns true if given subkey exists.
207
208
209\membersection{wxRegKey::HasSubKeys}\label{wxregkeyhassubkeys}
210
211\constfunc{bool}{HasSubKeys}{\void}
212
213Returns true if any subkeys exist.
214
215
216\membersection{wxRegKey::IsEmpty}\label{wxregkeyisempty}
217
218\constfunc{bool}{IsEmpty}{\void}
219
220Returns 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
227Returns true if the key is opened.
228
229
230\membersection{wxRegKey::Open}\label{wxregkeyopen}
231
232\func{bool}{Open}{\param{AccessMode }{mode = Write}}
233
234Explicitly opens the key. This method also allows the key to be opened in
235read-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
243Retrieves the string value.
244
245\constfunc{bool}{QueryValue}{\param{const wxChar *}{szValue}, \param{long *}{plValue}}
246
247Retrieves the numeric value.
248
249
250\membersection{wxRegKey::Rename}\label{wxregkeyrename}
251
252\func{bool}{Rename}{\param{const wxChar *}{ szNewName}}
253
254Renames the key.
255
256
257\membersection{wxRegKey::RenameValue}\label{wxregkeyrenamevalue}
258
259\func{bool}{RenameValue}{\param{const wxChar *}{szValueOld}, \param{const wxChar *}{szValueNew}}
260
261Renames 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
272Sets the given \arg{szValue} which must be numeric, string or binary depending
273on the overload used. If the value doesn't exist, it is created.
274
275