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 to goes out of scope (is destroyed), the weak reference is automatically
   7 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 ({\bf 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 {\bf wxTrackableBase}
  35 or {\bf wxTrackable}. By default, wxEvtHandler and wxWindow derive from
  36 wxTrackableBase. However, 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 \latexignore{\rtfignore{\wxheading{Members}}}
  75
  76
  77 \membersection{wxWeakRef<T>::wxWeakRef<T>}\label{wxweakrefwxweakref}
  78
  79 \func{}{wxWeakRef<T>}{\param{T* }{pobj = NULL}}
  80
  81 Constructor. The weak reference is initialized to {\it pobj}.
  82
  83
  84 \membersection{wxWeakRef<T>::\destruct{wxWeakRef<T>}}\label{wxweakrefdtor}
  85
  86 \func{}{\destruct{wxWeakRef<T>}}{\void}
  87
  88 Destructor.
  89
  90
  91 \membersection{wxWeakRef<T>::get}\label{wxweakrefget}
  92
  93 \constfunc{T *}{get}{\void}
  94
  95 Returns pointer to the tracked object or NULL.
  96
  97
  98 \membersection{wxWeakRef<T>::operator*}\label{wxweakrefoperatorreft}
  99
 100 \constfunc{T \&}{operator*}{\void}
 101
 102 Returns a reference to the tracked object. If the internal pointer is NULL
 103 this method will cause an assert in debug mode.
 104
 105
 106 \membersection{wxWeakRef<T>::operator->}\label{wxweakrefoperatorderef}
 107
 108 \func{T*}{operator->}{\void}
 109
 110 Smart pointer member access. Returns a pointer to the
 111 tracked object. If the internal pointer is NULL this
 112 method will cause an assert in debug mode.
 113
 114
 115 \membersection{wxWeakRef<T>::operator=}\label{wxweakrefoperatorassign}
 116
 117 \func{T* operator}{operator=}{\param{T* }{pobj}}
 118
 119 Releases the currently tracked object and starts tracking {\it pobj}.
 120 A weak reference may be reset by passing {\it NULL} as {\it pobj}.
 121
 122
 123 \membersection{wxWeakRef<T>::operator =}\label{wxweakrefoperatorassign2}
 124
 125 \func{T* operator}{operator =}{\param{wxWeakRef<T>\& }{wr}}
 126
 127 Release currently tracked object and start tracking the same object as
 128 the wxWeakRef {\it wr}.
 129
 130
 131 \membersection{wxWeakRef<T>::OnObjectDestroy}\label{wxweakrefonobjectdestroy}
 132
 133 \func{virtual void}{OnObjectDestroy}{\void}
 134
 135 Called when the tracked object is destroyed. Be default sets
 136 internal pointer to NULL.
 137