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