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 list of variants
 146     */
 147     wxVariant(const wxVariantList& value, const wxString& name = wxEmptyString);
 148
 149     /**
 150         Constructs a variant from a void pointer.
 151     */
 152     wxVariant(void* value, const wxString& name = wxEmptyString);
 153
 154     /**
 155         Constructs a variant from a pointer to an wxObject
 156         derived class.
 157     */
 158     wxVariant(wxObject* value, const wxString& name = wxEmptyString);
 159
 160     /**
 161         Constructs a variant from a wxDateTime.
 162     */
 163     wxVariant(const wxDateTime& val, const wxString& name = wxEmptyString);
 164
 165     /**
 166         Constructs a variant from a wxArrayString.
 167     */
 168     wxVariant(const wxArrayString& val, const wxString& name = wxEmptyString);
 169
 170     /**
 171         Destructor.
 172
 173         @note wxVariantData's destructor is protected, so wxVariantData cannot
 174               usually be deleted. Instead, wxVariantData::DecRef() should be
 175               called. See @ref overview_refcount_destruct
 176               "reference-counted object destruction" for more info.
 177     */
 178     virtual ~wxVariant();
 179
 180
 181     /**
 182         @name List Functionality
 183     */
 184     //@{
 185
 186     /**
 187         Returns the value at @a idx (zero-based).
 188     */
 189     wxVariant operator [](size_t idx) const;
 190     /**
 191         Returns a reference to the value at @a idx (zero-based). This can be
 192         used to change the value at this index.
 193     */
 194     wxVariant& operator [](size_t idx);
 195
 196     /**
 197         Appends a value to the list.
 198     */
 199     void Append(const wxVariant& value);
 200
 201     /**
 202         Makes the variant null by deleting the internal data and set the name
 203         to wxEmptyString.
 204     */
 205     void Clear();
 206
 207     /**
 208         Deletes the contents of the list.
 209     */
 210     void ClearList();
 211
 212     /**
 213         Deletes the zero-based @a item from the list.
 214     */
 215     bool Delete(size_t item);
 216
 217     /**
 218         Returns the number of elements in the list.
 219     */
 220     size_t GetCount() const;
 221
 222     /**
 223         Returns a reference to the wxVariantList class used by wxVariant if
 224         this wxVariant is currently a list of variants.
 225     */
 226     wxVariantList& GetList() const;
 227
 228     /**
 229         Inserts a value at the front of the list.
 230     */
 231     void Insert(const wxVariant& value);
 232
 233     /**
 234         Makes an empty list. This differs from a null variant which has no
 235         data; a null list is of type list, but the number of elements in the
 236         list is zero.
 237     */
 238     void NullList();
 239
 240     //@}
 241
 242
 243     //@{
 244     /**
 245         Retrieves and converts the value of this variant to the type that
 246         @a value is.
 247     */
 248     bool Convert(long* value) const;
 249     bool Convert(bool* value) const;
 250     bool Convert(double* value) const;
 251     bool Convert(wxString* value) const;
 252     bool Convert(wxChar* value) const;
 253     bool Convert(wxDateTime* value) const;
 254     //@}
 255
 256     /**
 257         Returns the string array value.
 258     */
 259     wxArrayString GetArrayString() const;
 260
 261     /**
 262         Returns the boolean value.
 263     */
 264     bool GetBool() const;
 265
 266     /**
 267         Returns the character value.
 268     */
 269     wxUniChar GetChar() const;
 270
 271     /**
 272         Returns a pointer to the internal variant data. To take ownership of
 273         this data, you must call its wxVariantData::IncRef() method. When you
 274         stop using it, wxVariantData::DecRef() must be called as well.
 275     */
 276     wxVariantData* GetData() const;
 277
 278     /**
 279         Returns the date value.
 280     */
 281     wxDateTime GetDateTime() const;
 282
 283     /**
 284         Returns the floating point value.
 285     */
 286     double GetDouble() const;
 287
 288     /**
 289         Returns the integer value.
 290     */
 291     long GetLong() const;
 292
 293     /**
 294         Returns a constant reference to the variant name.
 295     */
 296     const wxString& GetName() const;
 297
 298     /**
 299         Gets the string value.
 300     */
 301     wxString GetString() const;
 302
 303     /**
 304         Returns the value type as a string.
 305
 306         The built-in types are:
 307         - "bool"
 308         - "char"
 309         - "datetime"
 310         - "double"
 311         - "list"
 312         - "long"
 313         - "string"
 314         - "arrstring"
 315         - "void*"
 316
 317         If the variant is null, the value type returned is the string "null"
 318         (not the empty string).
 319     */
 320     wxString GetType() const;
 321
 322     /**
 323         Gets the void pointer value.
 324
 325         Notice that this method can be used for null objects (i.e. those for
 326         which IsNull() returns @true) and will return @NULL for them.
 327     */
 328     void* GetVoidPtr() const;
 329
 330     /**
 331         Gets the wxObject pointer value.
 332     */
 333     wxObject* GetWxObjectPtr() const;
 334
 335     /**
 336         Returns @true if there is no data associated with this variant, @false
 337         if there is data.
 338     */
 339     bool IsNull() const;
 340
 341     /**
 342         Returns @true if @a type matches the type of the variant, @false
 343         otherwise.
 344     */
 345     bool IsType(const wxString& type) const;
 346
 347     /**
 348         Returns @true if the data is derived from the class described by
 349         @a type, @false otherwise.
 350     */
 351     bool IsValueKindOf(const wxClassInfo* type) const;
 352
 353     /**
 354         Makes the variant null by deleting the internal data.
 355     */
 356     void MakeNull();
 357
 358     /**
 359         Makes a string representation of the variant value (for any type).
 360     */
 361     wxString MakeString() const;
 362
 363     /**
 364         Returns @true if @a value matches an element in the list.
 365     */
 366     bool Member(const wxVariant& value) const;
 367
 368     /**
 369         Sets the internal variant data, deleting the existing data if there is
 370         any.
 371     */
 372     void SetData(wxVariantData* data);
 373
 374     /**
 375         Makes sure that any data associated with this variant is not shared
 376         with other variants. For this to work, wxVariantData::Clone() must be
 377         implemented for the data types you are working with.
 378         wxVariantData::Clone() is implemented for all the default data types.
 379     */
 380     bool Unshare();
 381
 382     //@{
 383     /**
 384         Inequality test operator.
 385     */
 386     bool operator !=(const wxVariant& value) const;
 387     bool operator !=(const wxString& value) const;
 388     bool operator !=(const wxChar* value) const;
 389     bool operator !=(wxChar value) const;
 390     bool operator !=(long value) const;
 391     bool operator !=(bool value) const;
 392     bool operator !=(double value) const;
 393     bool operator !=(void* value) const;
 394     bool operator !=(wxObject* value) const;
 395     bool operator !=(const wxVariantList& value) const;
 396     bool operator !=(const wxArrayString& value) const;
 397     bool operator !=(const wxDateTime& value) const;
 398     //@}
 399
 400     //@{
 401     /**
 402         Assignment operator, using @ref overview_refcount "reference counting"
 403         if possible.
 404     */
 405     void operator =(const wxVariant& value);
 406     void operator =(wxVariantData* value);
 407     void operator =(const wxString& value);
 408     void operator =(const wxChar* value);
 409     void operator =(wxChar value);
 410     void operator =(long value);
 411     void operator =(bool value);
 412     void operator =(double value);
 413     void operator =(void* value);
 414     void operator =(wxObject* value);
 415     void operator =(const wxVariantList& value);
 416     void operator =(const wxDateTime& value);
 417     void operator =(const wxArrayString& value);
 418     //@}
 419
 420     //@{
 421     /**
 422         Equality test operator.
 423     */
 424     bool operator ==(const wxVariant& value) const;
 425     bool operator ==(const wxString& value) const;
 426     bool operator ==(const wxChar* value) const;
 427     bool operator ==(wxChar value) const;
 428     bool operator ==(long value) const;
 429     bool operator ==(bool value) const;
 430     bool operator ==(double value) const;
 431     bool operator ==(void* value) const;
 432     bool operator ==(wxObject* value) const;
 433     bool operator ==(const wxVariantList& value) const;
 434     bool operator ==(const wxArrayString& value) const;
 435     bool operator ==(const wxDateTime& value) const;
 436     //@}
 437
 438     //@{
 439     /**
 440         Operator for implicit conversion to a long, using GetLong().
 441     */
 442     double operator double() const;
 443     long operator long() const;
 444     //@}
 445
 446     /**
 447         Operator for implicit conversion to a pointer to a void, using
 448         GetVoidPtr().
 449     */
 450     void* operator void*() const;
 451
 452     /**
 453         Operator for implicit conversion to a wxChar, using GetChar().
 454     */
 455     char operator wxChar() const;
 456
 457     /**
 458         Operator for implicit conversion to a pointer to a wxDateTime, using
 459         GetDateTime().
 460     */
 461     void* operator wxDateTime() const;
 462
 463     /**
 464         Operator for implicit conversion to a string, using MakeString().
 465     */
 466     wxString operator wxString() const;
 467 };
 468
 469
 470
 471 /**
 472     @class wxVariantData
 473
 474     The wxVariantData class is used to implement a new type for wxVariant.
 475     Derive from wxVariantData, and override the pure virtual functions.
 476
 477     wxVariantData is @ref overview_refcount "reference counted", but you don't
 478     normally have to care about this, as wxVariant manages the count
 479     automatically. However, in case your application needs to take ownership of
 480     wxVariantData, be aware that the object is created with a reference count
 481     of 1, and passing it to wxVariant will not increase this. In other words,
 482     IncRef() needs to be called only if you both take ownership of
 483     wxVariantData and pass it to a wxVariant. Also note that the destructor is
 484     protected, so you can never explicitly delete a wxVariantData instance.
 485     Instead, DecRef() will delete the object automatically when the reference
 486     count reaches zero.
 487
 488     @library{wxbase}
 489     @category{data}
 490
 491     @see wxVariant, wxGetVariantCast()
 492 */
 493 class wxVariantData
 494 {
 495 public:
 496     /**
 497         Default constructor.
 498     */
 499     wxVariantData();
 500
 501     /**
 502         This function can be overridden to clone the data. You must implement
 503         this function in order for wxVariant::Unshare() to work for your data.
 504         This function is implemented for all built-in data types.
 505     */
 506     virtual wxVariantData* Clone() const;
 507
 508     /**
 509         Decreases reference count. If the count reaches zero, the object is
 510         automatically deleted.
 511
 512         @note The destructor of wxVariantData is protected, so delete cannot be
 513               used as normal. Instead, DecRef() should be called.
 514     */
 515     void DecRef();
 516
 517     /**
 518         Returns @true if this object is equal to @a data.
 519     */
 520     virtual bool Eq(wxVariantData& data) const = 0;
 521
 522     /**
 523         Returns the string type of the data.
 524     */
 525     virtual wxString GetType() const = 0;
 526
 527     /**
 528         If the data is a wxObject returns a pointer to the objects wxClassInfo
 529         structure, if the data isn't a wxObject the method returns @NULL.
 530     */
 531     virtual wxClassInfo* GetValueClassInfo();
 532
 533     /**
 534         Increases reference count. Note that initially wxVariantData has
 535         reference count of 1.
 536     */
 537     void IncRef();
 538
 539     /**
 540         Reads the data from @a stream.
 541     */
 542     virtual bool Read(istream& stream);
 543
 544     /**
 545         Reads the data from @a string.
 546     */
 547     virtual bool Read(wxString& string);
 548
 549     /**
 550         Writes the data to @a stream.
 551     */
 552     virtual bool Write(ostream& stream) const;
 553     /**
 554         Writes the data to @a string.
 555     */
 556     virtual bool Write(wxString& string) const;
 557 };
 558
 559
 560
 561 // ============================================================================
 562 // Global functions/macros
 563 // ============================================================================
 564
 565 /** @addtogroup group_funcmacro_rtti */
 566 //@{
 567
 568 /**
 569     This macro returns a pointer to the data stored in @a var (wxVariant) cast
 570     to the type @a classname if the data is of this type (the check is done
 571     during the run-time) or @NULL otherwise.
 572
 573     @header{wx/variant.h}
 574
 575     @see @ref overview_rtti, wxDynamicCast()
 576 */
 577 #define wxGetVariantCast(var, classname)
 578
 579 //@}
 580