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