better documentation for wxWindow::SetSizerAndFit()

[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 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 *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 
\helpref{wxTrackableBase}{wxtrackablebase} or \helpref{wxTrackable}{wxtrackable}.
By default, wxEvtHandler and wxWindow derive from wxTrackableBase. 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}

\textbf{Note:} Custom trackable objects should derive from wxTrackable 
if one wants to reference them from a \texttt{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 \texttt{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{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 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.


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