added initial version of the Doxygen manual

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

docs/doxygen/overviews/runtimeclass.h

@@ -0,0 +1,111 @@
+/////////////////////////////////////////////////////////////////////////////
+// Name:        runtimeclass
+// Purpose:     topic overview
+// Author:      wxWidgets team
+// RCS-ID:      $Id$
+// Licence:     wxWindows license
+/////////////////////////////////////////////////////////////////////////////
+
+/*!
+ 
+ @page runtimeclass_overview Runtime class information (aka RTTI) overview
+ 
+ Classes: #wxObject, #wxClassInfo.
+ One of the failings of C++ used to be that no run-time information was provided
+ about a class and its position in the inheritance hierarchy.
+ Another, which still persists, is that instances of a class cannot be created
+ just by knowing the name of a class, which makes facilities such as persistent
+ storage hard to implement.
+ Most C++ GUI frameworks overcome these limitations by means of a set of
+ macros and functions and wxWidgets is no exception. As it originated before the
+ addition of RTTI to the C++ standard and as support for it is still missing from
+ some (albeit old) compilers, wxWidgets doesn't (yet) use it, but provides its
+ own macro-based RTTI system.
+ In the future, the standard C++ RTTI will be used though and you're encouraged
+ to use whenever possible the #wxDynamicCast() macro which,
+ for the implementations that support it, is defined just as dynamic_cast and
+ uses wxWidgets RTTI for all the others. This macro is limited to wxWidgets
+ classes only and only works with pointers (unlike the real dynamic_cast which
+ also accepts references).
+ Each class that you wish to be known to the type system should have
+ a macro such as DECLARE_DYNAMIC_CLASS just inside the class declaration.
+ The macro IMPLEMENT_DYNAMIC_CLASS should be in the implementation file.
+ Note that these are entirely optional; use them if you wish to check object
+ types, or create instances of classes using the class name. However,
+ it is good to get into the habit of adding these macros for all classes.
+ Variations on these #macros are used for multiple inheritance, and abstract
+ classes that cannot be instantiated dynamically or otherwise.
+ DECLARE_DYNAMIC_CLASS inserts a static wxClassInfo declaration into the
+ class, initialized by IMPLEMENT_DYNAMIC_CLASS. When initialized, the
+ wxClassInfo object inserts itself into a linked list (accessed through
+ wxClassInfo::first and wxClassInfo::next pointers). The linked list
+ is fully created by the time all global initialisation is done.
+ IMPLEMENT_DYNAMIC_CLASS is a macro that not only initialises the static
+ wxClassInfo member, but defines a global function capable of creating a
+ dynamic object of the class in question. A pointer to this function is
+ stored in wxClassInfo, and is used when an object should be created
+ dynamically.
+ wxObject::IsKindOf uses the linked list of
+ wxClassInfo. It takes a wxClassInfo argument, so use CLASSINFO(className)
+ to return an appropriate wxClassInfo pointer to use in this function.
+ The function #wxCreateDynamicObject can be used
+ to construct a new object of a given type, by supplying a string name.
+ If you have a pointer to the wxClassInfo object instead, then you
+ can simply call wxClassInfo::CreateObject.
+ #wxClassInfo
+ #Example
+ 
+ 
+ @section wxclassinfooverview wxClassInfo
+ 
+ #Runtime class information (aka RTTI) overview
+ Class: #wxClassInfo
+ This class stores meta-information about classes. An application
+ may use macros such as DECLARE_DYNAMIC_CLASS and IMPLEMENT_DYNAMIC_CLASS
+ to record run-time information about a class, including:
+ 
+ 
+  its position in the inheritance hierarchy;
+  the base class name(s) (up to two base classes are permitted);
+  a string representation of the class name;
+  a function that can be called to construct an instance of this class.
+ 
+ 
+ The DECLARE_... macros declare a static wxClassInfo variable in a class, which is initialized
+ by macros of the form IMPLEMENT_... in the implementation C++ file. Classes whose instances may be
+ constructed dynamically are given a global constructor function which returns a new object.
+ You can get the wxClassInfo for a class by using the CLASSINFO macro, e.g. CLASSINFO(wxFrame).
+ You can get the wxClassInfo for an object using wxObject::GetClassInfo.
+ See also #wxObject and #wxCreateDynamicObject.
+ 
+ @section runtimeclassinformationexample Example
+ 
+ In a header file frame.h:
+ 
+ @code
+ class wxFrame : public wxWindow
+ {
+ DECLARE_DYNAMIC_CLASS(wxFrame)
+ 
+ private:
+     wxString m_title;
+ 
+ public:
+     ...
+ };
+ @endcode
+ 
+ In a C++ file frame.cpp:
+ 
+ @code
+ IMPLEMENT_DYNAMIC_CLASS(wxFrame, wxWindow)
+ 
+ wxFrame::wxFrame()
+ {
+ ...
+ }
+ @endcode
+ 
+ */
+ 
+