interface/wx/weakref.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        weakref.h
   3 // Purpose:     interface of wxWeakRefDynamic<T>, wxWeakRef<T>
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9
  10 /**
  11     @class wxWeakRefDynamic
  12
  13     wxWeakRefDynamic<T> is a template class for weak references that is used in
  14     the same way as wxWeakRef<T>. The only difference is that wxWeakRefDynamic
  15     defaults to using @c dynamic_cast for establishing the object reference
  16     (while wxWeakRef defaults to @c static_cast).
  17
  18     So, wxWeakRef will detect a type mismatch during compile time and will
  19     have a little better run-time performance. The role of wxWeakRefDynamic
  20     is to handle objects which derived type one does not know.
  21
  22     @note wxWeakRef<T> selects an implementation based on the static type of T.
  23           If T does not have wxTrackable statically, it defaults to to a mixed-
  24           mode operation, where it uses @c dynamic_cast as the last measure
  25           (if available from the compiler and enabled when building wxWidgets).
  26
  27     For general cases, wxWeakRef<T> is the better choice.
  28
  29     For API documentation, see: wxWeakRef<T>.
  30
  31     @tparam T
  32         @todo docme
  33
  34     @nolibrary
  35     @category{misc}
  36 */
  37 template<typename T>
  38 class wxWeakRefDynamic<T>
  39 {
  40 public:
  41
  42 };
  43
  44
  45
  46 /**
  47     @class wxWeakRef
  48
  49     wxWeakRef<T> is a template class for weak references to wxWidgets objects,
  50     such as wxEvtHandler, wxWindow and wxObject.
  51     A weak reference behaves much like an ordinary pointer, but when the object
  52     pointed is destroyed, the weak reference is automatically reset to a @NULL pointer.
  53
  54     wxWeakRef<T> can be used whenever one must keep a pointer to an object
  55     that one does not directly own, and that may be destroyed before the object
  56     holding the reference.
  57
  58     wxWeakRef<T> is a small object and the mechanism behind it is fast
  59     (@b O(1)). So the overall cost of using it is small.
  60
  61     Example:
  62
  63     @code
  64     wxWindow *wnd = new wxWindow( parent, wxID_ANY, "wxWindow" );
  65     wxWeakRef<wxWindow> wr = wnd;
  66     wxWindowRef wr2 = wnd;        // Same as above, but using a typedef
  67     // Do things with window
  68     wnd->Show( true );
  69     // Weak ref is used like an ordinary pointer
  70     wr->Show( false );
  71     wnd->Destroy();
  72     // Now the weak ref has been reset, so we don't risk accessing
  73     // a dangling pointer:
  74     wxASSERT( wr==NULL );
  75     @endcode
  76
  77     wxWeakRef<T> works for any objects that are derived from wxTrackable.
  78     By default, wxEvtHandler and wxWindow derive from wxTrackable.
  79     However, wxObject does not, so types like wxFont and wxColour are not
  80     trackable. The example below shows how to create a wxObject derived class
  81     that is trackable:
  82
  83     @code
  84     class wxMyTrackableObject : public wxObject, public wxTrackable
  85     {
  86         // ... other members here
  87     };
  88     @endcode
  89
  90     The following types of weak references are predefined:
  91
  92     @code
  93     typedef wxWeakRef<wxEvtHandler>  wxEvtHandlerRef;
  94     typedef wxWeakRef<wxWindow>      wxWindowRef;
  95     @endcode
  96
  97     @tparam T
  98         @todo docme
  99
 100     @nolibrary
 101     @category{misc}
 102
 103     @see wxSharedPtr<T>, wxScopedPtr<T>
 104 */
 105 template<typename T>
 106 class wxWeakRef<T> : public wxTrackerNode
 107 {
 108 public:
 109     /**
 110         Constructor. The weak reference is initialized to @e pobj.
 111     */
 112     wxWeakRef(T* pobj = NULL);
 113
 114     /**
 115         Copy constructor.
 116     */
 117     wxWeakRef(const wxWeakRef<T>& wr);
 118
 119     /**
 120         Destructor.
 121     */
 122     ~wxWeakRef();
 123
 124     /**
 125         Called when the tracked object is destroyed. Be default sets
 126         internal pointer to @NULL.
 127         You need to call this method if you override it.
 128     */
 129     virtual void OnObjectDestroy();
 130
 131     /**
 132         Release currently tracked object and rests object reference.
 133     */
 134     void Release();
 135
 136     /**
 137         Returns pointer to the tracked object or @NULL.
 138     */
 139     T* get() const;
 140
 141     /**
 142         Release currently tracked object and start tracking the same object as
 143         the wxWeakRef @e wr.
 144     */
 145     T* operator =(wxWeakRef<T>& wr);
 146
 147     /**
 148         Implicit conversion to T*.
 149         Returns pointer to the tracked object or @NULL.
 150     */
 151     T* operator*() const;
 152
 153     /**
 154         Returns a reference to the tracked object.
 155         If the internal pointer is @NULL this method will cause an assert in debug mode.
 156     */
 157     T& operator*() const;
 158
 159     /**
 160         Smart pointer member access.
 161         Returns a pointer to the tracked object.
 162         If the internal pointer is @NULL this method will cause an assert in debug mode.
 163     */
 164     T* operator-();
 165
 166     /**
 167         Releases the currently tracked object and starts tracking @e pobj.
 168         A weak reference may be reset by passing @e @NULL as @e pobj.
 169     */
 170     T* operator=(T* pobj);
 171 };
 172