// Name: variant.h
// Purpose: interface of wxVariant
// Author: wxWidgets team
-// RCS-ID: $Id$
-// Licence: wxWindows license
+// Licence: wxWindows licence
/////////////////////////////////////////////////////////////////////////////
/**
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
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
wxDynamicCast(), to use C++ RTTI type information instead of wxWidgets
RTTI.
+ @section variant_wxanyconversion 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):
+
+ @code
+ // 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);
+
+ @endcode
+
+ Some caveats:
+ @li 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.
+
+ @li Unlike wxVariant, wxAny does not store a (rarely needed) name string.
+
+ @li 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:
+
+ @code
+
+ // 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)
+
+ @endcode
+
@library{wxbase}
@category{data}
- @see wxVariantData
+ @see wxVariantData, wxAny
*/
class wxVariant : public wxObject
{
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 = "");
-
+ wxVariant(wxVariantData* data, const wxString& name = wxEmptyString);
+
/**
Constructs a variant from another variant by increasing the reference
count.
*/
wxVariant(const wxVariant& variant);
-
+
+ /**
+ Constructs a variant by converting it from wxAny.
+ */
+ wxVariant(const wxAny& any);
+
/**
Constructs a variant from a wide string literal.
*/
- wxVariant(const wxChar* value, const wxString& name = "");
-
+ wxVariant(const wxChar* value, const wxString& name = wxEmptyString);
+
/**
Constructs a variant from a string.
*/
- wxVariant(const wxString& value, const wxString& name = "");
-
+ wxVariant(const wxString& value, const wxString& name = wxEmptyString);
+
/**
Constructs a variant from a wide char.
*/
- wxVariant(wxChar value, const wxString& name = "");
-
+ wxVariant(wxChar value, const wxString& name = wxEmptyString);
+
/**
Constructs a variant from a long.
*/
- wxVariant(long value, const wxString& name = "");
-
+ wxVariant(long value, const wxString& name = wxEmptyString);
+
/**
Constructs a variant from a bool.
*/
- wxVariant(bool value, const wxString& name = "");
-
+ wxVariant(bool value, const wxString& name = wxEmptyString);
+
/**
Constructs a variant from a double.
*/
- wxVariant(double value, const wxString& name = "");
-
+ wxVariant(double value, const wxString& name = wxEmptyString);
+
+ /**
+ Constructs a variant from a wxLongLong.
+ */
+ wxVariant(wxLongLong value, const wxString& name = wxEmptyString);
+
+ /**
+ Constructs a variant from a wxULongLong.
+ */
+ wxVariant(wxULongLong value, const wxString& name = wxEmptyString);
+
/**
Constructs a variant from a list of variants
*/
- wxVariant(const wxVariantList& value, const wxString& name = "");
-
+ wxVariant(const wxVariantList& value, const wxString& name = wxEmptyString);
+
/**
Constructs a variant from a void pointer.
*/
- wxVariant(void* value, const wxString& name = "");
-
+ wxVariant(void* value, const wxString& name = wxEmptyString);
+
/**
Constructs a variant from a pointer to an wxObject
derived class.
*/
- wxVariant(wxObject* value, const wxString& name = "");
-
+ wxVariant(wxObject* value, const wxString& name = wxEmptyString);
+
/**
Constructs a variant from a wxDateTime.
*/
- wxVariant(wxDateTime& val, const wxString& name = "");
-
+ wxVariant(const wxDateTime& val, const wxString& name = wxEmptyString);
+
/**
Constructs a variant from a wxArrayString.
*/
- wxVariant(wxArrayString& val, const wxString& name = "");
+ wxVariant(const wxArrayString& val, const wxString& name = wxEmptyString);
/**
Destructor.
called. See @ref overview_refcount_destruct
"reference-counted object destruction" for more info.
*/
- ~wxVariant();
+ virtual ~wxVariant();
/**
bool Convert(double* value) const;
bool Convert(wxString* value) const;
bool Convert(wxChar* value) const;
+ bool Convert(wxLongLong* value) const;
+ bool Convert(wxULongLong* value) const;
bool Convert(wxDateTime* value) const;
//@}
+ /**
+ Converts wxVariant into wxAny.
+ */
+ wxAny GetAny() const;
+
/**
Returns the string array value.
*/
/**
Returns the character value.
*/
- wxChar GetChar() const;
+ wxUniChar GetChar() const;
/**
Returns a pointer to the internal variant data. To take ownership of
*/
long GetLong() const;
+ /**
+ Returns the signed 64-bit integer value.
+ */
+ wxLongLong GetLongLong() const;
+
/**
Returns a constant reference to the variant name.
*/
- const wxString GetName() const;
+ const wxString& GetName() const;
/**
Gets the string value.
- "double"
- "list"
- "long"
+ - "longlong"
- "string"
+ - "ulonglong"
- "arrstring"
- "void*"
*/
wxString GetType() const;
+ /**
+ Returns the unsigned 64-bit integer value.
+ */
+ wxULongLong GetULongLong() const;
+
/**
Gets the void pointer value.
+
+ Notice that this method can be used for null objects (i.e. those for
+ which IsNull() returns @true) and will return @NULL for them.
*/
void* GetVoidPtr() 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 !=(long value) const;
+ bool operator !=(bool value) const;
+ bool operator !=(double value) const;
+ bool operator !=(wxLongLong value) const;
+ bool operator !=(wxULongLong value) const;
bool operator !=(void* value) const;
bool operator !=(wxObject* value) const;
bool operator !=(const wxVariantList& value) const;
void operator =(const wxString& value);
void operator =(const wxChar* value);
void operator =(wxChar value);
- void operator =(const long value);
- void operator =(const bool value);
- void operator =(const double value);
+ void operator =(long value);
+ void operator =(bool value);
+ void operator =(double value);
+ bool operator =(wxLongLong value) const;
+ bool operator =(wxULongLong value) const;
void operator =(void* value);
void operator =(wxObject* value);
void operator =(const wxVariantList& value);
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 ==(long value) const;
+ bool operator ==(bool value) const;
+ bool operator ==(double value) const;
+ bool operator ==(wxLongLong value) const;
+ bool operator ==(wxULongLong value) const;
bool operator ==(void* value) const;
bool operator ==(wxObject* value) const;
bool operator ==(const wxVariantList& value) const;
//@{
/**
- Operator for implicit conversion to a long, using GetLong().
+ Operators for implicit conversion, using appropriate getter member
+ function.
*/
double operator double() const;
long operator long() const;
+ wxLongLong operator wxLongLong() const;
+ wxULongLong operator wxULongLong() const;
//@}
/**
@see wxVariant, wxGetVariantCast()
*/
-class wxVariantData
+class wxVariantData : public wxObjectRefData
{
public:
/**
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;
+ virtual wxVariantData* Clone() const;
/**
Decreases reference count. If the count reaches zero, the object is
/**
Returns @true if this object is equal to @a data.
*/
- bool Eq(wxVariantData& data) const;
+ virtual bool Eq(wxVariantData& data) const = 0;
+
+ /**
+ Converts value to wxAny, if possible. Return @true if successful.
+ */
+ virtual bool GetAny(wxAny* any) const;
/**
Returns the string type of the data.
*/
- wxString GetType() const;
+ virtual wxString GetType() const = 0;
/**
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.
*/
- wxClassInfo* GetValueClassInfo() const;
+ virtual wxClassInfo* GetValueClassInfo();
/**
Increases reference count. Note that initially wxVariantData has
/**
Reads the data from @a stream.
*/
- bool Read(ostream& stream);
+ virtual bool Read(istream& stream);
+
/**
Reads the data from @a string.
*/
- bool Read(wxString& string);
+ virtual bool Read(wxString& string);
/**
Writes the data to @a stream.
*/
- bool Write(ostream& stream) const;
+ virtual bool Write(ostream& stream) const;
/**
Writes the data to @a string.
*/
- bool Write(wxString& string) const;
+ virtual bool Write(wxString& string) const;
};
// Global functions/macros
// ============================================================================
-/** @ingroup group_funcmacro_rtti */
+/** @addtogroup group_funcmacro_rtti */
//@{
/**
projects / wxWidgets.git / blobdiff