Updated wxWeakRef<T> to patch Weak references for wx - part 2, removed T*() and added T* get(), other minor docs corr

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

docs/latex/wx/weakref.tex

@@ -1,18 +1,66 @@
 \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).
+{\bf wxWeakRef} is a template class for weak references to wxWidgets objects, 
+such as {\bf wxEvtHandler}, {\bf wxWindow} and {\bf wxObject}. A weak 
+reference behaves much like an ordinary pointer, but when the object pointed 
+to goes out of scope (is destroyed), the weak reference is automatically 
+reset to a NULL pointer. 
+
+wxWeakref<T> can be used whenever one must keep a pointer to an object 
+that does not directly own, and that may be destroyed before the object 
+holding the reference. 
+
+wxWeakref<T> is a small object and the mechanism behind it is fast 
+({\bf O(1)}). So the overall cost of using it is small. 
+
+
+\wxheading{Example}
 
 \begin{verbatim}
-class MyClass: public Foo, public TrackableBase
-{
-   // whatever
-}
-
-typedef wxWeakRef<MyClass> MyClassRef;
+    wxWindow *parent = /* Get parent window from somewhere */;
+    wxWindow *wnd = new wxWindow( parent, wxID_ANY, "wxWindow" );
+    wxWeakRef<wxWindow> wr = wnd;  
+    wxWindowRef wr2 = wnd;        // Same as above, but using a typedef
+    // Do things with window
+    wnd->Show( true );
+    // Weak ref is used like an ordinary pointer 
+    wr->Show( false );
+    wnd->Destroy(); 
+    // Now the weak ref has been reset, so we don't risk accessing
+    // a dangling pointer:
+    wxASSERT( wr==NULL );
 \end{verbatim}
 
+wxWeakref<T> works for any objects that are derived from {\bf wxTrackableBase} 
+or {\bf wxTrackable}. By default, wxEvtHandler and wxWindow derive from 
+wxTrackableBase. However, wxObject does not, so types like {\bf wxFont} and 
+{\bf wxColour} are not trackable. The example below shows how to create a 
+wxObject derived class that is trackable: 
+
+\begin{verbatim}
+    class wxMyTrackableObject : public wxObject, public wxTrackable { 
+        // ... other members here 
+    }; 
+\end{verbatim}
+
+{\bf Note:} Custom trackable objects should derive from wxTrackable 
+if one wants to reference them from a {\bf wxWeakRef<wxObject>}. The 
+difference between the two base classes is that wxTrackableBase 
+has no virtual member functions (no VTable), and thus cannot be detected
+through {\bf dynamic_cast<>}.
+
+
+\wxheading{Predefined types}
+
+The following types of weak references are predefined: 
+
+\begin{verbatim}
+typedef wxWeakRef<wxObject>      wxObjectRef;
+typedef wxWeakRef<wxEvtHandler>  wxEvtHandlerRef;
+typedef wxWeakRef<wxWindow>      wxWindowRef;
+\end{verbatim}
+
+
 \wxheading{Derived from}
 
 wxTrackerNode
@@ -30,7 +78,8 @@ wxTrackerNode
 
 \func{}{wxWeakRef<T>}{\param{T* }{pobj = NULL}}
 
-Constructor.
+Constructor. The weak reference is initialized to {\it pobj}.
+
 
 \membersection{wxWeakRef<T>::\destruct{wxWeakRef<T>}}\label{wxweakrefdtor}
 
@@ -38,36 +87,46 @@ Constructor.
 
 Destructor.
 
-\membersection{wxWeakRef<T>::T*}\label{wxweakreft}
 
-\func{operator}{T*}{\void}
+\membersection{wxWeakRef<T>::get}\label{wxweakrefget}
+
+\constfunc{T *}{get}{\void}
+
+Returns pointer to the tracked object or NULL.
+
+
+\membersection{wxWeakRef<T>::operator*}\label{wxweakrefoperatorreft}
+
+\constfunc{T \&}{operator*}{\void}
+
+Returns a reference to the tracked object. If the internal pointer is NULL
+this method will cause an assert in debug mode.
 
-Returns pointer to tracked object or NULL.
 
 \membersection{wxWeakRef<T>::operator->}\label{wxweakrefoperatorderef}
 
 \func{T*}{operator->}{\void}
 
-Returns pointer to tracked object or NULL.
+Smart pointer member access. Returns a pointer to the
+tracked object. If the internal pointer is NULL this
+method will cause an assert in debug mode.
+
 
 \membersection{wxWeakRef<T>::operator=}\label{wxweakrefoperatorassign}
 
 \func{T* operator}{operator=}{\param{T* }{pobj}}
 
-Assigns pointer to trackable object to this weak reference.
+Releases the currently tracked object and starts tracking {\it pobj}.
+A weak reference may be reset by passing {\it NULL} as {\it pobj}.
 
-\membersection{wxWeakRef<T>::Assign}\label{wxweakrefassign}
 
-\func{void}{Assign}{\param{T* }{pobj}}
+\membersection{wxWeakRef<T>::operator =}\label{wxweakrefoperatorassign2}
 
-This uses static\_cast if possible or dynamic\_cast otherwise.
+\func{T* operator}{operator =}{\param{wxWeakRef<T>\& }{wr}}
 
-\membersection{wxWeakRef<T>::GetTrackable}\label{wxweakrefgettrackable}
+Release currently tracked object and start tracking the same object as
+the wxWeakRef {\it wr}.
 
-\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}