X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/eb23d11e000642b1e2a455df072db4e3783077aa..92c0fc34c104c8d7c12d6a3b78ea232690fc23f4:/interface/wx/any.h diff --git a/interface/wx/any.h b/interface/wx/any.h index 2f96ade0e7..6862746c88 100644 --- a/interface/wx/any.h +++ b/interface/wx/any.h @@ -2,8 +2,7 @@ // Name: any.h // Purpose: interface of wxAny // Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license +// Licence: wxWindows licence ///////////////////////////////////////////////////////////////////////////// @@ -13,9 +12,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 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: @@ -45,23 +44,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': + 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). - @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. + @note When performing conversions between strings and floating point + numbers, the representation of numbers in C locale is always used. + I.e. @code wxAny("1.23").GetAs() @endcode will always work, + even if the current locale uses comma as decimal separator. @library{wxbase} @category{data} @@ -87,20 +76,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,7 +119,7 @@ public: @see wxAnyValueType::CheckType() */ template - bool CheckType(); + bool CheckType() const; /** Template function that retrieves and converts the value of this @@ -127,18 +130,35 @@ public: 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 +174,7 @@ public: template wxAny& operator=(const T &value); wxAny& operator=(const wxAny &any); + wxAny& operator=(const wxVariant &variant); //@} //@{ @@ -378,14 +399,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