From eb23d11e000642b1e2a455df072db4e3783077aa Mon Sep 17 00:00:00 2001 From: Jaakko Salli 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 + + +
+ + +@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) +@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 @@ -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 @@ -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 @@ -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 -- 2.45.2