]> git.saurik.com Git - wxWidgets.git/blob - docs/latex/wx/variant.tex
Tweaks for demos on MacOSX
[wxWidgets.git] / docs / latex / wx / variant.tex
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 wxVariant's capabilities by deriving from the class \helpref{wxVariantData}{wxvariantdata} and using the wxVariantData form of the wxVariant constructor or assignment operator to assign this data to a variant. Actual values for user-defined types will need to be accessed via the wxVariantData object, unlike the case for basic data types where convenience functions such as GetLong can be used.
8
9 This class is useful for reducing the programming for certain tasks, such as an editor
10 for different data types, or a remote procedure call protocol.
11
12 An optional name member is associated with a wxVariant. This might be used, for example, in CORBA
13 or OLE automation classes, where named parameters are required.
14
15 \wxheading{Derived from}
16
17 \helpref{wxObject}{wxobject}
18
19 \wxheading{Include files}
20
21 <wx/variant.h>
22
23 \wxheading{See also}
24
25 \helpref{wxVariantData}{wxvariantdata}
26
27 \latexignore{\rtfignore{\wxheading{Members}}}
28
29 \membersection{wxVariant::wxVariant}\label{wxvariantctor}
30
31 \func{}{wxVariant}{\void}
32
33 Default constructor.
34
35 \func{}{wxVariant}{\param{const wxVariant\& }{variant}}
36
37 Copy constructor.
38
39 \func{}{wxVariant}{\param{const char*}{ value}, \param{const wxString\& }{name = ``"}}
40
41 \func{}{wxVariant}{\param{const wxString\&}{ value}, \param{const wxString\& }{name = ``"}}
42
43 Construction from a string value.
44
45 \func{}{wxVariant}{\param{char}{ value}, \param{const wxString\& }{name = ``"}}
46
47 Construction from a character value.
48
49 \func{}{wxVariant}{\param{long}{ value}, \param{const wxString\& }{name = ``"}}
50
51 Construction from an integer value. You may need to cast to (long) to
52 avoid confusion with other constructors (such as the bool constructor).
53
54 \func{}{wxVariant}{\param{bool}{ value}, \param{const wxString\& }{name = ``"}}
55
56 Construction from a boolean value.
57
58 \func{}{wxVariant}{\param{double}{ value}, \param{const wxString\& }{name = ``"}}
59
60 Construction from a double-precision floating point value.
61
62 \func{}{wxVariant}{\param{const wxList\&}{ value}, \param{const wxString\& }{name = ``"}}
63
64 Construction from a list of wxVariant objects. This constructor
65 copies {\it value}, the application is still responsible for
66 deleting {\it value} and its contents.
67
68 \func{}{wxVariant}{\param{void*}{ value}, \param{const wxString\& }{name = ``"}}
69
70 Construction from a void pointer.
71
72 \func{}{wxVariant}{\param{wxObject*}{ value}, \param{const wxString\& }{name = ``"}}
73
74 Construction from a wxObject pointer.
75
76 \func{}{wxVariant}{\param{wxVariantData*}{ data}, \param{const wxString\& }{name = ``"}}
77
78 Construction from user-defined data. The variant holds onto the {\it data} pointer.
79
80 \func{}{wxVariant}{\param{wxDateTime\&}{ val}, \param{const wxString\& }{name = ``"}}
81
82 Construction from a \helpref{wxDateTime}{wxdatetime}.
83
84 \func{}{wxVariant}{\param{wxArrayString\&}{ val}, \param{const wxString\& }{name = ``"}}
85
86 Construction from an array of strings. This constructor copies {\it value} and its contents.
87
88 \func{}{wxVariant}{\param{DATE\_STRUCT*}{ val}, \param{const wxString\& }{name = ``"}}
89
90 Construction from a odbc date value. Represented internally by a \helpref{wxDateTime}{wxdatetime} value.
91
92 \func{}{wxVariant}{\param{TIME\_STRUCT*}{ val}, \param{const wxString\& }{name = ``"}}
93
94 Construction from a odbc time value. Represented internally by a \helpref{wxDateTime}{wxdatetime} value.
95
96 \func{}{wxVariant}{\param{TIMESTAMP\_STRUCT*}{ val}, \param{const wxString\& }{name = ``"}}
97
98 Construction from a odbc timestamp value. Represented internally by a \helpref{wxDateTime}{wxdatetime} value.
99
100 \membersection{wxVariant::\destruct{wxVariant}}\label{wxvariantdtor}
101
102 \func{}{\destruct{wxVariant}}{\void}
103
104 Destructor.
105
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
120 \membersection{wxVariant::Convert}\label{wxvariantconvert}
121
122 \constfunc{bool}{Convert}{\param{long*}{ value}}
123
124 \constfunc{bool}{Convert}{\param{bool*}{ value}}
125
126 \constfunc{bool}{Convert}{\param{double*}{ value}}
127
128 \constfunc{bool}{Convert}{\param{wxString*}{ value}}
129
130 \constfunc{bool}{Convert}{\param{char*}{ value}}
131
132 \constfunc{bool}{Convert}{\param{wxDateTime*}{ value}}
133
134 Retrieves and converts the value of this variant to the type that {\it value} is.
135
136
137 \membersection{wxVariant::GetCount}\label{wxvariantgetcount}
138
139 \constfunc{int}{GetCount}{\void}
140
141 Returns the number of elements in the list.
142
143 \membersection{wxVariant::Delete}\label{wxvariantdelete}
144
145 \func{bool}{Delete}{\param{int }{item}}
146
147 Deletes the zero-based {\it item} from the list.
148
149 \membersection{wxVariant::GetArrayString}\label{wxvariantgetarraystring}
150
151 \constfunc{wxArrayString}{GetArrayString}{\void}
152
153 Returns the string array value.
154
155 \membersection{wxVariant::GetBool}\label{wxvariantgetbool}
156
157 \constfunc{bool}{GetBool}{\void}
158
159 Returns the boolean value.
160
161 \membersection{wxVariant::GetChar}\label{wxvariantgetchar}
162
163 \constfunc{char}{GetChar}{\void}
164
165 Returns the character value.
166
167 \membersection{wxVariant::GetData}\label{wxvariantgetdata}
168
169 \constfunc{wxVariantData*}{GetData}{\void}
170
171 Returns a pointer to the internal variant data.
172
173 \membersection{wxVariant::GetDateTime}\label{wxvariantgetdatetime}
174
175 \constfunc{wxDateTime}{GetDateTime}{\void}
176
177 Returns the date value.
178
179 \membersection{wxVariant::GetDouble}\label{wxvariantgetdouble}
180
181 \constfunc{double}{GetDouble}{\void}
182
183 Returns the floating point value.
184
185 \membersection{wxVariant::GetLong}\label{wxvariantgetlong}
186
187 \constfunc{long}{GetLong}{\void}
188
189 Returns the integer value.
190
191 \membersection{wxVariant::GetName}\label{wxvariantgetname}
192
193 \constfunc{const wxString\&}{GetName}{\void}
194
195 Returns a constant reference to the variant name.
196
197 \membersection{wxVariant::GetString}\label{wxvariantgetstring}
198
199 \constfunc{wxString}{GetString}{\void}
200
201 Gets the string value.
202
203 \membersection{wxVariant::GetType}\label{wxvariantgettype}
204
205 \constfunc{wxString}{GetType}{\void}
206
207 Returns the value type as a string. The built-in types are: bool, char, date, double, list, long, string, stringlist, time, void*.
208
209 If the variant is null, the value type returned is the string ``null" (not the empty string).
210
211 \membersection{wxVariant::GetVoidPtr}\label{wxvariantgetvoidptr}
212
213 \constfunc{void*}{GetVoidPtr}{\void}
214
215 Gets the void pointer value.
216
217 \membersection{wxVariant::GetWxObjectPtr}\label{wxvariantgetwxobjectptr}
218
219 \constfunc{void*}{GetWxObjectPtr}{\void}
220
221 Gets the wxObject pointer value.
222
223 \membersection{wxVariant::Insert}\label{wxvariantinsert}
224
225 \func{void}{Insert}{\param{const wxVariant\&}{ value}}
226
227 Inserts a value at the front of the list.
228
229 \membersection{wxVariant::IsNull}\label{wxvariantisnull}
230
231 \constfunc{bool}{IsNull}{\void}
232
233 Returns true if there is no data associated with this variant, false if there is data.
234
235 \membersection{wxVariant::IsType}\label{wxvariantistype}
236
237 \constfunc{bool}{IsType}{\param{const wxString\&}{ type}}
238
239 Returns true if {\it type} matches the type of the variant, false otherwise.
240
241 \membersection{wxVariant::IsValueKindOf}\label{wxvariantisvaluekindof}
242
243 \constfunc{bool}{IsValueKindOf}{\param{const wxClassInfo* type}{ type}}
244
245 Returns true if the data is derived from the class described by {\it type}, false otherwise.
246
247 \membersection{wxVariant::MakeNull}\label{wxvariantmakenull}
248
249 \func{void}{MakeNull}{\void}
250
251 Makes the variant null by deleting the internal data.
252
253 \membersection{wxVariant::MakeString}\label{wxvariantmakestring}
254
255 \constfunc{wxString}{MakeString}{\void}
256
257 Makes a string representation of the variant value (for any type).
258
259 \membersection{wxVariant::Member}\label{wxvariantmember}
260
261 \constfunc{bool}{Member}{\param{const wxVariant\&}{ value}}
262
263 Returns true if {\it value} matches an element in the list.
264
265 \membersection{wxVariant::NullList}\label{wxvariantnulllist}
266
267 \func{void}{NullList}{\void}
268
269 Makes an empty list. This differs from a null variant which has no data; a null list
270 is of type list, but the number of elements in the list is zero.
271
272 \membersection{wxVariant::SetData}\label{wxvariantsetdata}
273
274 \func{void}{SetData}{\param{wxVariantData*}{ data}}
275
276 Sets the internal variant data, deleting the existing data if there is any.
277
278 \membersection{wxVariant::operator $=$}\label{wxvariantassignment}
279
280 \func{void}{operator $=$}{\param{const wxVariant\& }{value}}
281
282 \func{void}{operator $=$}{\param{wxVariantData* }{value}}
283
284 \func{void}{operator $=$}{\param{const wxString\& }{value}}
285
286 \func{void}{operator $=$}{\param{const char* }{value}}
287
288 \func{void}{operator $=$}{\param{char }{value}}
289
290 \func{void}{operator $=$}{\param{const long }{value}}
291
292 \func{void}{operator $=$}{\param{const bool }{value}}
293
294 \func{void}{operator $=$}{\param{const double }{value}}
295
296 \func{void}{operator $=$}{\param{void* }{value}}
297
298 \func{void}{operator $=$}{\param{const wxList\& }{value}}
299
300 \func{void}{operator $=$}{\param{const wxDateTime\& }{value}}
301
302 \func{void}{operator $=$}{\param{const wxArrayString\& }{value}}
303
304 \func{void}{operator $=$}{\param{const DATE\_STRUCT* }{value}}
305
306 \func{void}{operator $=$}{\param{const TIME\_STRUCT* }{value}}
307
308 \func{void}{operator $=$}{\param{const TIMESTAMP\_STRUCT* }{value}}
309
310 Assignment operators.
311
312 \membersection{wxVariant::operator $==$}\label{wxvarianteq}
313
314 \constfunc{bool}{operator $==$}{\param{const wxVariant\& }{value}}
315
316 \constfunc{bool}{operator $==$}{\param{const wxString\& }{value}}
317
318 \constfunc{bool}{operator $==$}{\param{const char* }{value}}
319
320 \constfunc{bool}{operator $==$}{\param{char }{value}}
321
322 \constfunc{bool}{operator $==$}{\param{const long }{value}}
323
324 \constfunc{bool}{operator $==$}{\param{const bool }{value}}
325
326 \constfunc{bool}{operator $==$}{\param{const double }{value}}
327
328 \constfunc{bool}{operator $==$}{\param{void* }{value}}
329
330 \constfunc{bool}{operator $==$}{\param{const wxList\& }{value}}
331
332 \constfunc{bool}{operator $==$}{\param{const wxArrayString\& }{value}}
333
334 \constfunc{bool}{operator $==$}{\param{const wxDateTime\& }{value}}
335
336 Equality test operators.
337
338 \membersection{wxVariant::operator $!=$}\label{wxvariantneq}
339
340 \constfunc{bool}{operator $!=$}{\param{const wxVariant\& }{value}}
341
342 \constfunc{bool}{operator $!=$}{\param{const wxString\& }{value}}
343
344 \constfunc{bool}{operator $!=$}{\param{const char* }{value}}
345
346 \constfunc{bool}{operator $!=$}{\param{char }{value}}
347
348 \constfunc{bool}{operator $!=$}{\param{const long }{value}}
349
350 \constfunc{bool}{operator $!=$}{\param{const bool }{value}}
351
352 \constfunc{bool}{operator $!=$}{\param{const double }{value}}
353
354 \constfunc{bool}{operator $!=$}{\param{void* }{value}}
355
356 \constfunc{bool}{operator $!=$}{\param{const wxList\& }{value}}
357
358 \constfunc{bool}{operator $!=$}{\param{const wxArrayString\& }{value}}
359
360 \constfunc{bool}{operator $!=$}{\param{const wxDateTime\& }{value}}
361
362 Inequality test operators.
363
364 \membersection{wxVariant::operator $[]$}\label{wxvariantarray}
365
366 \constfunc{wxVariant}{operator $[]$}{\param{size\_t }{idx}}
367
368 Returns the value at {\it idx} (zero-based).
369
370 \func{wxVariant\&}{operator $[]$}{\param{size\_t }{idx}}
371
372 Returns a reference to the value at {\it idx} (zero-based). This can be used
373 to change the value at this index.
374
375 \membersection{wxVariant::operator char}\label{wxvariantchar}
376
377 \constfunc{char}{operator char}{\void}
378
379 Operator for implicit conversion to a char, using \helpref{wxVariant::GetChar}{wxvariantgetchar}.
380
381 \membersection{wxVariant::operator double}\label{wxvariantdouble}
382
383 \constfunc{double}{operator double}{\void}
384
385 Operator for implicit conversion to a double, using \helpref{wxVariant::GetDouble}{wxvariantgetdouble}.
386
387 \constfunc{long}{operator long}{\void}
388
389 Operator for implicit conversion to a long, using \helpref{wxVariant::GetLong}{wxvariantgetlong}.
390
391 \membersection{wxVariant::operator wxString}\label{wxvariantwxstring}
392
393 \constfunc{wxString}{operator wxString}{\void}
394
395 Operator for implicit conversion to a string, using \helpref{wxVariant::MakeString}{wxvariantmakestring}.
396
397 \membersection{wxVariant::operator void*}\label{wxvariantvoid}
398
399 \constfunc{void*}{operator void*}{\void}
400
401 Operator for implicit conversion to a pointer to a void, using \helpref{wxVariant::GetVoidPtr}{wxvariantgetvoidptr}.
402
403 \membersection{wxVariant::operator wxDateTime}\label{wxvariantdatetime}
404
405 \constfunc{void*}{operator wxDateTime}{\void}
406
407 Operator for implicit conversion to a pointer to a \helpref{wxDateTime}{wxdatetime}, using \helpref{wxVariant::GetDateTime}{wxvariantgetdatetime}.
408
409 \section{\class{wxVariantData}}\label{wxvariantdata}
410
411 The {\bf wxVariantData} is used to implement a new type for wxVariant. Derive from wxVariantData,
412 and override the pure virtual functions.
413
414 \wxheading{Derived from}
415
416 \helpref{wxObject}{wxobject}
417
418 \wxheading{Include files}
419
420 <wx/variant.h>
421
422 \wxheading{See also}
423
424 \helpref{wxVariant}{wxvariant}
425
426 \latexignore{\rtfignore{\wxheading{Members}}}
427
428 \membersection{wxVariantData::wxVariantData}\label{wxvariantdatactor}
429
430 \func{}{wxVariantData}{\void}
431
432 Default constructor.
433
434 \membersection{wxVariantData::Copy}\label{wxvariantdatacopy}
435
436 \func{void}{Copy}{\param{wxVariantData\&}{ data}}
437
438 Copy the data from `this' object to {\it data}.
439
440 \membersection{wxVariantData::Eq}\label{wxvariantdataeq}
441
442 \constfunc{bool}{Eq}{\param{wxVariantData\&}{ data}}
443
444 Returns true if this object is equal to {\it data}.
445
446 \membersection{wxVariantData::GetType}\label{wxvariantdatagettype}
447
448 \constfunc{wxString}{GetType}{\void}
449
450 Returns the string type of the data.
451
452 \membersection{wxVariantData::GetValueClassInfo}\label{wxvariantdatagetvalueclassinfo}
453
454 \constfunc{wxClassInfo*}{GetValueClassInfo}{\void}
455
456 If the data is a wxObject returns a pointer to the objects wxClassInfo structure, if
457 the data isn't a wxObject the method returns NULL.
458
459 \membersection{wxVariantData::Read}\label{wxvariantdataread}
460
461 \func{bool}{Read}{\param{ostream\&}{ stream}}
462
463 \func{bool}{Read}{\param{wxString\&}{ string}}
464
465 Reads the data from {\it stream} or {\it string}.
466
467 \membersection{wxVariantData::Write}\label{wxvariantdatawrite}
468
469 \constfunc{bool}{Write}{\param{ostream\&}{ stream}}
470
471 \constfunc{bool}{Write}{\param{wxString\&}{ string}}
472
473 Writes the data to {\it stream} or {\it string}.
474
475
476 \membersection{wxGetVariantCast}\label{wxgetvariantcast}
477
478 \func{classname *}{wxGetVariantCast}{wxVariant\&, classname}
479
480 This macro returns the data stored in {\it variant} cast to the type {\it classname *} if
481 the data is of this type (the check is done during the run-time) or
482 {\tt NULL} otherwise.
483
484
485 \wxheading{See also}
486
487 \helpref{RTTI overview}{runtimeclassoverview}\\
488 \helpref{wxDynamicCast}{wxdynamiccast}
489