From eb23d11e000642b1e2a455df072db4e3783077aa Mon Sep 17 00:00:00 2001
From: Jaakko Salli <jaakko.salli@dnainternet.net>
Date: Sat, 21 Nov 2009 11:39:32 +0000
Subject: [PATCH] Added a new documentation overview section 'Caveats When Not
Using C++ RTTI', describing possible problems with Bind() and wxAny when C++
RTTI is disabled.
git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@62694 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
---
docs/doxygen/mainpages/topics.h | 1 +
docs/doxygen/overviews/cpprttidisabled.h | 95 ++++++++++++++++++++++++
docs/doxygen/overviews/eventhandling.h | 2 +
interface/wx/any.h | 2 +-
interface/wx/event.h | 8 ++
5 files changed, 107 insertions(+), 1 deletion(-)
create mode 100644 docs/doxygen/overviews/cpprttidisabled.h
diff --git a/docs/doxygen/mainpages/topics.h b/docs/doxygen/mainpages/topics.h
index 5eb2ecc24a..82706b3810 100644
--- 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
index 0000000000..e6435cbaf6
--- /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 05ad03f49a..0c78592351 100644
--- 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 eee17db785..2f96ade0e7 100644
--- 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 769d289c0d..baa35fc9c3 100644
--- 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>
--
2.47.2