interface/weakref.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        weakref.h
   3 // Purpose:     documentation for wxWeakRefDynamic<T> class
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxWeakRefDynamicT
  11     @wxheader{weakref.h}
  12
  13     wxWeakRefDynamicT is a template class for weak references that is used in
  14     the same way as wxWeakRefT. The only difference is that wxWeakRefDynamic
  15     defaults to using @c dynamic_cast for establishing the object
  16     reference (while wxWeakRef defaults to @c static_cast).
  17
  18     So, wxWeakRef will detect a type mismatch during compile time and will
  19     have a little better run-time performance. The role of wxWeakRefDynamic
  20     is to handle objects which derived type one does not know.
  21
  22     @b Note: wxWeakRefT selects an implementation based on the static type
  23     of T. If T does not have wxTrackable statically, it defaults to to a mixed-
  24     mode operation, where it uses @c dynamic_cast as the last measure (if
  25     available from the compiler and enabled when building wxWidgets).
  26
  27     For general cases, wxWeakRefT is the better choice.
  28
  29     For API documentation, see: wxWeakRef
  30
  31     @library{wxcore}
  32     @category{FIXME}
  33 */
  34 class wxWeakRefDynamic<T>
  35 {
  36 public:
  37
  38 };
  39
  40
  41 /**
  42     @class wxWeakRefT
  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     wxWeakRefT 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     wxWeakRefT 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     @seealso
  62     wxSharedPtr, wxScopedPtr
  63 */
  64 class wxWeakRef<T>
  65 {
  66 public:
  67     /**
  68         Constructor. The weak reference is initialized to @e pobj.
  69     */
  70     wxWeakRefT(T* pobj = @NULL);
  71
  72     /**
  73         Destructor.
  74     */
  75     ~wxWeakRefT();
  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();
  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*();
 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*();
 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 };