\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 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 MyClass: public Foo, public TrackableBase
-{
- // whatever
-}
+ 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:
-typedef wxWeakRef<MyClass> MyClassRef;
+\begin{verbatim}
+typedef wxWeakRef<wxObject> wxObjectRef;
+typedef wxWeakRef<wxEvtHandler> wxEvtHandlerRef;
+typedef wxWeakRef<wxWindow> wxWindowRef;
\end{verbatim}
+
\wxheading{Derived from}
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}}}
\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}
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}
-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}}
-Assigns pointer to trackable object to this weak reference.
-
-\membersection{wxWeakRef<T>::Assign}\label{wxweakrefassign}
+Releases the currently tracked object and starts tracking {\it pobj}.
+A weak reference may be reset by passing {\it NULL} as {\it pobj}.
-\func{void}{Assign}{\param{T* }{pobj}}
-This uses static\_cast if possible or dynamic\_cast otherwise.
+\membersection{wxWeakRef<T>::operator =}\label{wxweakrefoperatorassign2}
-\membersection{wxWeakRef<T>::GetTrackable}\label{wxweakrefgettrackable}
+\func{T* operator}{operator =}{\param{wxWeakRef<T>\& }{wr}}
-\func{wxTrackableBase*}{GetTrackable}{\param{T* }{pobj}}
+Release currently tracked object and start tracking the same object as
+the wxWeakRef {\it wr}.
-Returns the trackable objects to which the weak reference
-points or NULL if it has been destroyed.
\membersection{wxWeakRef<T>::OnObjectDestroy}\label{wxweakrefonobjectdestroy}
projects / wxWidgets.git / blobdiff