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