1%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 2%% Name: variant.tex 3%% Purpose: wxVariant docs 4%% Author: wxWidgets Team 5%% Modified by: 6%% Created: 01/30/2005 7%% RCS-ID: $Id: variant.tex 50299 2007-11-28 02:56:19Z VZ $ 8%% Copyright: (c) wxWidgets Team 9%% License: wxWindows license 10%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 11 12\section{\class{wxVariant}}\label{wxvariant} 13 14The {\bf wxVariant} class represents a container for any type. 15A variant's value can be changed at run time, possibly to a different type of value. 16 17As standard, wxVariant can store values of type bool, wxChar, double, long, string, 18string list, time, date, void pointer, list of strings, and list of variants. 19However, an application can extend wxVariant's capabilities by deriving from the 20class \helpref{wxVariantData}{wxvariantdata} and using the wxVariantData form of 21the wxVariant constructor or assignment operator to assign this data to a variant. 22Actual values for user-defined types will need to be accessed via the wxVariantData 23object, unlike the case for basic data types where convenience functions such as 24\helpref{GetLong}{wxvariantgetlong} can be used. 25 26Pointers to any \helpref{wxObject}{wxobject} derived class can also easily be stored 27in a wxVariant. wxVariant will then use wxWidgets' built-in RTTI system to set the 28type name (returned by \helpref{GetType}{wxvariantgettype}) and to perform 29type-safety checks at runtime. 30 31This class is useful for reducing the programming for certain tasks, such as an editor 32for different data types, or a remote procedure call protocol. 33 34An optional name member is associated with a wxVariant. This might be used, for example, 35in CORBA or OLE automation classes, where named parameters are required. 36 37Note that as of wxWidgets 2.7.1, wxVariant is \helpref{reference counted}{trefcount}. 38Additionally, the convenience macros {\bf DECLARE\_VARIANT\_OBJECT} and 39{\bf IMPLEMENT\_VARIANT\_OBJECT} were added so that adding (limited) support 40for conversion to and from wxVariant can be very easily implemented without modifying 41either wxVariant or the class to be stored by wxVariant. Since assignment operators 42cannot be declared outside the class, the shift left operators are used like this: 43 44\begin{verbatim} 45 // in the header file 46 DECLARE_VARIANT_OBJECT(MyClass) 47 48 // in the implementation file 49 IMPLEMENT_VARIANT_OBJECT(MyClass) 50 51 // in the user code 52 wxVariant variant; 53 MyClass value; 54 variant << value; 55 56 // or 57 value << variant; 58\end{verbatim} 59 60For this to work, MyClass must derive from \helpref{wxObject}{wxobject}, implement 61the \helpref{wxWidgets RTTI system}{runtimeclassoverview} 62and support the assignment operator and equality operator for itself. Ideally, it 63should also be reference counted to make copying operations cheap and fast. This 64can be most easily implemented using the reference counting support offered by 65\helpref{wxObject}{wxobject} itself. By default, wxWidgets already implements 66the shift operator conversion for a few of its drawing related classes: 67 68\begin{verbatim} 69IMPLEMENT_VARIANT_OBJECT(wxColour) 70IMPLEMENT_VARIANT_OBJECT(wxImage) 71IMPLEMENT_VARIANT_OBJECT(wxIcon) 72IMPLEMENT_VARIANT_OBJECT(wxBitmap) 73\end{verbatim} 74 75\wxheading{Derived from} 76 77\helpref{wxObject}{wxobject} 78 79\wxheading{Include files} 80 81<wx/variant.h> 82 83\wxheading{See also} 84 85\helpref{wxVariantData}{wxvariantdata} 86 87\latexignore{\rtfignore{\wxheading{Members}}} 88 89\membersection{wxVariant::wxVariant}\label{wxvariantctor} 90 91\func{}{wxVariant}{\void} 92 93Default constructor. 94 95\func{}{wxVariant}{\param{const wxVariant\& }{variant}} 96 97Copy constructor, uses \helpref{reference counting}{trefcount}. 98 99\func{}{wxVariant}{\param{const wxChar*}{ value}, \param{const wxString\& }{name = ``"}} 100 101\func{}{wxVariant}{\param{const wxString\&}{ value}, \param{const wxString\& }{name = ``"}} 102 103Construction from a string value. 104 105\func{}{wxVariant}{\param{wxChar}{ value}, \param{const wxString\& }{name = ``"}} 106 107Construction from a character value. 108 109\func{}{wxVariant}{\param{long}{ value}, \param{const wxString\& }{name = ``"}} 110 111Construction from an integer value. You may need to cast to (long) to 112avoid confusion with other constructors (such as the bool constructor). 113 114\func{}{wxVariant}{\param{bool}{ value}, \param{const wxString\& }{name = ``"}} 115 116Construction from a boolean value. 117 118\func{}{wxVariant}{\param{double}{ value}, \param{const wxString\& }{name = ``"}} 119 120Construction from a double-precision floating point value. 121 122\func{}{wxVariant}{\param{const wxList\&}{ value}, \param{const wxString\& }{name = ``"}} 123 124Construction from a list of wxVariant objects. This constructor 125copies {\it value}, the application is still responsible for 126deleting {\it value} and its contents. 127 128\func{}{wxVariant}{\param{void*}{ value}, \param{const wxString\& }{name = ``"}} 129 130Construction from a void pointer. 131 132\func{}{wxVariant}{\param{wxObject*}{ value}, \param{const wxString\& }{name = ``"}} 133 134Construction from a wxObject pointer. 135 136\func{}{wxVariant}{\param{wxVariantData*}{ data}, \param{const wxString\& }{name = ``"}} 137 138Construction from user-defined data. The variant holds onto the {\it data} pointer. 139 140\func{}{wxVariant}{\param{wxDateTime\&}{ val}, \param{const wxString\& }{name = ``"}} 141 142Construction from a \helpref{wxDateTime}{wxdatetime}. 143 144\func{}{wxVariant}{\param{wxArrayString\&}{ val}, \param{const wxString\& }{name = ``"}} 145 146Construction from an array of strings. This constructor copies {\it value} and its contents. 147 148\func{}{wxVariant}{\param{DATE\_STRUCT*}{ val}, \param{const wxString\& }{name = ``"}} 149 150Construction from a odbc date value. Represented internally by a \helpref{wxDateTime}{wxdatetime} value. 151 152\func{}{wxVariant}{\param{TIME\_STRUCT*}{ val}, \param{const wxString\& }{name = ``"}} 153 154Construction from a odbc time value. Represented internally by a \helpref{wxDateTime}{wxdatetime} value. 155 156\func{}{wxVariant}{\param{TIMESTAMP\_STRUCT*}{ val}, \param{const wxString\& }{name = ``"}} 157 158Construction from a odbc timestamp value. Represented internally by a \helpref{wxDateTime}{wxdatetime} value. 159 160\membersection{wxVariant::\destruct{wxVariant}}\label{wxvariantdtor} 161 162\func{}{\destruct{wxVariant}}{\void} 163 164Destructor. 165 166Note that destructor is protected, so wxVariantData cannot usually 167be deleted. Instead, \helpref{DecRef}{wxvariantdatadecref} should be called. 168See \helpref{reference-counted object destruction}{refcountdestruct} for more info. 169 170 171\membersection{wxVariant::Append}\label{wxvariantappend} 172 173\func{void}{Append}{\param{const wxVariant\&}{ value}} 174 175Appends a value to the list. 176 177\membersection{wxVariant::Clear}\label{wxvariantclear} 178 179\func{void}{Clear}{\void} 180 181Makes the variant null by deleting the internal data and 182set the name to {\it wxEmptyString}. 183 184\membersection{wxVariant::ClearList}\label{wxvariantclearlist} 185 186\func{void}{ClearList}{\void} 187 188Deletes the contents of the list. 189 190 191\membersection{wxVariant::Convert}\label{wxvariantconvert} 192 193\constfunc{bool}{Convert}{\param{long*}{ value}} 194 195\constfunc{bool}{Convert}{\param{bool*}{ value}} 196 197\constfunc{bool}{Convert}{\param{double*}{ value}} 198 199\constfunc{bool}{Convert}{\param{wxString*}{ value}} 200 201\constfunc{bool}{Convert}{\param{wxChar*}{ value}} 202 203\constfunc{bool}{Convert}{\param{wxDateTime*}{ value}} 204 205Retrieves and converts the value of this variant to the type that {\it value} is. 206 207 208\membersection{wxVariant::GetCount}\label{wxvariantgetcount} 209 210\constfunc{size\_t}{GetCount}{\void} 211 212Returns the number of elements in the list. 213 214\membersection{wxVariant::Delete}\label{wxvariantdelete} 215 216\func{bool}{Delete}{\param{size\_t }{item}} 217 218Deletes the zero-based {\it item} from the list. 219 220\membersection{wxVariant::GetArrayString}\label{wxvariantgetarraystring} 221 222\constfunc{wxArrayString}{GetArrayString}{\void} 223 224Returns the string array value. 225 226\membersection{wxVariant::GetBool}\label{wxvariantgetbool} 227 228\constfunc{bool}{GetBool}{\void} 229 230Returns the boolean value. 231 232\membersection{wxVariant::GetChar}\label{wxvariantgetchar} 233 234\constfunc{wxChar}{GetChar}{\void} 235 236Returns the character value. 237 238\membersection{wxVariant::GetData}\label{wxvariantgetdata} 239 240\constfunc{wxVariantData*}{GetData}{\void} 241 242Returns a pointer to the internal variant data. To take ownership 243of this data, you must call its \helpref{IncRef}{wxvariantdataincref} 244method. When you stop using it, \helpref{DecRef}{wxvariantdatadecref} 245must be likewise called. 246 247\membersection{wxVariant::GetDateTime}\label{wxvariantgetdatetime} 248 249\constfunc{wxDateTime}{GetDateTime}{\void} 250 251Returns the date value. 252 253\membersection{wxVariant::GetDouble}\label{wxvariantgetdouble} 254 255\constfunc{double}{GetDouble}{\void} 256 257Returns the floating point value. 258 259\membersection{wxVariant::GetLong}\label{wxvariantgetlong} 260 261\constfunc{long}{GetLong}{\void} 262 263Returns the integer value. 264 265\membersection{wxVariant::GetName}\label{wxvariantgetname} 266 267\constfunc{const wxString\&}{GetName}{\void} 268 269Returns a constant reference to the variant name. 270 271\membersection{wxVariant::GetString}\label{wxvariantgetstring} 272 273\constfunc{wxString}{GetString}{\void} 274 275Gets the string value. 276 277\membersection{wxVariant::GetType}\label{wxvariantgettype} 278 279\constfunc{wxString}{GetType}{\void} 280 281Returns the value type as a string. The built-in types are: bool, char, date, double, list, long, string, stringlist, time, void*. 282 283If the variant is null, the value type returned is the string ``null" (not the empty string). 284 285\membersection{wxVariant::GetVoidPtr}\label{wxvariantgetvoidptr} 286 287\constfunc{void*}{GetVoidPtr}{\void} 288 289Gets the void pointer value. 290 291\membersection{wxVariant::GetWxObjectPtr}\label{wxvariantgetwxobjectptr} 292 293\constfunc{wxObject*}{GetWxObjectPtr}{\void} 294 295Gets the wxObject pointer value. 296 297\membersection{wxVariant::Insert}\label{wxvariantinsert} 298 299\func{void}{Insert}{\param{const wxVariant\&}{ value}} 300 301Inserts a value at the front of the list. 302 303\membersection{wxVariant::IsNull}\label{wxvariantisnull} 304 305\constfunc{bool}{IsNull}{\void} 306 307Returns true if there is no data associated with this variant, false if there is data. 308 309\membersection{wxVariant::IsType}\label{wxvariantistype} 310 311\constfunc{bool}{IsType}{\param{const wxString\&}{ type}} 312 313Returns true if {\it type} matches the type of the variant, false otherwise. 314 315\membersection{wxVariant::IsValueKindOf}\label{wxvariantisvaluekindof} 316 317\constfunc{bool}{IsValueKindOf}{\param{const wxClassInfo* type}{ type}} 318 319Returns true if the data is derived from the class described by {\it type}, false otherwise. 320 321\membersection{wxVariant::MakeNull}\label{wxvariantmakenull} 322 323\func{void}{MakeNull}{\void} 324 325Makes the variant null by deleting the internal data. 326 327\membersection{wxVariant::MakeString}\label{wxvariantmakestring} 328 329\constfunc{wxString}{MakeString}{\void} 330 331Makes a string representation of the variant value (for any type). 332 333\membersection{wxVariant::Member}\label{wxvariantmember} 334 335\constfunc{bool}{Member}{\param{const wxVariant\&}{ value}} 336 337Returns true if {\it value} matches an element in the list. 338 339\membersection{wxVariant::NullList}\label{wxvariantnulllist} 340 341\func{void}{NullList}{\void} 342 343Makes an empty list. This differs from a null variant which has no data; a null list 344is of type list, but the number of elements in the list is zero. 345 346\membersection{wxVariant::SetData}\label{wxvariantsetdata} 347 348\func{void}{SetData}{\param{wxVariantData*}{ data}} 349 350Sets the internal variant data, deleting the existing data if there is any. 351 352\membersection{wxVariant::operator $=$}\label{wxvariantassignment} 353 354\func{void}{operator $=$}{\param{const wxVariant\& }{value}} 355 356\func{void}{operator $=$}{\param{wxVariantData* }{value}} 357 358\func{void}{operator $=$}{\param{const wxString\& }{value}} 359 360\func{void}{operator $=$}{\param{const wxChar* }{value}} 361 362\func{void}{operator $=$}{\param{wxChar }{value}} 363 364\func{void}{operator $=$}{\param{const long }{value}} 365 366\func{void}{operator $=$}{\param{const bool }{value}} 367 368\func{void}{operator $=$}{\param{const double }{value}} 369 370\func{void}{operator $=$}{\param{void* }{value}} 371 372\func{void}{operator $=$}{\param{wxObject* }{value}} 373 374\func{void}{operator $=$}{\param{const wxList\& }{value}} 375 376\func{void}{operator $=$}{\param{const wxDateTime\& }{value}} 377 378\func{void}{operator $=$}{\param{const wxArrayString\& }{value}} 379 380\func{void}{operator $=$}{\param{const DATE\_STRUCT* }{value}} 381 382\func{void}{operator $=$}{\param{const TIME\_STRUCT* }{value}} 383 384\func{void}{operator $=$}{\param{const TIMESTAMP\_STRUCT* }{value}} 385 386Assignment operators, using \helpref{reference counting}{trefcount} when possible. 387 388\membersection{wxVariant::operator $==$}\label{wxvarianteq} 389 390\constfunc{bool}{operator $==$}{\param{const wxVariant\& }{value}} 391 392\constfunc{bool}{operator $==$}{\param{const wxString\& }{value}} 393 394\constfunc{bool}{operator $==$}{\param{const wxChar* }{value}} 395 396\constfunc{bool}{operator $==$}{\param{wxChar }{value}} 397 398\constfunc{bool}{operator $==$}{\param{const long }{value}} 399 400\constfunc{bool}{operator $==$}{\param{const bool }{value}} 401 402\constfunc{bool}{operator $==$}{\param{const double }{value}} 403 404\constfunc{bool}{operator $==$}{\param{void* }{value}} 405 406\constfunc{bool}{operator $==$}{\param{wxObject* }{value}} 407 408\constfunc{bool}{operator $==$}{\param{const wxList\& }{value}} 409 410\constfunc{bool}{operator $==$}{\param{const wxArrayString\& }{value}} 411 412\constfunc{bool}{operator $==$}{\param{const wxDateTime\& }{value}} 413 414Equality test operators. 415 416\membersection{wxVariant::operator $!=$}\label{wxvariantneq} 417 418\constfunc{bool}{operator $!=$}{\param{const wxVariant\& }{value}} 419 420\constfunc{bool}{operator $!=$}{\param{const wxString\& }{value}} 421 422\constfunc{bool}{operator $!=$}{\param{const wxChar* }{value}} 423 424\constfunc{bool}{operator $!=$}{\param{wxChar }{value}} 425 426\constfunc{bool}{operator $!=$}{\param{const long }{value}} 427 428\constfunc{bool}{operator $!=$}{\param{const bool }{value}} 429 430\constfunc{bool}{operator $!=$}{\param{const double }{value}} 431 432\constfunc{bool}{operator $!=$}{\param{void* }{value}} 433 434\constfunc{bool}{operator $!=$}{\param{wxObject* }{value}} 435 436\constfunc{bool}{operator $!=$}{\param{const wxList\& }{value}} 437 438\constfunc{bool}{operator $!=$}{\param{const wxArrayString\& }{value}} 439 440\constfunc{bool}{operator $!=$}{\param{const wxDateTime\& }{value}} 441 442Inequality test operators. 443 444\membersection{wxVariant::operator $[]$}\label{wxvariantarray} 445 446\constfunc{wxVariant}{operator $[]$}{\param{size\_t }{idx}} 447 448Returns the value at {\it idx} (zero-based). 449 450\func{wxVariant\&}{operator $[]$}{\param{size\_t }{idx}} 451 452Returns a reference to the value at {\it idx} (zero-based). This can be used 453to change the value at this index. 454 455\membersection{wxVariant::operator wxChar}\label{wxvariantchar} 456 457\constfunc{char}{operator wxChar}{\void} 458 459Operator for implicit conversion to a wxChar, using \helpref{wxVariant::GetChar}{wxvariantgetchar}. 460 461\membersection{wxVariant::operator double}\label{wxvariantdouble} 462 463\constfunc{double}{operator double}{\void} 464 465Operator for implicit conversion to a double, using \helpref{wxVariant::GetDouble}{wxvariantgetdouble}. 466 467\constfunc{long}{operator long}{\void} 468 469Operator for implicit conversion to a long, using \helpref{wxVariant::GetLong}{wxvariantgetlong}. 470 471\membersection{wxVariant::operator wxString}\label{wxvariantwxstring} 472 473\constfunc{wxString}{operator wxString}{\void} 474 475Operator for implicit conversion to a string, using \helpref{wxVariant::MakeString}{wxvariantmakestring}. 476 477\membersection{wxVariant::operator void*}\label{wxvariantvoid} 478 479\constfunc{void*}{operator void*}{\void} 480 481Operator for implicit conversion to a pointer to a void, using \helpref{wxVariant::GetVoidPtr}{wxvariantgetvoidptr}. 482 483\membersection{wxVariant::operator wxDateTime}\label{wxvariantdatetime} 484 485\constfunc{void*}{operator wxDateTime}{\void} 486 487Operator for implicit conversion to a pointer to a \helpref{wxDateTime}{wxdatetime}, using \helpref{wxVariant::GetDateTime}{wxvariantgetdatetime}. 488 489 490 491%% wxVariantData 492 493 494\section{\class{wxVariantData}}\label{wxvariantdata} 495 496The {\bf wxVariantData} class is used to implement a new type for \helpref{wxVariant}{wxvariant}. 497Derive from wxVariantData, and override the pure virtual functions. 498 499wxVariantData is \helpref{reference counted}{refcount}, but you don't normally have to care about this, 500as wxVariant manages the count automatically. However, in case your application needs to take 501ownership of wxVariantData, be aware that the object is created with reference count of 1, 502and passing it to wxVariant will not increase this. In other words, \helpref{IncRef}{wxvariantdataincref} 503needs to be called only if you both take ownership of wxVariantData and pass it to a wxVariant. 504Also note that the destructor is protected, so you can never explicitly delete a wxVariantData 505instance. Instead, \helpref{DecRef}{wxvariantdatadecref} will delete the object automatically 506when the reference count reaches zero. 507 508\wxheading{Derived from} 509 510\helpref{wxObject}{wxobject} 511 512\wxheading{Include files} 513 514<wx/variant.h> 515 516\wxheading{See also} 517 518\helpref{wxVariant}{wxvariant} 519 520\latexignore{\rtfignore{\wxheading{Members}}} 521 522\membersection{wxVariantData::wxVariantData}\label{wxvariantdatactor} 523 524\func{}{wxVariantData}{\void} 525 526Default constructor. 527 528\membersection{wxVariantData::DecRef}\label{wxvariantdatadecref} 529 530\func{void}{DecRef}{\void} 531 532Decreases reference count. If the count reaches zero, the object is 533automatically deleted. 534 535Note that destructor of wxVariantData is protected, so delete 536cannot be used as normal. Instead, \helpref{DecRef}{wxvariantdatadecref} should be called. 537 538 539 540\membersection{wxVariantData::Eq}\label{wxvariantdataeq} 541 542\constfunc{bool}{Eq}{\param{wxVariantData\&}{ data}} 543 544Returns true if this object is equal to {\it data}. 545 546\membersection{wxVariantData::GetType}\label{wxvariantdatagettype} 547 548\constfunc{wxString}{GetType}{\void} 549 550Returns the string type of the data. 551 552\membersection{wxVariantData::GetValueClassInfo}\label{wxvariantdatagetvalueclassinfo} 553 554\constfunc{wxClassInfo*}{GetValueClassInfo}{\void} 555 556If the data is a wxObject returns a pointer to the objects wxClassInfo structure, if 557the data isn't a wxObject the method returns NULL. 558 559\membersection{wxVariantData::IncRef}\label{wxvariantdataincref} 560 561\func{void}{IncRef}{\void} 562 563Increases reference count. Note that initially wxVariantData has reference count of 1. 564 565\membersection{wxVariantData::Read}\label{wxvariantdataread} 566 567\func{bool}{Read}{\param{ostream\&}{ stream}} 568 569\func{bool}{Read}{\param{wxString\&}{ string}} 570 571Reads the data from {\it stream} or {\it string}. 572 573\membersection{wxVariantData::Write}\label{wxvariantdatawrite} 574 575\constfunc{bool}{Write}{\param{ostream\&}{ stream}} 576 577\constfunc{bool}{Write}{\param{wxString\&}{ string}} 578 579Writes the data to {\it stream} or {\it string}. 580 581 582\membersection{wxGetVariantCast}\label{wxgetvariantcast} 583 584\func{classname *}{wxGetVariantCast}{wxVariant\&, classname} 585 586This macro returns the data stored in {\it variant} cast to the type {\it classname *} if 587the data is of this type (the check is done during the run-time) or 588{\tt NULL} otherwise. 589 590 591\wxheading{See also} 592 593\helpref{RTTI overview}{runtimeclassoverview}\\ 594\helpref{wxDynamicCast}{wxdynamiccast} 595 596