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