interface/wx/weakref.h

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