X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/39601a7f74796aae377ad1520595f083fdafd7b6..7344108e8a129a3f9b4df5ab0f98a1713db03b89:/interface/wx/any.h diff --git a/interface/wx/any.h b/interface/wx/any.h index acbd9157a2..de177e1430 100644 --- a/interface/wx/any.h +++ b/interface/wx/any.h @@ -3,7 +3,7 @@ // Purpose: interface of wxAny // Author: wxWidgets team // RCS-ID: $Id$ -// Licence: wxWindows license +// Licence: wxWindows licence ///////////////////////////////////////////////////////////////////////////// @@ -13,9 +13,9 @@ 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: @@ -45,28 +45,13 @@ 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 { @@ -87,20 +72,34 @@ public: */ 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 T As() const; @@ -116,29 +115,46 @@ public: @see wxAnyValueType::CheckType() */ template - 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 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() 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; @@ -154,6 +170,7 @@ public: template wxAny& operator=(const T &value); wxAny& operator=(const wxAny &any); + wxAny& operator=(const wxVariant &variant); //@} //@{ @@ -321,6 +338,8 @@ union wxAnyValueBuffer 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, @@ -376,14 +395,14 @@ public: 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 - bool CheckType(); + bool CheckType() const; /** Convert value into buffer of different type. Return false if @@ -394,9 +413,14 @@ public: 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; @@ -407,11 +431,6 @@ public: */ 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. */