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