Commit | Line | Data |
---|---|---|
a974387a JS |
1 | \section{\class{wxVariant}}\label{wxvariant} |
2 | ||
3 | The {\bf wxVariant} class represents a container for any type. | |
4 | A variant's value can be changed at run time, possibly to a different type of value. | |
5 | ||
6 | As standard, wxVariant can store values of type bool, char, double, long, string, | |
7 | string list, time, date, void pointer, list of strings, and list of variants. However, an application can extend | |
8 | wxVariant's capabilities by deriving from the class \helpref{wxVariantData}{wxvariantdata} and | |
9 | using the wxVariantData form of the wxVariant constructor or assignment operator | |
10 | to assign this data to a variant. Actual values for user-defined types will need to be accessed | |
11 | via the wxVariantData object, unlike the case for basic data types where convenience | |
12 | functions such as GetLong can be used. | |
13 | ||
14 | This class is useful for reducing the programming for certain tasks, such as an editor | |
15 | for different data types, or a remote procedure call protocol. | |
16 | ||
17 | An optional name member is associated with a wxVariant. This might be used, for example, in CORBA | |
18 | or OLE automation classes, where named parameters are required. | |
19 | ||
20 | wxVariant is similar to wxExpr and also to wxPropertyValue. However, wxExpr is efficiency-optimized for | |
21 | a restricted range of data types, whereas wxVariant is less efficient but more extensible. | |
22 | wxPropertyValue may be replaced by wxVariant eventually. | |
23 | ||
24 | \wxheading{Derived from} | |
25 | ||
26 | \helpref{wxObject}{wxobject} | |
27 | ||
954b8ae6 JS |
28 | \wxheading{Include files} |
29 | ||
30 | <wx/variant.h> | |
31 | ||
a974387a JS |
32 | \wxheading{See also} |
33 | ||
34 | \helpref{wxVariantData}{wxvariantdata} | |
35 | ||
36 | \latexignore{\rtfignore{\wxheading{Members}}} | |
37 | ||
38 | \membersection{wxVariant::wxVariant}\label{wxvariantctor} | |
39 | ||
40 | \func{}{wxVariant}{\void} | |
41 | ||
42 | Default constructor. | |
43 | ||
44 | \func{}{wxVariant}{\param{const wxVariant\& }{variant}} | |
45 | ||
46 | Copy constructor. | |
47 | ||
f6bcfd97 BP |
48 | \func{}{wxVariant}{\param{const char*}{ value}, \param{const wxString\& }{name = ``"}} |
49 | ||
a974387a JS |
50 | \func{}{wxVariant}{\param{const wxString\&}{ value}, \param{const wxString\& }{name = ``"}} |
51 | ||
52 | Construction from a string value. | |
53 | ||
54 | \func{}{wxVariant}{\param{char}{ value}, \param{const wxString\& }{name = ``"}} | |
55 | ||
56 | Construction from a character value. | |
57 | ||
58 | \func{}{wxVariant}{\param{long}{ value}, \param{const wxString\& }{name = ``"}} | |
59 | ||
60 | Construction from an integer value. You may need to cast to (long) to | |
61 | avoid confusion with other constructors (such as the bool constructor). | |
62 | ||
63 | \func{}{wxVariant}{\param{bool}{ value}, \param{const wxString\& }{name = ``"}} | |
64 | ||
65 | Construction from a boolean value. | |
66 | ||
67 | \func{}{wxVariant}{\param{double}{ value}, \param{const wxString\& }{name = ``"}} | |
68 | ||
69 | Construction from a double-precision floating point value. | |
70 | ||
71 | \func{}{wxVariant}{\param{const wxList\&}{ value}, \param{const wxString\& }{name = ``"}} | |
72 | ||
73 | Construction from a list of wxVariant objects. This constructor | |
74 | copies {\it value}, the application is still responsible for | |
75 | deleting {\it value} and its contents. | |
76 | ||
77 | \func{}{wxVariant}{\param{const wxStringList\&}{ value}, \param{const wxString\& }{name = ``"}} | |
78 | ||
79 | Construction from a list of strings. This constructor | |
80 | copies {\it value}, the application is still responsible for | |
81 | deleting {\it value} and its contents. | |
82 | ||
83 | %Note: this constructor is currently disabled because it causes a C++ ambiguity. | |
84 | ||
85 | \func{}{wxVariant}{\param{const wxTime\&}{ value}, \param{const wxString\& }{name = ``"}} | |
86 | ||
87 | Construction from a time. | |
88 | ||
89 | \func{}{wxVariant}{\param{const wxDate\&}{ value}, \param{const wxString\& }{name = ``"}} | |
90 | ||
91 | Construction from a date. | |
92 | ||
93 | \func{}{wxVariant}{\param{void*}{ value}, \param{const wxString\& }{name = ``"}} | |
94 | ||
95 | Construction from a void pointer. | |
96 | ||
97 | \func{}{wxVariant}{\param{wxVariantData*}{ data}, \param{const wxString\& }{name = ``"}} | |
98 | ||
99 | Construction from user-defined data. The variant holds on to the {\it data} pointer. | |
100 | ||
101 | \membersection{wxVariant::\destruct{wxVariant}}\label{wxvariantdtor} | |
102 | ||
103 | \func{}{\destruct{wxVariant}}{\void} | |
104 | ||
105 | Destructor. | |
106 | ||
107 | \membersection{wxVariant::Append}\label{wxvariantappend} | |
108 | ||
109 | \func{void}{Append}{\param{const wxVariant\&}{ value}} | |
110 | ||
111 | Appends a value to the list. | |
112 | ||
113 | \membersection{wxVariant::ClearList}\label{wxvariantclearlist} | |
114 | ||
115 | \func{void}{ClearList}{\void} | |
116 | ||
117 | Deletes the contents of the list. | |
118 | ||
119 | \membersection{wxVariant::GetCount}\label{wxvariantgetcount} | |
120 | ||
121 | \constfunc{int}{GetCount}{\void} | |
122 | ||
123 | Returns the number of elements in the list. | |
124 | ||
125 | \membersection{wxVariant::Delete}\label{wxvariantdelete} | |
126 | ||
127 | \func{bool}{Delete}{\param{int }{item}} | |
128 | ||
129 | Deletes the zero-based {\it item} from the list. | |
130 | ||
131 | \membersection{wxVariant::GetBool}\label{wxvariantgetbool} | |
132 | ||
133 | \constfunc{bool}{GetBool}{\void} | |
134 | ||
135 | Returns the boolean value. | |
136 | ||
137 | \membersection{wxVariant::GetChar}\label{wxvariantgetchar} | |
138 | ||
139 | \constfunc{char}{GetChar}{\void} | |
140 | ||
141 | Returns the character value. | |
142 | ||
143 | \membersection{wxVariant::GetData}\label{wxvariantgetdata} | |
144 | ||
145 | \constfunc{wxVariantData*}{GetData}{\void} | |
146 | ||
147 | Returns a pointer to the internal variant data. | |
148 | ||
149 | \membersection{wxVariant::GetDate}\label{wxvariantgetdate} | |
150 | ||
151 | \constfunc{wxDate}{GetDate}{\void} | |
152 | ||
153 | Gets the date value. | |
154 | ||
155 | \membersection{wxVariant::GetDouble}\label{wxvariantgetdouble} | |
156 | ||
157 | \constfunc{double}{GetDouble}{\void} | |
158 | ||
159 | Returns the floating point value. | |
160 | ||
161 | \membersection{wxVariant::GetLong}\label{wxvariantgetlong} | |
162 | ||
163 | \constfunc{long}{GetLong}{\void} | |
164 | ||
165 | Returns the integer value. | |
166 | ||
167 | \membersection{wxVariant::GetName}\label{wxvariantgetname} | |
168 | ||
169 | \constfunc{const wxString\&}{GetName}{\void} | |
170 | ||
171 | Returns a constant reference to the variant name. | |
172 | ||
173 | \membersection{wxVariant::GetString}\label{wxvariantgetstring} | |
174 | ||
175 | \constfunc{wxString}{GetString}{\void} | |
176 | ||
177 | Gets the string value. | |
178 | ||
179 | \membersection{wxVariant::GetTime}\label{wxvariantgettime} | |
180 | ||
181 | \constfunc{wxTime}{GetTime}{\void} | |
182 | ||
183 | Gets the time value. | |
184 | ||
185 | \membersection{wxVariant::GetType}\label{wxvariantgettype} | |
186 | ||
187 | \constfunc{wxString}{GetType}{\void} | |
188 | ||
189 | Returns the value type as a string. The built-in types are: bool, char, date, double, list, long, string, stringlist, time, void*. | |
190 | ||
191 | If the variant is null, the value type returned is the string ``null" (not the empty string). | |
192 | ||
193 | \membersection{wxVariant::GetVoidPtr}\label{wxvariantgetvoidptr} | |
194 | ||
195 | \constfunc{void*}{GetVoidPtr}{\void} | |
196 | ||
197 | Gets the void pointer value. | |
198 | ||
199 | \membersection{wxVariant::Insert}\label{wxvariantinsert} | |
200 | ||
201 | \func{void}{Insert}{\param{const wxVariant\&}{ value}} | |
202 | ||
203 | Inserts a value at the front of the list. | |
204 | ||
205 | \membersection{wxVariant::IsNull}\label{wxvariantisnull} | |
206 | ||
207 | \constfunc{bool}{IsNull}{\void} | |
208 | ||
209 | Returns TRUE if there is no data associated with this variant, FALSE if there is data. | |
210 | ||
211 | \membersection{wxVariant::IsType}\label{wxvariantistype} | |
212 | ||
213 | \constfunc{bool}{IsType}{\param{const wxString\&}{ type}} | |
214 | ||
215 | Returns TRUE if {\it type} matches the type of the variant, FALSE otherwise. | |
216 | ||
217 | \membersection{wxVariant::MakeNull}\label{wxvariantmakenull} | |
218 | ||
219 | \func{void}{MakeNull}{\void} | |
220 | ||
221 | Makes the variant null by deleting the internal data. | |
222 | ||
223 | \membersection{wxVariant::MakeString}\label{wxvariantmakestring} | |
224 | ||
225 | \constfunc{wxString}{MakeString}{\void} | |
226 | ||
227 | Makes a string representation of the variant value (for any type). | |
228 | ||
229 | \membersection{wxVariant::Member}\label{wxvariantmember} | |
230 | ||
231 | \constfunc{bool}{Member}{\param{const wxVariant\&}{ value}} | |
232 | ||
233 | Returns TRUE if {\it value} matches an element in the list. | |
234 | ||
235 | \membersection{wxVariant::NullList}\label{wxvariantnulllist} | |
236 | ||
237 | \func{void}{NullList}{\void} | |
238 | ||
239 | Makes an empty list. This differs from a null variant which has no data; a null list | |
240 | is of type list, but the number of elements in the list is zero. | |
241 | ||
242 | \membersection{wxVariant::SetData}\label{wxvariantsetdata} | |
243 | ||
244 | \func{void}{SetData}{\param{wxVariantData*}{ data}} | |
245 | ||
246 | Sets the internal variant data, deleting the existing data if there is any. | |
247 | ||
248 | \membersection{wxVariant::operator $=$}\label{wxvariantassignment} | |
249 | ||
250 | \func{void}{operator $=$}{\param{const wxVariant\& }{value}} | |
251 | ||
252 | \func{void}{operator $=$}{\param{wxVariantData* }{value}} | |
253 | ||
254 | \func{void}{operator $=$}{\param{const wxString\& }{value}} | |
255 | ||
256 | \func{void}{operator $=$}{\param{const char* }{value}} | |
257 | ||
258 | \func{void}{operator $=$}{\param{char }{value}} | |
259 | ||
260 | \func{void}{operator $=$}{\param{const long }{value}} | |
261 | ||
262 | \func{void}{operator $=$}{\param{const bool }{value}} | |
263 | ||
264 | \func{void}{operator $=$}{\param{const double }{value}} | |
265 | ||
266 | \func{void}{operator $=$}{\param{const wxDate\& }{value}} | |
267 | ||
268 | \func{void}{operator $=$}{\param{const wxTime\& }{value}} | |
269 | ||
270 | \func{void}{operator $=$}{\param{void* }{value}} | |
271 | ||
272 | \func{void}{operator $=$}{\param{const wxList\& }{value}} | |
273 | ||
274 | \func{void}{operator $=$}{\param{const wxStringList\& }{value}} | |
275 | ||
276 | Assignment operators. | |
277 | ||
278 | \membersection{wxVariant::operator $==$}\label{wxvarianteq} | |
279 | ||
280 | \func{bool}{operator $==$}{\param{const wxVariant\& }{value}} | |
281 | ||
282 | \func{bool}{operator $==$}{\param{const wxString\& }{value}} | |
283 | ||
284 | \func{bool}{operator $==$}{\param{const char* }{value}} | |
285 | ||
286 | \func{bool}{operator $==$}{\param{char }{value}} | |
287 | ||
288 | \func{bool}{operator $==$}{\param{const long }{value}} | |
289 | ||
290 | \func{bool}{operator $==$}{\param{const bool }{value}} | |
291 | ||
292 | \func{bool}{operator $==$}{\param{const double }{value}} | |
293 | ||
294 | \func{bool}{operator $==$}{\param{const wxDate\& }{value}} | |
295 | ||
296 | \func{bool}{operator $==$}{\param{const wxTime\& }{value}} | |
297 | ||
298 | \func{bool}{operator $==$}{\param{void* }{value}} | |
299 | ||
300 | \func{bool}{operator $==$}{\param{const wxList\& }{value}} | |
301 | ||
302 | \func{bool}{operator $==$}{\param{const wxStringList\& }{value}} | |
303 | ||
304 | Equality test operators. | |
305 | ||
306 | \membersection{wxVariant::operator $!=$}\label{wxvariantneq} | |
307 | ||
308 | \func{bool}{operator $!=$}{\param{const wxVariant\& }{value}} | |
309 | ||
310 | \func{bool}{operator $!=$}{\param{const wxString\& }{value}} | |
311 | ||
312 | \func{bool}{operator $!=$}{\param{const char* }{value}} | |
313 | ||
314 | \func{bool}{operator $!=$}{\param{char }{value}} | |
315 | ||
316 | \func{bool}{operator $!=$}{\param{const long }{value}} | |
317 | ||
318 | \func{bool}{operator $!=$}{\param{const bool }{value}} | |
319 | ||
320 | \func{bool}{operator $!=$}{\param{const double }{value}} | |
321 | ||
322 | \func{bool}{operator $!=$}{\param{const wxDate\& }{value}} | |
323 | ||
324 | \func{bool}{operator $!=$}{\param{const wxTime\& }{value}} | |
325 | ||
326 | \func{bool}{operator $!=$}{\param{void* }{value}} | |
327 | ||
328 | \func{bool}{operator $!=$}{\param{const wxList\& }{value}} | |
329 | ||
330 | \func{bool}{operator $!=$}{\param{const wxStringList\& }{value}} | |
331 | ||
332 | Inequality test operators. | |
333 | ||
334 | \membersection{wxVariant::operator $[]$}\label{wxvariantarray} | |
335 | ||
336 | \constfunc{wxVariant}{operator $[]$}{\param{size\_t }{idx}} | |
337 | ||
338 | Returns the value at {\it idx} (zero-based). | |
339 | ||
340 | \func{wxVariant\&}{operator $[]$}{\param{size\_t }{idx}} | |
341 | ||
342 | Returns a reference to the value at {\it idx} (zero-based). This can be used | |
343 | to change the value at this index. | |
344 | ||
345 | \membersection{wxVariant::operator char}\label{wxvariantchar} | |
346 | ||
347 | \constfunc{char}{operator char}{\void} | |
348 | ||
349 | Operator for implicit conversion to a char, using \helpref{wxVariant::GetChar}{wxvariantgetchar}. | |
350 | ||
351 | \membersection{wxVariant::operator double}\label{wxvariantdouble} | |
352 | ||
353 | \constfunc{double}{operator double}{\void} | |
354 | ||
355 | Operator for implicit conversion to a double, using \helpref{wxVariant::GetDouble}{wxvariantgetdouble}. | |
356 | ||
357 | \constfunc{long}{operator long}{\void} | |
358 | ||
359 | Operator for implicit conversion to a long, using \helpref{wxVariant::GetLong}{wxvariantgetlong}. | |
360 | ||
361 | \membersection{wxVariant::operator wxDate}\label{wxvariantwxdate} | |
362 | ||
363 | \constfunc{wxDate}{operator wxDate}{\void} | |
364 | ||
365 | Operator for implicit conversion to a wxDate, using \helpref{wxVariant::GetDate}{wxvariantgetdate}. | |
366 | ||
367 | \membersection{wxVariant::operator wxString}\label{wxvariantwxstring} | |
368 | ||
369 | \constfunc{wxString}{operator wxString}{\void} | |
370 | ||
371 | Operator for implicit conversion to a string, using \helpref{wxVariant::MakeString}{wxvariantmakestring}. | |
372 | ||
373 | \membersection{wxVariant::operator wxTime}\label{wxvariantwxtime} | |
374 | ||
375 | \constfunc{wxTime}{operator wxTime}{\void} | |
376 | ||
377 | Operator for implicit conversion to a wxTime, using \helpref{wxVariant::GetTime}{wxvariantgettime}. | |
378 | ||
379 | \membersection{wxVariant::operator void*}\label{wxvariantvoid} | |
380 | ||
381 | \constfunc{void*}{operator void*}{\void} | |
382 | ||
383 | Operator for implicit conversion to a pointer to a void, using \helpref{wxVariant::GetVoidPtr}{wxvariantgetvoidptr}. | |
384 | ||
385 | \section{\class{wxVariantData}}\label{wxvariantdata} | |
386 | ||
387 | The {\bf wxVariantData} is used to implement a new type for wxVariant. Derive from wxVariantData, | |
388 | and override the pure virtual functions. | |
389 | ||
390 | \wxheading{Derived from} | |
391 | ||
392 | \helpref{wxObject}{wxobject} | |
393 | ||
954b8ae6 JS |
394 | \wxheading{Include files} |
395 | ||
396 | <wx/variant.h> | |
397 | ||
a974387a JS |
398 | \wxheading{See also} |
399 | ||
400 | \helpref{wxVariant}{wxvariant} | |
401 | ||
402 | \latexignore{\rtfignore{\wxheading{Members}}} | |
403 | ||
404 | \membersection{wxVariantData::wxVariantData}\label{wxvariantdatactor} | |
405 | ||
406 | \func{}{wxVariantData}{\void} | |
407 | ||
408 | Default constructor. | |
409 | ||
410 | \membersection{wxVariantData::Copy}\label{wxvariantdatacopy} | |
411 | ||
412 | \func{void}{Copy}{\param{wxVariantData\&}{ data}} | |
413 | ||
414 | Copy the data from `this' object to {\it data}. | |
415 | ||
416 | \membersection{wxVariantData::Eq}\label{wxvariantdataeq} | |
417 | ||
418 | \constfunc{bool}{Eq}{\param{wxVariantData\&}{ data}} | |
419 | ||
420 | Returns TRUE if this object is equal to {\it data}. | |
421 | ||
422 | \membersection{wxVariantData::GetType}\label{wxvariantdatagettype} | |
423 | ||
424 | \constfunc{wxString}{GetType}{\void} | |
425 | ||
426 | Returns the string type of the data. | |
427 | ||
428 | \membersection{wxVariantData::Read}\label{wxvariantdataread} | |
429 | ||
430 | \func{bool}{Read}{\param{ostream\&}{ stream}} | |
431 | ||
432 | \func{bool}{Read}{\param{wxString\&}{ string}} | |
433 | ||
434 | Reads the data from {\it stream} or {\it string}. | |
435 | ||
436 | \membersection{wxVariantData::Write}\label{wxvariantdatawrite} | |
437 | ||
438 | \constfunc{bool}{Write}{\param{ostream\&}{ stream}} | |
439 | ||
440 | \constfunc{bool}{Write}{\param{wxString\&}{ string}} | |
441 | ||
442 | Writes the data to {\it stream} or {\it string}. | |
443 | ||
444 | ||
445 |