interface/variant.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        variant.h
   3 // Purpose:     documentation for wxVariant class
   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     @seealso
 103     wxVariantData
 104 */
 105 class wxVariant : public wxObject
 106 {
 107 public:
 108     //@{
 109     /**
 110         Construction from a ODBC timestamp value.  Represented internally by a
 111         wxDateTime value.
 112     */
 113     wxVariant();
 114     wxVariant(const wxVariant& variant);
 115     wxVariant(const wxChar* value, const wxString& name = "");
 116     wxVariant(const wxString& value, const wxString& name = "");
 117     wxVariant(wxChar value, const wxString& name = "");
 118     wxVariant(long value, const wxString& name = "");
 119     wxVariant(bool value, const wxString& name = "");
 120     wxVariant(double value, const wxString& name = "");
 121     wxVariant(const wxVariantList& value,
 122               const wxString& name = "");
 123     wxVariant(void* value, const wxString& name = "");
 124     wxVariant(wxObject* value, const wxString& name = "");
 125     wxVariant(wxVariantData* data, const wxString& name = "");
 126     wxVariant(wxDateTime& val, const wxString& name = "");
 127     wxVariant(wxArrayString& val, const wxString& name = "");
 128     wxVariant(DATE_STRUCT* val, const wxString& name = "");
 129     wxVariant(TIME_STRUCT* val, const wxString& name = "");
 130     wxVariant(TIMESTAMP_STRUCT* val, const wxString& name = "");
 131     //@}
 132
 133     /**
 134         Destructor.
 135         Note that destructor is protected, so wxVariantData cannot usually
 136         be deleted. Instead, wxVariantData::DecRef should be called.
 137         See @ref overview_refcountdestruct "reference-counted object destruction" for
 138         more info.
 139     */
 140     ~wxVariant();
 141
 142     /**
 143         Appends a value to the list.
 144     */
 145     void Append(const wxVariant& value);
 146
 147     /**
 148         Makes the variant null by deleting the internal data and
 149         set the name to @e wxEmptyString.
 150     */
 151     void Clear();
 152
 153     /**
 154         Deletes the contents of the list.
 155     */
 156     void ClearList();
 157
 158     //@{
 159     /**
 160         Retrieves and converts the value of this variant to the type that @a value is.
 161     */
 162     bool Convert(long* value) const;
 163     const bool Convert(bool* value) const;
 164     const bool Convert(double* value) const;
 165     const bool Convert(wxString* value) const;
 166     const bool Convert(wxChar* value) const;
 167     const bool Convert(wxDateTime* value) const;
 168     //@}
 169
 170     /**
 171         Deletes the zero-based @a item from the list.
 172     */
 173     bool Delete(size_t item);
 174
 175     /**
 176         Returns the string array value.
 177     */
 178     wxArrayString GetArrayString() const;
 179
 180     /**
 181         Returns the boolean value.
 182     */
 183     bool GetBool() const;
 184
 185     /**
 186         Returns the character value.
 187     */
 188     wxChar GetChar() const;
 189
 190     /**
 191         Returns the number of elements in the list.
 192     */
 193     size_t GetCount() const;
 194
 195     /**
 196         Returns a pointer to the internal variant data. To take ownership
 197         of this data, you must call its wxVariantData::IncRef
 198         method. When you stop using it, wxVariantData::DecRef
 199         must be likewise called.
 200     */
 201     wxVariantData* GetData() const;
 202
 203     /**
 204         Returns the date value.
 205     */
 206     wxDateTime GetDateTime() const;
 207
 208     /**
 209         Returns the floating point value.
 210     */
 211     double GetDouble() const;
 212
 213     /**
 214         Returns a reference to the wxVariantList class used by
 215         wxVariant if this wxVariant is currently a list of variants.
 216     */
 217     wxVariantList GetList() const;
 218
 219     /**
 220         Returns the integer value.
 221     */
 222     long GetLong() const;
 223
 224     /**
 225         Returns a constant reference to the variant name.
 226     */
 227     const wxString GetName() const;
 228
 229     /**
 230         Gets the string value.
 231     */
 232     wxString GetString() const;
 233
 234     /**
 235         Returns the value type as a string. The built-in types are: bool, char,
 236         datetime, double, list, long, string, arrstring, void*.
 237         If the variant is null, the value type returned is the string "null" (not the
 238         empty string).
 239     */
 240     wxString GetType() const;
 241
 242     /**
 243         Gets the void pointer value.
 244     */
 245     void* GetVoidPtr() const;
 246
 247     /**
 248         Gets the wxObject pointer value.
 249     */
 250     wxObject* GetWxObjectPtr() const;
 251
 252     /**
 253         Inserts a value at the front of the list.
 254     */
 255     void Insert(const wxVariant& value);
 256
 257     /**
 258         Returns @true if there is no data associated with this variant, @false if there
 259         is data.
 260     */
 261     bool IsNull() const;
 262
 263     /**
 264         Returns @true if @a type matches the type of the variant, @false otherwise.
 265     */
 266     bool IsType(const wxString& type) const;
 267
 268     /**
 269         Returns @true if the data is derived from the class described by @e type, @false
 270         otherwise.
 271     */
 272     bool IsValueKindOf(const wxClassInfo* type type) const;
 273
 274     /**
 275         Makes the variant null by deleting the internal data.
 276     */
 277     void MakeNull();
 278
 279     /**
 280         Makes a string representation of the variant value (for any type).
 281     */
 282     wxString MakeString() const;
 283
 284     /**
 285         Returns @true if @a value matches an element in the list.
 286     */
 287     bool Member(const wxVariant& value) const;
 288
 289     /**
 290         Makes an empty list. This differs from a null variant which has no data; a null
 291         list
 292         is of type list, but the number of elements in the list is zero.
 293     */
 294     void NullList();
 295
 296     /**
 297         Sets the internal variant data, deleting the existing data if there is any.
 298     */
 299     void SetData(wxVariantData* data);
 300
 301     /**
 302         Makes sure that any data associated with this variant is not shared with other
 303         variants. For this to work, wxVariantData::Clone must
 304         be implemented for the data types you are working with. Clone is implemented
 305         for all the default data types.
 306     */
 307     bool Unshare();
 308
 309     //@{
 310     /**
 311         Inequality test operators.
 312     */
 313     bool operator !=(const wxVariant& value) const;
 314     const bool operator !=(const wxString& value) const;
 315     const bool operator !=(const wxChar* value) const;
 316     const bool operator !=(wxChar value) const;
 317     const bool operator !=(const long value) const;
 318     const bool operator !=(const bool value) const;
 319     const bool operator !=(const double value) const;
 320     const bool operator !=(void* value) const;
 321     const bool operator !=(wxObject* value) const;
 322     const bool operator !=(const wxVariantList& value) const;
 323     const bool operator !=(const wxArrayString& value) const;
 324     const bool operator !=(const wxDateTime& value) const;
 325     //@}
 326
 327     //@{
 328     /**
 329         Assignment operators, using @ref overview_trefcount "reference counting" when
 330         possible.
 331     */
 332     void operator =(const wxVariant& value);
 333     void operator =(wxVariantData* value);
 334     void operator =(const wxString& value);
 335     void operator =(const wxChar* value);
 336     void operator =(wxChar value);
 337     void operator =(const long value);
 338     void operator =(const bool value);
 339     void operator =(const double value);
 340     void operator =(void* value);
 341     void operator =(wxObject* value);
 342     void operator =(const wxVariantList& value);
 343     void operator =(const wxDateTime& value);
 344     void operator =(const wxArrayString& value);
 345     void operator =(const DATE_STRUCT* value);
 346     void operator =(const TIME_STRUCT* value);
 347     void operator =(const TIMESTAMP_STRUCT* value);
 348     //@}
 349
 350     //@{
 351     /**
 352         Equality test operators.
 353     */
 354     bool operator ==(const wxVariant& value) const;
 355     const bool operator ==(const wxString& value) const;
 356     const bool operator ==(const wxChar* value) const;
 357     const bool operator ==(wxChar value) const;
 358     const bool operator ==(const long value) const;
 359     const bool operator ==(const bool value) const;
 360     const bool operator ==(const double value) const;
 361     const bool operator ==(void* value) const;
 362     const bool operator ==(wxObject* value) const;
 363     const bool operator ==(const wxVariantList& value) const;
 364     const bool operator ==(const wxArrayString& value) const;
 365     const bool operator ==(const wxDateTime& value) const;
 366     //@}
 367
 368     //@{
 369     /**
 370         Returns a reference to the value at @a idx (zero-based). This can be used
 371         to change the value at this index.
 372     */
 373     wxVariant operator [](size_t idx);
 374     const wxVariant&  operator [](size_t idx);
 375     //@}
 376
 377     //@{
 378     /**
 379         Operator for implicit conversion to a long, using GetLong().
 380     */
 381     double operator double() const;
 382     const long operator long() const;
 383     //@}
 384
 385     /**
 386         Operator for implicit conversion to a pointer to a void, using GetVoidPtr().
 387     */
 388     void* operator void*() const;
 389
 390     /**
 391         Operator for implicit conversion to a wxChar, using GetChar().
 392     */
 393     char operator wxChar() const;
 394
 395     /**
 396         Operator for implicit conversion to a pointer to a wxDateTime, using
 397         GetDateTime().
 398     */
 399     void* operator wxDateTime() const;
 400
 401     /**
 402         Operator for implicit conversion to a string, using MakeString().
 403     */
 404     wxString operator wxString() const;
 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     @seealso
 434     wxVariant
 435 */
 436 class wxVariantData
 437 {
 438 public:
 439     /**
 440         Default constructor.
 441     */
 442     wxVariantData();
 443
 444     /**
 445         This function can be overridden to clone the data.
 446         Implement Clone if you wish wxVariant::Unshare to work
 447         for your data. This function is implemented for all built-in data types.
 448     */
 449     wxVariantData* Clone() const;
 450
 451     /**
 452         Decreases reference count. If the count reaches zero, the object is
 453         automatically deleted.
 454         Note that destructor of wxVariantData is protected, so delete
 455         cannot be used as normal. Instead, DecRef() should be called.
 456     */
 457     void DecRef();
 458
 459     /**
 460         Returns @true if this object is equal to @e data.
 461     */
 462     bool Eq(wxVariantData& data) const;
 463
 464     /**
 465         Returns the string type of the data.
 466     */
 467     wxString GetType() const;
 468
 469     /**
 470         If the data is a wxObject returns a pointer to the objects wxClassInfo
 471         structure, if
 472         the data isn't a wxObject the method returns @NULL.
 473     */
 474     wxClassInfo* GetValueClassInfo() const;
 475
 476     /**
 477         Increases reference count. Note that initially wxVariantData has reference
 478         count of 1.
 479     */
 480     void IncRef();
 481
 482     //@{
 483     /**
 484         Reads the data from @a stream or @e string.
 485     */
 486     bool Read(ostream& stream);
 487     bool Read(wxString& string);
 488     //@}
 489
 490     //@{
 491     /**
 492         Writes the data to @a stream or @e string.
 493     */
 494     bool Write(ostream& stream) const;
 495     const bool Write(wxString& string) const;
 496     //@}
 497
 498     /**
 499         This macro returns the data stored in @e variant cast to the type @e classname
 500         * if
 501         the data is of this type (the check is done during the run-time) or
 502         @NULL otherwise.
 503     */
 504     classname* wxGetVariantCast();
 505 };