docs/latex/wx/weakref.tex

   1 \section{\class{wxWeakRef<T>}}\label{wxweakref}
   2
   3 wxWeakRef is a template class for weak references to wxWidgets objects,
   4 such as \helpref{wxEvtHandler}{wxevthandler}, \helpref{wxWindow}{wxwindow} and
   5 \helpref{wxObject}{wxobject}. A weak reference behaves much like an ordinary
   6 pointer, but when the object pointed is destroyed, the weak reference is
   7 automatically reset to a NULL pointer.
   8
   9 wxWeakref<T> can be used whenever one must keep a pointer to an object
  10 that does not directly own, and that may be destroyed before the object
  11 holding the reference.
  12
  13 wxWeakref<T> is a small object and the mechanism behind it is fast
  14 (\textbf{O(1)}). So the overall cost of using it is small.
  15
  16
  17 \wxheading{Example}
  18
  19 \begin{verbatim}
  20     wxWindow *parent = /* Get parent window from somewhere */;
  21     wxWindow *wnd = new wxWindow( parent, wxID_ANY, "wxWindow" );
  22     wxWeakRef<wxWindow> wr = wnd;
  23     wxWindowRef wr2 = wnd;        // Same as above, but using a typedef
  24     // Do things with window
  25     wnd->Show( true );
  26     // Weak ref is used like an ordinary pointer
  27     wr->Show( false );
  28     wnd->Destroy();
  29     // Now the weak ref has been reset, so we don't risk accessing
  30     // a dangling pointer:
  31     wxASSERT( wr==NULL );
  32 \end{verbatim}
  33
  34 wxWeakref<T> works for any objects that are derived from
  35 \helpref{wxTrackableBase}{wxtrackablebase} or \helpref{wxTrackable}{wxtrackable}.
  36 By default, wxEvtHandler and wxWindow derive from wxTrackableBase. However,
  37 wxObject does not, so types like \helpref{wxFont}{wxfont} and
  38 \helpref{wxColour}{wxcolour} are not trackable. The example below shows how to
  39 create a wxObject derived class that is trackable:
  40
  41 \begin{verbatim}
  42     class wxMyTrackableObject : public wxObject, public wxTrackable {
  43         // ... other members here
  44     };
  45 \end{verbatim}
  46
  47 \textbf{Note:} Custom trackable objects should derive from wxTrackable
  48 if one wants to reference them from a \texttt{wxWeakRef<wxObject>}. The
  49 difference between the two base classes is that wxTrackableBase
  50 has no virtual member functions (no VTable), and thus cannot be detected
  51 through \texttt{dynamic\_cast<>}.
  52
  53 \wxheading{Predefined types}
  54
  55 The following types of weak references are predefined:
  56
  57 \begin{verbatim}
  58 typedef wxWeakRef<wxObject>      wxObjectRef;
  59 typedef wxWeakRef<wxEvtHandler>  wxEvtHandlerRef;
  60 typedef wxWeakRef<wxWindow>      wxWindowRef;
  61 \end{verbatim}
  62
  63
  64 \wxheading{Derived from}
  65
  66 wxTrackerNode
  67
  68 \wxheading{Include files}
  69
  70 <weakref.h>
  71
  72 \wxheading{See also}
  73
  74 \helpref{wxSharedPtr}{wxsharedptr}, \helpref{wxScopedPtr}{wxscopedptrtemplate}
  75
  76 \wxheading{Data structures}
  77
  78 {\small%
  79 \begin{verbatim}
  80 typedef T element_type
  81 \end{verbatim}
  82 }%
  83
  84
  85 \latexignore{\rtfignore{\wxheading{Members}}}
  86
  87
  88 \membersection{wxWeakRef<T>::wxWeakRef<T>}\label{wxweakrefwxweakref}
  89
  90 \func{}{wxWeakRef<T>}{\param{T* }{pobj = NULL}}
  91
  92 Constructor. The weak reference is initialized to {\it pobj}.
  93
  94
  95 \membersection{wxWeakRef<T>::\destruct{wxWeakRef<T>}}\label{wxweakrefdtor}
  96
  97 \func{}{\destruct{wxWeakRef<T>}}{\void}
  98
  99 Destructor.
 100
 101
 102 \membersection{wxWeakRef<T>::get}\label{wxweakrefget}
 103
 104 \constfunc{T *}{get}{\void}
 105
 106 Returns pointer to the tracked object or NULL.
 107
 108 \membersection{wxWeakRef<T>::operator unspecified\_bool\_type}\label{wxweakrefoperatorbool}
 109
 110 \constfunc{}{operator unspecified\_bool\_type}{\void}
 111
 112 Conversion to a boolean expression (in a variant which is not
 113 convertable to anything but a boolean expression). If this class
 114 contains a valid pointer it will return {\it true}, if it contains
 115 a NULL pointer it will return {\it false}.
 116
 117
 118 \membersection{wxWeakRef<T>::operator*}\label{wxweakrefoperatorreft}
 119
 120 \constfunc{T \&}{operator*}{\void}
 121
 122 Returns a reference to the tracked object. If the internal pointer is NULL
 123 this method will cause an assert in debug mode.
 124
 125
 126 \membersection{wxWeakRef<T>::operator->}\label{wxweakrefoperatorderef}
 127
 128 \func{T*}{operator->}{\void}
 129
 130 Smart pointer member access. Returns a pointer to the
 131 tracked object. If the internal pointer is NULL this
 132 method will cause an assert in debug mode.
 133
 134
 135 \membersection{wxWeakRef<T>::operator=}\label{wxweakrefoperatorassign}
 136
 137 \func{T* operator}{operator=}{\param{T* }{pobj}}
 138
 139 Releases the currently tracked object and starts tracking {\it pobj}.
 140 A weak reference may be reset by passing {\it NULL} as {\it pobj}.
 141
 142
 143 \membersection{wxWeakRef<T>::operator =}\label{wxweakrefoperatorassign2}
 144
 145 \func{T* operator}{operator =}{\param{wxWeakRef<T>\& }{wr}}
 146
 147 Release currently tracked object and start tracking the same object as
 148 the wxWeakRef {\it wr}.
 149
 150
 151 \membersection{wxWeakRef<T>::OnObjectDestroy}\label{wxweakrefonobjectdestroy}
 152
 153 \func{virtual void}{OnObjectDestroy}{\void}
 154
 155 Called when the tracked object is destroyed. Be default sets
 156 internal pointer to NULL.
 157