interface/wx/variant.h

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