Added wxSharedPtr<T>

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

\section{\class{wxWeakRef<T>}}\label{wxweakref}

{\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}
    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

\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. The weak reference is initialized to {\it pobj}.


\membersection{wxWeakRef<T>::\destruct{wxWeakRef<T>}}\label{wxweakrefdtor}

\func{}{\destruct{wxWeakRef<T>}}{\void}

Destructor.


\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.


\membersection{wxWeakRef<T>::operator->}\label{wxweakrefoperatorderef}

\func{T*}{operator->}{\void}

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}}

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}

\func{T* operator}{operator =}{\param{wxWeakRef<T>\& }{wr}}

Release currently tracked object and start tracking the same object as
the wxWeakRef {\it wr}.


\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.