]>
Commit | Line | Data |
---|---|---|
23324ae1 FM |
1 | ///////////////////////////////////////////////////////////////////////////// |
2 | // Name: weakref.h | |
e25cd775 | 3 | // Purpose: interface of wxWeakRefDynamic<T>, wxWeakRef<T> |
23324ae1 FM |
4 | // Author: wxWidgets team |
5 | // RCS-ID: $Id$ | |
526954c5 | 6 | // Licence: wxWindows licence |
23324ae1 FM |
7 | ///////////////////////////////////////////////////////////////////////////// |
8 | ||
e25cd775 | 9 | |
23324ae1 | 10 | /** |
73473b3e RR |
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 | |
e25cd775 FM |
13 | defaults to using @c dynamic_cast for establishing the object reference |
14 | (while wxWeakRef defaults to @c static_cast). | |
7c913512 | 15 | |
23324ae1 FM |
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 | |
7c913512 FM |
18 | is to handle objects which derived type one does not know. |
19 | ||
e25cd775 | 20 | @note wxWeakRef<T> selects an implementation based on the static type of T. |
4c51a665 | 21 | If T does not have wxTrackable statically, it defaults to a mixed- |
e25cd775 FM |
22 | mode operation, where it uses @c dynamic_cast as the last measure |
23 | (if available from the compiler and enabled when building wxWidgets). | |
7c913512 | 24 | |
73473b3e | 25 | For general cases, wxWeakRef<T> is the better choice. |
7c913512 | 26 | |
e25cd775 | 27 | For API documentation, see: wxWeakRef<T>. |
7c913512 | 28 | |
6c107bd2 | 29 | @tparam T |
f045c7f5 | 30 | The type to which the smart pointer points to. |
6c107bd2 | 31 | |
e25cd775 | 32 | @nolibrary |
d9a09273 | 33 | @category{smartpointers} |
23324ae1 | 34 | */ |
5cb947fd | 35 | template<typename T> |
7c913512 | 36 | class wxWeakRefDynamic<T> |
23324ae1 FM |
37 | { |
38 | public: | |
7c913512 | 39 | |
23324ae1 FM |
40 | }; |
41 | ||
42 | ||
e54c96f1 | 43 | |
23324ae1 | 44 | /** |
e25cd775 FM |
45 | wxWeakRef<T> is a template class for weak references to wxWidgets objects, |
46 | such as wxEvtHandler, wxWindow and wxObject. | |
47 | A weak reference behaves much like an ordinary pointer, but when the object | |
48 | pointed is destroyed, the weak reference is automatically reset to a @NULL pointer. | |
7c913512 | 49 | |
73473b3e | 50 | wxWeakRef<T> can be used whenever one must keep a pointer to an object |
23324ae1 | 51 | that one does not directly own, and that may be destroyed before the object |
7c913512 FM |
52 | holding the reference. |
53 | ||
73473b3e | 54 | wxWeakRef<T> is a small object and the mechanism behind it is fast |
7c913512 FM |
55 | (@b O(1)). So the overall cost of using it is small. |
56 | ||
e25cd775 FM |
57 | Example: |
58 | ||
e84fd6a1 RR |
59 | @code |
60 | wxWindow *wnd = new wxWindow( parent, wxID_ANY, "wxWindow" ); | |
e25cd775 | 61 | wxWeakRef<wxWindow> wr = wnd; |
e84fd6a1 RR |
62 | wxWindowRef wr2 = wnd; // Same as above, but using a typedef |
63 | // Do things with window | |
64 | wnd->Show( true ); | |
e25cd775 | 65 | // Weak ref is used like an ordinary pointer |
e84fd6a1 | 66 | wr->Show( false ); |
e25cd775 | 67 | wnd->Destroy(); |
e84fd6a1 RR |
68 | // Now the weak ref has been reset, so we don't risk accessing |
69 | // a dangling pointer: | |
70 | wxASSERT( wr==NULL ); | |
71 | @endcode | |
72 | ||
e25cd775 FM |
73 | wxWeakRef<T> works for any objects that are derived from wxTrackable. |
74 | By default, wxEvtHandler and wxWindow derive from wxTrackable. | |
75 | However, wxObject does not, so types like wxFont and wxColour are not | |
76 | trackable. The example below shows how to create a wxObject derived class | |
77 | that is trackable: | |
e84fd6a1 RR |
78 | |
79 | @code | |
80 | class wxMyTrackableObject : public wxObject, public wxTrackable | |
e25cd775 FM |
81 | { |
82 | // ... other members here | |
83 | }; | |
e84fd6a1 RR |
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 | ||
6c107bd2 | 93 | @tparam T |
f045c7f5 | 94 | The type to which the smart pointer points to. |
6c107bd2 | 95 | |
e25cd775 | 96 | @nolibrary |
d9a09273 | 97 | @category{smartpointers} |
7c913512 | 98 | |
73473b3e | 99 | @see wxSharedPtr<T>, wxScopedPtr<T> |
23324ae1 | 100 | */ |
5cb947fd | 101 | template<typename T> |
e25cd775 | 102 | class wxWeakRef<T> : public wxTrackerNode |
23324ae1 FM |
103 | { |
104 | public: | |
fc4e23d7 VZ |
105 | /// Type of the element stored by this reference. |
106 | typedef T element_type; | |
107 | ||
23324ae1 FM |
108 | /** |
109 | Constructor. The weak reference is initialized to @e pobj. | |
110 | */ | |
5cb947fd | 111 | wxWeakRef(T* pobj = NULL); |
23324ae1 | 112 | |
6dd21c54 RR |
113 | /** |
114 | Copy constructor. | |
115 | */ | |
116 | wxWeakRef(const wxWeakRef<T>& wr); | |
e25cd775 | 117 | |
23324ae1 FM |
118 | /** |
119 | Destructor. | |
120 | */ | |
fc4e23d7 | 121 | virtual ~wxWeakRef(); |
23324ae1 FM |
122 | |
123 | /** | |
124 | Called when the tracked object is destroyed. Be default sets | |
e25cd775 FM |
125 | internal pointer to @NULL. |
126 | You need to call this method if you override it. | |
23324ae1 FM |
127 | */ |
128 | virtual void OnObjectDestroy(); | |
129 | ||
130 | /** | |
131 | Release currently tracked object and rests object reference. | |
132 | */ | |
133 | void Release(); | |
134 | ||
135 | /** | |
136 | Returns pointer to the tracked object or @NULL. | |
137 | */ | |
328f5751 | 138 | T* get() const; |
23324ae1 FM |
139 | |
140 | /** | |
141 | Release currently tracked object and start tracking the same object as | |
142 | the wxWeakRef @e wr. | |
143 | */ | |
144 | T* operator =(wxWeakRef<T>& wr); | |
145 | ||
146 | /** | |
e25cd775 FM |
147 | Implicit conversion to T*. |
148 | Returns pointer to the tracked object or @NULL. | |
23324ae1 | 149 | */ |
328f5751 | 150 | T* operator*() const; |
23324ae1 FM |
151 | |
152 | /** | |
e25cd775 FM |
153 | Returns a reference to the tracked object. |
154 | If the internal pointer is @NULL this method will cause an assert in debug mode. | |
23324ae1 | 155 | */ |
e25cd775 | 156 | T& operator*() const; |
23324ae1 FM |
157 | |
158 | /** | |
37494cb3 | 159 | Smart pointer member access. Returns a pointer to the tracked object. |
e25cd775 | 160 | If the internal pointer is @NULL this method will cause an assert in debug mode. |
23324ae1 | 161 | */ |
37494cb3 | 162 | T* operator->(); |
23324ae1 FM |
163 | |
164 | /** | |
165 | Releases the currently tracked object and starts tracking @e pobj. | |
166 | A weak reference may be reset by passing @e @NULL as @e pobj. | |
167 | */ | |
168 | T* operator=(T* pobj); | |
169 | }; | |
e54c96f1 | 170 |