1// Copyright (C) 2016 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
7 \brief The QPointer class is a template class that provides guarded pointers to QObject.
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
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.
22 Note that Qt 5 introduces a slight change in behavior when using QPointer.
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.
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.
40 \snippet pointer/pointer.cpp 0
42 \snippet pointer/pointer.cpp 1
43 \snippet pointer/pointer.cpp 2
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
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.
54 Use QPointers like normal pointers and you will not need to read
55 this class documentation.
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.
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
71 Note that class \c T must inherit QObject, or a compilation or
72 link error will result.
74 \sa QSharedPointer, QObject, QObjectCleanupHandler
78 \fn template <class T> QPointer<T>::QPointer()
79 \fn template <class T> QPointer<T>::QPointer(std::nullptr_t)
81 Constructs a guarded pointer with value \nullptr.
87 \fn template <class T> QPointer<T>::QPointer(T* p)
89 Constructs a guarded pointer that points to the same object that \a p
94 \fn template <class T> QPointer<T>::~QPointer()
96 Destroys the guarded pointer. Just like a normal pointer,
97 destroying a guarded pointer does \e not destroy the object being
102 \fn template <class T> template <typename X, QPointer<T>::if_convertible<X> = true> QPointer<T>::QPointer(QPointer<X> &&other)
103 \fn template <class T> template <typename X, QPointer<T>::if_convertible<X> = true> QPointer<T>::QPointer(const QPointer<X> &other)
106 Conversion constructor. Constructs a new QPointer by moving or copying from
109 The moved-from QPointer is reset to nullptr.
111 \note These constructors participate in overload resolution only if \c{X*}
112 is convertible to \c{T*}.
116 \fn template <class T> template <typename X, QPointer<T>::if_convertible<X> = true> QPointer<T> &QPointer<T>::operator=(const QPointer<X> &other)
119 Conversion assignment operator. Makes this guarded pointer guard the
120 same object guarded by \a other.
122 \note This operator participates in overload resolution only if \c{X*}
123 is convertible to \c{T*}.
127 \fn template <class T> template <typename X, QPointer<T>::if_convertible<X> = true> &QPointer<T>::operator=(QPointer<X> &&other)
130 Conversion move-assignment operator. Makes this guarded pointer guard the
131 same object guarded by \a other and resets \a other to nullptr.
133 \note This operator participates in overload resolution only if \c{X*}
134 is convertible to \c{T*}.
138 \fn template <class T> void QPointer<T>::swap(QPointer &other)
141 Swaps the contents of this QPointer with the contents of \a other.
142 This operation is very fast and never fails.
146 \fn template <class T> QPointer<T> & QPointer<T>::operator=(T* p)
148 Assignment operator. This guarded pointer will now point to the
149 same object that \a p points to.
153 \fn template <class T> T* QPointer<T>::data() const
156 Returns the pointer to the object being guarded.
160 \fn template <class T> T* QPointer<T>::get() const
163 Same as data(). This function is provided for STL compatibility.
167 \fn template <class T> bool QPointer<T>::isNull() const
169 Returns \c true if the referenced object has been destroyed or if
170 there is no referenced object; otherwise returns \c false.
174 \fn template <class T> void QPointer<T>::clear()
177 Clears this QPointer object.
183 \fn template <class T> T* QPointer<T>::operator->() const
185 Overloaded arrow operator; implements pointer semantics. Just use
186 this operator as you would with a normal C++ pointer.
190 \fn template <class T> T& QPointer<T>::operator*() const
192 Dereference operator; implements pointer semantics. Just use this
193 operator as you would with a normal C++ pointer.
197 \fn template <class T> QPointer<T>::operator T*() const
199 Cast operator; implements pointer semantics. Because of this
200 function you can pass a QPointer<T> to a function where a T*
205 \fn template <typename T> template<typename X> bool QPointer<T>::operator==(X *o, const QPointer<T> &p)
207 Equality operator. Returns \c true if \a o and the guarded
208 pointer \a p are pointing to the same object, otherwise
213 \fn template <typename T> template<typename X> bool QPointer<T>::operator==(const QPointer<T> &p, X *o)
215 Equality operator. Returns \c true if \a o and the guarded
216 pointer \a p are pointing to the same object, otherwise
221 \fn template <typename T> template<typename X> bool QPointer<T>::operator==(const QPointer<T> &p1, const QPointer<X> &p2)
223 Equality operator. Returns \c true if the guarded pointers \a p1 and \a p2
224 are pointing to the same object, otherwise
229 \fn template <typename T> bool QPointer<T>::operator==(std::nullptr_t, const QPointer<T> &rhs)
231 Equality operator. Returns \c true if the pointer guarded by \a rhs
232 is \nullptr, otherwise
236 \fn template <typename T> bool QPointer<T>::operator==(const QPointer<T> &lhs, std::nullptr_t)
238 Equality operator. Returns \c true if the pointer guarded by \a lhs
239 is \nullptr, otherwise
244 \fn template <typename T> template<typename X> bool QPointer<T>::operator!=(const QPointer<T> &p, X *o)
246 Inequality operator. Returns \c true if \a o and the guarded
247 pointer \a p are not pointing to the same object, otherwise
251 \fn template <typename T> template<typename X> bool QPointer<T>::operator!=(X *o, const QPointer<T> &p)
253 Inequality operator. Returns \c true if \a o and the guarded
254 pointer \a p are not pointing to the same object, otherwise
258 \fn template <typename T> template<typename X> bool QPointer<T>::operator!=(const QPointer<T> &p1, const QPointer<X> &p2)
260 Inequality operator. Returns \c true if the guarded pointers \a p1 and
261 \a p2 are not pointing to the same object, otherwise
265 \fn template <typename T> bool QPointer<T>::operator!=(std::nullptr_t, const QPointer<T> &rhs)
267 Inequality operator. Returns \c true if the pointer guarded by \a rhs is
268 a valid (ie not \nullptr) pointer, otherwise
272 \fn template <typename T> bool QPointer<T>::operator!=(const QPointer<T> &lhs, std::nullptr_t)
274 Inequality operator. Returns \c true if the pointer guarded by \a lhs is
275 a valid (ie not \nullptr) pointer, otherwise
280 \fn template <typename T> QPointer<T> qPointerFromVariant(const QVariant &variant)
284 Returns a guarded pointer that points to the same object that