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> bool QPointer<T>::isNull() const
160
161 Returns \c true if the referenced object has been destroyed or if
162 there is no referenced object; otherwise returns \c false.
163*/
164
165/*!
166 \fn template <class T> void QPointer<T>::clear()
167 \since 5.0
168
169 Clears this QPointer object.
170
171 \sa isNull()
172*/
173
174/*!
175 \fn template <class T> T* QPointer<T>::operator->() const
176
177 Overloaded arrow operator; implements pointer semantics. Just use
178 this operator as you would with a normal C++ pointer.
179*/
180
181/*!
182 \fn template <class T> T& QPointer<T>::operator*() const
183
184 Dereference operator; implements pointer semantics. Just use this
185 operator as you would with a normal C++ pointer.
186*/
187
188/*!
189 \fn template <class T> QPointer<T>::operator T*() const
190
191 Cast operator; implements pointer semantics. Because of this
192 function you can pass a QPointer\<T\> to a function where a T*
193 is required.
194*/
195
196/*!
197 \fn template <class T> bool operator==(const T *o, const QPointer<T> &p)
198 \relates QPointer
199
200 Equality operator. Returns \c true if \a o and the guarded
201 pointer \a p are pointing to the same object, otherwise
202 returns \c false.
203
204*/
205/*!
206 \fn template <class T> bool operator==(const QPointer<T> &p, const T *o)
207 \relates QPointer
208
209 Equality operator. Returns \c true if \a o and the guarded
210 pointer \a p are pointing to the same object, otherwise
211 returns \c false.
212
213*/
214/*!
215 \fn template <class T> bool operator==(T *o, const QPointer<T> &p)
216 \relates QPointer
217
218 Equality operator. Returns \c true if \a o and the guarded
219 pointer \a p are pointing to the same object, otherwise
220 returns \c false.
221
222*/
223/*!
224 \fn template <class T> bool operator==(const QPointer<T> &p, T *o)
225 \relates QPointer
226
227 Equality operator. Returns \c true if \a o and the guarded
228 pointer \a p are pointing to the same object, otherwise
229 returns \c false.
230
231*/
232/*!
233 \fn template <class T> bool operator==(const QPointer<T> &p1, const QPointer<T> &p2)
234 \relates QPointer
235
236 Equality operator. Returns \c true if the guarded pointers \a p1 and \a p2
237 are pointing to the same object, otherwise
238 returns \c false.
239
240*/
241
242
243/*!
244 \fn template <class T> bool operator!=(const T *o, const QPointer<T> &p)
245 \relates QPointer
246
247 Inequality operator. Returns \c true if \a o and the guarded
248 pointer \a p are not pointing to the same object, otherwise
249 returns \c false.
250*/
251/*!
252 \fn template <class T> bool operator!=(const QPointer<T> &p, const T *o)
253 \relates QPointer
254
255 Inequality operator. Returns \c true if \a o and the guarded
256 pointer \a p are not pointing to the same object, otherwise
257 returns \c false.
258*/
259/*!
260 \fn template <class T> bool operator!=(T *o, const QPointer<T> &p)
261 \relates QPointer
262
263 Inequality operator. Returns \c true if \a o and the guarded
264 pointer \a p are not pointing to the same object, otherwise
265 returns \c false.
266*/
267/*!
268 \fn template <class T> bool operator!=(const QPointer<T> &p, T *o)
269 \relates QPointer
270
271 Inequality operator. Returns \c true if \a o and the guarded
272 pointer \a p are not pointing to the same object, otherwise
273 returns \c false.
274*/
275/*!
276 \fn template <class T> bool operator!=(const QPointer<T> &p1, const QPointer<T> &p2)
277 \relates QPointer
278
279 Inequality operator. Returns \c true if the guarded pointers \a p1 and
280 \a p2 are not pointing to the same object, otherwise
281 returns \c false.
282*/
283/*!
284 \fn template <typename T> QPointer<T> qPointerFromVariant(const QVariant &variant)
285
286 \internal
287
288 Returns a guarded pointer that points to the same object that
289 \a variant holds.
290*/
291

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