synchronize GTK2 minimum version in docs

[wxWidgets.git] / interface / wx / any.h

diff --git a/interface/wx/any.h b/interface/wx/any.h
index acbd9157a2adf983923f171ef0b036b3d8944762..de177e1430e2d23bde4d13368972eeb888db94b7 100644 (file)
--- a/interface/wx/any.h
+++ b/interface/wx/any.h
@@ -3,7 +3,7 @@
 // Purpose:     interface of wxAny
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // 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.
 
     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:
 
 
     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
 
     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}
 
 
     @library{wxbase}
     @category{data}
 

-    @see wxAnyValueType, wxVariant
+    @see wxAnyValueType, wxVariant, @ref overview_cpp_rtti_disabled

 */
 class wxAny
 {
 */
 class wxAny
 {


@@ -87,20 +72,34 @@ public:
     */
     wxAny(const wxAny& any);
 
     */
     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();
 
     /**
     /**
         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;
     */
     template<typename T>
     T As() const;


@@ -116,29 +115,46 @@ public:
         @see wxAnyValueType::CheckType()
     */
     template<typename T>
         @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.
 
 
     /**
         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;
 
     */
     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
     /**
         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;
 
     /**
     */
     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;
 
     */
     bool IsNull() const;
 


@@ -154,6 +170,7 @@ public:
     template<typename T>
     wxAny& operator=(const T &value);
     wxAny& operator=(const wxAny &any);
     template<typename T>
     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.
                                     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,
             }
 
             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
         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>
                 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
 
     /**
         Convert value into buffer of different type. Return false if


@@ -394,9 +413,14 @@ public:
                               wxAnyValueBuffer& dst) const = 0;
 
     /**
                               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 CopyBuffer(const wxAnyValueBuffer& src,
                             wxAnyValueBuffer& dst) const = 0;


@@ -407,11 +431,6 @@ public:
     */
     virtual void DeleteValue(wxAnyValueBuffer& buf) 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.
     */
     /**
         This function is used for internal type matching.
     */