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