@class wxVariant
@wxheader{variant.h}
- The @b wxVariant class represents a container for any type. A variant's 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 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.
+ 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 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.
+ 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:
+ 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
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)
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}
wxVariant();
/**
- Constructs a variant directly with a wxVariantData
- object. wxVariant will take ownership of the wxVariantData
- and will not increase its reference count.
+ 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.
+ Constructs a variant from another variant by increasing the reference
+ count.
*/
wxVariant(const wxVariant& variant);
/**
Constructs a variant from a list of variants
*/
- wxVariant(const wxVariantList& value,
- const wxString& name = "");
+ wxVariant(const wxVariantList& value, const wxString& name = "");
/**
Constructs a variant from a void pointer.
/**
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
+ @name List Functionality
*/
//@{
+
/**
Returns the value at @a idx (zero-based).
*/
- wxVariant operator [](size_t idx);
+ 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.
+ Returns a reference to the value at @a idx (zero-based). This can be
+ used to change the value at this index.
*/
- const wxVariant& operator [](size_t idx);
+ 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 wxEmptyString.
+ */
+ void Clear();
+
/**
Deletes the contents of the list.
*/
void ClearList();
+
/**
Deletes the zero-based @a item from the list.
*/
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.
+ Returns a reference to the wxVariantList class used by wxVariant if
+ this wxVariant is currently a list of variants.
*/
wxVariantList& GetList() const;
- /**
- Makes the variant null by deleting the internal data and
- set the name to @e wxEmptyString.
- */
- void Clear();
+
/**
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.
+ 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();
+
//@}
+
//@{
/**
- Retrieves and converts the value of this variant to the type that @a value is.
+ Retrieves and converts the value of this variant to the type that
+ @a value is.
*/
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 Convert(bool* value) const;
+ bool Convert(double* value) const;
+ bool Convert(wxString* value) const;
+ bool Convert(wxChar* value) const;
+ bool Convert(wxDateTime* value) const;
//@}
/**
wxChar GetChar() 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;
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;
wxObject* GetWxObjectPtr() const;
/**
- 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.
bool Member(const wxVariant& value) const;
/**
- 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);
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;
+ 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;
//@}
//@{
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;
@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}
- @see wxVariant
+ @see wxVariant, wxGetVariantCast()
*/
class wxVariantData
{
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;
/**
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)
+
+//@}
+
projects / wxWidgets.git / commitdiff
