// 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 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.
+ 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
wxAny to the type that T* value is.
- @return Returns @true if conversion was succesfull.
+ @return Returns @true if conversion was successful.
*/
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);
//@}
//@{
wxAnyValueBuffer& dst) const
{
// TODO: Copy value from one buffer to another.
+ // dst is already uninitialized and does not
+ // need to be freed.
}
virtual bool ConvertValue(const wxAnyValueBuffer& src,
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
wxAnyValueBuffer& dst) const = 0;
/**
- Implement this for buffer-to-buffer copy. src.m_ptr can
- be expected to be NULL if value type of previously stored
- data was different.
+ Implement this for buffer-to-buffer copy.
+
+ @param src
+ This is the source data buffer.
+
+ @param dst
+ This is the destination data buffer that is in either
+ uninitialized or freed state.
*/
virtual void CopyBuffer(const wxAnyValueBuffer& src,
wxAnyValueBuffer& dst) const = 0;
*/
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