docs/doxygen/overviews/cpprttidisabled.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        cpprttidisabled.h
   3 // Purpose:     topic overview
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows licence
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10
  11 @page overview_cpp_rtti_disabled Caveats When Not Using C++ RTTI
  12
  13 @li @ref overview_cpp_rtti_disabled_intro
  14 @li @ref overview_cpp_rtti_disabled_bind
  15 @li @ref overview_cpp_rtti_disabled_wxany
  16
  17 @see
  18
  19 @li @ref overview_rtti
  20 @li wxEvtHandler::Bind()
  21 @li wxAny
  22
  23
  24 <hr>
  25
  26
  27 @section overview_cpp_rtti_disabled_intro Introduction
  28
  29 @note C++ RTTI is usually enabled by default in most wxWidgets builds. If you
  30       do not know if your build has C++ RTTI enabled or not, then it probably
  31       is enabled, and you should not worry about anything mentioned in this
  32       section.
  33
  34 While in general wxWidgets standard @ref overview_rtti is used throughout the
  35 library, there are some places where it won't work. One of those places
  36 is template classes.
  37
  38 When available, C++ RTTI is used to address this issue. If you have built the
  39 library with C++ RTTI disabled, an internal RTTI system is substituted.
  40 However, this system is not perfect and one proven scenario where it may break
  41 is a shared library or DLL build. More specifically, a template class instance
  42 created in one physical binary may not be recognized as its correct type when
  43 used in another one.
  44
  45
  46 @section overview_cpp_rtti_disabled_bind Bind() Issues
  47
  48 wxWidgets 2.9.0 introduced a new @ref overview_events_bind system, using
  49 wxEvtHandler::Bind<>() and Unbind<>(). This functionality uses templates
  50 behind the scenes and therefore is vulnerable to breakage in shared library
  51 builds, as described above.
  52
  53 Currently only Unbind<>() needs the type information, so you should be immune
  54 to this problem simply if you only need to use Bind<>() and not Unbind<>().
  55
  56 Also, if you only bind and unbind same event handler inside same binary, you
  57 should be fine.
  58
  59
  60 @section overview_cpp_rtti_disabled_wxany wxAny Issues
  61
  62 wxAny is a dynamic type class which transparently uses templates to generate
  63 data type handlers, and therefore is vulnerable to breakage in shared library
  64 builds, as described above
  65
  66 You should be fine if you only create and use wxAny instances inside same
  67 physical binary. However, if you do need to be able to use wxAny freely
  68 across binary boundaries, (and for sake of code-safety, you probably do),
  69 then specializations for wxAnyValueTypeImpl<> templates need to be defined in
  70 one of your shared library (DLL) files. One specialization is required for
  71 every data type you use with wxAny. Easiest way to do this is using macros
  72 provided in wx/any.h. Note that you @b do @b not need to define
  73 specializations for C built-in types, nor for wxString or wxDateTime, because
  74 these are already provided in wxBase. However, you @b do need to define
  75 specializations for all pointer types except char* and wchar_t*.
  76
  77 Let's define a specialization for imaginary type 'MyClass'. In your shared
  78 library source code you will need to have this line:
  79
  80 @code
  81     WX_IMPLEMENT_ANY_VALUE_TYPE(wxAnyValueTypeImpl<MyClass>)
  82 @endcode
  83
  84 In your header file you will need the following:
  85
  86 @code
  87     wxDECLARE_ANY_TYPE(MyClass, WXIMPORT_OR_WXEXPORT)
  88 @endcode
  89
  90 Where WXIMPORT_OR_WXEXPORT is WXEXPORT when being included from the shared
  91 library that called the WX_IMPLEMENT_ANY_VALUE_TYPE() macro, and WXIMPORT
  92 otherwise.
  93
  94 */
  95