X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/a6acecec4051afb021a16752ddf87bf9fff8f279..6e4ae332ac7d85be3592640ffef56a60924cc1c9:/docs/latex/wx/weakref.tex

diff --git a/docs/latex/wx/weakref.tex b/docs/latex/wx/weakref.tex
index d4e368ea77..ad01dcf198 100644
--- a/docs/latex/wx/weakref.tex
+++ b/docs/latex/wx/weakref.tex
@@ -1,18 +1,57 @@
 \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).
+wxWeakRef is a template class for weak references to wxWidgets objects, 
+such as \helpref{wxEvtHandler}{wxevthandler}, \helpref{wxWindow}{wxwindow} and 
+\helpref{wxObject}{wxobject}. A weak reference behaves much like an ordinary
+pointer, but when the object pointed 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 one 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 
+(\textbf{O(1)}). So the overall cost of using it is small. 
+
+
+\wxheading{Example}
+
+\begin{verbatim}
+    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 \helpref{wxTrackable}{wxtrackable}.
+By default, wxEvtHandler and wxWindow derive from wxTrackable. However, 
+wxObject does not, so types like \helpref{wxFont}{wxfont} and 
+\helpref{wxColour}{wxcolour} are not trackable. The example below shows how to
+create a wxObject derived class that is trackable: 
 
 \begin{verbatim}
-class MyClass: public Foo, public TrackableBase
-{
-   // whatever
-}
+    class wxMyTrackableObject : public wxObject, public wxTrackable { 
+        // ... other members here 
+    }; 
+\end{verbatim}
+
+\wxheading{Predefined types}
 
-typedef wxWeakRef<MyClass> MyClassRef;
+The following types of weak references are predefined: 
+
+\begin{verbatim}
+typedef wxWeakRef<wxEvtHandler>  wxEvtHandlerRef;
+typedef wxWeakRef<wxWindow>      wxWindowRef;
 \end{verbatim}
 
+
 \wxheading{Derived from}
 
 wxTrackerNode
@@ -21,8 +60,19 @@ wxTrackerNode
 
 <weakref.h>
 
+\wxheading{See also}
+
+\helpref{wxSharedPtr}{wxsharedptr}, \helpref{wxScopedPtr}{wxscopedptrtemplate}
+
 \wxheading{Data structures}
 
+{\small% 
+\begin{verbatim}
+typedef T element_type
+\end{verbatim}
+}%
+
+
 \latexignore{\rtfignore{\wxheading{Members}}}
 
 
@@ -30,7 +80,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 +89,59 @@ 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 T*}\label{wxweakrefoperatorconvt}
+
+\constfunc{T*}{operator*}{\void}
+
+Implicit conversion to T*. 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}}
+\func{T*}{operator=}{\param{T* }{pobj}}
+
+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>::operator =}\label{wxweakrefoperatorassign2}
 
-Assigns pointer to trackable object to this weak reference.
+\func{T*}{operator =}{\param{wxWeakRef<T>\& }{wr}}
 
-\membersection{wxWeakRef<T>::Assign}\label{wxweakrefassign}
+Release currently tracked object and start tracking the same object as
+the wxWeakRef {\it wr}.
 
-\func{void}{Assign}{\param{T* }{pobj}}
 
-This uses static\_cast if possible or dynamic\_cast otherwise.
+\membersection{wxWeakRef<T>::Release}\label{wxweakrefrelease}
 
-\membersection{wxWeakRef<T>::GetTrackable}\label{wxweakrefgettrackable}
+\func{void}{Release}{\void}
 
-\func{wxTrackableBase*}{GetTrackable}{\param{T* }{pobj}}
+Release currently tracked object and rests object reference.
 
-Returns the trackable objects to which the weak reference
-points or NULL if it has been destroyed.
 
 \membersection{wxWeakRef<T>::OnObjectDestroy}\label{wxweakrefonobjectdestroy}