interface/wx/weakref.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        weakref.h
   3 // Purpose:     interface of wxWeakRefDynamic<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
  14     reference (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
  21     of T. 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 (if
  23     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     @library{wxcore}
  30     @category{FIXME}
  31 */
  32 template<typename T>
  33 class wxWeakRefDynamic<T>
  34 {
  35 public:
  36
  37 };
  38
  39
  40
  41 /**
  42
  43     wxWeakRef is a template class for weak references to wxWidgets objects,
  44     such as wxEvtHandler, wxWindow and
  45     wxObject. A weak reference behaves much like an ordinary
  46     pointer, but when the object pointed is destroyed, the weak reference is
  47     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. By default,
  73     wxEvtHandler and wxWindow derive from wxTrackable. However, wxObject does not, so
  74     types like wxFont and wxColour are not trackable. The example below shows how to
  75     create a wxObject derived class that is trackable:
  76
  77     @code
  78     class wxMyTrackableObject : public wxObject, public wxTrackable
  79     {
  80         // ... other members here
  81     };
  82     @endcode
  83
  84     The following types of weak references are predefined:
  85
  86     @code
  87     typedef wxWeakRef<wxEvtHandler>  wxEvtHandlerRef;
  88     typedef wxWeakRef<wxWindow>      wxWindowRef;
  89     @endcode
  90
  91
  92     @library{wxbase}
  93     @category{FIXME}
  94
  95     @see wxSharedPtr<T>, wxScopedPtr<T>
  96 */
  97 template<typename T>
  98 class wxWeakRef<T>
  99 {
 100 public:
 101     /**
 102         Constructor. The weak reference is initialized to @e pobj.
 103     */
 104     wxWeakRef(T* pobj = NULL);
 105
 106     /**
 107         Copy constructor.
 108     */
 109     wxWeakRef(const wxWeakRef<T>& wr);
 110
 111     /**
 112         Destructor.
 113     */
 114     ~wxWeakRef();
 115
 116     /**
 117         Called when the tracked object is destroyed. Be default sets
 118         internal pointer to @NULL. You need to call this method if
 119         you override it.
 120     */
 121     virtual void OnObjectDestroy();
 122
 123     /**
 124         Release currently tracked object and rests object reference.
 125     */
 126     void Release();
 127
 128     /**
 129         Returns pointer to the tracked object or @NULL.
 130     */
 131     T* get() const;
 132
 133     /**
 134         Release currently tracked object and start tracking the same object as
 135         the wxWeakRef @e wr.
 136     */
 137     T* operator =(wxWeakRef<T>& wr);
 138
 139     /**
 140         Implicit conversion to T*. Returns pointer to the tracked
 141         object or @NULL.
 142     */
 143     T* operator*() const;
 144
 145     /**
 146         Returns a reference to the tracked object. If the internal pointer is @NULL
 147         this method will cause an assert in debug mode.
 148     */
 149     T operator*() const;
 150
 151     /**
 152         Smart pointer member access. Returns a pointer to the
 153         tracked object. If the internal pointer is @NULL this
 154         method will cause an assert in debug mode.
 155     */
 156     T* operator-();
 157
 158     /**
 159         Releases the currently tracked object and starts tracking @e pobj.
 160         A weak reference may be reset by passing @e @NULL as @e pobj.
 161     */
 162     T* operator=(T* pobj);
 163 };
 164