X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/328f5751e8a06727b137189fe04891a9f43bfc8b..3201a1046ba71ba8e5ef2ed694fde34d12f743f3:/interface/variant.h diff --git a/interface/variant.h b/interface/variant.h index 31748972ac..e276cce933 100644 --- a/interface/variant.h +++ b/interface/variant.h @@ -1,6 +1,6 @@ ///////////////////////////////////////////////////////////////////////////// // Name: variant.h -// Purpose: documentation for wxVariant class +// Purpose: interface of wxVariant // Author: wxWidgets team // RCS-ID: $Id$ // Licence: wxWindows license @@ -10,71 +10,61 @@ @class wxVariant @wxheader{variant.h} - The @b wxVariant class represents a container for any type. - A variant's value can be changed at run time, possibly to a different type of - value. + The wxVariant class represents a container for any type. A variant's value + can be changed at run time, possibly to a different type of value. As standard, wxVariant can store values of type bool, wxChar, double, long, - string, - string list, time, date, void pointer, list of strings, and list of variants. - However, an application can extend wxVariant's capabilities by deriving from the - class wxVariantData and using the wxVariantData form of + string, string list, time, date, void pointer, list of strings, and list of + variants. However, an application can extend wxVariant's capabilities by + deriving from the class wxVariantData and using the wxVariantData form of the wxVariant constructor or assignment operator to assign this data to a - variant. - Actual values for user-defined types will need to be accessed via the - wxVariantData - object, unlike the case for basic data types where convenience functions such as - wxVariant::GetLong can be used. - - Pointers to any wxObject derived class can also easily be stored - in a wxVariant. wxVariant will then use wxWidgets' built-in RTTI system to set - the - type name (returned by wxVariant::GetType) and to perform - type-safety checks at runtime. - - This class is useful for reducing the programming for certain tasks, such as an - editor - for different data types, or a remote procedure call protocol. - - An optional name member is associated with a wxVariant. This might be used, for - example, - in CORBA or OLE automation classes, where named parameters are required. - - Note that as of wxWidgets 2.7.1, wxVariant is @ref overview_trefcount - "reference counted". - Additionally, the convenience macros @b DECLARE_VARIANT_OBJECT and - @b IMPLEMENT_VARIANT_OBJECT were added so that adding (limited) support - for conversion to and from wxVariant can be very easily implemented without - modifying - either wxVariant or the class to be stored by wxVariant. Since assignment - operators - cannot be declared outside the class, the shift left operators are used like - this: + variant. Actual values for user-defined types will need to be accessed via + the wxVariantData object, unlike the case for basic data types where + convenience functions such as GetLong() can be used. + + Pointers to any wxObject derived class can also easily be stored in a + wxVariant. wxVariant will then use wxWidgets' built-in RTTI system to set + the type name (returned by GetType()) and to perform type-safety checks at + runtime. + + This class is useful for reducing the programming for certain tasks, such + as an editor for different data types, or a remote procedure call protocol. + + An optional name member is associated with a wxVariant. This might be used, + for example, in CORBA or OLE automation classes, where named parameters are + required. + + Note that as of wxWidgets 2.7.1, wxVariant is + @ref overview_refcount "reference counted". Additionally, the convenience + macros DECLARE_VARIANT_OBJECT() and IMPLEMENT_VARIANT_OBJECT() were added + so that adding (limited) support for conversion to and from wxVariant can + be very easily implemented without modifying either wxVariant or the class + to be stored by wxVariant. Since assignment operators cannot be declared + outside the class, the shift left operators are used like this: @code // in the header file - DECLARE_VARIANT_OBJECT(MyClass) + DECLARE_VARIANT_OBJECT(MyClass) - // in the implementation file - IMPLEMENT_VARIANT_OBJECT(MyClass) + // in the implementation file + IMPLEMENT_VARIANT_OBJECT(MyClass) - // in the user code - wxVariant variant; - MyClass value; - variant value; + // in the user code + wxVariant variant; + MyClass value; + variant << value; - // or - value variant; + // or + value << variant; @endcode - For this to work, MyClass must derive from wxObject, implement - the @ref overview_runtimeclassoverview "wxWidgets RTTI system" - and support the assignment operator and equality operator for itself. Ideally, - it - should also be reference counted to make copying operations cheap and fast. This - can be most easily implemented using the reference counting support offered by - wxObject itself. By default, wxWidgets already implements - the shift operator conversion for a few of its drawing related classes: + For this to work, MyClass must derive from wxObject, implement the + @ref overview_rtti "wxWidgets RTTI system" and support the assignment + operator and equality operator for itself. Ideally, it should also be + reference counted to make copying operations cheap and fast. This can be + most easily implemented using the reference counting support offered by + wxObject itself. By default, wxWidgets already implements the shift + operator conversion for a few of its drawing related classes: @code IMPLEMENT_VARIANT_OBJECT(wxColour) @@ -83,70 +73,135 @@ IMPLEMENT_VARIANT_OBJECT(wxBitmap) @endcode - Note that as of wxWidgets 2.9.0, wxVariantData no longer inherits from wxObject - and wxVariant no longer uses the type-unsafe wxList class for list + Note that as of wxWidgets 2.9.0, wxVariantData no longer inherits from + wxObject and wxVariant no longer uses the type-unsafe wxList class for list operations but the type-safe wxVariantList class. Also, wxVariantData now - supports the Clone function for implementing the wxVariant::Unshare function. - Clone is implemented automatically by IMPLEMENT_VARIANT_OBJECT. + supports the wxVariantData::Clone() function for implementing the Unshare() + function. wxVariantData::Clone() is implemented automatically by + IMPLEMENT_VARIANT_OBJECT(). - Since wxVariantData no longer derives from wxObject, any code that tests the - type - of the data using wxDynamicCast will require adjustment. You can use the macro - wxDynamicCastVariantData with the same arguments as wxDynamicCast, to use C++ - RTTI - type information instead of wxWidgets RTTI. + Since wxVariantData no longer derives from wxObject, any code that tests + the type of the data using wxDynamicCast() will require adjustment. You can + use the macro wxDynamicCastVariantData() with the same arguments as + wxDynamicCast(), to use C++ RTTI type information instead of wxWidgets + RTTI. @library{wxbase} @category{data} - @seealso - wxVariantData + @see wxVariantData */ class wxVariant : public wxObject { public: - //@{ /** - Construction from a ODBC timestamp value. Represented internally by a - wxDateTime value. + Default constructor. */ wxVariant(); + + /** + Constructs a variant directly with a wxVariantData object. wxVariant + will take ownership of the wxVariantData and will not increase its + reference count. + */ + wxVariant(wxVariantData* data, const wxString& name = ""); + + /** + Constructs a variant from another variant by increasing the reference + count. + */ wxVariant(const wxVariant& variant); + + /** + Constructs a variant from a wide string literal. + */ wxVariant(const wxChar* value, const wxString& name = ""); + + /** + Constructs a variant from a string. + */ wxVariant(const wxString& value, const wxString& name = ""); + + /** + Constructs a variant from a wide char. + */ wxVariant(wxChar value, const wxString& name = ""); + + /** + Constructs a variant from a long. + */ wxVariant(long value, const wxString& name = ""); + + /** + Constructs a variant from a bool. + */ wxVariant(bool value, const wxString& name = ""); + + /** + Constructs a variant from a double. + */ wxVariant(double value, const wxString& name = ""); - wxVariant(const wxVariantList& value, - const wxString& name = ""); + + /** + Constructs a variant from a list of variants + */ + wxVariant(const wxVariantList& value, const wxString& name = ""); + + /** + Constructs a variant from a void pointer. + */ wxVariant(void* value, const wxString& name = ""); + + /** + Constructs a variant from a pointer to an wxObject + derived class. + */ wxVariant(wxObject* value, const wxString& name = ""); - wxVariant(wxVariantData* data, const wxString& name = ""); + + /** + Constructs a variant from a wxDateTime. + */ wxVariant(wxDateTime& val, const wxString& name = ""); + + /** + Constructs a variant from a wxArrayString. + */ wxVariant(wxArrayString& val, const wxString& name = ""); - wxVariant(DATE_STRUCT* val, const wxString& name = ""); - wxVariant(TIME_STRUCT* val, const wxString& name = ""); - wxVariant(TIMESTAMP_STRUCT* val, const wxString& name = ""); - //@} /** Destructor. - Note that destructor is protected, so wxVariantData cannot usually - be deleted. Instead, wxVariantData::DecRef should be called. - See @ref overview_refcountdestruct "reference-counted object destruction" for - more info. + + @note wxVariantData's destructor is protected, so wxVariantData cannot + usually be deleted. Instead, wxVariantData::DecRef() should be + called. See @ref overview_refcount_destruct + "reference-counted object destruction" for more info. */ ~wxVariant(); + + /** + @name List Functionality + */ + //@{ + + /** + Returns the value at @a idx (zero-based). + */ + wxVariant operator [](size_t idx) const; + /** + Returns a reference to the value at @a idx (zero-based). This can be + used to change the value at this index. + */ + wxVariant& operator [](size_t idx); + /** Appends a value to the list. */ void Append(const wxVariant& value); /** - Makes the variant null by deleting the internal data and - set the name to @e wxEmptyString. + Makes the variant null by deleting the internal data and set the name + to wxEmptyString. */ void Clear(); @@ -155,22 +210,49 @@ public: */ void ClearList(); - //@{ /** - Retrieves and converts the value of this variant to the type that @a value is. + Deletes the zero-based @a item from the list. */ - bool Convert(long* value) const; - const bool Convert(bool* value) const; - const bool Convert(double* value) const; - const bool Convert(wxString* value) const; - const bool Convert(wxChar* value) const; - const bool Convert(wxDateTime* value) const; + bool Delete(size_t item); + + /** + Returns the number of elements in the list. + */ + size_t GetCount() const; + + /** + Returns a reference to the wxVariantList class used by wxVariant if + this wxVariant is currently a list of variants. + */ + wxVariantList& GetList() const; + + /** + Inserts a value at the front of the list. + */ + void Insert(const wxVariant& value); + + /** + Makes an empty list. This differs from a null variant which has no + data; a null list is of type list, but the number of elements in the + list is zero. + */ + void NullList(); + //@} + + //@{ /** - Deletes the zero-based @a item from the list. + Retrieves and converts the value of this variant to the type that + @a value is. */ - bool Delete(size_t item); + bool Convert(long* value) const; + bool Convert(bool* value) const; + bool Convert(double* value) const; + bool Convert(wxString* value) const; + bool Convert(wxChar* value) const; + bool Convert(wxDateTime* value) const; + //@} /** Returns the string array value. @@ -188,15 +270,9 @@ public: wxChar GetChar() const; /** - Returns the number of elements in the list. - */ - size_t GetCount() const; - - /** - Returns a pointer to the internal variant data. To take ownership - of this data, you must call its wxVariantData::IncRef - method. When you stop using it, wxVariantData::DecRef - must be likewise called. + Returns a pointer to the internal variant data. To take ownership of + this data, you must call its wxVariantData::IncRef() method. When you + stop using it, wxVariantData::DecRef() must be called as well. */ wxVariantData* GetData() const; @@ -210,12 +286,6 @@ public: */ double GetDouble() const; - /** - Returns a reference to the wxVariantList class used by - wxVariant if this wxVariant is currently a list of variants. - */ - wxVariantList GetList() const; - /** Returns the integer value. */ @@ -232,10 +302,21 @@ public: wxString GetString() const; /** - Returns the value type as a string. The built-in types are: bool, char, - datetime, double, list, long, string, arrstring, void*. - If the variant is null, the value type returned is the string "null" (not the - empty string). + Returns the value type as a string. + + The built-in types are: + - "bool" + - "char" + - "datetime" + - "double" + - "list" + - "long" + - "string" + - "arrstring" + - "void*" + + If the variant is null, the value type returned is the string "null" + (not the empty string). */ wxString GetType() const; @@ -250,26 +331,22 @@ public: wxObject* GetWxObjectPtr() const; /** - Inserts a value at the front of the list. - */ - void Insert(const wxVariant& value); - - /** - Returns @true if there is no data associated with this variant, @false if there - is data. + Returns @true if there is no data associated with this variant, @false + if there is data. */ bool IsNull() const; /** - Returns @true if @a type matches the type of the variant, @false otherwise. + Returns @true if @a type matches the type of the variant, @false + otherwise. */ bool IsType(const wxString& type) const; /** - Returns @true if the data is derived from the class described by @e type, @false - otherwise. + Returns @true if the data is derived from the class described by + @a type, @false otherwise. */ - bool IsValueKindOf(const wxClassInfo* type type) const; + bool IsValueKindOf(const wxClassInfo* type) const; /** Makes the variant null by deleting the internal data. @@ -287,47 +364,41 @@ public: bool Member(const wxVariant& value) const; /** - Makes an empty list. This differs from a null variant which has no data; a null - list - is of type list, but the number of elements in the list is zero. - */ - void NullList(); - - /** - Sets the internal variant data, deleting the existing data if there is any. + Sets the internal variant data, deleting the existing data if there is + any. */ void SetData(wxVariantData* data); /** - Makes sure that any data associated with this variant is not shared with other - variants. For this to work, wxVariantData::Clone must - be implemented for the data types you are working with. Clone is implemented - for all the default data types. + Makes sure that any data associated with this variant is not shared + with other variants. For this to work, wxVariantData::Clone() must be + implemented for the data types you are working with. + wxVariantData::Clone() is implemented for all the default data types. */ bool Unshare(); //@{ /** - Inequality test operators. + Inequality test operator. */ bool operator !=(const wxVariant& value) const; - const bool operator !=(const wxString& value) const; - const bool operator !=(const wxChar* value) const; - const bool operator !=(wxChar value) const; - const bool operator !=(const long value) const; - const bool operator !=(const bool value) const; - const bool operator !=(const double value) const; - const bool operator !=(void* value) const; - const bool operator !=(wxObject* value) const; - const bool operator !=(const wxVariantList& value) const; - const bool operator !=(const wxArrayString& value) const; - const bool operator !=(const wxDateTime& value) const; + bool operator !=(const wxString& value) const; + bool operator !=(const wxChar* value) const; + bool operator !=(wxChar value) const; + bool operator !=(const long value) const; + bool operator !=(const bool value) const; + bool operator !=(const double value) const; + bool operator !=(void* value) const; + bool operator !=(wxObject* value) const; + bool operator !=(const wxVariantList& value) const; + bool operator !=(const wxArrayString& value) const; + bool operator !=(const wxDateTime& value) const; //@} //@{ /** - Assignment operators, using @ref overview_trefcount "reference counting" when - possible. + Assignment operator, using @ref overview_refcount "reference counting" + if possible. */ void operator =(const wxVariant& value); void operator =(wxVariantData* value); @@ -342,36 +413,24 @@ public: void operator =(const wxVariantList& value); void operator =(const wxDateTime& value); void operator =(const wxArrayString& value); - void operator =(const DATE_STRUCT* value); - void operator =(const TIME_STRUCT* value); - void operator =(const TIMESTAMP_STRUCT* value); //@} //@{ /** - Equality test operators. + Equality test operator. */ bool operator ==(const wxVariant& value) const; - const bool operator ==(const wxString& value) const; - const bool operator ==(const wxChar* value) const; - const bool operator ==(wxChar value) const; - const bool operator ==(const long value) const; - const bool operator ==(const bool value) const; - const bool operator ==(const double value) const; - const bool operator ==(void* value) const; - const bool operator ==(wxObject* value) const; - const bool operator ==(const wxVariantList& value) const; - const bool operator ==(const wxArrayString& value) const; - const bool operator ==(const wxDateTime& value) const; - //@} - - //@{ - /** - Returns a reference to the value at @a idx (zero-based). This can be used - to change the value at this index. - */ - wxVariant operator [](size_t idx); - const wxVariant& operator [](size_t idx); + bool operator ==(const wxString& value) const; + bool operator ==(const wxChar* value) const; + bool operator ==(wxChar value) const; + bool operator ==(const long value) const; + bool operator ==(const bool value) const; + bool operator ==(const double value) const; + bool operator ==(void* value) const; + bool operator ==(wxObject* value) const; + bool operator ==(const wxVariantList& value) const; + bool operator ==(const wxArrayString& value) const; + bool operator ==(const wxDateTime& value) const; //@} //@{ @@ -379,11 +438,12 @@ public: Operator for implicit conversion to a long, using GetLong(). */ double operator double() const; - const long operator long() const; + long operator long() const; //@} /** - Operator for implicit conversion to a pointer to a void, using GetVoidPtr(). + Operator for implicit conversion to a pointer to a void, using + GetVoidPtr(). */ void* operator void*() const; @@ -405,33 +465,29 @@ public: }; + /** @class wxVariantData @wxheader{variant.h} - The @b wxVariantData class is used to implement a new type for wxVariant. + The wxVariantData class is used to implement a new type for wxVariant. Derive from wxVariantData, and override the pure virtual functions. wxVariantData is @ref overview_refcount "reference counted", but you don't - normally have to care about this, - as wxVariant manages the count automatically. However, in case your application - needs to take - ownership of wxVariantData, be aware that the object is created with reference - count of 1, - and passing it to wxVariant will not increase this. In other words, - wxVariantData::IncRef - needs to be called only if you both take ownership of wxVariantData and pass it - to a wxVariant. - Also note that the destructor is protected, so you can never explicitly delete - a wxVariantData - instance. Instead, wxVariantData::DecRef will delete the object automatically - when the reference count reaches zero. + normally have to care about this, as wxVariant manages the count + automatically. However, in case your application needs to take ownership of + wxVariantData, be aware that the object is created with a reference count + of 1, and passing it to wxVariant will not increase this. In other words, + IncRef() needs to be called only if you both take ownership of + wxVariantData and pass it to a wxVariant. Also note that the destructor is + protected, so you can never explicitly delete a wxVariantData instance. + Instead, DecRef() will delete the object automatically when the reference + count reaches zero. @library{wxbase} - @category{FIXME} + @category{data} - @seealso - wxVariant + @see wxVariant, wxGetVariantCast() */ class wxVariantData { @@ -442,22 +498,23 @@ public: wxVariantData(); /** - This function can be overridden to clone the data. - Implement Clone if you wish wxVariant::Unshare to work - for your data. This function is implemented for all built-in data types. + This function can be overridden to clone the data. You must implement + this function in order for wxVariant::Unshare() to work for your data. + This function is implemented for all built-in data types. */ wxVariantData* Clone() const; /** Decreases reference count. If the count reaches zero, the object is automatically deleted. - Note that destructor of wxVariantData is protected, so delete - cannot be used as normal. Instead, DecRef() should be called. + + @note The destructor of wxVariantData is protected, so delete cannot be + used as normal. Instead, DecRef() should be called. */ void DecRef(); /** - Returns @true if this object is equal to @e data. + Returns @true if this object is equal to @a data. */ bool Eq(wxVariantData& data) const; @@ -468,38 +525,54 @@ public: /** If the data is a wxObject returns a pointer to the objects wxClassInfo - structure, if - the data isn't a wxObject the method returns @NULL. + structure, if the data isn't a wxObject the method returns @NULL. */ wxClassInfo* GetValueClassInfo() const; /** - Increases reference count. Note that initially wxVariantData has reference - count of 1. + Increases reference count. Note that initially wxVariantData has + reference count of 1. */ void IncRef(); - //@{ /** - Reads the data from @a stream or @e string. + Reads the data from @a stream. */ bool Read(ostream& stream); + /** + Reads the data from @a string. + */ bool Read(wxString& string); - //@} - //@{ /** - Writes the data to @a stream or @e string. + Writes the data to @a stream. */ bool Write(ostream& stream) const; - const bool Write(wxString& string) const; - //@} - /** - This macro returns the data stored in @e variant cast to the type @e classname - * if - the data is of this type (the check is done during the run-time) or - @NULL otherwise. + Writes the data to @a string. */ - classname* wxGetVariantCast(); + bool Write(wxString& string) const; }; + + + +// ============================================================================ +// Global functions/macros +// ============================================================================ + +/** @ingroup group_funcmacro_rtti */ +//@{ + +/** + This macro returns a pointer to the data stored in @a var (wxVariant) cast + to the type @a classname if the data is of this type (the check is done + during the run-time) or @NULL otherwise. + + @header{wx/variant.h} + + @see @ref overview_rtti, wxDynamicCast() +*/ +#define wxGetVariantCast(var, classname) + +//@} +