Added docs to wxTrackable and wxWeakRef<T>

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

diff --git a/docs/latex/wx/category.tex b/docs/latex/wx/category.tex
index ff9602fd9059c577315461fb745e9bd607564e6f..81cad80b67abb752e2c351cc85fb8aa1205d8973 100644 (file)
--- a/docs/latex/wx/category.tex
+++ b/docs/latex/wx/category.tex
@@ -373,7 +373,17 @@ of these classes provide a subset or almost complete STL API.
 \twocolitem{\helpref{wxHashSet<T>}{wxhashset}}{A type-safe hash set implementation(macro based)}
 \twocolitem{\helpref{wxHashTable}{wxhashtable}}{A simple hash table implementation (deprecated, use wxHashMap)}
 \twocolitem{\helpref{wxList<T>}{wxlist}}{A type-safe linked list implementation (macro based)}
 \twocolitem{\helpref{wxHashSet<T>}{wxhashset}}{A type-safe hash set implementation(macro based)}
 \twocolitem{\helpref{wxHashTable}{wxhashtable}}{A simple hash table implementation (deprecated, use wxHashMap)}
 \twocolitem{\helpref{wxList<T>}{wxlist}}{A type-safe linked list implementation (macro based)}

-\twocolitem{\helpref{wxVector<T>}{wxvector}}{Template base vector implementation}
+\twocolitem{\helpref{wxVector<T>}{wxvector}}{Template base vector implementation identical to std::vector}
+\end{twocollist}
+
+{\large {\bf Smart pointers}}
+
+wxWidgets provides a few smart pointer class templates.
+
+\twocolwidtha{6cm}
+\begin{twocollist}\itemsep=0pt
+\twocolitem{\helpref{wxWeakRef<T>}{wxweakref}}{A weak reference}
+\twocolitem{\helpref{wxObjectDataPtr<T>}{wxobjectdataptr}}{A shared pointer using intrusive reference counting}

 \end{twocollist}
 
 {\large {\bf Run-time class information system}}
 \end{twocollist}
 
 {\large {\bf Run-time class information system}}

diff --git a/docs/latex/wx/classes.tex b/docs/latex/wx/classes.tex
index d0fd86c69db5c1e7c299065804a5eb540c218348..b15b8c5ad3b17eee18deea6294bd47baaf5d1238 100644 (file)
--- a/docs/latex/wx/classes.tex
+++ b/docs/latex/wx/classes.tex
@@ -438,6 +438,7 @@
 \input toolbook.tex
 \input tooltip.tex
 \input tlw.tex
 \input toolbook.tex
 \input tooltip.tex
 \input tlw.tex

+\input trackable.tex

 \input treebook.tex
 \input treebookevent.tex
 \input treectrl.tex
 \input treebook.tex
 \input treebookevent.tex
 \input treectrl.tex


@@ -463,6 +464,7 @@
 \input createevt.tex
 \input windowdc.tex
 \input destroyevt.tex
 \input createevt.tex
 \input windowdc.tex
 \input destroyevt.tex

+\input weakref.tex

 \input wnddisbl.tex
 \input wizard.tex
 \input wizevt.tex
 \input wnddisbl.tex
 \input wizard.tex
 \input wizevt.tex

diff --git a/docs/latex/wx/list.tex b/docs/latex/wx/list.tex
index 2d49800cafa23b28fe80f51b09ea21111ca46d20..b5064e807216f11667aebf3f31e4f53922b60823 100644 (file)
--- a/docs/latex/wx/list.tex
+++ b/docs/latex/wx/list.tex
@@ -11,18 +11,17 @@
 
 \section{\class{wxList<T>}}\label{wxlist}
 
 
 \section{\class{wxList<T>}}\label{wxlist}
 

-The wxList<T> class provides linked list functionality. It has been written
+The wxList<T> class provides linked list functionality. It has been rewritten

 to be type safe and to provide the full API of the STL std::list container and
 should be used like it. The exception is that wxList<T> actually stores
 pointers and therefore its iterators return pointers and not references
 to the actual objets in the list (see example below) and {\it value\_type} 
 to be type safe and to provide the full API of the STL std::list container and
 should be used like it. The exception is that wxList<T> actually stores
 pointers and therefore its iterators return pointers and not references
 to the actual objets in the list (see example below) and {\it value\_type} 

-is defined as {\it T*}.
+is defined as {\it T*}. wxList<T> destroys an object after removing it only
+if \helpref{DeleteContents}{wxlistdeletecontents} has been called.

 
 

-
-Unfortunately, the
-new wxList<T> class requires that you declare and define each wxList<T>
-class in your program. This is done with {\it WX\_DECLARE\_LIST} and 
-{\it WX\_DEFINE\_LIST} macros (see example). We hope that we'll be able
+wxList<T> is not a real template and it requires that you declare and define 
+each wxList<T> class in your program. This is done with {\it WX\_DECLARE\_LIST}
+and {\it WX\_DEFINE\_LIST} macros (see example). We hope that we'll be able

 to provide a proper template class providing both the STL std::list
 and the old wxList API in the future.
 
 to provide a proper template class providing both the STL std::list
 and the old wxList API in the future.
 

diff --git a/docs/latex/wx/trackable.tex b/docs/latex/wx/trackable.tex
new file mode 100644 (file)
index 0000000..274a1e8
--- /dev/null
+++ b/docs/latex/wx/trackable.tex
@@ -0,0 +1,48 @@
+
+\section{\class{wxTrackableBase}}\label{wxtrackablebase}
+
+Add-on base class for a trackable object. This class maintains
+an internal linked list of classes of type wxTrackerNode and
+calls OnObjectDestroy() on them if this object is destroyed.
+The most common usage is by using the \helpref{wxWeakRef<T>}{wxweakref}
+class template which automates this. This class has no public
+API. Its only use is by deriving another class from it to
+make it trackable.
+
+\begin{verbatim}
+class MyClass: public Foo, public TrackableBase
+{
+   // whatever
+}
+
+typedef wxWeakRef<MyClass> MyClassRef;
+\end{verbatim}
+
+\wxheading{Derived from}
+
+No base class
+
+\wxheading{Include files}
+
+<tracker.h>
+
+\wxheading{Data structures}
+
+
+\section{\class{wxTrackable}}\label{wxtrackable}
+
+The only difference to \helpref{wxTrackableBase}{wxtrackablebase} is
+that this class adds a virtual table to enable dynamic\_cast query for
+wxTrackable.
+
+\wxheading{Derived from}
+
+\helpref{wxTrackableBase}{wxtrackablebase}
+
+\wxheading{Include files}
+
+<tracker.h>
+
+\wxheading{Data structures}
+
+

diff --git a/docs/latex/wx/vector.tex b/docs/latex/wx/vector.tex
index 7301f19788766405d04202facb5eedee4fe74ada..3ad2b10da14e75114c3dab2b08fb51f60b057ac9 100644 (file)
--- a/docs/latex/wx/vector.tex
+++ b/docs/latex/wx/vector.tex
@@ -1,9 +1,12 @@
 \section{\class{wxVector<T>}}\label{wxvector}
 
 \section{\class{wxVector<T>}}\label{wxvector}
 

-wxVector is a template which implements most of the std::vector
-class and can be used like. If wxWidgets is compiled in STL mode,
-wxVector will just be a typedef to std::vector. You should
-refer to the STL documentation for further information.
+wxVector<T> is a template class which implements most of the std::vector
+class and can be used like it. If wxWidgets is compiled in STL mode,
+wxVector will just be a typedef to std::vector. Just like for std::vector,
+objects stored in wxVector<T> need to be {\it assignable} but don't have to
+be {\it default constructible}.
+
+You can refer to the STL documentation for further information.

 
 \wxheading{Derived from}
 
 
 \wxheading{Derived from}
 

diff --git a/docs/latex/wx/weakref.tex b/docs/latex/wx/weakref.tex
new file mode 100644 (file)
index 0000000..d4e368e
--- /dev/null
+++ b/docs/latex/wx/weakref.tex
@@ -0,0 +1,78 @@
+\section{\class{wxWeakRef<T>}}\label{wxweakref}
+
+A weak reference to an object of type T, where T has type 
+\helpref{wxTrackableBase}{wxTrackableBase} as one of its
+base classes  (in a static or dynamic sense).
+
+\begin{verbatim}
+class MyClass: public Foo, public TrackableBase
+{
+   // whatever
+}
+
+typedef wxWeakRef<MyClass> MyClassRef;
+\end{verbatim}
+
+\wxheading{Derived from}
+
+wxTrackerNode
+
+\wxheading{Include files}
+
+<weakref.h>
+
+\wxheading{Data structures}
+
+\latexignore{\rtfignore{\wxheading{Members}}}
+
+
+\membersection{wxWeakRef<T>::wxWeakRef<T>}\label{wxweakrefwxweakref}
+
+\func{}{wxWeakRef<T>}{\param{T* }{pobj = NULL}}
+
+Constructor.
+
+\membersection{wxWeakRef<T>::\destruct{wxWeakRef<T>}}\label{wxweakrefdtor}
+
+\func{}{\destruct{wxWeakRef<T>}}{\void}
+
+Destructor.
+
+\membersection{wxWeakRef<T>::T*}\label{wxweakreft}
+
+\func{operator}{T*}{\void}
+
+Returns pointer to tracked object or NULL.
+
+\membersection{wxWeakRef<T>::operator->}\label{wxweakrefoperatorderef}
+
+\func{T*}{operator->}{\void}
+
+Returns pointer to tracked object or NULL.
+
+\membersection{wxWeakRef<T>::operator=}\label{wxweakrefoperatorassign}
+
+\func{T* operator}{operator=}{\param{T* }{pobj}}
+
+Assigns pointer to trackable object to this weak reference.
+
+\membersection{wxWeakRef<T>::Assign}\label{wxweakrefassign}
+
+\func{void}{Assign}{\param{T* }{pobj}}
+
+This uses static\_cast if possible or dynamic\_cast otherwise.
+
+\membersection{wxWeakRef<T>::GetTrackable}\label{wxweakrefgettrackable}
+
+\func{wxTrackableBase*}{GetTrackable}{\param{T* }{pobj}}
+
+Returns the trackable objects to which the weak reference
+points or NULL if it has been destroyed.
+
+\membersection{wxWeakRef<T>::OnObjectDestroy}\label{wxweakrefonobjectdestroy}
+
+\func{virtual void}{OnObjectDestroy}{\void}
+
+Called when the tracked object is destroyed. Be default sets
+internal pointer to NULL.
+