src/corelib/kernel/qpointer.cpp - qt in Qt

/****************************************************************************
**
** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
** All rights reserved.
** Contact: Nokia Corporation (qt-info@nokia.com)
**
** This file is part of the QtCore module of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:LGPL$
** GNU Lesser General Public License Usage
** This file may be used under the terms of the GNU Lesser General Public
** License version 2.1 as published by the Free Software Foundation and
** appearing in the file LICENSE.LGPL included in the packaging of this
** file. Please review the following information to ensure the GNU Lesser
** General Public License version 2.1 requirements will be met:
** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
**
** In addition, as a special exception, Nokia gives you certain additional
** rights. These rights are described in the Nokia Qt LGPL Exception
** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
**
** GNU General Public License Usage
** Alternatively, this file may be used under the terms of the GNU General
** Public License version 3.0 as published by the Free Software Foundation
** and appearing in the file LICENSE.GPL included in the packaging of this
** file. Please review the following information to ensure the GNU General
** Public License version 3.0 requirements will be met:
** http://www.gnu.org/copyleft/gpl.html.
**
** Other Usage
** Alternatively, this file may be used in accordance with the terms and
** conditions contained in a signed written agreement between you and Nokia.
**
**
**
**
**
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
    \class QPointer
    \brief The QPointer class is a template class that provides guarded pointers to QObject.

    \ingroup objectmodel


    A guarded pointer, QPointer<T>, behaves like a normal C++
    pointer \c{T *}, except that it is automatically set to 0 when the
    referenced object is destroyed (unlike normal C++ pointers, which
    become "dangling pointers" in such cases). \c T must be a
    subclass of QObject.

    Guarded pointers are useful whenever you need to store a pointer
    to a QObject that is owned by someone else, and therefore might be
    destroyed while you still hold a reference to it. You can safely
    test the pointer for validity.

    Qt also provides QSharedPointer, an implementation of a reference-counted
    shared pointer object, which can be used to maintain a collection of
    references to an individual pointer.

    Example:

    \snippet doc/src/snippets/pointer/pointer.cpp 0
    \dots
    \snippet doc/src/snippets/pointer/pointer.cpp 1
    \snippet doc/src/snippets/pointer/pointer.cpp 2

    If the QLabel is deleted in the meantime, the \c label variable
    will hold 0 instead of an invalid address, and the last line will
    never be executed.

    The functions and operators available with a QPointer are the
    same as those available with a normal unguarded pointer, except
    the pointer arithmetic operators (\c{+}, \c{-}, \c{++}, and
    \c{--}), which are normally used only with arrays of objects.

    Use QPointers like normal pointers and you will not need to read
    this class documentation.

    For creating guarded pointers, you can construct or assign to them
    from a T* or from another guarded pointer of the same type. You
    can compare them with each other using operator==() and
    operator!=(), or test for 0 with isNull(). You can dereference
    them using either the \c *x or the \c x->member notation.

    A guarded pointer will automatically cast to a \c T *, so you can
    freely mix guarded and unguarded pointers. This means that if you
    have a QPointer<QWidget>, you can pass it to a function that
    requires a QWidget *. For this reason, it is of little value to
    declare functions to take a QPointer as a parameter; just use
    normal pointers. Use a QPointer when you are storing a pointer
    over time.

    Note that class \c T must inherit QObject, or a compilation or
    link error will result.

    \sa QSharedPointer, QWeakPointer, QObject, QObjectCleanupHandler
*/

/*!
    \fn QPointer::QPointer()

    Constructs a 0 guarded pointer.

    \sa isNull()
*/

/*!
    \fn QPointer::QPointer(T* p)

    Constructs a guarded pointer that points to same object that \a p
    points to.
*/

/*!
    \fn QPointer::QPointer(const QPointer<T> &p)

    Copies one guarded pointer from another. The constructed guarded
    pointer points to the same object that \a p points to (which may
    be 0).
*/

/*!
    \fn QPointer::~QPointer()

    Destroys the guarded pointer. Just like a normal pointer,
    destroying a guarded pointer does \e not destroy the object being
    pointed to.
*/

/*!
    \fn QPointer<T>& QPointer::operator=(const QPointer<T> &p)

    Assignment operator. This guarded pointer will now point to the
    same object that \a p points to.
*/

/*!
    \fn QPointer<T> & QPointer::operator=(T* p)

    Assignment operator. This guarded pointer will now point to the
    same object that \a p points to.
*/

/*!
    \fn T* QPointer::data() const
    \since 4.4

    Returns the pointer to the object being guarded.
*/

/*!
    \fn bool QPointer::isNull() const

    Returns \c true if the referenced object has been destroyed or if
    there is no referenced object; otherwise returns false.
*/

/*!
    \fn T* QPointer::operator->() const

    Overloaded arrow operator; implements pointer semantics. Just use
    this operator as you would with a normal C++ pointer.
*/

/*!
    \fn T& QPointer::operator*() const

    Dereference operator; implements pointer semantics. Just use this
    operator as you would with a normal C++ pointer.
*/

/*!
    \fn QPointer::operator T*() const

    Cast operator; implements pointer semantics. Because of this
    function you can pass a QPointer\<T\> to a function where a T*
    is required.
*/

/*!
    \fn bool operator==(const T *o, const QPointer<T> &p)
    \relates QPointer

    Equality operator. Returns true if \a o and the guarded
    pointer \a p are pointing to the same object, otherwise
    returns false.

*/
/*!
    \fn bool operator==(const QPointer<T> &p, const T *o)
    \relates QPointer

    Equality operator. Returns true if \a o and the guarded
    pointer \a p are pointing to the same object, otherwise
    returns false.

*/
/*!
    \fn bool operator==(T *o, const QPointer<T> &p)
    \relates QPointer

    Equality operator. Returns true if \a o and the guarded
    pointer \a p are pointing to the same object, otherwise
    returns false.

*/
/*!
    \fn bool operator==(const QPointer<T> &p, T *o)
    \relates QPointer

    Equality operator. Returns true if \a o and the guarded
    pointer \a p are pointing to the same object, otherwise
    returns false.

*/
/*!
    \fn bool operator==(const QPointer<T> &p1, const QPointer<T> &p2)
    \relates QPointer

    Equality operator. Returns true if the guarded pointers \a p1 and \a p2
    are pointing to the same object, otherwise
    returns false.

*/


/*!
    \fn bool operator!=(const T *o, const QPointer<T> &p)
    \relates QPointer

    Inequality operator. Returns true if \a o and the guarded
    pointer \a p are not pointing to the same object, otherwise
    returns false.
*/
/*!
    \fn bool operator!=(const QPointer<T> &p, const T *o)
    \relates QPointer

    Inequality operator. Returns true if \a o and the guarded
    pointer \a p are not pointing to the same object, otherwise
    returns false.
*/
/*!
    \fn bool operator!=(T *o, const QPointer<T> &p)
    \relates QPointer

    Inequality operator. Returns true if \a o and the guarded
    pointer \a p are not pointing to the same object, otherwise
    returns false.
*/
/*!
    \fn bool operator!=(const QPointer<T> &p, T *o)
    \relates QPointer

    Inequality operator. Returns true if \a o and the guarded
    pointer \a p are not pointing to the same object, otherwise
    returns false.
*/
/*!
    \fn bool operator!=(const QPointer<T> &p1, const QPointer<T> &p2)
    \relates QPointer

    Inequality operator. Returns true if  the guarded pointers \a p1 and
    \a p2 are not pointing to the same object, otherwise
    returns false.
*/

1	/****************************************************************************
2	**
3	** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
4	** All rights reserved.
5	** Contact: Nokia Corporation (qt-info@nokia.com)
6	**
7	** This file is part of the QtCore module of the Qt Toolkit.
8	**
9	** $QT_BEGIN_LICENSE:LGPL$
10	** GNU Lesser General Public License Usage
11	** This file may be used under the terms of the GNU Lesser General Public
12	** License version 2.1 as published by the Free Software Foundation and
13	** appearing in the file LICENSE.LGPL included in the packaging of this
14	** file. Please review the following information to ensure the GNU Lesser
15	** General Public License version 2.1 requirements will be met:
16	** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
17	**
18	** In addition, as a special exception, Nokia gives you certain additional
19	** rights. These rights are described in the Nokia Qt LGPL Exception
20	** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
21	**
22	** GNU General Public License Usage
23	** Alternatively, this file may be used under the terms of the GNU General
24	** Public License version 3.0 as published by the Free Software Foundation
25	** and appearing in the file LICENSE.GPL included in the packaging of this
26	** file. Please review the following information to ensure the GNU General
27	** Public License version 3.0 requirements will be met:
28	** http://www.gnu.org/copyleft/gpl.html.
29	**
30	** Other Usage
31	** Alternatively, this file may be used in accordance with the terms and
32	** conditions contained in a signed written agreement between you and Nokia.
33	**
34	**
35	**
36	**
37	**
38	** $QT_END_LICENSE$
39	**
40	****************************************************************************/
41
42	/*!
43	\class QPointer
44	\brief The QPointer class is a template class that provides guarded pointers to QObject.
45
46	\ingroup objectmodel
47
48
49	A guarded pointer, QPointer<T>, behaves like a normal C++
50	pointer \c{T *}, except that it is automatically set to 0 when the
51	referenced object is destroyed (unlike normal C++ pointers, which
52	become "dangling pointers" in such cases). \c T must be a
53	subclass of QObject.
54
55	Guarded pointers are useful whenever you need to store a pointer
56	to a QObject that is owned by someone else, and therefore might be
57	destroyed while you still hold a reference to it. You can safely
58	test the pointer for validity.
59
60	Qt also provides QSharedPointer, an implementation of a reference-counted
61	shared pointer object, which can be used to maintain a collection of
62	references to an individual pointer.
63
64	Example:
65
66	\snippet doc/src/snippets/pointer/pointer.cpp 0
67	\dots
68	\snippet doc/src/snippets/pointer/pointer.cpp 1
69	\snippet doc/src/snippets/pointer/pointer.cpp 2
70
71	If the QLabel is deleted in the meantime, the \c label variable
72	will hold 0 instead of an invalid address, and the last line will
73	never be executed.
74
75	The functions and operators available with a QPointer are the
76	same as those available with a normal unguarded pointer, except
77	the pointer arithmetic operators (\c{+}, \c{-}, \c{++}, and
78	\c{--}), which are normally used only with arrays of objects.
79
80	Use QPointers like normal pointers and you will not need to read
81	this class documentation.
82
83	For creating guarded pointers, you can construct or assign to them
84	from a T* or from another guarded pointer of the same type. You
85	can compare them with each other using operator==() and
86	operator!=(), or test for 0 with isNull(). You can dereference
87	them using either the \c *x or the \c x->member notation.
88
89	A guarded pointer will automatically cast to a \c T *, so you can
90	freely mix guarded and unguarded pointers. This means that if you
91	have a QPointer<QWidget>, you can pass it to a function that
92	requires a QWidget *. For this reason, it is of little value to
93	declare functions to take a QPointer as a parameter; just use
94	normal pointers. Use a QPointer when you are storing a pointer
95	over time.
96
97	Note that class \c T must inherit QObject, or a compilation or
98	link error will result.
99
100	\sa QSharedPointer, QWeakPointer, QObject, QObjectCleanupHandler
101	*/
102
103	/*!
104	\fn QPointer::QPointer()
105
106	Constructs a 0 guarded pointer.
107
108	\sa isNull()
109	*/
110
111	/*!
112	\fn QPointer::QPointer(T* p)
113
114	Constructs a guarded pointer that points to same object that \a p
115	points to.
116	*/
117
118	/*!
119	\fn QPointer::QPointer(const QPointer<T> &p)
120
121	Copies one guarded pointer from another. The constructed guarded
122	pointer points to the same object that \a p points to (which may
123	be 0).
124	*/
125
126	/*!
127	\fn QPointer::~QPointer()
128
129	Destroys the guarded pointer. Just like a normal pointer,
130	destroying a guarded pointer does \e not destroy the object being
131	pointed to.
132	*/
133
134	/*!
135	\fn QPointer<T>& QPointer::operator=(const QPointer<T> &p)
136
137	Assignment operator. This guarded pointer will now point to the
138	same object that \a p points to.
139	*/
140
141	/*!
142	\fn QPointer<T> & QPointer::operator=(T* p)
143
144	Assignment operator. This guarded pointer will now point to the
145	same object that \a p points to.
146	*/
147
148	/*!
149	\fn T* QPointer::data() const
150	\since 4.4
151
152	Returns the pointer to the object being guarded.
153	*/
154
155	/*!
156	\fn bool QPointer::isNull() const
157
158	Returns \c true if the referenced object has been destroyed or if
159	there is no referenced object; otherwise returns false.
160	*/
161
162	/*!
163	\fn T* QPointer::operator->() const
164
165	Overloaded arrow operator; implements pointer semantics. Just use
166	this operator as you would with a normal C++ pointer.
167	*/
168
169	/*!
170	\fn T& QPointer::operator*() const
171
172	Dereference operator; implements pointer semantics. Just use this
173	operator as you would with a normal C++ pointer.
174	*/
175
176	/*!
177	\fn QPointer::operator T*() const
178
179	Cast operator; implements pointer semantics. Because of this
180	function you can pass a QPointer\<T\> to a function where a T*
181	is required.
182	*/
183
184	/*!
185	\fn bool operator==(const T *o, const QPointer<T> &p)
186	\relates QPointer
187
188	Equality operator. Returns true if \a o and the guarded
189	pointer \a p are pointing to the same object, otherwise
190	returns false.
191
192	*/
193	/*!
194	\fn bool operator==(const QPointer<T> &p, const T *o)
195	\relates QPointer
196
197	Equality operator. Returns true if \a o and the guarded
198	pointer \a p are pointing to the same object, otherwise
199	returns false.
200
201	*/
202	/*!
203	\fn bool operator==(T *o, const QPointer<T> &p)
204	\relates QPointer
205
206	Equality operator. Returns true if \a o and the guarded
207	pointer \a p are pointing to the same object, otherwise
208	returns false.
209
210	*/
211	/*!
212	\fn bool operator==(const QPointer<T> &p, T *o)
213	\relates QPointer
214
215	Equality operator. Returns true if \a o and the guarded
216	pointer \a p are pointing to the same object, otherwise
217	returns false.
218
219	*/
220	/*!
221	\fn bool operator==(const QPointer<T> &p1, const QPointer<T> &p2)
222	\relates QPointer
223
224	Equality operator. Returns true if the guarded pointers \a p1 and \a p2
225	are pointing to the same object, otherwise
226	returns false.
227
228	*/
229
230
231	/*!
232	\fn bool operator!=(const T *o, const QPointer<T> &p)
233	\relates QPointer
234
235	Inequality operator. Returns true if \a o and the guarded
236	pointer \a p are not pointing to the same object, otherwise
237	returns false.
238	*/
239	/*!
240	\fn bool operator!=(const QPointer<T> &p, const T *o)
241	\relates QPointer
242
243	Inequality operator. Returns true if \a o and the guarded
244	pointer \a p are not pointing to the same object, otherwise
245	returns false.
246	*/
247	/*!
248	\fn bool operator!=(T *o, const QPointer<T> &p)
249	\relates QPointer
250
251	Inequality operator. Returns true if \a o and the guarded
252	pointer \a p are not pointing to the same object, otherwise
253	returns false.
254	*/
255	/*!
256	\fn bool operator!=(const QPointer<T> &p, T *o)
257	\relates QPointer
258
259	Inequality operator. Returns true if \a o and the guarded
260	pointer \a p are not pointing to the same object, otherwise
261	returns false.
262	*/
263	/*!
264	\fn bool operator!=(const QPointer<T> &p1, const QPointer<T> &p2)
265	\relates QPointer
266
267	Inequality operator. Returns true if the guarded pointers \a p1 and
268	\a p2 are not pointing to the same object, otherwise
269	returns false.
270	*/

Gitorious