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