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 one 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 *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 \helpref{wxTrackable}{wxtrackable}.
  34 By default, wxEvtHandler and wxWindow derive from wxTrackable. However,
  35 wxObject does not, so types like \helpref{wxFont}{wxfont} and
  36 \helpref{wxColour}{wxcolour} are not trackable. The example below shows how to
  37 create a wxObject derived class that is trackable:
  38
  39 \begin{verbatim}
  40     class wxMyTrackableObject : public wxObject, public wxTrackable {
  41         // ... other members here
  42     };
  43 \end{verbatim}
  44
  45 \wxheading{Predefined types}
  46
  47 The following types of weak references are predefined:
  48
  49 \begin{verbatim}
  50 typedef wxWeakRef<wxEvtHandler>  wxEvtHandlerRef;
  51 typedef wxWeakRef<wxWindow>      wxWindowRef;
  52 \end{verbatim}
  53
  54
  55 \wxheading{Derived from}
  56
  57 wxTrackerNode
  58
  59 \wxheading{Include files}
  60
  61 <weakref.h>
  62
  63 \wxheading{See also}
  64
  65 \helpref{wxSharedPtr}{wxsharedptr}, \helpref{wxScopedPtr}{wxscopedptrtemplate}
  66
  67 \wxheading{Data structures}
  68
  69 {\small%
  70 \begin{verbatim}
  71 typedef T element_type
  72 \end{verbatim}
  73 }%
  74
  75
  76 \latexignore{\rtfignore{\wxheading{Members}}}
  77
  78
  79 \membersection{wxWeakRef<T>::wxWeakRef<T>}\label{wxweakrefwxweakref}
  80
  81 \func{}{wxWeakRef<T>}{\param{T* }{pobj = NULL}}
  82
  83 Constructor. The weak reference is initialized to {\it pobj}.
  84
  85
  86 \membersection{wxWeakRef<T>::\destruct{wxWeakRef<T>}}\label{wxweakrefdtor}
  87
  88 \func{}{\destruct{wxWeakRef<T>}}{\void}
  89
  90 Destructor.
  91
  92
  93 \membersection{wxWeakRef<T>::get}\label{wxweakrefget}
  94
  95 \constfunc{T *}{get}{\void}
  96
  97 Returns pointer to the tracked object or NULL.
  98
  99 \membersection{wxWeakRef<T>::operator T*}\label{wxweakrefoperatorconvt}
 100
 101 \constfunc{T*}{operator*}{\void}
 102
 103 Implicit conversion to T*. Returns pointer to the tracked
 104 object or NULL.
 105
 106 \membersection{wxWeakRef<T>::operator*}\label{wxweakrefoperatorreft}
 107
 108 \constfunc{T \&}{operator*}{\void}
 109
 110 Returns a reference to the tracked object. If the internal pointer is NULL
 111 this method will cause an assert in debug mode.
 112
 113
 114 \membersection{wxWeakRef<T>::operator->}\label{wxweakrefoperatorderef}
 115
 116 \func{T*}{operator->}{\void}
 117
 118 Smart pointer member access. Returns a pointer to the
 119 tracked object. If the internal pointer is NULL this
 120 method will cause an assert in debug mode.
 121
 122
 123 \membersection{wxWeakRef<T>::operator=}\label{wxweakrefoperatorassign}
 124
 125 \func{T*}{operator=}{\param{T* }{pobj}}
 126
 127 Releases the currently tracked object and starts tracking {\it pobj}.
 128 A weak reference may be reset by passing {\it NULL} as {\it pobj}.
 129
 130
 131 \membersection{wxWeakRef<T>::operator =}\label{wxweakrefoperatorassign2}
 132
 133 \func{T*}{operator =}{\param{wxWeakRef<T>\& }{wr}}
 134
 135 Release currently tracked object and start tracking the same object as
 136 the wxWeakRef {\it wr}.
 137
 138
 139 \membersection{wxWeakRef<T>::Release}\label{wxweakrefrelease}
 140
 141 \func{void}{Release}{\void}
 142
 143 Release currently tracked object and rests object reference.
 144
 145
 146 \membersection{wxWeakRef<T>::OnObjectDestroy}\label{wxweakrefonobjectdestroy}
 147
 148 \func{virtual void}{OnObjectDestroy}{\void}
 149
 150 Called when the tracked object is destroyed. Be default sets
 151 internal pointer to NULL.
 152