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

source code of qtbase/src/corelib/kernel/qpointer.cpp