#include <wx/variant.h>

Inheritance diagram for wxVariant:

Detailed Description

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.

Note: As of wxWidgets 2.9.1, wxAny has become the preferred variant class. While most controls still use wxVariant in their interface, you can start using wxAny in your code because of an implicit conversion layer. See below for more information.

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 GetLong() can be used.

Under Microsoft Windows, three additional wxVariantData-derived classes – wxVariantDataCurrency, wxVariantDataErrorCode and wxVariantDataSafeArray – are available for interoperation with OLE VARIANT when using wxAutomationObject.

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 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:

// in the header file
DECLARE_VARIANT_OBJECT(MyClass)
// in the implementation file
IMPLEMENT_VARIANT_OBJECT(MyClass)
// in the user code
wxVariant variant;
MyClass value;
variant << value;
// or
value << variant;

For this to work, MyClass must derive from wxObject, implement the 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:

IMPLEMENT_VARIANT_OBJECT(wxColour)
IMPLEMENT_VARIANT_OBJECT(wxImage)
IMPLEMENT_VARIANT_OBJECT(wxIcon)
IMPLEMENT_VARIANT_OBJECT(wxBitmap)

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 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.

wxVariant to wxAny Conversion Layer

wxAny is a more modern, template-based variant class. It is not directly compatible with wxVariant, but there is a transparent conversion layer.

Following is an example how to use these conversions with wxPropertyGrid's property class wxPGProperty (which currently uses wxVariants both internally and in the public API):

// Get property value as wxAny instead of wxVariant
wxAny value = property->GetValue();
// Do something with it
DoSomethingWithString(value.As<wxString>());
// Write back new value to property
value = "New Value";
property->SetValue(value);

Some caveats:

In wxAny, there are no separate types for handling integers of different sizes, so converting wxAny with 'long long' value will yield wxVariant of "long" type when the value is small enough to fit in without overflow. Otherwise, variant type "longlong" is used. Also note that wxAny holding unsigned integer will always be converted to "ulonglong" wxVariant type.

Unlike wxVariant, wxAny does not store a (rarely needed) name string.

Because of implicit conversion of wxVariant to wxAny, wxAny cannot usually contain value of type wxVariant. In other words, any.CheckType<wxVariant>() can never return true.

Supplied conversion functions will automatically work with all built-in wxVariant types, and also with all user-specified types generated using IMPLEMENT_VARIANT_OBJECT(). For hand-built wxVariantData classes, you will need to use supplied macros in a following manner:

// Declare wxVariantData for data type Foo
class wxVariantDataFoo: public wxVariantData
{
public:
    // interface
    // ...
    DECLARE_WXANY_CONVERSION()
protected:
    // data storage etc
    // ...
};
IMPLEMENT_TRIVIAL_WXANY_CONVERSION(Foo, wxVariantDataFoo)

Library: wxBase

Category: Data Structures

See Also: wxVariantData, wxAny

Public Member Functions
	wxVariant ()
	Default constructor.

	wxVariant (wxVariantData *data, const wxString &name=wxEmptyString)
	Constructs a variant directly with a wxVariantData object.

	wxVariant (const wxVariant &variant)
	Constructs a variant from another variant by increasing the reference count.

	wxVariant (const wxAny &any)
	Constructs a variant by converting it from wxAny.

	wxVariant (const wxChar *value, const wxString &name=wxEmptyString)
	Constructs a variant from a wide string literal.

	wxVariant (const wxString &value, const wxString &name=wxEmptyString)
	Constructs a variant from a string.

	wxVariant (wxChar value, const wxString &name=wxEmptyString)
	Constructs a variant from a wide char.

	wxVariant (long value, const wxString &name=wxEmptyString)
	Constructs a variant from a long.

	wxVariant (bool value, const wxString &name=wxEmptyString)
	Constructs a variant from a bool.

	wxVariant (double value, const wxString &name=wxEmptyString)
	Constructs a variant from a double.

	wxVariant (wxLongLong value, const wxString &name=wxEmptyString)
	Constructs a variant from a wxLongLong.

	wxVariant (wxULongLong value, const wxString &name=wxEmptyString)
	Constructs a variant from a wxULongLong.

	wxVariant (const wxVariantList &value, const wxString &name=wxEmptyString)
	Constructs a variant from a list of variants.

	wxVariant (void *value, const wxString &name=wxEmptyString)
	Constructs a variant from a void pointer.

	wxVariant (wxObject *value, const wxString &name=wxEmptyString)
	Constructs a variant from a pointer to an wxObject derived class.

	wxVariant (const wxDateTime &val, const wxString &name=wxEmptyString)
	Constructs a variant from a wxDateTime.

	wxVariant (const wxArrayString &val, const wxString &name=wxEmptyString)
	Constructs a variant from a wxArrayString.

virtual	~wxVariant ()
	Destructor.

wxAny	GetAny () const
	Converts wxVariant into wxAny.

wxArrayString	GetArrayString () const
	Returns the string array value.

bool	GetBool () const
	Returns the boolean value.

wxUniChar	GetChar () const
	Returns the character value.

wxVariantData *	GetData () const
	Returns a pointer to the internal variant data.

wxDateTime	GetDateTime () const
	Returns the date value.

double	GetDouble () const
	Returns the floating point value.

long	GetLong () const
	Returns the integer value.

wxLongLong	GetLongLong () const
	Returns the signed 64-bit integer value.

const wxString &	GetName () const
	Returns a constant reference to the variant name.

wxString	GetString () const
	Gets the string value.

wxString	GetType () const
	Returns the value type as a string.

wxULongLong	GetULongLong () const
	Returns the unsigned 64-bit integer value.

void *	GetVoidPtr () const
	Gets the void pointer value.

wxObject *	GetWxObjectPtr () const
	Gets the wxObject pointer value.

bool	IsNull () const
	Returns true if there is no data associated with this variant, false if there is data.

bool	IsType (const wxString &type) const
	Returns true if type matches the type of the variant, false otherwise.

bool	IsValueKindOf (const wxClassInfo *type) const
	Returns true if the data is derived from the class described by type, false otherwise.

void	MakeNull ()
	Makes the variant null by deleting the internal data.

wxString	MakeString () const
	Makes a string representation of the variant value (for any type).

bool	Member (const wxVariant &value) const
	Returns true if value matches an element in the list.

void	SetData (wxVariantData *data)
	Sets the internal variant data, deleting the existing data if there is any.

bool	Unshare ()
	Makes sure that any data associated with this variant is not shared with other variants.

void *	operator void * () const
	Operator for implicit conversion to a pointer to a void, using GetVoidPtr().

char	operator wxChar () const
	Operator for implicit conversion to a wxChar, using GetChar().

void *	operator wxDateTime () const
	Operator for implicit conversion to a pointer to a wxDateTime, using GetDateTime().

wxString	operator wxString () const
	Operator for implicit conversion to a string, using MakeString().

List Functionality
wxVariant	operator[] (size_t idx) const
	Returns the value at idx (zero-based).

wxVariant &	operator[] (size_t idx)
	Returns a reference to the value at idx (zero-based).

void	Append (const wxVariant &value)
	Appends a value to the list.

void	Clear ()
	Makes the variant null by deleting the internal data and set the name to wxEmptyString.

void	ClearList ()
	Deletes the contents of the list.

bool	Delete (size_t item)
	Deletes the zero-based item from the list.

size_t	GetCount () const
	Returns the number of elements in the list.

wxVariantList &	GetList () const
	Returns a reference to the wxVariantList class used by wxVariant if this wxVariant is currently a list of variants.

void	Insert (const wxVariant &value)
	Inserts a value at the front of the list.

void	NullList ()
	Makes an empty list.


bool	Convert (long *value) const
	Retrieves and converts the value of this variant to the type that value is.

bool	Convert (bool *value) const
	Retrieves and converts the value of this variant to the type that value is.

bool	Convert (double *value) const
	Retrieves and converts the value of this variant to the type that value is.

bool	Convert (wxString *value) const
	Retrieves and converts the value of this variant to the type that value is.

bool	Convert (wxChar *value) const
	Retrieves and converts the value of this variant to the type that value is.

bool	Convert (wxLongLong *value) const
	Retrieves and converts the value of this variant to the type that value is.

bool	Convert (wxULongLong *value) const
	Retrieves and converts the value of this variant to the type that value is.

bool	Convert (wxDateTime *value) const
	Retrieves and converts the value of this variant to the type that value is.


bool	operator!= (const wxVariant &value) const
	Inequality test operator.

bool	operator!= (const wxString &value) const
	Inequality test operator.

bool	operator!= (const wxChar *value) const
	Inequality test operator.

bool	operator!= (wxChar value) const
	Inequality test operator.

bool	operator!= (long value) const
	Inequality test operator.

bool	operator!= (bool value) const
	Inequality test operator.

bool	operator!= (double value) const
	Inequality test operator.

bool	operator!= (wxLongLong value) const
	Inequality test operator.

bool	operator!= (wxULongLong value) const
	Inequality test operator.

bool	operator!= (void *value) const
	Inequality test operator.

bool	operator!= (wxObject *value) const
	Inequality test operator.

bool	operator!= (const wxVariantList &value) const
	Inequality test operator.

bool	operator!= (const wxArrayString &value) const
	Inequality test operator.

bool	operator!= (const wxDateTime &value) const
	Inequality test operator.


void	operator= (const wxVariant &value)
	Assignment operator, using reference counting if possible.

void	operator= (wxVariantData *value)
	Assignment operator, using reference counting if possible.

void	operator= (const wxString &value)
	Assignment operator, using reference counting if possible.

void	operator= (const wxChar *value)
	Assignment operator, using reference counting if possible.

void	operator= (wxChar value)
	Assignment operator, using reference counting if possible.

void	operator= (long value)
	Assignment operator, using reference counting if possible.

void	operator= (bool value)
	Assignment operator, using reference counting if possible.

void	operator= (double value)
	Assignment operator, using reference counting if possible.

bool	operator= (wxLongLong value) const
	Assignment operator, using reference counting if possible.

bool	operator= (wxULongLong value) const
	Assignment operator, using reference counting if possible.

void	operator= (void *value)
	Assignment operator, using reference counting if possible.

void	operator= (wxObject *value)
	Assignment operator, using reference counting if possible.

void	operator= (const wxVariantList &value)
	Assignment operator, using reference counting if possible.

void	operator= (const wxDateTime &value)
	Assignment operator, using reference counting if possible.

void	operator= (const wxArrayString &value)
	Assignment operator, using reference counting if possible.


bool	operator== (const wxVariant &value) const
	Equality test operator.

bool	operator== (const wxString &value) const
	Equality test operator.

bool	operator== (const wxChar *value) const
	Equality test operator.

bool	operator== (wxChar value) const
	Equality test operator.

bool	operator== (long value) const
	Equality test operator.

bool	operator== (bool value) const
	Equality test operator.

bool	operator== (double value) const
	Equality test operator.

bool	operator== (wxLongLong value) const
	Equality test operator.

bool	operator== (wxULongLong value) const
	Equality test operator.

bool	operator== (void *value) const
	Equality test operator.

bool	operator== (wxObject *value) const
	Equality test operator.

bool	operator== (const wxVariantList &value) const
	Equality test operator.

bool	operator== (const wxArrayString &value) const
	Equality test operator.

bool	operator== (const wxDateTime &value) const
	Equality test operator.


double	operator double () const
	Operators for implicit conversion, using appropriate getter member function.

long	operator long () const
	Operators for implicit conversion, using appropriate getter member function.

wxLongLong	operator wxLongLong () const
	Operators for implicit conversion, using appropriate getter member function.

wxULongLong	operator wxULongLong () const
	Operators for implicit conversion, using appropriate getter member function.

Public Member Functions inherited from wxObject
	wxObject ()
	Default ctor; initializes to NULL the internal reference data.

	wxObject (const wxObject &other)
	Copy ctor.

virtual	~wxObject ()
	Destructor.

virtual wxClassInfo *	GetClassInfo () const
	This virtual function is redefined for every class that requires run-time type information, when using the wxDECLARE_CLASS macro (or similar).

wxObjectRefData *	GetRefData () const
	Returns the wxObject::m_refData pointer, i.e. the data referenced by this object.

bool	IsKindOf (const wxClassInfo *info) const
	Determines whether this class is a subclass of (or the same class as) the given class.

bool	IsSameAs (const wxObject &obj) const
	Returns true if this object has the same data pointer as obj.

void	Ref (const wxObject &clone)
	Makes this object refer to the data in clone.

void	SetRefData (wxObjectRefData *data)
	Sets the wxObject::m_refData pointer.

void	UnRef ()
	Decrements the reference count in the associated data, and if it is zero, deletes the data.

void	UnShare ()
	This is the same of AllocExclusive() but this method is public.

void	operator delete (void *buf)
	The delete operator is defined for debugging versions of the library only, when the identifier `WXDEBUG` is defined.

void *	operator new (size_t size, const wxString &filename=NULL, int lineNum=0)
	The new operator is defined for debugging versions of the library only, when the identifier `WXDEBUG` is defined.

Additional Inherited Members
Protected Member Functions inherited from wxObject
void	AllocExclusive ()
	Ensure that this object's data is not shared with any other object.

virtual wxObjectRefData *	CreateRefData () const
	Creates a new instance of the wxObjectRefData-derived class specific to this object and returns it.

virtual wxObjectRefData *	CloneRefData (const wxObjectRefData *data) const
	Creates a new instance of the wxObjectRefData-derived class specific to this object and initializes it copying data.

Protected Attributes inherited from wxObject
wxObjectRefData *	m_refData
	Pointer to an object which is the object's reference-counted data.

Constructor & Destructor Documentation

wxVariant::wxVariant ( )

Default constructor.

wxVariant::wxVariant	(	wxVariantData *	data,
		const wxString &	name = `wxEmptyString`
	)

Constructs a variant directly with a wxVariantData object.

wxVariant will take ownership of the wxVariantData and will not increase its reference count.

wxVariant::wxVariant ( const wxVariant & variant )

Constructs a variant from another variant by increasing the reference count.

wxVariant::wxVariant ( const wxAny & any )

Constructs a variant by converting it from wxAny.

wxVariant::wxVariant	(	const wxChar *	value,
		const wxString &	name = `wxEmptyString`
	)

Constructs a variant from a wide string literal.

wxVariant::wxVariant	(	const wxString &	value,
		const wxString &	name = `wxEmptyString`
	)

Constructs a variant from a string.

wxVariant::wxVariant	(	wxChar	value,
		const wxString &	name = `wxEmptyString`
	)

Constructs a variant from a wide char.

wxVariant::wxVariant	(	long	value,
		const wxString &	name = `wxEmptyString`
	)

Constructs a variant from a long.

wxVariant::wxVariant	(	bool	value,
		const wxString &	name = `wxEmptyString`
	)

Constructs a variant from a bool.

wxVariant::wxVariant	(	double	value,
		const wxString &	name = `wxEmptyString`
	)

Constructs a variant from a double.

wxVariant::wxVariant	(	wxLongLong	value,
		const wxString &	name = `wxEmptyString`
	)

Constructs a variant from a wxLongLong.

wxVariant::wxVariant	(	wxULongLong	value,
		const wxString &	name = `wxEmptyString`
	)

Constructs a variant from a wxULongLong.

wxVariant::wxVariant	(	const wxVariantList &	value,
		const wxString &	name = `wxEmptyString`
	)

Constructs a variant from a list of variants.

wxVariant::wxVariant	(	void *	value,
		const wxString &	name = `wxEmptyString`
	)

Constructs a variant from a void pointer.

wxVariant::wxVariant	(	wxObject *	value,
		const wxString &	name = `wxEmptyString`
	)

Constructs a variant from a pointer to an wxObject derived class.

wxVariant::wxVariant	(	const wxDateTime &	val,
		const wxString &	name = `wxEmptyString`
	)

Constructs a variant from a wxDateTime.

wxVariant::wxVariant	(	const wxArrayString &	val,
		const wxString &	name = `wxEmptyString`
	)

Constructs a variant from a wxArrayString.

virtual wxVariant::~wxVariant ( )

virtual

Destructor.

Note: wxVariantData's destructor is protected, so wxVariantData cannot usually be deleted. Instead, wxVariantData::DecRef() should be called. See reference-counted object destruction for more info.

Member Function Documentation

void wxVariant::Append ( const wxVariant & value )

Appends a value to the list.

void wxVariant::Clear ( )

Makes the variant null by deleting the internal data and set the name to wxEmptyString.

void wxVariant::ClearList ( )

Deletes the contents of the list.

bool wxVariant::Convert ( long * value ) const