Sort of autoresize if only 1 column is there

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

diff --git a/docs/latex/wx/weakref.tex b/docs/latex/wx/weakref.tex
index bda7029a8c78b666c1581f9578002dd3f29c2206..5464e81f6db59f11d84603f638c7a96bf8a348b9 100644 (file)
--- a/docs/latex/wx/weakref.tex
+++ b/docs/latex/wx/weakref.tex
@@ -1,18 +1,58 @@
 \section{\class{wxWeakRef<T>}}\label{wxweakref}
 
 \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}
 
 \begin{verbatim}

-class MyClass: public Foo, public TrackableBase
-{
-   // whatever
-}
+    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}

 
 

-typedef wxWeakRef<MyClass> MyClassRef;
+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 wxMyTrackableObject : public wxObject, public wxTrackable { 
+        // ... other members here 
+    }; 

 \end{verbatim}
 
 \end{verbatim}
 

+\wxheading{Predefined types}
+
+The following types of weak references are predefined: 
+
+\begin{verbatim}
+typedef wxWeakRef<wxEvtHandler>  wxEvtHandlerRef;
+typedef wxWeakRef<wxWindow>      wxWindowRef;
+\end{verbatim}
+
+

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


@@ -21,8 +61,19 @@ wxTrackerNode
 
 <weakref.h>
 
 
 <weakref.h>
 

+\wxheading{See also}
+
+\helpref{wxSharedPtr}{wxsharedptr}, \helpref{wxScopedPtr}{wxscopedptrtemplate}
+

 \wxheading{Data structures}
 
 \wxheading{Data structures}
 

+{\small% 
+\begin{verbatim}
+typedef T element_type
+\end{verbatim}
+}%
+
+

 \latexignore{\rtfignore{\wxheading{Members}}}
 
 
 \latexignore{\rtfignore{\wxheading{Members}}}
 
 


@@ -30,7 +81,8 @@ wxTrackerNode
 
 \func{}{wxWeakRef<T>}{\param{T* }{pobj = NULL}}
 
 
 \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}
 
 
 \membersection{wxWeakRef<T>::\destruct{wxWeakRef<T>}}\label{wxweakrefdtor}
 


@@ -38,36 +90,62 @@ Constructor.
 
 Destructor.
 
 
 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 unspecified\_bool\_type}\label{wxweakrefoperatorbool}
+
+\constfunc{}{operator unspecified\_bool\_type}{\void}
+
+Conversion to a boolean expression (in a variant which is not 
+convertable to anything but a boolean expression). If this class
+contains a valid pointer it will return {\it true}, if it contains
+a NULL pointer it will return {\it false}.
+
+
+\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}
 
 
 \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}
 
 
 \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}
 
 
 \membersection{wxWeakRef<T>::OnObjectDestroy}\label{wxweakrefonobjectdestroy}