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