X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/c5fe6a5bee092251f08fa204c8857c36af865157..92c0fc34c104c8d7c12d6a3b78ea232690fc23f4:/interface/wx/any.h diff --git a/interface/wx/any.h b/interface/wx/any.h index d8e69cbc58..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,47 +44,18 @@ 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. - - @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) - - // In code using said shared library/DLL - wxDECLARE_ANY_TYPE(MyClass, WXIMPORT) - @endcode + @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} - @see wxAnyValueType, wxVariant + @see wxAnyValueType, wxVariant, @ref overview_cpp_rtti_disabled */ class wxAny { @@ -106,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; @@ -135,7 +119,7 @@ public: @see wxAnyValueType::CheckType() */ template - bool CheckType(); + bool CheckType() const; /** Template function that retrieves and converts the value of this @@ -146,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; @@ -173,6 +174,7 @@ public: template wxAny& operator=(const T &value); wxAny& operator=(const wxAny &any); + wxAny& operator=(const wxVariant &variant); //@} //@{ @@ -397,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 @@ -433,11 +435,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. */