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