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 = "");
 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 = "");
 118
 119     /**
 120         Constructs a variant from a string.
 121     */
 122     wxVariant(const wxString& value, const wxString& name = "");
 123
 124     /**
 125         Constructs a variant from a wide char.
 126     */
 127     wxVariant(wxChar value, const wxString& name = "");
 128
 129     /**
 130         Constructs a variant from a long.
 131     */
 132     wxVariant(long value, const wxString& name = "");
 133
 134     /**
 135         Constructs a variant from a bool.
 136     */
 137     wxVariant(bool value, const wxString& name = "");
 138
 139     /**
 140         Constructs a variant from a double.
 141     */
 142     wxVariant(double value, const wxString& name = "");
 143
 144     /**
 145         Constructs a variant from a list of variants
 146     */
 147     wxVariant(const wxVariantList& value, const wxString& name = "");
 148
 149     /**
 150         Constructs a variant from a void pointer.
 151     */
 152     wxVariant(void* value, const wxString& name = "");
 153
 154     /**
 155         Constructs a variant from a pointer to an wxObject
 156         derived class.
 157     */
 158     wxVariant(wxObject* value, const wxString& name = "");
 159
 160     /**
 161         Constructs a variant from a wxDateTime.
 162     */
 163     wxVariant(wxDateTime& val, const wxString& name = "");
 164
 165     /**
 166         Constructs a variant from a wxArrayString.
 167     */
 168     wxVariant(wxArrayString& val, const wxString& name = "");
 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     ~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     wxChar 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     void* GetVoidPtr() const;
 326
 327     /**
 328         Gets the wxObject pointer value.
 329     */
 330     wxObject* GetWxObjectPtr() const;
 331
 332     /**
 333         Returns @true if there is no data associated with this variant, @false
 334         if there is data.
 335     */
 336     bool IsNull() const;
 337
 338     /**
 339         Returns @true if @a type matches the type of the variant, @false
 340         otherwise.
 341     */
 342     bool IsType(const wxString& type) const;
 343
 344     /**
 345         Returns @true if the data is derived from the class described by
 346         @a type, @false otherwise.
 347     */
 348     bool IsValueKindOf(const wxClassInfo* type) const;
 349
 350     /**
 351         Makes the variant null by deleting the internal data.
 352     */
 353     void MakeNull();
 354
 355     /**
 356         Makes a string representation of the variant value (for any type).
 357     */
 358     wxString MakeString() const;
 359
 360     /**
 361         Returns @true if @a value matches an element in the list.
 362     */
 363     bool Member(const wxVariant& value) const;
 364
 365     /**
 366         Sets the internal variant data, deleting the existing data if there is
 367         any.
 368     */
 369     void SetData(wxVariantData* data);
 370
 371     /**
 372         Makes sure that any data associated with this variant is not shared
 373         with other variants. For this to work, wxVariantData::Clone() must be
 374         implemented for the data types you are working with.
 375         wxVariantData::Clone() is implemented for all the default data types.
 376     */
 377     bool Unshare();
 378
 379     //@{
 380     /**
 381         Inequality test operator.
 382     */
 383     bool operator !=(const wxVariant& value) const;
 384     bool operator !=(const wxString& value) const;
 385     bool operator !=(const wxChar* value) const;
 386     bool operator !=(wxChar value) const;
 387     bool operator !=(const long value) const;
 388     bool operator !=(const bool value) const;
 389     bool operator !=(const double value) const;
 390     bool operator !=(void* value) const;
 391     bool operator !=(wxObject* value) const;
 392     bool operator !=(const wxVariantList& value) const;
 393     bool operator !=(const wxArrayString& value) const;
 394     bool operator !=(const wxDateTime& value) const;
 395     //@}
 396
 397     //@{
 398     /**
 399         Assignment operator, using @ref overview_refcount "reference counting"
 400         if possible.
 401     */
 402     void operator =(const wxVariant& value);
 403     void operator =(wxVariantData* value);
 404     void operator =(const wxString& value);
 405     void operator =(const wxChar* value);
 406     void operator =(wxChar value);
 407     void operator =(const long value);
 408     void operator =(const bool value);
 409     void operator =(const double value);
 410     void operator =(void* value);
 411     void operator =(wxObject* value);
 412     void operator =(const wxVariantList& value);
 413     void operator =(const wxDateTime& value);
 414     void operator =(const wxArrayString& value);
 415     //@}
 416
 417     //@{
 418     /**
 419         Equality test operator.
 420     */
 421     bool operator ==(const wxVariant& value) const;
 422     bool operator ==(const wxString& value) const;
 423     bool operator ==(const wxChar* value) const;
 424     bool operator ==(wxChar value) const;
 425     bool operator ==(const long value) const;
 426     bool operator ==(const bool value) const;
 427     bool operator ==(const double value) const;
 428     bool operator ==(void* value) const;
 429     bool operator ==(wxObject* value) const;
 430     bool operator ==(const wxVariantList& value) const;
 431     bool operator ==(const wxArrayString& value) const;
 432     bool operator ==(const wxDateTime& value) const;
 433     //@}
 434
 435     //@{
 436     /**
 437         Operator for implicit conversion to a long, using GetLong().
 438     */
 439     double operator double() const;
 440     long operator long() const;
 441     //@}
 442
 443     /**
 444         Operator for implicit conversion to a pointer to a void, using
 445         GetVoidPtr().
 446     */
 447     void* operator void*() const;
 448
 449     /**
 450         Operator for implicit conversion to a wxChar, using GetChar().
 451     */
 452     char operator wxChar() const;
 453
 454     /**
 455         Operator for implicit conversion to a pointer to a wxDateTime, using
 456         GetDateTime().
 457     */
 458     void* operator wxDateTime() const;
 459
 460     /**
 461         Operator for implicit conversion to a string, using MakeString().
 462     */
 463     wxString operator wxString() const;
 464 };
 465
 466
 467
 468 /**
 469     @class wxVariantData
 470
 471     The wxVariantData class is used to implement a new type for wxVariant.
 472     Derive from wxVariantData, and override the pure virtual functions.
 473
 474     wxVariantData is @ref overview_refcount "reference counted", but you don't
 475     normally have to care about this, as wxVariant manages the count
 476     automatically. However, in case your application needs to take ownership of
 477     wxVariantData, be aware that the object is created with a reference count
 478     of 1, and passing it to wxVariant will not increase this. In other words,
 479     IncRef() needs to be called only if you both take ownership of
 480     wxVariantData and pass it to a wxVariant. Also note that the destructor is
 481     protected, so you can never explicitly delete a wxVariantData instance.
 482     Instead, DecRef() will delete the object automatically when the reference
 483     count reaches zero.
 484
 485     @library{wxbase}
 486     @category{data}
 487
 488     @see wxVariant, wxGetVariantCast()
 489 */
 490 class wxVariantData
 491 {
 492 public:
 493     /**
 494         Default constructor.
 495     */
 496     wxVariantData();
 497
 498     /**
 499         This function can be overridden to clone the data. You must implement
 500         this function in order for wxVariant::Unshare() to work for your data.
 501         This function is implemented for all built-in data types.
 502     */
 503     wxVariantData* Clone() const;
 504
 505     /**
 506         Decreases reference count. If the count reaches zero, the object is
 507         automatically deleted.
 508
 509         @note The destructor of wxVariantData is protected, so delete cannot be
 510               used as normal. Instead, DecRef() should be called.
 511     */
 512     void DecRef();
 513
 514     /**
 515         Returns @true if this object is equal to @a data.
 516     */
 517     bool Eq(wxVariantData& data) const;
 518
 519     /**
 520         Returns the string type of the data.
 521     */
 522     wxString GetType() const;
 523
 524     /**
 525         If the data is a wxObject returns a pointer to the objects wxClassInfo
 526         structure, if the data isn't a wxObject the method returns @NULL.
 527     */
 528     wxClassInfo* GetValueClassInfo() const;
 529
 530     /**
 531         Increases reference count. Note that initially wxVariantData has
 532         reference count of 1.
 533     */
 534     void IncRef();
 535
 536     /**
 537         Reads the data from @a stream.
 538     */
 539     bool Read(ostream& stream);
 540     /**
 541         Reads the data from @a string.
 542     */
 543     bool Read(wxString& string);
 544
 545     /**
 546         Writes the data to @a stream.
 547     */
 548     bool Write(ostream& stream) const;
 549     /**
 550         Writes the data to @a string.
 551     */
 552     bool Write(wxString& string) const;
 553 };
 554
 555
 556
 557 // ============================================================================
 558 // Global functions/macros
 559 // ============================================================================
 560
 561 /** @ingroup group_funcmacro_rtti */
 562 //@{
 563
 564 /**
 565     This macro returns a pointer to the data stored in @a var (wxVariant) cast
 566     to the type @a classname if the data is of this type (the check is done
 567     during the run-time) or @NULL otherwise.
 568
 569     @header{wx/variant.h}
 570
 571     @see @ref overview_rtti, wxDynamicCast()
 572 */
 573 #define wxGetVariantCast(var, classname)
 574
 575 //@}
 576