]> git.saurik.com Git - wxWidgets.git/blob - interface/weakref.h
Try out - instead of @li, more backslash escaping
[wxWidgets.git] / 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.
116 */
117 virtual void OnObjectDestroy();
118
119 /**
120 Release currently tracked object and rests object reference.
121 */
122 void Release();
123
124 /**
125 Returns pointer to the tracked object or @NULL.
126 */
127 T* get() const;
128
129 /**
130 Release currently tracked object and start tracking the same object as
131 the wxWeakRef @e wr.
132 */
133 T* operator =(wxWeakRef<T>& wr);
134
135 /**
136 Implicit conversion to T*. Returns pointer to the tracked
137 object or @NULL.
138 */
139 T* operator*() const;
140
141 /**
142 Returns a reference to the tracked object. If the internal pointer is @NULL
143 this method will cause an assert in debug mode.
144 */
145 T operator*() const;
146
147 /**
148 Smart pointer member access. Returns a pointer to the
149 tracked object. If the internal pointer is @NULL this
150 method will cause an assert in debug mode.
151 */
152 T* operator-();
153
154 /**
155 Releases the currently tracked object and starts tracking @e pobj.
156 A weak reference may be reset by passing @e @NULL as @e pobj.
157 */
158 T* operator=(T* pobj);
159 };
160