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