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
   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
  28 \wxheading{Include files}
  29
  30 <wx/variant.h>
  31
  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
  48 \func{}{wxVariant}{\param{const char*}{ value}, \param{const wxString\& }{name = ``"}}
  49
  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
  83 \func{}{wxVariant}{\param{void*}{ value}, \param{const wxString\& }{name = ``"}}
  84
  85 Construction from a void pointer.
  86
  87 \func{}{wxVariant}{\param{wxObject*}{ value}, \param{const wxString\& }{name = ``"}}
  88
  89 Construction from a wxObject pointer.
  90
  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
 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
 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
 181 \membersection{wxVariant::GetWxObjectPtr}\label{wxvariantgetwxobjectptr}
 182
 183 \constfunc{void*}{GetWxObjectPtr}{\void}
 184
 185 Gets the wxObject pointer value.
 186
 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
 197 Returns true if there is no data associated with this variant, false if there is data.
 198
 199 \membersection{wxVariant::IsType}\label{wxvariantistype}
 200
 201 \constfunc{bool}{IsType}{\param{const wxString\&}{ type}}
 202
 203 Returns true if {\it type} matches the type of the variant, false otherwise.
 204
 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
 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
 227 Returns true if {\it value} matches an element in the list.
 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
 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
 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
 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
 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
 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
 364 \wxheading{Include files}
 365
 366 <wx/variant.h>
 367
 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
 390 Returns true if this object is equal to {\it data}.
 391
 392 \membersection{wxVariantData::GetType}\label{wxvariantdatagettype}
 393
 394 \constfunc{wxString}{GetType}{\void}
 395
 396 Returns the string type of the data.
 397
 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
 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
 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}
 432
 433 \helpref{RTTI overview}{runtimeclassoverview}\\
 434 \helpref{wxDynamicCast}{wxdynamiccast}
 435