added missing std sections

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

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

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 wxMyTrackableObject : public wxObject, public wxTrackable { 
        // ... other members here 
    }; 
\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{Include files}

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


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


\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=}{\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 =}{\param{wxWeakRef<T>\& }{wr}}

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


\membersection{wxWeakRef<T>::Release}\label{wxweakrefrelease}

\func{void}{Release}{\void}

Release currently tracked object and rests object reference.


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