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     @library{wxbase}
  59     @category{FIXME}
  60
  61     @see wxSharedPtr<T>, wxScopedPtr<T>
  62 */
  63 template<typename T>
  64 class wxWeakRef<T>
  65 {
  66 public:
  67     /**
  68         Constructor. The weak reference is initialized to @e pobj.
  69     */
  70     wxWeakRef(T* pobj = NULL);
  71
  72     /**
  73         Destructor.
  74     */
  75     ~wxWeakRef();
  76
  77     /**
  78         Called when the tracked object is destroyed. Be default sets
  79         internal pointer to @NULL.
  80     */
  81     virtual void OnObjectDestroy();
  82
  83     /**
  84         Release currently tracked object and rests object reference.
  85     */
  86     void Release();
  87
  88     /**
  89         Returns pointer to the tracked object or @NULL.
  90     */
  91     T* get() const;
  92
  93     /**
  94         Release currently tracked object and start tracking the same object as
  95         the wxWeakRef @e wr.
  96     */
  97     T* operator =(wxWeakRef<T>& wr);
  98
  99     /**
 100         Implicit conversion to T*. Returns pointer to the tracked
 101         object or @NULL.
 102     */
 103     T* operator*() const;
 104
 105     /**
 106         Returns a reference to the tracked object. If the internal pointer is @NULL
 107         this method will cause an assert in debug mode.
 108     */
 109     T operator*() const;
 110
 111     /**
 112         Smart pointer member access. Returns a pointer to the
 113         tracked object. If the internal pointer is @NULL this
 114         method will cause an assert in debug mode.
 115     */
 116     T* operator-();
 117
 118     /**
 119         Releases the currently tracked object and starts tracking @e pobj.
 120         A weak reference may be reset by passing @e @NULL as @e pobj.
 121     */
 122     T* operator=(T* pobj);
 123 };
 124