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