// Purpose: interface of wxAny
// Author: wxWidgets team
// RCS-ID: $Id$
-// Licence: wxWindows license
+// Licence: wxWindows licence
/////////////////////////////////////////////////////////////////////////////
The wxAny class represents a container for any type. Its value
can be changed at run time, possibly to a different type of value.
- wxAny is a backwards incompatible successor class for wxVariant,
- essentially doing the same thing in a more modern, template-based manner
- and with transparent support for any user data type.
+ wxAny is a backwards-incompatible (but convertible) successor class for
+ wxVariant, essentially doing the same thing in a more modern, template-
+ based manner and with transparent support for any user data type.
Some pseudo-code'ish example of use with arbitrary user data:
When compared to wxVariant, there are various internal implementation
differences as well. For instance, wxAny only allocates separate data
- object in heap for large (ie. size in bytes more than
- WX_ANY_VALUE_BUFFER_SIZE) or 'non-movable' data types. Pointers, integers,
- bools etc. are fitted in the wxAny's own buffer without need for any extra
- allocation. Use following code to declare your own data type as 'movable':
-
- @code
- #include "wx/meta/movable.h"
- WX_DECLARE_TYPE_MOVABLE(MyClass)
- @endcode
-
- However, you must be aware that 'movable' means such data that can be
- copied with memcpy() without corrupting program integrity. For instance,
- movable objects usually cannot contain pointers or references to other
- data. wxRect, wxPoint, and wxSize are good examples of movable classes.
-
- Note that pointers to any and all classes are already automatically
- declared as movable data.
-
- @warning Caveat with shared libraries (DLLs): If you have a scenario where
- you use wxAny across application's shared library and application
- itself (or, with another of your shared libraries), then you must
- use wxDECLARE_ANY_TYPE() macro in your shared library code to
- correctly make sure that the wxAnyValueType implementation is
- generated correctly. Failure to do this will result in breakage
- of the wxAny type recognition with type in question. Below is an
- example how to use the macro.
- @code
- // In your shared library/DLL-only
- wxDECLARE_ANY_TYPE(MyClass, WXEXPORT)
-
- // In your shared library/DLL source code
- WX_IMPLEMENT_ANY_VALUE_TYPE(wxAnyValueTypeImpl<MyClass>)
-
- // In code using said shared library/DLL
- wxDECLARE_ANY_TYPE(MyClass, WXIMPORT)
- @endcode
+ object in heap for large objects (i.e. ones with size more than
+ WX_ANY_VALUE_BUFFER_SIZE, which at the time of writing is 16 bytes).
@library{wxbase}
@category{data}
- @see wxAnyValueType, wxVariant
+ @see wxAnyValueType, wxVariant, @ref overview_cpp_rtti_disabled
*/
class wxAny
{
*/
wxAny(const wxAny& any);
+ /**
+ Constructs wxAny, converting value from wxVariant.
+
+ @remarks Because of this conversion, it is not usually possible to
+ have wxAny that actually holds a wxVariant. If wxVariant
+ cannot be converted to a specific data type, wxAny will then
+ hold and manage reference to wxVariantData* similar to how
+ wxVariant does.
+ */
+ wxAny(const wxVariant& variant);
+
/**
Destructor.
*/
~wxAny();
/**
- This template function converts wxAny into given type. No dynamic
- conversion is performed, so if the type is incorrect an assertion
- failure will occur in debug builds, and a bogus value is returned
- in release ones.
+ This template function converts wxAny into given type. In most cases
+ no type conversion is performed, so if the type is incorrect an
+ assertion failure will occur.
- @remarks This template function may not work properly with Visual C++
- 6. For full compiler compatibility, please use
- wxANY_AS(any, T) macro instead.
+ @remarks For conveniency, conversion is done when T is wxString. This
+ is useful when a string literal (which are treated as
+ const char* and const wchar_t*) has been assigned to wxAny.
+
+ This template function may not work properly with Visual C++
+ 6. For full compiler compatibility, please use
+ wxANY_AS(any, T) macro instead.
*/
template<typename T>
T As() const;
@see wxAnyValueType::CheckType()
*/
template<typename T>
- bool CheckType();
+ bool CheckType() const;
/**
Template function that retrieves and converts the value of this
template<typename T>
bool GetAs(T* value) const;
+ /**
+ Specialization of GetAs() that allows conversion of wxAny into
+ wxVariant.
+
+ @return Returns @true if conversion was successful. Conversion usually
+ only fails if variant used custom wxVariantData that did not
+ implement the wxAny to wxVariant conversion functions.
+ */
+ bool GetAs(wxVariant* value) const;
+
/**
Returns the value type as wxAnyValueType instance.
@remarks You cannot reliably test whether two wxAnys are of
- same value type by simply comparing return values
- of wxAny::GetType(). Instead use
- wxAnyValueType::CheckType<T>() template function.
+ same value type by simply comparing return values
+ of wxAny::GetType(). Instead, use wxAny::HasSameType().
+
+ @see HasSameType()
*/
const wxAnyValueType* GetType() const;
/**
- Tests if wxAny is null (that is, whether there is data).
+ Returns @true if this and another wxAny have the same
+ value type.
+ */
+ bool HasSameType(const wxAny& other) const;
+
+ /**
+ Tests if wxAny is null (that is, whether there is no data).
*/
bool IsNull() const;
template<typename T>
wxAny& operator=(const T &value);
wxAny& operator=(const wxAny &any);
+ wxAny& operator=(const wxVariant &variant);
//@}
//@{
a specific C++ data type.
@remarks This template function does not work on some older compilers
- (such as Visual C++ 6.0). For full compiler ccompatibility
+ (such as Visual C++ 6.0). For full compiler compatibility
please use wxANY_VALUE_TYPE_CHECK_TYPE(valueTypePtr, T) macro
instead.
@see wxAny::CheckType()
*/
template <typename T>
- bool CheckType();
+ bool CheckType() const;
/**
Convert value into buffer of different type. Return false if
*/
virtual void DeleteValue(wxAnyValueBuffer& buf) const = 0;
- /**
- This function is used for internal type matching.
- */
- virtual wxAnyClassInfo GetClassInfo() const = 0;
-
/**
This function is used for internal type matching.
*/
projects / wxWidgets.git / blobdiff