mention that Wait() relocks the mutex before returning (patch 1482390)

[wxWidgets.git] / docs / latex / wx / truntime.tex

diff --git a/docs/latex/wx/truntime.tex b/docs/latex/wx/truntime.tex
index 2d1da9c0217ddd3f4c8c3ecb01c89473e49a231d..04ee1e02a7a5ed06bcbf99d2c6608b5c3e89a6eb 100644 (file)
--- a/docs/latex/wx/truntime.tex
+++ b/docs/latex/wx/truntime.tex
@@ -1,19 +1,34 @@
-\section{Run time class information overview}\label{runtimeclassoverview}
+\section{Runtime class information (aka RTTI) overview}\label{runtimeclassoverview}
 
 Classes: \helpref{wxObject}{wxobject}, \helpref{wxClassInfo}{wxclassinfo}.
 
-One of the failings of C++ is that no run-time information is provided
+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 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.
+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 wxWindows (from version 1.62) is no exception.
-Each class that you wish to be known the type system should have
+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 \helpref{wxDynamicCast()}{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 \helpref{macros}{macros} are used for multiple inheritance, and abstract
+Variations on these \helpref{macros}{rttimacros} 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
@@ -28,18 +43,18 @@ 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.
+\helpref{wxObject::IsKindOf}{wxobjectiskindof} 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 \helpref{wxCreateDynamicObject}{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.
+can simply call \helpref{wxClassInfo::CreateObject}{wxclassinfocreateobject}.
 
 \subsection{wxClassInfo}\label{wxclassinfooverview}
 
-\overview{Run time class information overview}{runtimeclassoverview}
+\overview{Runtime class information (aka RTTI) overview}{runtimeclassoverview}
 
 Class: \helpref{wxClassInfo}{wxclassinfo}
 
@@ -63,28 +78,29 @@ You can get the wxClassInfo for an object using wxObject::GetClassInfo.
 
 See also \helpref{wxObject}{wxobject} and \helpref{wxCreateDynamicObject}{wxcreatedynamicobject}.
 
-\subsection{Example}
+\subsection{Example}\label{runtimeclassinformationexample}
 
-In a header file wx\_frame.h:
+In a header file frame.h:
 
 \begin{verbatim}
-class wxFrame: public wxWindow
+class wxFrame : public wxWindow
 {
-  DECLARE_DYNAMIC_CLASS(wxFrame)
+DECLARE_DYNAMIC_CLASS(wxFrame)
 
- private:
-  char *frameTitle;
- public:
-  ...
+private:
+    wxString m_title;
+
+public:
+    ...
 };
 \end{verbatim}
 
-In a C++ file wx\_frame.cc:
+In a C++ file frame.cpp:
 
 \begin{verbatim}
 IMPLEMENT_DYNAMIC_CLASS(wxFrame, wxWindow)
 
-wxFrame::wxFrame(void)
+wxFrame::wxFrame()
 {
 ...
 }