]> git.saurik.com Git - wxWidgets.git/blame - docs/latex/wx/variant.tex
Use the new event handler macros
[wxWidgets.git] / docs / latex / wx / variant.tex
CommitLineData
a974387a
JS
1\section{\class{wxVariant}}\label{wxvariant}
2
3The {\bf wxVariant} class represents a container for any type.
4A variant's value can be changed at run time, possibly to a different type of value.
5
6As standard, wxVariant can store values of type bool, char, double, long, string,
8715d2d3 7string 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.
a974387a
JS
8
9This class is useful for reducing the programming for certain tasks, such as an editor
10for different data types, or a remote procedure call protocol.
11
12An optional name member is associated with a wxVariant. This might be used, for example, in CORBA
13or OLE automation classes, where named parameters are required.
14
a974387a
JS
15\wxheading{Derived from}
16
17\helpref{wxObject}{wxobject}
18
954b8ae6
JS
19\wxheading{Include files}
20
21<wx/variant.h>
22
a974387a
JS
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
33Default constructor.
34
35\func{}{wxVariant}{\param{const wxVariant\& }{variant}}
36
37Copy constructor.
38
f6bcfd97
BP
39\func{}{wxVariant}{\param{const char*}{ value}, \param{const wxString\& }{name = ``"}}
40
a974387a
JS
41\func{}{wxVariant}{\param{const wxString\&}{ value}, \param{const wxString\& }{name = ``"}}
42
43Construction from a string value.
44
45\func{}{wxVariant}{\param{char}{ value}, \param{const wxString\& }{name = ``"}}
46
47Construction from a character value.
48
49\func{}{wxVariant}{\param{long}{ value}, \param{const wxString\& }{name = ``"}}
50
51Construction from an integer value. You may need to cast to (long) to
52avoid confusion with other constructors (such as the bool constructor).
53
54\func{}{wxVariant}{\param{bool}{ value}, \param{const wxString\& }{name = ``"}}
55
56Construction from a boolean value.
57
58\func{}{wxVariant}{\param{double}{ value}, \param{const wxString\& }{name = ``"}}
59
60Construction from a double-precision floating point value.
61
62\func{}{wxVariant}{\param{const wxList\&}{ value}, \param{const wxString\& }{name = ``"}}
63
64Construction from a list of wxVariant objects. This constructor
65copies {\it value}, the application is still responsible for
66deleting {\it value} and its contents.
67
a974387a
JS
68\func{}{wxVariant}{\param{void*}{ value}, \param{const wxString\& }{name = ``"}}
69
70Construction from a void pointer.
71
cf6ae290
RG
72\func{}{wxVariant}{\param{wxObject*}{ value}, \param{const wxString\& }{name = ``"}}
73
74Construction from a wxObject pointer.
75
a974387a
JS
76\func{}{wxVariant}{\param{wxVariantData*}{ data}, \param{const wxString\& }{name = ``"}}
77
8715d2d3
RN
78Construction from user-defined data. The variant holds onto the {\it data} pointer.
79
80\func{}{wxVariant}{\param{wxDateTime\&}{ val}, \param{const wxString\& }{name = ``"}}
81
82Construction from a \helpref{wxDateTime}{wxdatetime}.
83
84\func{}{wxVariant}{\param{wxArrayString\&}{ val}, \param{const wxString\& }{name = ``"}}
85
86Construction 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
90Construction 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
94Construction 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
98Construction from a odbc timestamp value. Represented internally by a \helpref{wxDateTime}{wxdatetime} value.
a974387a
JS
99
100\membersection{wxVariant::\destruct{wxVariant}}\label{wxvariantdtor}
101
102\func{}{\destruct{wxVariant}}{\void}
103
104Destructor.
105
8715d2d3 106
a974387a
JS
107\membersection{wxVariant::Append}\label{wxvariantappend}
108
109\func{void}{Append}{\param{const wxVariant\&}{ value}}
110
111Appends a value to the list.
112
113\membersection{wxVariant::ClearList}\label{wxvariantclearlist}
114
115\func{void}{ClearList}{\void}
116
117Deletes the contents of the list.
118
8715d2d3
RN
119
120\membersection{wxVariant::Convert}\label{wxvariantconvert}
121
122\constfunc{bool}{Convert}{long* value}
123
124\constfunc{bool}{Convert}{bool* value}
125
126\constfunc{bool}{Convert}{double* value}
127
128\constfunc{bool}{Convert}{wxString* value}
129
130\constfunc{bool}{Convert}{char* value}
131
132\constfunc{bool}{Convert}{wxDateTime* value}
133
134Retrieves and converts the value of this variant to the type that {\it value} is.
135
136
a974387a
JS
137\membersection{wxVariant::GetCount}\label{wxvariantgetcount}
138
139\constfunc{int}{GetCount}{\void}
140
141Returns the number of elements in the list.
142
143\membersection{wxVariant::Delete}\label{wxvariantdelete}
144
145\func{bool}{Delete}{\param{int }{item}}
146
147Deletes the zero-based {\it item} from the list.
148
8715d2d3
RN
149\membersection{wxVariant::GetArrayString}\label{wxvariantgetarraystring}
150
151\constfunc{wxArrayString}{GetArrayString}{\void}
152
153Returns the string array value.
154
a974387a
JS
155\membersection{wxVariant::GetBool}\label{wxvariantgetbool}
156
157\constfunc{bool}{GetBool}{\void}
158
159Returns the boolean value.
160
161\membersection{wxVariant::GetChar}\label{wxvariantgetchar}
162
163\constfunc{char}{GetChar}{\void}
164
165Returns the character value.
166
167\membersection{wxVariant::GetData}\label{wxvariantgetdata}
168
169\constfunc{wxVariantData*}{GetData}{\void}
170
171Returns a pointer to the internal variant data.
172
8715d2d3
RN
173\membersection{wxVariant::GetDateTime}\label{wxvariantgetdatetime}
174
175\constfunc{wxDateTime}{GetDateTime}{\void}
176
177Returns the date value.
178
a974387a
JS
179\membersection{wxVariant::GetDouble}\label{wxvariantgetdouble}
180
181\constfunc{double}{GetDouble}{\void}
182
183Returns the floating point value.
184
185\membersection{wxVariant::GetLong}\label{wxvariantgetlong}
186
187\constfunc{long}{GetLong}{\void}
188
189Returns the integer value.
190
191\membersection{wxVariant::GetName}\label{wxvariantgetname}
192
193\constfunc{const wxString\&}{GetName}{\void}
194
195Returns a constant reference to the variant name.
196
197\membersection{wxVariant::GetString}\label{wxvariantgetstring}
198
199\constfunc{wxString}{GetString}{\void}
200
201Gets the string value.
202
a974387a
JS
203\membersection{wxVariant::GetType}\label{wxvariantgettype}
204
205\constfunc{wxString}{GetType}{\void}
206
207Returns the value type as a string. The built-in types are: bool, char, date, double, list, long, string, stringlist, time, void*.
208
209If 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
215Gets the void pointer value.
216
cf6ae290
RG
217\membersection{wxVariant::GetWxObjectPtr}\label{wxvariantgetwxobjectptr}
218
219\constfunc{void*}{GetWxObjectPtr}{\void}
220
221Gets the wxObject pointer value.
222
a974387a
JS
223\membersection{wxVariant::Insert}\label{wxvariantinsert}
224
225\func{void}{Insert}{\param{const wxVariant\&}{ value}}
226
227Inserts a value at the front of the list.
228
229\membersection{wxVariant::IsNull}\label{wxvariantisnull}
230
231\constfunc{bool}{IsNull}{\void}
232
cc81d32f 233Returns true if there is no data associated with this variant, false if there is data.
a974387a
JS
234
235\membersection{wxVariant::IsType}\label{wxvariantistype}
236
237\constfunc{bool}{IsType}{\param{const wxString\&}{ type}}
238
cc81d32f 239Returns true if {\it type} matches the type of the variant, false otherwise.
a974387a 240
cf6ae290
RG
241\membersection{wxVariant::IsValueKindOf}\label{wxvariantisvaluekindof}
242
243\constfunc{bool}{IsValueKindOf}{\param{const wxClassInfo* type}{ type}}
244
245Returns true if the data is derived from the class described by {\it type}, false otherwise.
246
a974387a
JS
247\membersection{wxVariant::MakeNull}\label{wxvariantmakenull}
248
249\func{void}{MakeNull}{\void}
250
251Makes the variant null by deleting the internal data.
252
253\membersection{wxVariant::MakeString}\label{wxvariantmakestring}
254
255\constfunc{wxString}{MakeString}{\void}
256
257Makes 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
cc81d32f 263Returns true if {\it value} matches an element in the list.
a974387a
JS
264
265\membersection{wxVariant::NullList}\label{wxvariantnulllist}
266
267\func{void}{NullList}{\void}
268
269Makes an empty list. This differs from a null variant which has no data; a null list
270is 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
276Sets 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
a974387a
JS
296\func{void}{operator $=$}{\param{void* }{value}}
297
298\func{void}{operator $=$}{\param{const wxList\& }{value}}
299
8715d2d3
RN
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
a974387a
JS
310Assignment operators.
311
312\membersection{wxVariant::operator $==$}\label{wxvarianteq}
313
8715d2d3
RN
314\constfunc{bool}{operator $==$}{\param{const wxVariant\& }{value}}
315
316\constfunc{bool}{operator $==$}{\param{const wxString\& }{value}}
a974387a 317
8715d2d3 318\constfunc{bool}{operator $==$}{\param{const char* }{value}}
a974387a 319
8715d2d3 320\constfunc{bool}{operator $==$}{\param{char }{value}}
a974387a 321
8715d2d3 322\constfunc{bool}{operator $==$}{\param{const long }{value}}
a974387a 323
8715d2d3 324\constfunc{bool}{operator $==$}{\param{const bool }{value}}
a974387a 325
8715d2d3 326\constfunc{bool}{operator $==$}{\param{const double }{value}}
a974387a 327
8715d2d3 328\constfunc{bool}{operator $==$}{\param{void* }{value}}
a974387a 329
8715d2d3 330\constfunc{bool}{operator $==$}{\param{const wxList\& }{value}}
a974387a 331
8715d2d3
RN
332\constfunc{bool}{operator $==$}{\param{const wxArrayString\& }{value}}
333
334\constfunc{bool}{operator $==$}{\param{const wxDateTime\& }{value}}
a974387a
JS
335
336Equality test operators.
337
338\membersection{wxVariant::operator $!=$}\label{wxvariantneq}
339
8715d2d3
RN
340\constfunc{bool}{operator $!=$}{\param{const wxVariant\& }{value}}
341
342\constfunc{bool}{operator $!=$}{\param{const wxString\& }{value}}
a974387a 343
8715d2d3 344\constfunc{bool}{operator $!=$}{\param{const char* }{value}}
a974387a 345
8715d2d3 346\constfunc{bool}{operator $!=$}{\param{char }{value}}
a974387a 347
8715d2d3 348\constfunc{bool}{operator $!=$}{\param{const long }{value}}
a974387a 349
8715d2d3 350\constfunc{bool}{operator $!=$}{\param{const bool }{value}}
a974387a 351
8715d2d3 352\constfunc{bool}{operator $!=$}{\param{const double }{value}}
a974387a 353
8715d2d3 354\constfunc{bool}{operator $!=$}{\param{void* }{value}}
a974387a 355
8715d2d3 356\constfunc{bool}{operator $!=$}{\param{const wxList\& }{value}}
a974387a 357
8715d2d3
RN
358\constfunc{bool}{operator $!=$}{\param{const wxArrayString\& }{value}}
359
360\constfunc{bool}{operator $!=$}{\param{const wxDateTime\& }{value}}
a974387a
JS
361
362Inequality test operators.
363
364\membersection{wxVariant::operator $[]$}\label{wxvariantarray}
365
366\constfunc{wxVariant}{operator $[]$}{\param{size\_t }{idx}}
367
368Returns the value at {\it idx} (zero-based).
369
370\func{wxVariant\&}{operator $[]$}{\param{size\_t }{idx}}
371
372Returns a reference to the value at {\it idx} (zero-based). This can be used
373to change the value at this index.
374
375\membersection{wxVariant::operator char}\label{wxvariantchar}
376
377\constfunc{char}{operator char}{\void}
378
379Operator 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
385Operator for implicit conversion to a double, using \helpref{wxVariant::GetDouble}{wxvariantgetdouble}.
386
387\constfunc{long}{operator long}{\void}
388
389Operator for implicit conversion to a long, using \helpref{wxVariant::GetLong}{wxvariantgetlong}.
390
a974387a
JS
391\membersection{wxVariant::operator wxString}\label{wxvariantwxstring}
392
393\constfunc{wxString}{operator wxString}{\void}
394
395Operator for implicit conversion to a string, using \helpref{wxVariant::MakeString}{wxvariantmakestring}.
396
a974387a
JS
397\membersection{wxVariant::operator void*}\label{wxvariantvoid}
398
399\constfunc{void*}{operator void*}{\void}
400
401Operator for implicit conversion to a pointer to a void, using \helpref{wxVariant::GetVoidPtr}{wxvariantgetvoidptr}.
402
8715d2d3
RN
403\membersection{wxVariant::operator wxDateTime}\label{wxvariantdatetime}
404
405\constfunc{void*}{operator wxDateTime}{\void}
406
407Operator for implicit conversion to a pointer to a \helpref{wxDateTime}{wxdatetime}, using \helpref{wxVariant::GetDateTime}{wxvariantgetdatetime}.
408
a974387a
JS
409\section{\class{wxVariantData}}\label{wxvariantdata}
410
411The {\bf wxVariantData} is used to implement a new type for wxVariant. Derive from wxVariantData,
412and override the pure virtual functions.
413
414\wxheading{Derived from}
415
416\helpref{wxObject}{wxobject}
417
954b8ae6
JS
418\wxheading{Include files}
419
420<wx/variant.h>
421
a974387a
JS
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
432Default constructor.
433
434\membersection{wxVariantData::Copy}\label{wxvariantdatacopy}
435
436\func{void}{Copy}{\param{wxVariantData\&}{ data}}
437
438Copy the data from `this' object to {\it data}.
439
440\membersection{wxVariantData::Eq}\label{wxvariantdataeq}
441
442\constfunc{bool}{Eq}{\param{wxVariantData\&}{ data}}
443
cc81d32f 444Returns true if this object is equal to {\it data}.
a974387a
JS
445
446\membersection{wxVariantData::GetType}\label{wxvariantdatagettype}
447
448\constfunc{wxString}{GetType}{\void}
449
450Returns the string type of the data.
451
cf6ae290
RG
452\membersection{wxVariantData::GetValueClassInfo}\label{wxvariantdatagetvalueclassinfo}
453
454\constfunc{wxClassInfo*}{GetValueClassInfo}{\void}
455
456If the data is a wxObject returns a pointer to the objects wxClassInfo structure, if
457the data isn't a wxObject the method returns NULL.
458
a974387a
JS
459\membersection{wxVariantData::Read}\label{wxvariantdataread}
460
461\func{bool}{Read}{\param{ostream\&}{ stream}}
462
463\func{bool}{Read}{\param{wxString\&}{ string}}
464
465Reads 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
473Writes the data to {\it stream} or {\it string}.
474
475
cf6ae290
RG
476\membersection{wxGetVariantCast}\label{wxgetvariantcast}
477
478\func{classname *}{wxGetVariantCast}{wxVariant\&, classname}
479
480This macro returns the data stored in {\it variant} cast to the type {\it classname *} if
481the data is of this type (the check is done during the run-time) or
482{\tt NULL} otherwise.
483
484
485\wxheading{See also}
a974387a 486
cf6ae290 487\helpref{RTTI overview}{runtimeclassoverview}\\
0497e172
JS
488\helpref{wxDynamicCast}{wxdynamiccast}
489