interface/wx/variant.h

   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