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{wxObject*}{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{wxObject* }{value}}
 310
 311 \func{void}{operator $=$}{\param{const wxList\& }{value}}
 312
 313 \func{void}{operator $=$}{\param{const wxDateTime\& }{value}}
 314
 315 \func{void}{operator $=$}{\param{const wxArrayString\& }{value}}
 316
 317 \func{void}{operator $=$}{\param{const DATE\_STRUCT* }{value}}
 318
 319 \func{void}{operator $=$}{\param{const TIME\_STRUCT* }{value}}
 320
 321 \func{void}{operator $=$}{\param{const TIMESTAMP\_STRUCT* }{value}}
 322
 323 Assignment operators.
 324
 325 \membersection{wxVariant::operator $==$}\label{wxvarianteq}
 326
 327 \constfunc{bool}{operator $==$}{\param{const wxVariant\& }{value}}
 328
 329 \constfunc{bool}{operator $==$}{\param{const wxString\& }{value}}
 330
 331 \constfunc{bool}{operator $==$}{\param{const char* }{value}}
 332
 333 \constfunc{bool}{operator $==$}{\param{char }{value}}
 334
 335 \constfunc{bool}{operator $==$}{\param{const long }{value}}
 336
 337 \constfunc{bool}{operator $==$}{\param{const bool }{value}}
 338
 339 \constfunc{bool}{operator $==$}{\param{const double }{value}}
 340
 341 \constfunc{bool}{operator $==$}{\param{void* }{value}}
 342
 343 \constfunc{bool}{operator $==$}{\param{wxObject* }{value}}
 344
 345 \constfunc{bool}{operator $==$}{\param{const wxList\& }{value}}
 346
 347 \constfunc{bool}{operator $==$}{\param{const wxArrayString\& }{value}}
 348
 349 \constfunc{bool}{operator $==$}{\param{const wxDateTime\& }{value}}
 350
 351 Equality test operators.
 352
 353 \membersection{wxVariant::operator $!=$}\label{wxvariantneq}
 354
 355 \constfunc{bool}{operator $!=$}{\param{const wxVariant\& }{value}}
 356
 357 \constfunc{bool}{operator $!=$}{\param{const wxString\& }{value}}
 358
 359 \constfunc{bool}{operator $!=$}{\param{const char* }{value}}
 360
 361 \constfunc{bool}{operator $!=$}{\param{char }{value}}
 362
 363 \constfunc{bool}{operator $!=$}{\param{const long }{value}}
 364
 365 \constfunc{bool}{operator $!=$}{\param{const bool }{value}}
 366
 367 \constfunc{bool}{operator $!=$}{\param{const double }{value}}
 368
 369 \constfunc{bool}{operator $!=$}{\param{void* }{value}}
 370
 371 \constfunc{bool}{operator $!=$}{\param{wxObject* }{value}}
 372
 373 \constfunc{bool}{operator $!=$}{\param{const wxList\& }{value}}
 374
 375 \constfunc{bool}{operator $!=$}{\param{const wxArrayString\& }{value}}
 376
 377 \constfunc{bool}{operator $!=$}{\param{const wxDateTime\& }{value}}
 378
 379 Inequality test operators.
 380
 381 \membersection{wxVariant::operator $[]$}\label{wxvariantarray}
 382
 383 \constfunc{wxVariant}{operator $[]$}{\param{size\_t }{idx}}
 384
 385 Returns the value at {\it idx} (zero-based).
 386
 387 \func{wxVariant\&}{operator $[]$}{\param{size\_t }{idx}}
 388
 389 Returns a reference to the value at {\it idx} (zero-based). This can be used
 390 to change the value at this index.
 391
 392 \membersection{wxVariant::operator char}\label{wxvariantchar}
 393
 394 \constfunc{char}{operator char}{\void}
 395
 396 Operator for implicit conversion to a char, using \helpref{wxVariant::GetChar}{wxvariantgetchar}.
 397
 398 \membersection{wxVariant::operator double}\label{wxvariantdouble}
 399
 400 \constfunc{double}{operator double}{\void}
 401
 402 Operator for implicit conversion to a double, using \helpref{wxVariant::GetDouble}{wxvariantgetdouble}.
 403
 404 \constfunc{long}{operator long}{\void}
 405
 406 Operator for implicit conversion to a long, using \helpref{wxVariant::GetLong}{wxvariantgetlong}.
 407
 408 \membersection{wxVariant::operator wxString}\label{wxvariantwxstring}
 409
 410 \constfunc{wxString}{operator wxString}{\void}
 411
 412 Operator for implicit conversion to a string, using \helpref{wxVariant::MakeString}{wxvariantmakestring}.
 413
 414 \membersection{wxVariant::operator void*}\label{wxvariantvoid}
 415
 416 \constfunc{void*}{operator void*}{\void}
 417
 418 Operator for implicit conversion to a pointer to a void, using \helpref{wxVariant::GetVoidPtr}{wxvariantgetvoidptr}.
 419
 420 \membersection{wxVariant::operator wxDateTime}\label{wxvariantdatetime}
 421
 422 \constfunc{void*}{operator wxDateTime}{\void}
 423
 424 Operator for implicit conversion to a pointer to a \helpref{wxDateTime}{wxdatetime}, using \helpref{wxVariant::GetDateTime}{wxvariantgetdatetime}.
 425
 426 \section{\class{wxVariantData}}\label{wxvariantdata}
 427
 428 The {\bf wxVariantData} is used to implement a new type for wxVariant. Derive from wxVariantData,
 429 and override the pure virtual functions.
 430
 431 \wxheading{Derived from}
 432
 433 \helpref{wxObject}{wxobject}
 434
 435 \wxheading{Include files}
 436
 437 <wx/variant.h>
 438
 439 \wxheading{See also}
 440
 441 \helpref{wxVariant}{wxvariant}
 442
 443 \latexignore{\rtfignore{\wxheading{Members}}}
 444
 445 \membersection{wxVariantData::wxVariantData}\label{wxvariantdatactor}
 446
 447 \func{}{wxVariantData}{\void}
 448
 449 Default constructor.
 450
 451 \membersection{wxVariantData::Copy}\label{wxvariantdatacopy}
 452
 453 \func{void}{Copy}{\param{wxVariantData\&}{ data}}
 454
 455 Copy the data from `this' object to {\it data}.
 456
 457 \membersection{wxVariantData::Eq}\label{wxvariantdataeq}
 458
 459 \constfunc{bool}{Eq}{\param{wxVariantData\&}{ data}}
 460
 461 Returns true if this object is equal to {\it data}.
 462
 463 \membersection{wxVariantData::GetType}\label{wxvariantdatagettype}
 464
 465 \constfunc{wxString}{GetType}{\void}
 466
 467 Returns the string type of the data.
 468
 469 \membersection{wxVariantData::GetValueClassInfo}\label{wxvariantdatagetvalueclassinfo}
 470
 471 \constfunc{wxClassInfo*}{GetValueClassInfo}{\void}
 472
 473 If the data is a wxObject returns a pointer to the objects wxClassInfo structure, if
 474 the data isn't a wxObject the method returns NULL.
 475
 476 \membersection{wxVariantData::Read}\label{wxvariantdataread}
 477
 478 \func{bool}{Read}{\param{ostream\&}{ stream}}
 479
 480 \func{bool}{Read}{\param{wxString\&}{ string}}
 481
 482 Reads the data from {\it stream} or {\it string}.
 483
 484 \membersection{wxVariantData::Write}\label{wxvariantdatawrite}
 485
 486 \constfunc{bool}{Write}{\param{ostream\&}{ stream}}
 487
 488 \constfunc{bool}{Write}{\param{wxString\&}{ string}}
 489
 490 Writes the data to {\it stream} or {\it string}.
 491
 492
 493 \membersection{wxGetVariantCast}\label{wxgetvariantcast}
 494
 495 \func{classname *}{wxGetVariantCast}{wxVariant\&, classname}
 496
 497 This macro returns the data stored in {\it variant} cast to the type {\it classname *} if
 498 the data is of this type (the check is done during the run-time) or
 499 {\tt NULL} otherwise.
 500
 501
 502 \wxheading{See also}
 503
 504 \helpref{RTTI overview}{runtimeclassoverview}\\
 505 \helpref{wxDynamicCast}{wxdynamiccast}