1 | /**************************************************************************** |
2 | ** |
3 | ** Copyright (C) 2016 The Qt Company Ltd. |
4 | ** Contact: https://www.qt.io/licensing/ |
5 | ** |
6 | ** This file is part of the QtCore module of the Qt Toolkit. |
7 | ** |
8 | ** $QT_BEGIN_LICENSE:LGPL$ |
9 | ** Commercial License Usage |
10 | ** Licensees holding valid commercial Qt licenses may use this file in |
11 | ** accordance with the commercial license agreement provided with the |
12 | ** Software or, alternatively, in accordance with the terms contained in |
13 | ** a written agreement between you and The Qt Company. For licensing terms |
14 | ** and conditions see https://www.qt.io/terms-conditions. For further |
15 | ** information use the contact form at https://www.qt.io/contact-us. |
16 | ** |
17 | ** GNU Lesser General Public License Usage |
18 | ** Alternatively, this file may be used under the terms of the GNU Lesser |
19 | ** General Public License version 3 as published by the Free Software |
20 | ** Foundation and appearing in the file LICENSE.LGPL3 included in the |
21 | ** packaging of this file. Please review the following information to |
22 | ** ensure the GNU Lesser General Public License version 3 requirements |
23 | ** will be met: https://www.gnu.org/licenses/lgpl-3.0.html. |
24 | ** |
25 | ** GNU General Public License Usage |
26 | ** Alternatively, this file may be used under the terms of the GNU |
27 | ** General Public License version 2.0 or (at your option) the GNU General |
28 | ** Public license version 3 or any later version approved by the KDE Free |
29 | ** Qt Foundation. The licenses are as published by the Free Software |
30 | ** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3 |
31 | ** included in the packaging of this file. Please review the following |
32 | ** information to ensure the GNU General Public License requirements will |
33 | ** be met: https://www.gnu.org/licenses/gpl-2.0.html and |
34 | ** https://www.gnu.org/licenses/gpl-3.0.html. |
35 | ** |
36 | ** $QT_END_LICENSE$ |
37 | ** |
38 | ****************************************************************************/ |
39 | |
40 | /*! |
41 | \class QPointer |
42 | \inmodule QtCore |
43 | \brief The QPointer class is a template class that provides guarded pointers to QObject. |
44 | |
45 | \ingroup objectmodel |
46 | |
47 | A guarded pointer, QPointer<T>, behaves like a normal C++ |
48 | pointer \c{T *}, except that it is automatically cleared when the |
49 | referenced object is destroyed (unlike normal C++ pointers, which |
50 | become "dangling pointers" in such cases). \c T must be a |
51 | subclass of QObject. |
52 | |
53 | Guarded pointers are useful whenever you need to store a pointer |
54 | to a QObject that is owned by someone else, and therefore might be |
55 | destroyed while you still hold a reference to it. You can safely |
56 | test the pointer for validity. |
57 | |
58 | Note that Qt 5 introduces a slight change in behavior when using QPointer. |
59 | |
60 | \list |
61 | |
62 | \li When using QPointer on a QWidget (or a subclass of QWidget), previously |
63 | the QPointer would be cleared by the QWidget destructor. Now, the QPointer |
64 | is cleared by the QObject destructor (since this is when QWeakPointer objects are |
65 | cleared). Any QPointers tracking a widget will \b NOT be cleared before the |
66 | QWidget destructor destroys the children for the widget being tracked. |
67 | |
68 | \endlist |
69 | |
70 | Qt also provides QSharedPointer, an implementation of a reference-counted |
71 | shared pointer object, which can be used to maintain a collection of |
72 | references to an individual pointer. |
73 | |
74 | Example: |
75 | |
76 | \snippet pointer/pointer.cpp 0 |
77 | \dots |
78 | \snippet pointer/pointer.cpp 1 |
79 | \snippet pointer/pointer.cpp 2 |
80 | |
81 | If the QLabel is deleted in the meantime, the \c label variable |
82 | will hold \nullptr instead of an invalid address, and the last line will |
83 | never be executed. |
84 | |
85 | The functions and operators available with a QPointer are the |
86 | same as those available with a normal unguarded pointer, except |
87 | the pointer arithmetic operators (\c{+}, \c{-}, \c{++}, and |
88 | \c{--}), which are normally used only with arrays of objects. |
89 | |
90 | Use QPointers like normal pointers and you will not need to read |
91 | this class documentation. |
92 | |
93 | For creating guarded pointers, you can construct or assign to them |
94 | from a T* or from another guarded pointer of the same type. You |
95 | can compare them with each other using operator==() and |
96 | operator!=(), or test for \nullptr with isNull(). You can dereference |
97 | them using either the \c *x or the \c x->member notation. |
98 | |
99 | A guarded pointer will automatically cast to a \c T *, so you can |
100 | freely mix guarded and unguarded pointers. This means that if you |
101 | have a QPointer<QWidget>, you can pass it to a function that |
102 | requires a QWidget *. For this reason, it is of little value to |
103 | declare functions to take a QPointer as a parameter; just use |
104 | normal pointers. Use a QPointer when you are storing a pointer |
105 | over time. |
106 | |
107 | Note that class \c T must inherit QObject, or a compilation or |
108 | link error will result. |
109 | |
110 | \sa QSharedPointer, QObject, QObjectCleanupHandler |
111 | */ |
112 | |
113 | /*! |
114 | \fn template <class T> QPointer<T>::QPointer() |
115 | |
116 | Constructs a guarded pointer with value \nullptr. |
117 | |
118 | \sa isNull() |
119 | */ |
120 | |
121 | /*! |
122 | \fn template <class T> QPointer<T>::QPointer(T* p) |
123 | |
124 | Constructs a guarded pointer that points to the same object that \a p |
125 | points to. |
126 | */ |
127 | |
128 | /*! |
129 | \fn template <class T> QPointer<T>::~QPointer() |
130 | |
131 | Destroys the guarded pointer. Just like a normal pointer, |
132 | destroying a guarded pointer does \e not destroy the object being |
133 | pointed to. |
134 | */ |
135 | |
136 | /*! |
137 | \fn template <class T> void QPointer<T>::swap(QPointer &other) |
138 | \since 5.6 |
139 | |
140 | Swaps the contents of this QPointer with the contents of \a other. |
141 | This operation is very fast and never fails. |
142 | */ |
143 | |
144 | /*! |
145 | \fn template <class T> QPointer<T> & QPointer<T>::operator=(T* p) |
146 | |
147 | Assignment operator. This guarded pointer will now point to the |
148 | same object that \a p points to. |
149 | */ |
150 | |
151 | /*! |
152 | \fn template <class T> T* QPointer<T>::data() const |
153 | \since 4.4 |
154 | |
155 | Returns the pointer to the object being guarded. |
156 | */ |
157 | |
158 | /*! |
159 | \fn template <class T> T* QPointer<T>::get() const |
160 | \since 6.0 |
161 | |
162 | Same as data(). This function is provided for STL compatibility. |
163 | */ |
164 | |
165 | /*! |
166 | \fn template <class T> bool QPointer<T>::isNull() const |
167 | |
168 | Returns \c true if the referenced object has been destroyed or if |
169 | there is no referenced object; otherwise returns \c false. |
170 | */ |
171 | |
172 | /*! |
173 | \fn template <class T> void QPointer<T>::clear() |
174 | \since 5.0 |
175 | |
176 | Clears this QPointer object. |
177 | |
178 | \sa isNull() |
179 | */ |
180 | |
181 | /*! |
182 | \fn template <class T> T* QPointer<T>::operator->() const |
183 | |
184 | Overloaded arrow operator; implements pointer semantics. Just use |
185 | this operator as you would with a normal C++ pointer. |
186 | */ |
187 | |
188 | /*! |
189 | \fn template <class T> T& QPointer<T>::operator*() const |
190 | |
191 | Dereference operator; implements pointer semantics. Just use this |
192 | operator as you would with a normal C++ pointer. |
193 | */ |
194 | |
195 | /*! |
196 | \fn template <class T> QPointer<T>::operator T*() const |
197 | |
198 | Cast operator; implements pointer semantics. Because of this |
199 | function you can pass a QPointer\<T\> to a function where a T* |
200 | is required. |
201 | */ |
202 | |
203 | /*! |
204 | \fn template <typename T, typename X> bool QPointer<T>::operator==(X *o, const QPointer<T> &p) |
205 | |
206 | Equality operator. Returns \c true if \a o and the guarded |
207 | pointer \a p are pointing to the same object, otherwise |
208 | returns \c false. |
209 | |
210 | */ |
211 | /*! |
212 | \fn template <typename T, typename X> bool QPointer<T>::operator==(const QPointer<T> &p, X *o) |
213 | |
214 | Equality operator. Returns \c true if \a o and the guarded |
215 | pointer \a p are pointing to the same object, otherwise |
216 | returns \c false. |
217 | |
218 | */ |
219 | /*! |
220 | \fn template <typename T, typename X> bool QPointer<T>::operator==(const QPointer<T> &p1, const QPointer<X> &p2) |
221 | |
222 | Equality operator. Returns \c true if the guarded pointers \a p1 and \a p2 |
223 | are pointing to the same object, otherwise |
224 | returns \c false. |
225 | |
226 | */ |
227 | /*! |
228 | \fn template <typename T> bool QPointer<T>::operator==(std::nullptr_t, const QPointer<T> &rhs) |
229 | |
230 | Equality operator. Returns \c true if the pointer guarded by \a rhs |
231 | is \nullptr, otherwise |
232 | returns \c false. |
233 | */ |
234 | /*! |
235 | \fn template <typename T> bool QPointer<T>::operator==(const QPointer<T> &lhs, std::nullptr_t) |
236 | |
237 | Equality operator. Returns \c true if the pointer guarded by \a lhs |
238 | is \nullptr, otherwise |
239 | returns \c false. |
240 | */ |
241 | |
242 | /*! |
243 | \fn template <typename T, typename X> bool QPointer<T>::operator!=(const QPointer<T> &p, X *o) |
244 | |
245 | Inequality operator. Returns \c true if \a o and the guarded |
246 | pointer \a p are not pointing to the same object, otherwise |
247 | returns \c false. |
248 | */ |
249 | /*! |
250 | \fn template <typename T, typename X> bool QPointer<T>::operator!=(X *o, const QPointer<T> &p) |
251 | |
252 | Inequality operator. Returns \c true if \a o and the guarded |
253 | pointer \a p are not pointing to the same object, otherwise |
254 | returns \c false. |
255 | */ |
256 | /*! |
257 | \fn template <typename T, typename X> bool QPointer<T>::operator!=(const QPointer<T> &p1, const QPointer<X> &p2) |
258 | |
259 | Inequality operator. Returns \c true if the guarded pointers \a p1 and |
260 | \a p2 are not pointing to the same object, otherwise |
261 | returns \c false. |
262 | */ |
263 | /*! |
264 | \fn template <typename T> bool QPointer<T>::operator!=(std::nullptr_t, const QPointer<T> &rhs) |
265 | |
266 | Inequality operator. Returns \c true if the pointer guarded by \a rhs is |
267 | a valid (ie not \nullptr) pointer, otherwise |
268 | returns \c false. |
269 | */ |
270 | /*! |
271 | \fn template <typename T> bool QPointer<T>::operator!=(const QPointer<T> &lhs, std::nullptr_t) |
272 | |
273 | Inequality operator. Returns \c true if the pointer guarded by \a lhs is |
274 | a valid (ie not \nullptr) pointer, otherwise |
275 | returns \c false. |
276 | */ |
277 | |
278 | /*! |
279 | \fn template <typename T> QPointer<T> qPointerFromVariant(const QVariant &variant) |
280 | |
281 | \internal |
282 | |
283 | Returns a guarded pointer that points to the same object that |
284 | \a variant holds. |
285 | */ |
286 | |