1 ///////////////////////////////////////////////////////////////////////////// 2 // Name: variant.h 3 // Purpose: interface of wxVariant 4 // Author: wxWidgets team 5 // Licence: wxWindows licence 6 ///////////////////////////////////////////////////////////////////////////// 7 8 /** 9 @class wxVariant 10 11 The wxVariant class represents a container for any type. A variant's value 12 can be changed at run time, possibly to a different type of value. 13 14 @note As of wxWidgets 2.9.1, wxAny has become the preferred variant class. 15 While most controls still use wxVariant in their interface, you 16 can start using wxAny in your code because of an implicit conversion 17 layer. See below for more information. 18 19 As standard, wxVariant can store values of type bool, wxChar, double, long, 20 string, string list, time, date, void pointer, list of strings, and list of 21 variants. However, an application can extend wxVariant's capabilities by 22 deriving from the class wxVariantData and using the wxVariantData form of 23 the wxVariant constructor or assignment operator to assign this data to a 24 variant. Actual values for user-defined types will need to be accessed via 25 the wxVariantData object, unlike the case for basic data types where 26 convenience functions such as GetLong() can be used. 27 28 Under Microsoft Windows, three additional wxVariantData-derived classes -- 29 wxVariantDataCurrency, wxVariantDataErrorCode and wxVariantDataSafeArray -- 30 are available for interoperation with OLE VARIANT when using wxAutomationObject. 31 32 Pointers to any wxObject derived class can also easily be stored in a 33 wxVariant. wxVariant will then use wxWidgets' built-in RTTI system to set 34 the type name (returned by GetType()) and to perform type-safety checks at 35 runtime. 36 37 This class is useful for reducing the programming for certain tasks, such 38 as an editor for different data types, or a remote procedure call protocol. 39 40 An optional name member is associated with a wxVariant. This might be used, 41 for example, in CORBA or OLE automation classes, where named parameters are 42 required. 43 44 Note that as of wxWidgets 2.7.1, wxVariant is 45 @ref overview_refcount "reference counted". Additionally, the convenience 46 macros DECLARE_VARIANT_OBJECT() and IMPLEMENT_VARIANT_OBJECT() were added 47 so that adding (limited) support for conversion to and from wxVariant can 48 be very easily implemented without modifying either wxVariant or the class 49 to be stored by wxVariant. Since assignment operators cannot be declared 50 outside the class, the shift left operators are used like this: 51 52 @code 53 // in the header file 54 DECLARE_VARIANT_OBJECT(MyClass) 55 56 // in the implementation file 57 IMPLEMENT_VARIANT_OBJECT(MyClass) 58 59 // in the user code 60 wxVariant variant; 61 MyClass value; 62 variant << value; 63 64 // or 65 value << variant; 66 @endcode 67 68 For this to work, MyClass must derive from wxObject, implement the 69 @ref overview_rtti "wxWidgets RTTI system" and support the assignment 70 operator and equality operator for itself. Ideally, it should also be 71 reference counted to make copying operations cheap and fast. This can be 72 most easily implemented using the reference counting support offered by 73 wxObject itself. By default, wxWidgets already implements the shift 74 operator conversion for a few of its drawing related classes: 75 76 @code 77 IMPLEMENT_VARIANT_OBJECT(wxColour) 78 IMPLEMENT_VARIANT_OBJECT(wxImage) 79 IMPLEMENT_VARIANT_OBJECT(wxIcon) 80 IMPLEMENT_VARIANT_OBJECT(wxBitmap) 81 @endcode 82 83 Note that as of wxWidgets 2.9.0, wxVariantData no longer inherits from 84 wxObject and wxVariant no longer uses the type-unsafe wxList class for list 85 operations but the type-safe wxVariantList class. Also, wxVariantData now 86 supports the wxVariantData::Clone() function for implementing the Unshare() 87 function. wxVariantData::Clone() is implemented automatically by 88 IMPLEMENT_VARIANT_OBJECT(). 89 90 Since wxVariantData no longer derives from wxObject, any code that tests 91 the type of the data using wxDynamicCast() will require adjustment. You can 92 use the macro wxDynamicCastVariantData() with the same arguments as 93 wxDynamicCast(), to use C++ RTTI type information instead of wxWidgets 94 RTTI. 95 96 @section variant_wxanyconversion wxVariant to wxAny Conversion Layer 97 98 wxAny is a more modern, template-based variant class. It is not 99 directly compatible with wxVariant, but there is a transparent conversion 100 layer. 101 102 Following is an example how to use these conversions with wxPropertyGrid's 103 property class wxPGProperty (which currently uses wxVariants both 104 internally and in the public API): 105 106 @code 107 // Get property value as wxAny instead of wxVariant 108 wxAny value = property->GetValue(); 109 110 // Do something with it 111 DoSomethingWithString(value.As<wxString>()); 112 113 // Write back new value to property 114 value = "New Value"; 115 property->SetValue(value); 116 117 @endcode 118 119 Some caveats: 120 @li In wxAny, there are no separate types for handling integers of 121 different sizes, so converting wxAny with 'long long' value 122 will yield wxVariant of "long" type when the value is small 123 enough to fit in without overflow. Otherwise, variant type 124 "longlong" is used. Also note that wxAny holding unsigned integer 125 will always be converted to "ulonglong" wxVariant type. 126 127 @li Unlike wxVariant, wxAny does not store a (rarely needed) name string. 128 129 @li Because of implicit conversion of wxVariant to wxAny, wxAny cannot 130 usually contain value of type wxVariant. In other words, 131 any.CheckType<wxVariant>() can never return @true. 132 133 Supplied conversion functions will automatically work with all 134 built-in wxVariant types, and also with all user-specified types generated 135 using IMPLEMENT_VARIANT_OBJECT(). For hand-built wxVariantData classes, 136 you will need to use supplied macros in a following manner: 137 138 @code 139 140 // Declare wxVariantData for data type Foo 141 class wxVariantDataFoo: public wxVariantData 142 { 143 public: 144 // interface 145 // ... 146 147 DECLARE_WXANY_CONVERSION() 148 protected: 149 // data storage etc 150 // ... 151 }; 152 153 IMPLEMENT_TRIVIAL_WXANY_CONVERSION(Foo, wxVariantDataFoo) 154 155 @endcode 156 157 @library{wxbase} 158 @category{data} 159 160 @see wxVariantData, wxAny 161 */ 162 class wxVariant : public wxObject 163 { 164 public: 165 /** 166 Default constructor. 167 */ 168 wxVariant(); 169 170 /** 171 Constructs a variant directly with a wxVariantData object. wxVariant 172 will take ownership of the wxVariantData and will not increase its 173 reference count. 174 */ 175 wxVariant(wxVariantData* data, const wxString& name = wxEmptyString); 176 177 /** 178 Constructs a variant from another variant by increasing the reference 179 count. 180 */ 181 wxVariant(const wxVariant& variant); 182 183 /** 184 Constructs a variant by converting it from wxAny. 185 */ 186 wxVariant(const wxAny& any); 187 188 /** 189 Constructs a variant from a wide string literal. 190 */ 191 wxVariant(const wxChar* value, const wxString& name = wxEmptyString); 192 193 /** 194 Constructs a variant from a string. 195 */ 196 wxVariant(const wxString& value, const wxString& name = wxEmptyString); 197 198 /** 199 Constructs a variant from a wide char. 200 */ 201 wxVariant(wxChar value, const wxString& name = wxEmptyString); 202 203 /** 204 Constructs a variant from a long. 205 */ 206 wxVariant(long value, const wxString& name = wxEmptyString); 207 208 /** 209 Constructs a variant from a bool. 210 */ 211 wxVariant(bool value, const wxString& name = wxEmptyString); 212 213 /** 214 Constructs a variant from a double. 215 */ 216 wxVariant(double value, const wxString& name = wxEmptyString); 217 218 /** 219 Constructs a variant from a wxLongLong. 220 */ 221 wxVariant(wxLongLong value, const wxString& name = wxEmptyString); 222 223 /** 224 Constructs a variant from a wxULongLong. 225 */ 226 wxVariant(wxULongLong value, const wxString& name = wxEmptyString); 227 228 /** 229 Constructs a variant from a list of variants 230 */ 231 wxVariant(const wxVariantList& value, const wxString& name = wxEmptyString); 232 233 /** 234 Constructs a variant from a void pointer. 235 */ 236 wxVariant(void* value, const wxString& name = wxEmptyString); 237 238 /** 239 Constructs a variant from a pointer to an wxObject 240 derived class. 241 */ 242 wxVariant(wxObject* value, const wxString& name = wxEmptyString); 243 244 /** 245 Constructs a variant from a wxDateTime. 246 */ 247 wxVariant(const wxDateTime& val, const wxString& name = wxEmptyString); 248 249 /** 250 Constructs a variant from a wxArrayString. 251 */ 252 wxVariant(const wxArrayString& val, const wxString& name = wxEmptyString); 253 254 /** 255 Destructor. 256 257 @note wxVariantData's destructor is protected, so wxVariantData cannot 258 usually be deleted. Instead, wxVariantData::DecRef() should be 259 called. See @ref overview_refcount_destruct 260 "reference-counted object destruction" for more info. 261 */ 262 virtual ~wxVariant(); 263 264 265 /** 266 @name List Functionality 267 */ 268 //@{ 269 270 /** 271 Returns the value at @a idx (zero-based). 272 */ 273 wxVariant operator [](size_t idx) const; 274 /** 275 Returns a reference to the value at @a idx (zero-based). This can be 276 used to change the value at this index. 277 */ 278 wxVariant& operator [](size_t idx); 279 280 /** 281 Appends a value to the list. 282 */ 283 void Append(const wxVariant& value); 284 285 /** 286 Makes the variant null by deleting the internal data and set the name 287 to wxEmptyString. 288 */ 289 void Clear(); 290 291 /** 292 Deletes the contents of the list. 293 */ 294 void ClearList(); 295 296 /** 297 Deletes the zero-based @a item from the list. 298 */ 299 bool Delete(size_t item); 300 301 /** 302 Returns the number of elements in the list. 303 */ 304 size_t GetCount() const; 305 306 /** 307 Returns a reference to the wxVariantList class used by wxVariant if 308 this wxVariant is currently a list of variants. 309 */ 310 wxVariantList& GetList() const; 311 312 /** 313 Inserts a value at the front of the list. 314 */ 315 void Insert(const wxVariant& value); 316 317 /** 318 Makes an empty list. This differs from a null variant which has no 319 data; a null list is of type list, but the number of elements in the 320 list is zero. 321 */ 322 void NullList(); 323 324 //@} 325 326 327 //@{ 328 /** 329 Retrieves and converts the value of this variant to the type that 330 @a value is. 331 */ 332 bool Convert(long* value) const; 333 bool Convert(bool* value) const; 334 bool Convert(double* value) const; 335 bool Convert(wxString* value) const; 336 bool Convert(wxChar* value) const; 337 bool Convert(wxLongLong* value) const; 338 bool Convert(wxULongLong* value) const; 339 bool Convert(wxDateTime* value) const; 340 //@} 341 342 /** 343 Converts wxVariant into wxAny. 344 */ 345 wxAny GetAny() const; 346 347 /** 348 Returns the string array value. 349 */ 350 wxArrayString GetArrayString() const; 351 352 /** 353 Returns the boolean value. 354 */ 355 bool GetBool() const; 356 357 /** 358 Returns the character value. 359 */ 360 wxUniChar GetChar() const; 361 362 /** 363 Returns a pointer to the internal variant data. To take ownership of 364 this data, you must call its wxVariantData::IncRef() method. When you 365 stop using it, wxVariantData::DecRef() must be called as well. 366 */ 367 wxVariantData* GetData() const; 368 369 /** 370 Returns the date value. 371 */ 372 wxDateTime GetDateTime() const; 373 374 /** 375 Returns the floating point value. 376 */ 377 double GetDouble() const; 378 379 /** 380 Returns the integer value. 381 */ 382 long GetLong() const; 383 384 /** 385 Returns the signed 64-bit integer value. 386 */ 387 wxLongLong GetLongLong() const; 388 389 /** 390 Returns a constant reference to the variant name. 391 */ 392 const wxString& GetName() const; 393 394 /** 395 Gets the string value. 396 */ 397 wxString GetString() const; 398 399 /** 400 Returns the value type as a string. 401 402 The built-in types are: 403 - "bool" 404 - "char" 405 - "datetime" 406 - "double" 407 - "list" 408 - "long" 409 - "longlong" 410 - "string" 411 - "ulonglong" 412 - "arrstring" 413 - "void*" 414 415 If the variant is null, the value type returned is the string "null" 416 (not the empty string). 417 */ 418 wxString GetType() const; 419 420 /** 421 Returns the unsigned 64-bit integer value. 422 */ 423 wxULongLong GetULongLong() const; 424 425 /** 426 Gets the void pointer value. 427 428 Notice that this method can be used for null objects (i.e. those for 429 which IsNull() returns @true) and will return @NULL for them. 430 */ 431 void* GetVoidPtr() const; 432 433 /** 434 Gets the wxObject pointer value. 435 */ 436 wxObject* GetWxObjectPtr() const; 437 438 /** 439 Returns @true if there is no data associated with this variant, @false 440 if there is data. 441 */ 442 bool IsNull() const; 443 444 /** 445 Returns @true if @a type matches the type of the variant, @false 446 otherwise. 447 */ 448 bool IsType(const wxString& type) const; 449 450 /** 451 Returns @true if the data is derived from the class described by 452 @a type, @false otherwise. 453 */ 454 bool IsValueKindOf(const wxClassInfo* type) const; 455 456 /** 457 Makes the variant null by deleting the internal data. 458 */ 459 void MakeNull(); 460 461 /** 462 Makes a string representation of the variant value (for any type). 463 */ 464 wxString MakeString() const; 465 466 /** 467 Returns @true if @a value matches an element in the list. 468 */ 469 bool Member(const wxVariant& value) const; 470 471 /** 472 Sets the internal variant data, deleting the existing data if there is 473 any. 474 */ 475 void SetData(wxVariantData* data); 476 477 /** 478 Makes sure that any data associated with this variant is not shared 479 with other variants. For this to work, wxVariantData::Clone() must be 480 implemented for the data types you are working with. 481 wxVariantData::Clone() is implemented for all the default data types. 482 */ 483 bool Unshare(); 484 485 //@{ 486 /** 487 Inequality test operator. 488 */ 489 bool operator !=(const wxVariant& value) const; 490 bool operator !=(const wxString& value) const; 491 bool operator !=(const wxChar* value) const; 492 bool operator !=(wxChar value) const; 493 bool operator !=(long value) const; 494 bool operator !=(bool value) const; 495 bool operator !=(double value) const; 496 bool operator !=(wxLongLong value) const; 497 bool operator !=(wxULongLong value) const; 498 bool operator !=(void* value) const; 499 bool operator !=(wxObject* value) const; 500 bool operator !=(const wxVariantList& value) const; 501 bool operator !=(const wxArrayString& value) const; 502 bool operator !=(const wxDateTime& value) const; 503 //@} 504 505 //@{ 506 /** 507 Assignment operator, using @ref overview_refcount "reference counting" 508 if possible. 509 */ 510 void operator =(const wxVariant& value); 511 void operator =(wxVariantData* value); 512 void operator =(const wxString& value); 513 void operator =(const wxChar* value); 514 void operator =(wxChar value); 515 void operator =(long value); 516 void operator =(bool value); 517 void operator =(double value); 518 bool operator =(wxLongLong value) const; 519 bool operator =(wxULongLong value) const; 520 void operator =(void* value); 521 void operator =(wxObject* value); 522 void operator =(const wxVariantList& value); 523 void operator =(const wxDateTime& value); 524 void operator =(const wxArrayString& value); 525 //@} 526 527 //@{ 528 /** 529 Equality test operator. 530 */ 531 bool operator ==(const wxVariant& value) const; 532 bool operator ==(const wxString& value) const; 533 bool operator ==(const wxChar* value) const; 534 bool operator ==(wxChar value) const; 535 bool operator ==(long value) const; 536 bool operator ==(bool value) const; 537 bool operator ==(double value) const; 538 bool operator ==(wxLongLong value) const; 539 bool operator ==(wxULongLong value) const; 540 bool operator ==(void* value) const; 541 bool operator ==(wxObject* value) const; 542 bool operator ==(const wxVariantList& value) const; 543 bool operator ==(const wxArrayString& value) const; 544 bool operator ==(const wxDateTime& value) const; 545 //@} 546 547 //@{ 548 /** 549 Operators for implicit conversion, using appropriate getter member 550 function. 551 */ 552 double operator double() const; 553 long operator long() const; 554 wxLongLong operator wxLongLong() const; 555 wxULongLong operator wxULongLong() const; 556 //@} 557 558 /** 559 Operator for implicit conversion to a pointer to a void, using 560 GetVoidPtr(). 561 */ 562 void* operator void*() const; 563 564 /** 565 Operator for implicit conversion to a wxChar, using GetChar(). 566 */ 567 char operator wxChar() const; 568 569 /** 570 Operator for implicit conversion to a pointer to a wxDateTime, using 571 GetDateTime(). 572 */ 573 void* operator wxDateTime() const; 574 575 /** 576 Operator for implicit conversion to a string, using MakeString(). 577 */ 578 wxString operator wxString() const; 579 }; 580 581 582 583 /** 584 @class wxVariantData 585 586 The wxVariantData class is used to implement a new type for wxVariant. 587 Derive from wxVariantData, and override the pure virtual functions. 588 589 wxVariantData is @ref overview_refcount "reference counted", but you don't 590 normally have to care about this, as wxVariant manages the count 591 automatically. However, in case your application needs to take ownership of 592 wxVariantData, be aware that the object is created with a reference count 593 of 1, and passing it to wxVariant will not increase this. In other words, 594 IncRef() needs to be called only if you both take ownership of 595 wxVariantData and pass it to a wxVariant. Also note that the destructor is 596 protected, so you can never explicitly delete a wxVariantData instance. 597 Instead, DecRef() will delete the object automatically when the reference 598 count reaches zero. 599 600 @library{wxbase} 601 @category{data} 602 603 @see wxVariant, wxGetVariantCast() 604 */ 605 class wxVariantData : public wxObjectRefData 606 { 607 public: 608 /** 609 Default constructor. 610 */ 611 wxVariantData(); 612 613 /** 614 This function can be overridden to clone the data. You must implement 615 this function in order for wxVariant::Unshare() to work for your data. 616 This function is implemented for all built-in data types. 617 */ 618 virtual wxVariantData* Clone() const; 619 620 /** 621 Decreases reference count. If the count reaches zero, the object is 622 automatically deleted. 623 624 @note The destructor of wxVariantData is protected, so delete cannot be 625 used as normal. Instead, DecRef() should be called. 626 */ 627 void DecRef(); 628 629 /** 630 Returns @true if this object is equal to @a data. 631 */ 632 virtual bool Eq(wxVariantData& data) const = 0; 633 634 /** 635 Converts value to wxAny, if possible. Return @true if successful. 636 */ 637 virtual bool GetAny(wxAny* any) const; 638 639 /** 640 Returns the string type of the data. 641 */ 642 virtual wxString GetType() const = 0; 643 644 /** 645 If the data is a wxObject returns a pointer to the objects wxClassInfo 646 structure, if the data isn't a wxObject the method returns @NULL. 647 */ 648 virtual wxClassInfo* GetValueClassInfo(); 649 650 /** 651 Increases reference count. Note that initially wxVariantData has 652 reference count of 1. 653 */ 654 void IncRef(); 655 656 /** 657 Reads the data from @a stream. 658 */ 659 virtual bool Read(istream& stream); 660 661 /** 662 Reads the data from @a string. 663 */ 664 virtual bool Read(wxString& string); 665 666 /** 667 Writes the data to @a stream. 668 */ 669 virtual bool Write(ostream& stream) const; 670 /** 671 Writes the data to @a string. 672 */ 673 virtual bool Write(wxString& string) const; 674 }; 675 676 677 678 // ============================================================================ 679 // Global functions/macros 680 // ============================================================================ 681 682 /** @addtogroup group_funcmacro_rtti */ 683 //@{ 684 685 /** 686 This macro returns a pointer to the data stored in @a var (wxVariant) cast 687 to the type @a classname if the data is of this type (the check is done 688 during the run-time) or @NULL otherwise. 689 690 @header{wx/variant.h} 691 692 @see @ref overview_rtti, wxDynamicCast() 693 */ 694 #define wxGetVariantCast(var, classname) 695 696 //@} 697 698