docs/doxygen/overviews/runtimeclass.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        runtimeclass
   3 // Purpose:     topic overview
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /*!
  10
  11  @page runtimeclass_overview Runtime class information (aka RTTI) overview
  12
  13  Classes: #wxObject, #wxClassInfo.
  14  One of the failings of C++ used to be that no run-time information was provided
  15  about a class and its position in the inheritance hierarchy.
  16  Another, which still persists, is that instances of a class cannot be created
  17  just by knowing the name of a class, which makes facilities such as persistent
  18  storage hard to implement.
  19  Most C++ GUI frameworks overcome these limitations by means of a set of
  20  macros and functions and wxWidgets is no exception. As it originated before the
  21  addition of RTTI to the C++ standard and as support for it is still missing from
  22  some (albeit old) compilers, wxWidgets doesn't (yet) use it, but provides its
  23  own macro-based RTTI system.
  24  In the future, the standard C++ RTTI will be used though and you're encouraged
  25  to use whenever possible the #wxDynamicCast() macro which,
  26  for the implementations that support it, is defined just as dynamic_cast and
  27  uses wxWidgets RTTI for all the others. This macro is limited to wxWidgets
  28  classes only and only works with pointers (unlike the real dynamic_cast which
  29  also accepts references).
  30  Each class that you wish to be known to the type system should have
  31  a macro such as DECLARE_DYNAMIC_CLASS just inside the class declaration.
  32  The macro IMPLEMENT_DYNAMIC_CLASS should be in the implementation file.
  33  Note that these are entirely optional; use them if you wish to check object
  34  types, or create instances of classes using the class name. However,
  35  it is good to get into the habit of adding these macros for all classes.
  36  Variations on these #macros are used for multiple inheritance, and abstract
  37  classes that cannot be instantiated dynamically or otherwise.
  38  DECLARE_DYNAMIC_CLASS inserts a static wxClassInfo declaration into the
  39  class, initialized by IMPLEMENT_DYNAMIC_CLASS. When initialized, the
  40  wxClassInfo object inserts itself into a linked list (accessed through
  41  wxClassInfo::first and wxClassInfo::next pointers). The linked list
  42  is fully created by the time all global initialisation is done.
  43  IMPLEMENT_DYNAMIC_CLASS is a macro that not only initialises the static
  44  wxClassInfo member, but defines a global function capable of creating a
  45  dynamic object of the class in question. A pointer to this function is
  46  stored in wxClassInfo, and is used when an object should be created
  47  dynamically.
  48  wxObject::IsKindOf uses the linked list of
  49  wxClassInfo. It takes a wxClassInfo argument, so use CLASSINFO(className)
  50  to return an appropriate wxClassInfo pointer to use in this function.
  51  The function #wxCreateDynamicObject can be used
  52  to construct a new object of a given type, by supplying a string name.
  53  If you have a pointer to the wxClassInfo object instead, then you
  54  can simply call wxClassInfo::CreateObject.
  55  #wxClassInfo
  56  #Example
  57
  58
  59  @section wxclassinfooverview wxClassInfo
  60
  61  #Runtime class information (aka RTTI) overview
  62  Class: #wxClassInfo
  63  This class stores meta-information about classes. An application
  64  may use macros such as DECLARE_DYNAMIC_CLASS and IMPLEMENT_DYNAMIC_CLASS
  65  to record run-time information about a class, including:
  66
  67
  68   its position in the inheritance hierarchy;
  69   the base class name(s) (up to two base classes are permitted);
  70   a string representation of the class name;
  71   a function that can be called to construct an instance of this class.
  72
  73
  74  The DECLARE_... macros declare a static wxClassInfo variable in a class, which is initialized
  75  by macros of the form IMPLEMENT_... in the implementation C++ file. Classes whose instances may be
  76  constructed dynamically are given a global constructor function which returns a new object.
  77  You can get the wxClassInfo for a class by using the CLASSINFO macro, e.g. CLASSINFO(wxFrame).
  78  You can get the wxClassInfo for an object using wxObject::GetClassInfo.
  79  See also #wxObject and #wxCreateDynamicObject.
  80
  81  @section runtimeclassinformationexample Example
  82
  83  In a header file frame.h:
  84
  85  @code
  86  class wxFrame : public wxWindow
  87  {
  88  DECLARE_DYNAMIC_CLASS(wxFrame)
  89
  90  private:
  91      wxString m_title;
  92
  93  public:
  94      ...
  95  };
  96  @endcode
  97
  98  In a C++ file frame.cpp:
  99
 100  @code
 101  IMPLEMENT_DYNAMIC_CLASS(wxFrame, wxWindow)
 102
 103  wxFrame::wxFrame()
 104  {
 105  ...
 106  }
 107  @endcode
 108
 109  */
 110
 111