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