]>
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 | ||
a974387a JS |
83 | \func{}{wxVariant}{\param{void*}{ value}, \param{const wxString\& }{name = ``"}} |
84 | ||
85 | Construction from a void pointer. | |
86 | ||
cf6ae290 RG |
87 | \func{}{wxVariant}{\param{wxObject*}{ value}, \param{const wxString\& }{name = ``"}} |
88 | ||
89 | Construction from a wxObject pointer. | |
90 | ||
a974387a JS |
91 | \func{}{wxVariant}{\param{wxVariantData*}{ data}, \param{const wxString\& }{name = ``"}} |
92 | ||
93 | Construction 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 | ||
99 | Destructor. | |
100 | ||
101 | \membersection{wxVariant::Append}\label{wxvariantappend} | |
102 | ||
103 | \func{void}{Append}{\param{const wxVariant\&}{ value}} | |
104 | ||
105 | Appends a value to the list. | |
106 | ||
107 | \membersection{wxVariant::ClearList}\label{wxvariantclearlist} | |
108 | ||
109 | \func{void}{ClearList}{\void} | |
110 | ||
111 | Deletes the contents of the list. | |
112 | ||
113 | \membersection{wxVariant::GetCount}\label{wxvariantgetcount} | |
114 | ||
115 | \constfunc{int}{GetCount}{\void} | |
116 | ||
117 | Returns the number of elements in the list. | |
118 | ||
119 | \membersection{wxVariant::Delete}\label{wxvariantdelete} | |
120 | ||
121 | \func{bool}{Delete}{\param{int }{item}} | |
122 | ||
123 | Deletes the zero-based {\it item} from the list. | |
124 | ||
125 | \membersection{wxVariant::GetBool}\label{wxvariantgetbool} | |
126 | ||
127 | \constfunc{bool}{GetBool}{\void} | |
128 | ||
129 | Returns the boolean value. | |
130 | ||
131 | \membersection{wxVariant::GetChar}\label{wxvariantgetchar} | |
132 | ||
133 | \constfunc{char}{GetChar}{\void} | |
134 | ||
135 | Returns the character value. | |
136 | ||
137 | \membersection{wxVariant::GetData}\label{wxvariantgetdata} | |
138 | ||
139 | \constfunc{wxVariantData*}{GetData}{\void} | |
140 | ||
141 | Returns a pointer to the internal variant data. | |
142 | ||
a974387a JS |
143 | \membersection{wxVariant::GetDouble}\label{wxvariantgetdouble} |
144 | ||
145 | \constfunc{double}{GetDouble}{\void} | |
146 | ||
147 | Returns the floating point value. | |
148 | ||
149 | \membersection{wxVariant::GetLong}\label{wxvariantgetlong} | |
150 | ||
151 | \constfunc{long}{GetLong}{\void} | |
152 | ||
153 | Returns the integer value. | |
154 | ||
155 | \membersection{wxVariant::GetName}\label{wxvariantgetname} | |
156 | ||
157 | \constfunc{const wxString\&}{GetName}{\void} | |
158 | ||
159 | Returns a constant reference to the variant name. | |
160 | ||
161 | \membersection{wxVariant::GetString}\label{wxvariantgetstring} | |
162 | ||
163 | \constfunc{wxString}{GetString}{\void} | |
164 | ||
165 | Gets the string value. | |
166 | ||
a974387a JS |
167 | \membersection{wxVariant::GetType}\label{wxvariantgettype} |
168 | ||
169 | \constfunc{wxString}{GetType}{\void} | |
170 | ||
171 | Returns the value type as a string. The built-in types are: bool, char, date, double, list, long, string, stringlist, time, void*. | |
172 | ||
173 | If 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 | ||
179 | Gets the void pointer value. | |
180 | ||
cf6ae290 RG |
181 | \membersection{wxVariant::GetWxObjectPtr}\label{wxvariantgetwxobjectptr} |
182 | ||
183 | \constfunc{void*}{GetWxObjectPtr}{\void} | |
184 | ||
185 | Gets the wxObject pointer value. | |
186 | ||
a974387a JS |
187 | \membersection{wxVariant::Insert}\label{wxvariantinsert} |
188 | ||
189 | \func{void}{Insert}{\param{const wxVariant\&}{ value}} | |
190 | ||
191 | Inserts a value at the front of the list. | |
192 | ||
193 | \membersection{wxVariant::IsNull}\label{wxvariantisnull} | |
194 | ||
195 | \constfunc{bool}{IsNull}{\void} | |
196 | ||
cc81d32f | 197 | Returns 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 | 203 | Returns 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 | ||
209 | Returns 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 | ||
215 | Makes the variant null by deleting the internal data. | |
216 | ||
217 | \membersection{wxVariant::MakeString}\label{wxvariantmakestring} | |
218 | ||
219 | \constfunc{wxString}{MakeString}{\void} | |
220 | ||
221 | Makes 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 | 227 | Returns 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 | ||
233 | Makes an empty list. This differs from a null variant which has no data; a null list | |
234 | is 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 | ||
240 | Sets 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 | ||
266 | Assignment 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 | ||
290 | Equality 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 | ||
314 | Inequality test operators. | |
315 | ||
316 | \membersection{wxVariant::operator $[]$}\label{wxvariantarray} | |
317 | ||
318 | \constfunc{wxVariant}{operator $[]$}{\param{size\_t }{idx}} | |
319 | ||
320 | Returns the value at {\it idx} (zero-based). | |
321 | ||
322 | \func{wxVariant\&}{operator $[]$}{\param{size\_t }{idx}} | |
323 | ||
324 | Returns a reference to the value at {\it idx} (zero-based). This can be used | |
325 | to change the value at this index. | |
326 | ||
327 | \membersection{wxVariant::operator char}\label{wxvariantchar} | |
328 | ||
329 | \constfunc{char}{operator char}{\void} | |
330 | ||
331 | Operator 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 | ||
337 | Operator for implicit conversion to a double, using \helpref{wxVariant::GetDouble}{wxvariantgetdouble}. | |
338 | ||
339 | \constfunc{long}{operator long}{\void} | |
340 | ||
341 | Operator 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 | ||
347 | Operator 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 | ||
353 | Operator for implicit conversion to a pointer to a void, using \helpref{wxVariant::GetVoidPtr}{wxvariantgetvoidptr}. | |
354 | ||
355 | \section{\class{wxVariantData}}\label{wxvariantdata} | |
356 | ||
357 | The {\bf wxVariantData} is used to implement a new type for wxVariant. Derive from wxVariantData, | |
358 | and 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 | ||
378 | Default constructor. | |
379 | ||
380 | \membersection{wxVariantData::Copy}\label{wxvariantdatacopy} | |
381 | ||
382 | \func{void}{Copy}{\param{wxVariantData\&}{ data}} | |
383 | ||
384 | Copy 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 | 390 | Returns 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 | ||
396 | Returns the string type of the data. | |
397 | ||
cf6ae290 RG |
398 | \membersection{wxVariantData::GetValueClassInfo}\label{wxvariantdatagetvalueclassinfo} |
399 | ||
400 | \constfunc{wxClassInfo*}{GetValueClassInfo}{\void} | |
401 | ||
402 | If the data is a wxObject returns a pointer to the objects wxClassInfo structure, if | |
403 | the 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 | ||
411 | Reads 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 | ||
419 | Writes 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 | ||
426 | This macro returns the data stored in {\it variant} cast to the type {\it classname *} if | |
427 | the 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}\\ |