docs/latex/wx/weakref.tex

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