]> git.saurik.com Git - wxWidgets.git/blob - docs/latex/wx/variant.tex
Typo correction
[wxWidgets.git] / docs / latex / wx / variant.tex
1 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2 %% Name: variant.tex
3 %% Purpose: wxVariant docs
4 %% Author: wxWidgets Team
5 %% Modified by:
6 %% Created: 01/30/2005
7 %% RCS-ID: $Id$
8 %% Copyright: (c) wxWidgets Team
9 %% License: wxWindows license
10 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
11
12 \section{\class{wxVariant}}\label{wxvariant}
13
14 The {\bf wxVariant} class represents a container for any type.
15 A variant's value can be changed at run time, possibly to a different type of value.
16
17 As standard, wxVariant can store values of type bool, wxChar, double, long, string,
18 string list, time, date, void pointer, list of strings, and list of variants.
19 However, an application can extend wxVariant's capabilities by deriving from the
20 class \helpref{wxVariantData}{wxvariantdata} and using the wxVariantData form of
21 the wxVariant constructor or assignment operator to assign this data to a variant.
22 Actual values for user-defined types will need to be accessed via the wxVariantData
23 object, unlike the case for basic data types where convenience functions such as
24 \helpref{GetLong}{wxvariantgetlong} can be used.
25
26 Pointers to any \helpref{wxObject}{wxobject} derived class can also easily be stored
27 in a wxVariant. wxVariant will then use wxWidgets' built-in RTTI system to set the
28 type name (returned by \helpref{GetType}{wxvariantgettype}) and to perform
29 type-safety checks at runtime.
30
31 This class is useful for reducing the programming for certain tasks, such as an editor
32 for different data types, or a remote procedure call protocol.
33
34 An optional name member is associated with a wxVariant. This might be used, for example,
35 in CORBA or OLE automation classes, where named parameters are required.
36
37 Note that as of wxWidgets 2.7.1, wxVariant is \helpref{reference counted}{trefcount}.
38 Additionally, the convenience macros {\bf DECLARE\_VARIANT\_OBJECT} and
39 {\bf IMPLEMENT\_VARIANT\_OBJECT} were added so that adding (limited) support
40 for conversion to and from wxVariant can be very easily implemented without modifying
41 either wxVariant or the class to be stored by wxVariant. Since assignment operators
42 cannot be declared outside the class, the shift left operators are used like this:
43
44 \begin{verbatim}
45 // in the header file
46 DECLARE_VARIANT_OBJECT(MyClass)
47
48 // in the implementation file
49 IMPLMENT_VARIANT_OBJECT(MyClass)
50
51 // in the user code
52 wxVariant variant;
53 MyClass value;
54 variant << value;
55
56 // or
57 value << variant;
58 \end{verbatim}
59
60 For this to work, MyClass must derive from \helpref{wxObject}{wxobject}, implement
61 the \helpref{wxWidgets RTTI system}{runtimeclassoverview}
62 and support the assignment operator and equality operator for itself. Ideally, it
63 should also be reference counted to make copying operations cheap and fast. This
64 can be most easily implemented using the reference counting support offered by
65 \helpref{wxObject}{wxobject} itself. By default, wxWidgets already implements
66 the shift operator conversion for a few of its drawing related classes:
67
68 \begin{verbatim}
69 IMPLEMENT_VARIANT_OBJECT(wxColour)
70 IMPLEMENT_VARIANT_OBJECT(wxImage)
71 IMPLEMENT_VARIANT_OBJECT(wxIcon)
72 IMPLEMENT_VARIANT_OBJECT(wxBitmap)
73 \end{verbatim}
74
75 \wxheading{Derived from}
76
77 \helpref{wxObject}{wxobject}
78
79 \wxheading{Include files}
80
81 <wx/variant.h>
82
83 \wxheading{See also}
84
85 \helpref{wxVariantData}{wxvariantdata}
86
87 \latexignore{\rtfignore{\wxheading{Members}}}
88
89 \membersection{wxVariant::wxVariant}\label{wxvariantctor}
90
91 \func{}{wxVariant}{\void}
92
93 Default constructor.
94
95 \func{}{wxVariant}{\param{const wxVariant\& }{variant}}
96
97 Copy constructor, uses \helpref{reference counting}{trefcount}.
98
99 \func{}{wxVariant}{\param{const wxChar*}{ value}, \param{const wxString\& }{name = ``"}}
100
101 \func{}{wxVariant}{\param{const wxString\&}{ value}, \param{const wxString\& }{name = ``"}}
102
103 Construction from a string value.
104
105 \func{}{wxVariant}{\param{wxChar}{ value}, \param{const wxString\& }{name = ``"}}
106
107 Construction from a character value.
108
109 \func{}{wxVariant}{\param{long}{ value}, \param{const wxString\& }{name = ``"}}
110
111 Construction from an integer value. You may need to cast to (long) to
112 avoid confusion with other constructors (such as the bool constructor).
113
114 \func{}{wxVariant}{\param{bool}{ value}, \param{const wxString\& }{name = ``"}}
115
116 Construction from a boolean value.
117
118 \func{}{wxVariant}{\param{double}{ value}, \param{const wxString\& }{name = ``"}}
119
120 Construction from a double-precision floating point value.
121
122 \func{}{wxVariant}{\param{const wxList\&}{ value}, \param{const wxString\& }{name = ``"}}
123
124 Construction from a list of wxVariant objects. This constructor
125 copies {\it value}, the application is still responsible for
126 deleting {\it value} and its contents.
127
128 \func{}{wxVariant}{\param{void*}{ value}, \param{const wxString\& }{name = ``"}}
129
130 Construction from a void pointer.
131
132 \func{}{wxVariant}{\param{wxObject*}{ value}, \param{const wxString\& }{name = ``"}}
133
134 Construction from a wxObject pointer.
135
136 \func{}{wxVariant}{\param{wxVariantData*}{ data}, \param{const wxString\& }{name = ``"}}
137
138 Construction from user-defined data. The variant holds onto the {\it data} pointer.
139
140 \func{}{wxVariant}{\param{wxDateTime\&}{ val}, \param{const wxString\& }{name = ``"}}
141
142 Construction from a \helpref{wxDateTime}{wxdatetime}.
143
144 \func{}{wxVariant}{\param{wxArrayString\&}{ val}, \param{const wxString\& }{name = ``"}}
145
146 Construction from an array of strings. This constructor copies {\it value} and its contents.
147
148 \func{}{wxVariant}{\param{DATE\_STRUCT*}{ val}, \param{const wxString\& }{name = ``"}}
149
150 Construction from a odbc date value. Represented internally by a \helpref{wxDateTime}{wxdatetime} value.
151
152 \func{}{wxVariant}{\param{TIME\_STRUCT*}{ val}, \param{const wxString\& }{name = ``"}}
153
154 Construction from a odbc time value. Represented internally by a \helpref{wxDateTime}{wxdatetime} value.
155
156 \func{}{wxVariant}{\param{TIMESTAMP\_STRUCT*}{ val}, \param{const wxString\& }{name = ``"}}
157
158 Construction from a odbc timestamp value. Represented internally by a \helpref{wxDateTime}{wxdatetime} value.
159
160 \membersection{wxVariant::\destruct{wxVariant}}\label{wxvariantdtor}
161
162 \func{}{\destruct{wxVariant}}{\void}
163
164 Destructor.
165
166 Note that destructor is protected, so wxVariantData cannot usually
167 be deleted. Instead, \helpref{DecRef}{wxvariantdatadecref} should be called.
168 See \helpref{reference-counted object destruction}{refcountdestruct} for more info.
169
170
171 \membersection{wxVariant::Append}\label{wxvariantappend}
172
173 \func{void}{Append}{\param{const wxVariant\&}{ value}}
174
175 Appends a value to the list.
176
177 \membersection{wxVariant::Clear}\label{wxvariantclear}
178
179 \func{void}{Clear}{\void}
180
181 Makes the variant null by deleting the internal data and
182 set the name to {\it wxEmptyString}.
183
184 \membersection{wxVariant::ClearList}\label{wxvariantclearlist}
185
186 \func{void}{ClearList}{\void}
187
188 Deletes the contents of the list.
189
190
191 \membersection{wxVariant::Convert}\label{wxvariantconvert}
192
193 \constfunc{bool}{Convert}{\param{long*}{ value}}
194
195 \constfunc{bool}{Convert}{\param{bool*}{ value}}
196
197 \constfunc{bool}{Convert}{\param{double*}{ value}}
198
199 \constfunc{bool}{Convert}{\param{wxString*}{ value}}
200
201 \constfunc{bool}{Convert}{\param{wxChar*}{ value}}
202
203 \constfunc{bool}{Convert}{\param{wxDateTime*}{ value}}
204
205 Retrieves and converts the value of this variant to the type that {\it value} is.
206
207
208 \membersection{wxVariant::GetCount}\label{wxvariantgetcount}
209
210 \constfunc{size\_t}{GetCount}{\void}
211
212 Returns the number of elements in the list.
213
214 \membersection{wxVariant::Delete}\label{wxvariantdelete}
215
216 \func{bool}{Delete}{\param{size\_t }{item}}
217
218 Deletes the zero-based {\it item} from the list.
219
220 \membersection{wxVariant::GetArrayString}\label{wxvariantgetarraystring}
221
222 \constfunc{wxArrayString}{GetArrayString}{\void}
223
224 Returns the string array value.
225
226 \membersection{wxVariant::GetBool}\label{wxvariantgetbool}
227
228 \constfunc{bool}{GetBool}{\void}
229
230 Returns the boolean value.
231
232 \membersection{wxVariant::GetChar}\label{wxvariantgetchar}
233
234 \constfunc{wxChar}{GetChar}{\void}
235
236 Returns the character value.
237
238 \membersection{wxVariant::GetData}\label{wxvariantgetdata}
239
240 \constfunc{wxVariantData*}{GetData}{\void}
241
242 Returns a pointer to the internal variant data. To take ownership
243 of this data, you must call its \helpref{IncRef}{wxvariantdataincref}
244 method. When you stop using it, \helpref{DecRef}{wxvariantdatadecref}
245 must be likewise called.
246
247 \membersection{wxVariant::GetDateTime}\label{wxvariantgetdatetime}
248
249 \constfunc{wxDateTime}{GetDateTime}{\void}
250
251 Returns the date value.
252
253 \membersection{wxVariant::GetDouble}\label{wxvariantgetdouble}
254
255 \constfunc{double}{GetDouble}{\void}
256
257 Returns the floating point value.
258
259 \membersection{wxVariant::GetLong}\label{wxvariantgetlong}
260
261 \constfunc{long}{GetLong}{\void}
262
263 Returns the integer value.
264
265 \membersection{wxVariant::GetName}\label{wxvariantgetname}
266
267 \constfunc{const wxString\&}{GetName}{\void}
268
269 Returns a constant reference to the variant name.
270
271 \membersection{wxVariant::GetString}\label{wxvariantgetstring}
272
273 \constfunc{wxString}{GetString}{\void}
274
275 Gets the string value.
276
277 \membersection{wxVariant::GetType}\label{wxvariantgettype}
278
279 \constfunc{wxString}{GetType}{\void}
280
281 Returns the value type as a string. The built-in types are: bool, char, date, double, list, long, string, stringlist, time, void*.
282
283 If the variant is null, the value type returned is the string ``null" (not the empty string).
284
285 \membersection{wxVariant::GetVoidPtr}\label{wxvariantgetvoidptr}
286
287 \constfunc{void*}{GetVoidPtr}{\void}
288
289 Gets the void pointer value.
290
291 \membersection{wxVariant::GetWxObjectPtr}\label{wxvariantgetwxobjectptr}
292
293 \constfunc{wxObject*}{GetWxObjectPtr}{\void}
294
295 Gets the wxObject pointer value.
296
297 \membersection{wxVariant::Insert}\label{wxvariantinsert}
298
299 \func{void}{Insert}{\param{const wxVariant\&}{ value}}
300
301 Inserts a value at the front of the list.
302
303 \membersection{wxVariant::IsNull}\label{wxvariantisnull}
304
305 \constfunc{bool}{IsNull}{\void}
306
307 Returns true if there is no data associated with this variant, false if there is data.
308
309 \membersection{wxVariant::IsType}\label{wxvariantistype}
310
311 \constfunc{bool}{IsType}{\param{const wxString\&}{ type}}
312
313 Returns true if {\it type} matches the type of the variant, false otherwise.
314
315 \membersection{wxVariant::IsValueKindOf}\label{wxvariantisvaluekindof}
316
317 \constfunc{bool}{IsValueKindOf}{\param{const wxClassInfo* type}{ type}}
318
319 Returns true if the data is derived from the class described by {\it type}, false otherwise.
320
321 \membersection{wxVariant::MakeNull}\label{wxvariantmakenull}
322
323 \func{void}{MakeNull}{\void}
324
325 Makes the variant null by deleting the internal data.
326
327 \membersection{wxVariant::MakeString}\label{wxvariantmakestring}
328
329 \constfunc{wxString}{MakeString}{\void}
330
331 Makes a string representation of the variant value (for any type).
332
333 \membersection{wxVariant::Member}\label{wxvariantmember}
334
335 \constfunc{bool}{Member}{\param{const wxVariant\&}{ value}}
336
337 Returns true if {\it value} matches an element in the list.
338
339 \membersection{wxVariant::NullList}\label{wxvariantnulllist}
340
341 \func{void}{NullList}{\void}
342
343 Makes an empty list. This differs from a null variant which has no data; a null list
344 is of type list, but the number of elements in the list is zero.
345
346 \membersection{wxVariant::SetData}\label{wxvariantsetdata}
347
348 \func{void}{SetData}{\param{wxVariantData*}{ data}}
349
350 Sets the internal variant data, deleting the existing data if there is any.
351
352 \membersection{wxVariant::operator $=$}\label{wxvariantassignment}
353
354 \func{void}{operator $=$}{\param{const wxVariant\& }{value}}
355
356 \func{void}{operator $=$}{\param{wxVariantData* }{value}}
357
358 \func{void}{operator $=$}{\param{const wxString\& }{value}}
359
360 \func{void}{operator $=$}{\param{const wxChar* }{value}}
361
362 \func{void}{operator $=$}{\param{wxChar }{value}}
363
364 \func{void}{operator $=$}{\param{const long }{value}}
365
366 \func{void}{operator $=$}{\param{const bool }{value}}
367
368 \func{void}{operator $=$}{\param{const double }{value}}
369
370 \func{void}{operator $=$}{\param{void* }{value}}
371
372 \func{void}{operator $=$}{\param{wxObject* }{value}}
373
374 \func{void}{operator $=$}{\param{const wxList\& }{value}}
375
376 \func{void}{operator $=$}{\param{const wxDateTime\& }{value}}
377
378 \func{void}{operator $=$}{\param{const wxArrayString\& }{value}}
379
380 \func{void}{operator $=$}{\param{const DATE\_STRUCT* }{value}}
381
382 \func{void}{operator $=$}{\param{const TIME\_STRUCT* }{value}}
383
384 \func{void}{operator $=$}{\param{const TIMESTAMP\_STRUCT* }{value}}
385
386 Assignment operators, using \helpref{reference counting}{trefcount} when possible.
387
388 \membersection{wxVariant::operator $==$}\label{wxvarianteq}
389
390 \constfunc{bool}{operator $==$}{\param{const wxVariant\& }{value}}
391
392 \constfunc{bool}{operator $==$}{\param{const wxString\& }{value}}
393
394 \constfunc{bool}{operator $==$}{\param{const wxChar* }{value}}
395
396 \constfunc{bool}{operator $==$}{\param{wxChar }{value}}
397
398 \constfunc{bool}{operator $==$}{\param{const long }{value}}
399
400 \constfunc{bool}{operator $==$}{\param{const bool }{value}}
401
402 \constfunc{bool}{operator $==$}{\param{const double }{value}}
403
404 \constfunc{bool}{operator $==$}{\param{void* }{value}}
405
406 \constfunc{bool}{operator $==$}{\param{wxObject* }{value}}
407
408 \constfunc{bool}{operator $==$}{\param{const wxList\& }{value}}
409
410 \constfunc{bool}{operator $==$}{\param{const wxArrayString\& }{value}}
411
412 \constfunc{bool}{operator $==$}{\param{const wxDateTime\& }{value}}
413
414 Equality test operators.
415
416 \membersection{wxVariant::operator $!=$}\label{wxvariantneq}
417
418 \constfunc{bool}{operator $!=$}{\param{const wxVariant\& }{value}}
419
420 \constfunc{bool}{operator $!=$}{\param{const wxString\& }{value}}
421
422 \constfunc{bool}{operator $!=$}{\param{const wxChar* }{value}}
423
424 \constfunc{bool}{operator $!=$}{\param{wxChar }{value}}
425
426 \constfunc{bool}{operator $!=$}{\param{const long }{value}}
427
428 \constfunc{bool}{operator $!=$}{\param{const bool }{value}}
429
430 \constfunc{bool}{operator $!=$}{\param{const double }{value}}
431
432 \constfunc{bool}{operator $!=$}{\param{void* }{value}}
433
434 \constfunc{bool}{operator $!=$}{\param{wxObject* }{value}}
435
436 \constfunc{bool}{operator $!=$}{\param{const wxList\& }{value}}
437
438 \constfunc{bool}{operator $!=$}{\param{const wxArrayString\& }{value}}
439
440 \constfunc{bool}{operator $!=$}{\param{const wxDateTime\& }{value}}
441
442 Inequality test operators.
443
444 \membersection{wxVariant::operator $[]$}\label{wxvariantarray}
445
446 \constfunc{wxVariant}{operator $[]$}{\param{size\_t }{idx}}
447
448 Returns the value at {\it idx} (zero-based).
449
450 \func{wxVariant\&}{operator $[]$}{\param{size\_t }{idx}}
451
452 Returns a reference to the value at {\it idx} (zero-based). This can be used
453 to change the value at this index.
454
455 \membersection{wxVariant::operator wxChar}\label{wxvariantchar}
456
457 \constfunc{char}{operator wxChar}{\void}
458
459 Operator for implicit conversion to a wxChar, using \helpref{wxVariant::GetChar}{wxvariantgetchar}.
460
461 \membersection{wxVariant::operator double}\label{wxvariantdouble}
462
463 \constfunc{double}{operator double}{\void}
464
465 Operator for implicit conversion to a double, using \helpref{wxVariant::GetDouble}{wxvariantgetdouble}.
466
467 \constfunc{long}{operator long}{\void}
468
469 Operator for implicit conversion to a long, using \helpref{wxVariant::GetLong}{wxvariantgetlong}.
470
471 \membersection{wxVariant::operator wxString}\label{wxvariantwxstring}
472
473 \constfunc{wxString}{operator wxString}{\void}
474
475 Operator for implicit conversion to a string, using \helpref{wxVariant::MakeString}{wxvariantmakestring}.
476
477 \membersection{wxVariant::operator void*}\label{wxvariantvoid}
478
479 \constfunc{void*}{operator void*}{\void}
480
481 Operator for implicit conversion to a pointer to a void, using \helpref{wxVariant::GetVoidPtr}{wxvariantgetvoidptr}.
482
483 \membersection{wxVariant::operator wxDateTime}\label{wxvariantdatetime}
484
485 \constfunc{void*}{operator wxDateTime}{\void}
486
487 Operator for implicit conversion to a pointer to a \helpref{wxDateTime}{wxdatetime}, using \helpref{wxVariant::GetDateTime}{wxvariantgetdatetime}.
488
489
490
491 %% wxVariantData
492
493
494 \section{\class{wxVariantData}}\label{wxvariantdata}
495
496 The {\bf wxVariantData} class is used to implement a new type for \helpref{wxVariant}{wxvariant}.
497 Derive from wxVariantData, and override the pure virtual functions.
498
499 wxVariantData is \helpref{reference counted}{refcount}, but you don't normally have to care about this,
500 as wxVariant manages the count automatically. However, in case your application needs to take
501 ownership of wxVariantData, be aware that the object is created with reference count of 1,
502 and passing it to wxVariant will not increase this. In other words, \helpref{IncRef}{wxvariantdataincref}
503 needs to be called only if you both take ownership of wxVariantData and pass it to a wxVariant.
504 Also note that the destructor is protected, so you can never explicitly delete a wxVariantData
505 instance. Instead, \helpref{DecRef}{wxvariantdatadecref} will delete the object automatically
506 when the reference count reaches zero.
507
508 \wxheading{Derived from}
509
510 \helpref{wxObject}{wxobject}
511
512 \wxheading{Include files}
513
514 <wx/variant.h>
515
516 \wxheading{See also}
517
518 \helpref{wxVariant}{wxvariant}
519
520 \latexignore{\rtfignore{\wxheading{Members}}}
521
522 \membersection{wxVariantData::wxVariantData}\label{wxvariantdatactor}
523
524 \func{}{wxVariantData}{\void}
525
526 Default constructor.
527
528 \membersection{wxVariantData::DecRef}\label{wxvariantdatadecref}
529
530 \func{void}{DecRef}{\void}
531
532 Decreases reference count. If the count reaches zero, the object is
533 automatically deleted.
534
535 Note that destructor of wxVariantData is protected, so delete
536 cannot be used as normal. Instead, \helpref{DecRef}{wxvariantdatadecref} should be called.
537
538
539
540 \membersection{wxVariantData::Eq}\label{wxvariantdataeq}
541
542 \constfunc{bool}{Eq}{\param{wxVariantData\&}{ data}}
543
544 Returns true if this object is equal to {\it data}.
545
546 \membersection{wxVariantData::GetType}\label{wxvariantdatagettype}
547
548 \constfunc{wxString}{GetType}{\void}
549
550 Returns the string type of the data.
551
552 \membersection{wxVariantData::GetValueClassInfo}\label{wxvariantdatagetvalueclassinfo}
553
554 \constfunc{wxClassInfo*}{GetValueClassInfo}{\void}
555
556 If the data is a wxObject returns a pointer to the objects wxClassInfo structure, if
557 the data isn't a wxObject the method returns NULL.
558
559 \membersection{wxVariantData::IncRef}\label{wxvariantdataincref}
560
561 \func{void}{IncRef}{\void}
562
563 Increases reference count. Note that initially wxVariantData has reference count of 1.
564
565 \membersection{wxVariantData::Read}\label{wxvariantdataread}
566
567 \func{bool}{Read}{\param{ostream\&}{ stream}}
568
569 \func{bool}{Read}{\param{wxString\&}{ string}}
570
571 Reads the data from {\it stream} or {\it string}.
572
573 \membersection{wxVariantData::Write}\label{wxvariantdatawrite}
574
575 \constfunc{bool}{Write}{\param{ostream\&}{ stream}}
576
577 \constfunc{bool}{Write}{\param{wxString\&}{ string}}
578
579 Writes the data to {\it stream} or {\it string}.
580
581
582 \membersection{wxGetVariantCast}\label{wxgetvariantcast}
583
584 \func{classname *}{wxGetVariantCast}{wxVariant\&, classname}
585
586 This macro returns the data stored in {\it variant} cast to the type {\it classname *} if
587 the data is of this type (the check is done during the run-time) or
588 {\tt NULL} otherwise.
589
590
591 \wxheading{See also}
592
593 \helpref{RTTI overview}{runtimeclassoverview}\\
594 \helpref{wxDynamicCast}{wxdynamiccast}
595