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