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