git.saurik.com Git - wxWidgets.git/blame_incremental - docs/doxygen/overviews/cpprttidisabled.h

... / ...

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