Detailed Description

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.

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:

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:

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

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.

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: