]> git.saurik.com Git - wxWidgets.git/blame - interface/wx/weakref.h
Fixed wxUSE_STD_DEFAULT==0 compilation.
[wxWidgets.git] / interface / wx / weakref.h
CommitLineData
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 35template<typename T>
7c913512 36class wxWeakRefDynamic<T>
23324ae1
FM
37{
38public:
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 101template<typename T>
e25cd775 102class wxWeakRef<T> : public wxTrackerNode
23324ae1
FM
103{
104public:
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