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