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