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