Added a new documentation overview section 'Caveats When Not Using C++ RTTI', describ...

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@62694 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

diff --git a/docs/doxygen/mainpages/topics.h b/docs/doxygen/mainpages/topics.h
index 5eb2ecc24ab4ade9a99c435e80eaf87f4c7a87f8..82706b3810b2651aa4ea02180bdc1bc04bdc436a 100644 (file)
--- a/docs/doxygen/mainpages/topics.h
+++ b/docs/doxygen/mainpages/topics.h
@@ -100,6 +100,7 @@ The following is a basic categorization of them:
 @li @subpage overview_backwardcompat
 @li @subpage overview_exceptions
 @li @subpage overview_rtti
+@li @subpage overview_cpp_rtti_disabled
 @li @subpage overview_refcount
 @li @subpage overview_mbconv
 @li @subpage overview_nonenglish

diff --git a/docs/doxygen/overviews/cpprttidisabled.h b/docs/doxygen/overviews/cpprttidisabled.h
new file mode 100644 (file)
index 0000000..e6435cb
--- /dev/null
+++ b/docs/doxygen/overviews/cpprttidisabled.h
@@ -0,0 +1,95 @@
+/////////////////////////////////////////////////////////////////////////////
+// Name:        cpprttidisabled.h
+// Purpose:     topic overview
+// Author:      wxWidgets team
+// RCS-ID:      $Id$
+// Licence:     wxWindows license
+/////////////////////////////////////////////////////////////////////////////
+
+/**
+
+@page overview_cpp_rtti_disabled Caveats When Not Using C++ RTTI
+
+@li @ref overview_cpp_rtti_disabled_intro
+@li @ref overview_cpp_rtti_disabled_bind
+@li @ref overview_cpp_rtti_disabled_wxany
+
+@see
+
+@li @ref overview_rtti
+@li wxEvtHandler::Bind()
+@li wxAny
+
+
+<hr>
+
+
+@section overview_cpp_rtti_disabled_intro Introduction
+
+@note C++ RTTI is usually enabled by default in most wxWidgets builds. If you
+      do not know if your build has C++ RTTI enabled or not, then it probably
+      is enabled, and you should not worry about anything mentioned in this
+      section.
+
+While in general wxWidgets standard @ref overview_rtti is used throughout the
+library, there are some places where it won't work. One of those places
+is template classes.
+
+When available, C++ RTTI is used to address this issue. If you have built the
+library with C++ RTTI disabled, an internal RTTI system is substituted.
+However, this system is not perfect and one proven scenario where it may break
+is a shared library or DLL build. More specifically, a template class instance
+created in one physical binary may not be recognized as its correct type when
+used in another one.
+
+
+@section overview_cpp_rtti_disabled_bind Bind() Issues
+
+wxWidgets 2.9.0 introduced a new @ref overview_events_bind system, using
+wxEvtHandler::Bind<>() and Unbind<>(). This functionality uses templates
+behind the scenes and therefore is vulnerable to breakage in shared library
+builds, as described above.
+
+Currently only Unbind<>() needs the type information, so you should be immune
+to this problem simply if you only need to use Bind<>() and not Unbind<>().
+
+Also, if you only bind and unbind same event handler inside same binary, you
+should be fine.
+
+
+@section overview_cpp_rtti_disabled_wxany wxAny Issues
+
+wxAny is a dynamic type class which transparently uses templates to generate
+data type handlers, and therefore is vulnerable to breakage in shared library
+builds, as described above
+
+You should be fine if you only create and use wxAny instances inside same
+physical binary. However, if you do need to be able to use wxAny freely
+across binary boundaries, (and for sake of code-safety, you probably do),
+then specializations for wxAnyValueTypeImpl<> templates need to be defined in
+one of your shared library (DLL) files. One specialization is required for
+every data type you use with wxAny. Easiest way to do this is using macros
+provided in wx/any.h. Note that you @b do @b not need to define
+specializations for C built-in types, nor for wxString or wxDateTime, because
+these are already provided in wxBase. However, you @b do need to define
+specializations for all pointer types except char* and wchar_t*.
+
+Let's define a specialization for imaginary type 'MyClass'. In your shared
+library source code you will need to have this line:
+
+@code
+    WX_IMPLEMENT_ANY_VALUE_TYPE(wxAnyValueTypeImpl<MyClass>)
+@endcode
+
+In your header file you will need the following:
+
+@code
+    wxDECLARE_ANY_TYPE(MyClass, WXIMPORT_OR_WXEXPORT)
+@endcode
+
+Where WXIMPORT_OR_WXEXPORT is WXEXPORT when being included from the shared
+library that called the WX_IMPLEMENT_ANY_VALUE_TYPE() macro, and WXIMPORT
+otherwise.
+
+*/
+

diff --git a/docs/doxygen/overviews/eventhandling.h b/docs/doxygen/overviews/eventhandling.h
index 05ad03f49ad1a75de4714f4db07359eae8831459..0c78592351b11095dbd582222efe4a93b3769c26 100644 (file)
--- a/docs/doxygen/overviews/eventhandling.h
+++ b/docs/doxygen/overviews/eventhandling.h
@@ -221,6 +221,8 @@ events.
 
 @subsection overview_events_bind Dynamic Event Handling
 
+@see @ref overview_cpp_rtti_disabled
+
 The possibilities of handling events in this way are rather different.
 Let us start by looking at the syntax: the first obvious difference is that you
 need not use DECLARE_EVENT_TABLE() nor BEGIN_EVENT_TABLE() and the

diff --git a/interface/wx/any.h b/interface/wx/any.h
index eee17db785b14d21f3490b744bce29d001f56d49..2f96ade0e7ffb44a7647b8c71d1aa9a006487c97 100644 (file)
--- a/interface/wx/any.h
+++ b/interface/wx/any.h
@@ -66,7 +66,7 @@
     @library{wxbase}
     @category{data}
 
-    @see wxAnyValueType, wxVariant
+    @see wxAnyValueType, wxVariant, @ref overview_cpp_rtti_disabled
 */
 class wxAny
 {

diff --git a/interface/wx/event.h b/interface/wx/event.h
index 769d289c0d0607588a7d745e848ba00c5932f2ef..baa35fc9c3667229c3c7950bb2c0cd4fa1fe8ea6 100644 (file)
--- a/interface/wx/event.h
+++ b/interface/wx/event.h
@@ -790,6 +790,8 @@ public:
         @param userData
             Data to be associated with the event table entry.
 
+        @see @ref overview_cpp_rtti_disabled
+
         @since 2.9.0
     */
     template <typename EventTag, typename Functor>
@@ -823,6 +825,8 @@ public:
         @param userData
             Data to be associated with the event table entry.
 
+        @see @ref overview_cpp_rtti_disabled
+
         @since 2.9.0
     */
     template <typename EventTag, typename Class, typename EventArg, typename EventHandler>
@@ -855,6 +859,8 @@ public:
         @param userData
             Data associated with the event table entry.
 
+        @see @ref overview_cpp_rtti_disabled
+
         @since 2.9.0
     */
     template <typename EventTag, typename Functor>
@@ -885,6 +891,8 @@ public:
         @param userData
             Data associated with the event table entry.
 
+        @see @ref overview_cpp_rtti_disabled
+
         @since 2.9.0
     */
     template <typename EventTag, typename Class, typename EventArg, typename EventHandler>