X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/39601a7f74796aae377ad1520595f083fdafd7b6..d7bb29260e10308862505d833e3004727fb95fa1:/interface/wx/any.h?ds=sidebyside

diff --git a/interface/wx/any.h b/interface/wx/any.h
index acbd9157a2..d8e69cbc58 100644
--- a/interface/wx/any.h
+++ b/interface/wx/any.h
@@ -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 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:
 
@@ -63,6 +63,25 @@
     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<MyClass>)
+
+                // In code using said shared library/DLL
+                wxDECLARE_ANY_TYPE(MyClass, WXIMPORT)
+             @endcode
+
     @library{wxbase}
     @category{data}
 
@@ -122,7 +141,7 @@ public:
         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;
@@ -321,6 +340,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,
@@ -394,9 +415,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;