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