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