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 \func{}{wxVariant}{\param{const wxString\&}{ value}, \param{const wxString\& }{name = ``"}}
  50
  51 Construction from a string value.
  52
  53 \func{}{wxVariant}{\param{char}{ value}, \param{const wxString\& }{name = ``"}}
  54
  55 Construction from a character value.
  56
  57 \func{}{wxVariant}{\param{long}{ value}, \param{const wxString\& }{name = ``"}}
  58
  59 Construction from an integer value. You may need to cast to (long) to
  60 avoid confusion with other constructors (such as the bool constructor).
  61
  62 \func{}{wxVariant}{\param{bool}{ value}, \param{const wxString\& }{name = ``"}}
  63
  64 Construction from a boolean value.
  65
  66 \func{}{wxVariant}{\param{double}{ value}, \param{const wxString\& }{name = ``"}}
  67
  68 Construction from a double-precision floating point value.
  69
  70 \func{}{wxVariant}{\param{const wxList\&}{ value}, \param{const wxString\& }{name = ``"}}
  71
  72 Construction from a list of wxVariant objects. This constructor
  73 copies {\it value}, the application is still responsible for
  74 deleting {\it value} and its contents.
  75
  76 \func{}{wxVariant}{\param{const wxStringList\&}{ value}, \param{const wxString\& }{name = ``"}}
  77
  78 Construction from a list of strings. This constructor
  79 copies {\it value}, the application is still responsible for
  80 deleting {\it value} and its contents.
  81
  82 %Note: this constructor is currently disabled because it causes a C++ ambiguity.
  83
  84 \func{}{wxVariant}{\param{const wxTime\&}{ value}, \param{const wxString\& }{name = ``"}}
  85
  86 Construction from a time.
  87
  88 \func{}{wxVariant}{\param{const wxDate\&}{ value}, \param{const wxString\& }{name = ``"}}
  89
  90 Construction from a date.
  91
  92 \func{}{wxVariant}{\param{void*}{ value}, \param{const wxString\& }{name = ``"}}
  93
  94 Construction from a void pointer.
  95
  96 \func{}{wxVariant}{\param{wxVariantData*}{ data}, \param{const wxString\& }{name = ``"}}
  97
  98 Construction from user-defined data. The variant holds on to the {\it data} pointer.
  99
 100 \membersection{wxVariant::\destruct{wxVariant}}\label{wxvariantdtor}
 101
 102 \func{}{\destruct{wxVariant}}{\void}
 103
 104 Destructor.
 105
 106 \membersection{wxVariant::Append}\label{wxvariantappend}
 107
 108 \func{void}{Append}{\param{const wxVariant\&}{ value}}
 109
 110 Appends a value to the list.
 111
 112 \membersection{wxVariant::ClearList}\label{wxvariantclearlist}
 113
 114 \func{void}{ClearList}{\void}
 115
 116 Deletes the contents of the list.
 117
 118 \membersection{wxVariant::GetCount}\label{wxvariantgetcount}
 119
 120 \constfunc{int}{GetCount}{\void}
 121
 122 Returns the number of elements in the list.
 123
 124 \membersection{wxVariant::Delete}\label{wxvariantdelete}
 125
 126 \func{bool}{Delete}{\param{int }{item}}
 127
 128 Deletes the zero-based {\it item} from the list.
 129
 130 \membersection{wxVariant::GetBool}\label{wxvariantgetbool}
 131
 132 \constfunc{bool}{GetBool}{\void}
 133
 134 Returns the boolean value.
 135
 136 \membersection{wxVariant::GetChar}\label{wxvariantgetchar}
 137
 138 \constfunc{char}{GetChar}{\void}
 139
 140 Returns the character value.
 141
 142 \membersection{wxVariant::GetData}\label{wxvariantgetdata}
 143
 144 \constfunc{wxVariantData*}{GetData}{\void}
 145
 146 Returns a pointer to the internal variant data.
 147
 148 \membersection{wxVariant::GetDate}\label{wxvariantgetdate}
 149
 150 \constfunc{wxDate}{GetDate}{\void}
 151
 152 Gets the date value.
 153
 154 \membersection{wxVariant::GetDouble}\label{wxvariantgetdouble}
 155
 156 \constfunc{double}{GetDouble}{\void}
 157
 158 Returns the floating point value.
 159
 160 \membersection{wxVariant::GetLong}\label{wxvariantgetlong}
 161
 162 \constfunc{long}{GetLong}{\void}
 163
 164 Returns the integer value.
 165
 166 \membersection{wxVariant::GetName}\label{wxvariantgetname}
 167
 168 \constfunc{const wxString\&}{GetName}{\void}
 169
 170 Returns a constant reference to the variant name.
 171
 172 \membersection{wxVariant::GetString}\label{wxvariantgetstring}
 173
 174 \constfunc{wxString}{GetString}{\void}
 175
 176 Gets the string value.
 177
 178 \membersection{wxVariant::GetTime}\label{wxvariantgettime}
 179
 180 \constfunc{wxTime}{GetTime}{\void}
 181
 182 Gets the time value.
 183
 184 \membersection{wxVariant::GetType}\label{wxvariantgettype}
 185
 186 \constfunc{wxString}{GetType}{\void}
 187
 188 Returns the value type as a string. The built-in types are: bool, char, date, double, list, long, string, stringlist, time, void*.
 189
 190 If the variant is null, the value type returned is the string ``null" (not the empty string).
 191
 192 \membersection{wxVariant::GetVoidPtr}\label{wxvariantgetvoidptr}
 193
 194 \constfunc{void*}{GetVoidPtr}{\void}
 195
 196 Gets the void pointer value.
 197
 198 \membersection{wxVariant::Insert}\label{wxvariantinsert}
 199
 200 \func{void}{Insert}{\param{const wxVariant\&}{ value}}
 201
 202 Inserts a value at the front of the list.
 203
 204 \membersection{wxVariant::IsNull}\label{wxvariantisnull}
 205
 206 \constfunc{bool}{IsNull}{\void}
 207
 208 Returns TRUE if there is no data associated with this variant, FALSE if there is data.
 209
 210 \membersection{wxVariant::IsType}\label{wxvariantistype}
 211
 212 \constfunc{bool}{IsType}{\param{const wxString\&}{ type}}
 213
 214 Returns TRUE if {\it type} matches the type of the variant, FALSE otherwise.
 215
 216 \membersection{wxVariant::MakeNull}\label{wxvariantmakenull}
 217
 218 \func{void}{MakeNull}{\void}
 219
 220 Makes the variant null by deleting the internal data.
 221
 222 \membersection{wxVariant::MakeString}\label{wxvariantmakestring}
 223
 224 \constfunc{wxString}{MakeString}{\void}
 225
 226 Makes a string representation of the variant value (for any type).
 227
 228 \membersection{wxVariant::Member}\label{wxvariantmember}
 229
 230 \constfunc{bool}{Member}{\param{const wxVariant\&}{ value}}
 231
 232 Returns TRUE if {\it value} matches an element in the list.
 233
 234 \membersection{wxVariant::NullList}\label{wxvariantnulllist}
 235
 236 \func{void}{NullList}{\void}
 237
 238 Makes an empty list. This differs from a null variant which has no data; a null list
 239 is of type list, but the number of elements in the list is zero.
 240
 241 \membersection{wxVariant::SetData}\label{wxvariantsetdata}
 242
 243 \func{void}{SetData}{\param{wxVariantData*}{ data}}
 244
 245 Sets the internal variant data, deleting the existing data if there is any.
 246
 247 \membersection{wxVariant::operator $=$}\label{wxvariantassignment}
 248
 249 \func{void}{operator $=$}{\param{const wxVariant\& }{value}}
 250
 251 \func{void}{operator $=$}{\param{wxVariantData* }{value}}
 252
 253 \func{void}{operator $=$}{\param{const wxString\& }{value}}
 254
 255 \func{void}{operator $=$}{\param{const char* }{value}}
 256
 257 \func{void}{operator $=$}{\param{char }{value}}
 258
 259 \func{void}{operator $=$}{\param{const long }{value}}
 260
 261 \func{void}{operator $=$}{\param{const bool }{value}}
 262
 263 \func{void}{operator $=$}{\param{const double }{value}}
 264
 265 \func{void}{operator $=$}{\param{const wxDate\& }{value}}
 266
 267 \func{void}{operator $=$}{\param{const wxTime\& }{value}}
 268
 269 \func{void}{operator $=$}{\param{void* }{value}}
 270
 271 \func{void}{operator $=$}{\param{const wxList\& }{value}}
 272
 273 \func{void}{operator $=$}{\param{const wxStringList\& }{value}}
 274
 275 Assignment operators.
 276
 277 \membersection{wxVariant::operator $==$}\label{wxvarianteq}
 278
 279 \func{bool}{operator $==$}{\param{const wxVariant\& }{value}}
 280
 281 \func{bool}{operator $==$}{\param{const wxString\& }{value}}
 282
 283 \func{bool}{operator $==$}{\param{const char* }{value}}
 284
 285 \func{bool}{operator $==$}{\param{char }{value}}
 286
 287 \func{bool}{operator $==$}{\param{const long }{value}}
 288
 289 \func{bool}{operator $==$}{\param{const bool }{value}}
 290
 291 \func{bool}{operator $==$}{\param{const double }{value}}
 292
 293 \func{bool}{operator $==$}{\param{const wxDate\& }{value}}
 294
 295 \func{bool}{operator $==$}{\param{const wxTime\& }{value}}
 296
 297 \func{bool}{operator $==$}{\param{void* }{value}}
 298
 299 \func{bool}{operator $==$}{\param{const wxList\& }{value}}
 300
 301 \func{bool}{operator $==$}{\param{const wxStringList\& }{value}}
 302
 303 Equality test operators.
 304
 305 \membersection{wxVariant::operator $!=$}\label{wxvariantneq}
 306
 307 \func{bool}{operator $!=$}{\param{const wxVariant\& }{value}}
 308
 309 \func{bool}{operator $!=$}{\param{const wxString\& }{value}}
 310
 311 \func{bool}{operator $!=$}{\param{const char* }{value}}
 312
 313 \func{bool}{operator $!=$}{\param{char }{value}}
 314
 315 \func{bool}{operator $!=$}{\param{const long }{value}}
 316
 317 \func{bool}{operator $!=$}{\param{const bool }{value}}
 318
 319 \func{bool}{operator $!=$}{\param{const double }{value}}
 320
 321 \func{bool}{operator $!=$}{\param{const wxDate\& }{value}}
 322
 323 \func{bool}{operator $!=$}{\param{const wxTime\& }{value}}
 324
 325 \func{bool}{operator $!=$}{\param{void* }{value}}
 326
 327 \func{bool}{operator $!=$}{\param{const wxList\& }{value}}
 328
 329 \func{bool}{operator $!=$}{\param{const wxStringList\& }{value}}
 330
 331 Inequality test operators.
 332
 333 \membersection{wxVariant::operator $[]$}\label{wxvariantarray}
 334
 335 \constfunc{wxVariant}{operator $[]$}{\param{size\_t }{idx}}
 336
 337 Returns the value at {\it idx} (zero-based).
 338
 339 \func{wxVariant\&}{operator $[]$}{\param{size\_t }{idx}}
 340
 341 Returns a reference to the value at {\it idx} (zero-based). This can be used
 342 to change the value at this index.
 343
 344 \membersection{wxVariant::operator char}\label{wxvariantchar}
 345
 346 \constfunc{char}{operator char}{\void}
 347
 348 Operator for implicit conversion to a char, using \helpref{wxVariant::GetChar}{wxvariantgetchar}.
 349
 350 \membersection{wxVariant::operator double}\label{wxvariantdouble}
 351
 352 \constfunc{double}{operator double}{\void}
 353
 354 Operator for implicit conversion to a double, using \helpref{wxVariant::GetDouble}{wxvariantgetdouble}.
 355
 356 \constfunc{long}{operator long}{\void}
 357
 358 Operator for implicit conversion to a long, using \helpref{wxVariant::GetLong}{wxvariantgetlong}.
 359
 360 \membersection{wxVariant::operator wxDate}\label{wxvariantwxdate}
 361
 362 \constfunc{wxDate}{operator wxDate}{\void}
 363
 364 Operator for implicit conversion to a wxDate, using \helpref{wxVariant::GetDate}{wxvariantgetdate}.
 365
 366 \membersection{wxVariant::operator wxString}\label{wxvariantwxstring}
 367
 368 \constfunc{wxString}{operator wxString}{\void}
 369
 370 Operator for implicit conversion to a string, using \helpref{wxVariant::MakeString}{wxvariantmakestring}.
 371
 372 \membersection{wxVariant::operator wxTime}\label{wxvariantwxtime}
 373
 374 \constfunc{wxTime}{operator wxTime}{\void}
 375
 376 Operator for implicit conversion to a wxTime, using \helpref{wxVariant::GetTime}{wxvariantgettime}.
 377
 378 \membersection{wxVariant::operator void*}\label{wxvariantvoid}
 379
 380 \constfunc{void*}{operator void*}{\void}
 381
 382 Operator for implicit conversion to a pointer to a void, using \helpref{wxVariant::GetVoidPtr}{wxvariantgetvoidptr}.
 383
 384 \section{\class{wxVariantData}}\label{wxvariantdata}
 385
 386 The {\bf wxVariantData} is used to implement a new type for wxVariant. Derive from wxVariantData,
 387 and override the pure virtual functions.
 388
 389 \wxheading{Derived from}
 390
 391 \helpref{wxObject}{wxobject}
 392
 393 \wxheading{Include files}
 394
 395 <wx/variant.h>
 396
 397 \wxheading{See also}
 398
 399 \helpref{wxVariant}{wxvariant}
 400
 401 \latexignore{\rtfignore{\wxheading{Members}}}
 402
 403 \membersection{wxVariantData::wxVariantData}\label{wxvariantdatactor}
 404
 405 \func{}{wxVariantData}{\void}
 406
 407 Default constructor.
 408
 409 \membersection{wxVariantData::Copy}\label{wxvariantdatacopy}
 410
 411 \func{void}{Copy}{\param{wxVariantData\&}{ data}}
 412
 413 Copy the data from `this' object to {\it data}.
 414
 415 \membersection{wxVariantData::Eq}\label{wxvariantdataeq}
 416
 417 \constfunc{bool}{Eq}{\param{wxVariantData\&}{ data}}
 418
 419 Returns TRUE if this object is equal to {\it data}.
 420
 421 \membersection{wxVariantData::GetType}\label{wxvariantdatagettype}
 422
 423 \constfunc{wxString}{GetType}{\void}
 424
 425 Returns the string type of the data.
 426
 427 \membersection{wxVariantData::Read}\label{wxvariantdataread}
 428
 429 \func{bool}{Read}{\param{ostream\&}{ stream}}
 430
 431 \func{bool}{Read}{\param{wxString\&}{ string}}
 432
 433 Reads the data from {\it stream} or {\it string}.
 434
 435 \membersection{wxVariantData::Write}\label{wxvariantdatawrite}
 436
 437 \constfunc{bool}{Write}{\param{ostream\&}{ stream}}
 438
 439 \constfunc{bool}{Write}{\param{wxString\&}{ string}}
 440
 441 Writes the data to {\it stream} or {\it string}.
 442
 443
 444