← Back to branch summary

~ubuntu-branches/ubuntu/wily/qtbase-opensource-src/wily

« back to all changes in this revision

Viewing changes to src/corelib/kernel/qpointer.cpp

  • Committer: Package Import Robot
  • Author(s): Timo Jyrinki
  • Date: 2013-02-05 12:46:17 UTC
  • Revision ID: package-import@ubuntu.com-20130205124617-c8jouts182j002fx
Tags: upstream-5.0.1+dfsg
Import upstream version 5.0.1+dfsg

Show diffs side-by-side

added added

removed removed

Lines of Context:
src/corelib/kernel/qpointer.cpp
 
1
/****************************************************************************
 
2
**
 
3
** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
 
4
** Contact: http://www.qt-project.org/legal
 
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 Digia.  For licensing terms and
 
14
** conditions see http://qt.digia.com/licensing.  For further information
 
15
** use the contact form at http://qt.digia.com/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 2.1 as published by the Free Software
 
20
** Foundation and appearing in the file LICENSE.LGPL included in the
 
21
** packaging of this file.  Please review the following information to
 
22
** ensure the GNU Lesser General Public License version 2.1 requirements
 
23
** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
 
24
**
 
25
** In addition, as a special exception, Digia gives you certain additional
 
26
** rights.  These rights are described in the Digia Qt LGPL Exception
 
27
** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
 
28
**
 
29
** GNU General Public License Usage
 
30
** Alternatively, this file may be used under the terms of the GNU
 
31
** General Public License version 3.0 as published by the Free Software
 
32
** Foundation and appearing in the file LICENSE.GPL included in the
 
33
** packaging of this file.  Please review the following information to
 
34
** ensure the GNU General Public License version 3.0 requirements will be
 
35
** met: http://www.gnu.org/copyleft/gpl.html.
 
36
**
 
37
**
 
38
** $QT_END_LICENSE$
 
39
**
 
40
****************************************************************************/
 
41
 
 
42
/*!
 
43
    \class QPointer
 
44
    \inmodule QtCore
 
45
    \brief The QPointer class is a template class that provides guarded pointers to QObject.
 
46
 
 
47
    \ingroup objectmodel
 
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
    Note that Qt 5 introduces a slight change in behavior when using QPointer.
 
61
 
 
62
    \list
 
63
 
 
64
    \li When using QPointer on a QWidget (or a subclass of QWidget), previously
 
65
    the QPointer would be cleared by the QWidget destructor. Now, the QPointer
 
66
    is cleared by the QObject destructor (since this is when QWeakPointers are
 
67
    cleared). Any QPointers tracking a widget will \b NOT be cleared before the
 
68
    QWidget destructor destroys the children for the widget being tracked.
 
69
 
 
70
    \endlist
 
71
 
 
72
    Qt also provides QSharedPointer, an implementation of a reference-counted
 
73
    shared pointer object, which can be used to maintain a collection of
 
74
    references to an individual pointer.
 
75
 
 
76
    Example:
 
77
 
 
78
    \snippet pointer/pointer.cpp 0
 
79
    \dots
 
80
    \snippet pointer/pointer.cpp 1
 
81
    \snippet pointer/pointer.cpp 2
 
82
 
 
83
    If the QLabel is deleted in the meantime, the \c label variable
 
84
    will hold 0 instead of an invalid address, and the last line will
 
85
    never be executed.
 
86
 
 
87
    The functions and operators available with a QPointer are the
 
88
    same as those available with a normal unguarded pointer, except
 
89
    the pointer arithmetic operators (\c{+}, \c{-}, \c{++}, and
 
90
    \c{--}), which are normally used only with arrays of objects.
 
91
 
 
92
    Use QPointers like normal pointers and you will not need to read
 
93
    this class documentation.
 
94
 
 
95
    For creating guarded pointers, you can construct or assign to them
 
96
    from a T* or from another guarded pointer of the same type. You
 
97
    can compare them with each other using operator==() and
 
98
    operator!=(), or test for 0 with isNull(). You can dereference
 
99
    them using either the \c *x or the \c x->member notation.
 
100
 
 
101
    A guarded pointer will automatically cast to a \c T *, so you can
 
102
    freely mix guarded and unguarded pointers. This means that if you
 
103
    have a QPointer<QWidget>, you can pass it to a function that
 
104
    requires a QWidget *. For this reason, it is of little value to
 
105
    declare functions to take a QPointer as a parameter; just use
 
106
    normal pointers. Use a QPointer when you are storing a pointer
 
107
    over time.
 
108
 
 
109
    Note that class \c T must inherit QObject, or a compilation or
 
110
    link error will result.
 
111
 
 
112
    \sa QSharedPointer, QObject, QObjectCleanupHandler
 
113
*/
 
114
 
 
115
/*!
 
116
    \fn QPointer::QPointer()
 
117
 
 
118
    Constructs a 0 guarded pointer.
 
119
 
 
120
    \sa isNull()
 
121
*/
 
122
 
 
123
/*!
 
124
    \fn QPointer::QPointer(T* p)
 
125
 
 
126
    Constructs a guarded pointer that points to the same object that \a p
 
127
    points to.
 
128
*/
 
129
 
 
130
/*!
 
131
    \fn QPointer::~QPointer()
 
132
 
 
133
    Destroys the guarded pointer. Just like a normal pointer,
 
134
    destroying a guarded pointer does \e not destroy the object being
 
135
    pointed to.
 
136
*/
 
137
 
 
138
/*!
 
139
    \fn QPointer<T> & QPointer::operator=(T* p)
 
140
 
 
141
    Assignment operator. This guarded pointer will now point to the
 
142
    same object that \a p points to.
 
143
*/
 
144
 
 
145
/*!
 
146
    \fn T* QPointer::data() const
 
147
    \since 4.4
 
148
 
 
149
    Returns the pointer to the object being guarded.
 
150
*/
 
151
 
 
152
/*!
 
153
    \fn bool QPointer::isNull() const
 
154
 
 
155
    Returns \c true if the referenced object has been destroyed or if
 
156
    there is no referenced object; otherwise returns false.
 
157
*/
 
158
 
 
159
/*!
 
160
    \fn void QPointer::clear()
 
161
 
 
162
    Clears this QPointer object.
 
163
 
 
164
    \sa isNull()
 
165
*/
 
166
 
 
167
/*!
 
168
    \fn T* QPointer::operator->() const
 
169
 
 
170
    Overloaded arrow operator; implements pointer semantics. Just use
 
171
    this operator as you would with a normal C++ pointer.
 
172
*/
 
173
 
 
174
/*!
 
175
    \fn T& QPointer::operator*() const
 
176
 
 
177
    Dereference operator; implements pointer semantics. Just use this
 
178
    operator as you would with a normal C++ pointer.
 
179
*/
 
180
 
 
181
/*!
 
182
    \fn QPointer::operator T*() const
 
183
 
 
184
    Cast operator; implements pointer semantics. Because of this
 
185
    function you can pass a QPointer\<T\> to a function where a T*
 
186
    is required.
 
187
*/
 
188
 
 
189
/*!
 
190
    \fn bool operator==(const T *o, const QPointer<T> &p)
 
191
    \relates QPointer
 
192
 
 
193
    Equality operator. Returns true if \a o and the guarded
 
194
    pointer \a p are pointing to the same object, otherwise
 
195
    returns false.
 
196
 
 
197
*/
 
198
/*!
 
199
    \fn bool operator==(const QPointer<T> &p, const T *o)
 
200
    \relates QPointer
 
201
 
 
202
    Equality operator. Returns true if \a o and the guarded
 
203
    pointer \a p are pointing to the same object, otherwise
 
204
    returns false.
 
205
 
 
206
*/
 
207
/*!
 
208
    \fn bool operator==(T *o, const QPointer<T> &p)
 
209
    \relates QPointer
 
210
 
 
211
    Equality operator. Returns true if \a o and the guarded
 
212
    pointer \a p are pointing to the same object, otherwise
 
213
    returns false.
 
214
 
 
215
*/
 
216
/*!
 
217
    \fn bool operator==(const QPointer<T> &p, T *o)
 
218
    \relates QPointer
 
219
 
 
220
    Equality operator. Returns true if \a o and the guarded
 
221
    pointer \a p are pointing to the same object, otherwise
 
222
    returns false.
 
223
 
 
224
*/
 
225
/*!
 
226
    \fn bool operator==(const QPointer<T> &p1, const QPointer<T> &p2)
 
227
    \relates QPointer
 
228
 
 
229
    Equality operator. Returns true if the guarded pointers \a p1 and \a p2
 
230
    are pointing to the same object, otherwise
 
231
    returns false.
 
232
 
 
233
*/
 
234
 
 
235
 
 
236
/*!
 
237
    \fn bool operator!=(const T *o, const QPointer<T> &p)
 
238
    \relates QPointer
 
239
 
 
240
    Inequality operator. Returns true if \a o and the guarded
 
241
    pointer \a p are not pointing to the same object, otherwise
 
242
    returns false.
 
243
*/
 
244
/*!
 
245
    \fn bool operator!=(const QPointer<T> &p, const T *o)
 
246
    \relates QPointer
 
247
 
 
248
    Inequality operator. Returns true if \a o and the guarded
 
249
    pointer \a p are not pointing to the same object, otherwise
 
250
    returns false.
 
251
*/
 
252
/*!
 
253
    \fn bool operator!=(T *o, const QPointer<T> &p)
 
254
    \relates QPointer
 
255
 
 
256
    Inequality operator. Returns true if \a o and the guarded
 
257
    pointer \a p are not pointing to the same object, otherwise
 
258
    returns false.
 
259
*/
 
260
/*!
 
261
    \fn bool operator!=(const QPointer<T> &p, T *o)
 
262
    \relates QPointer
 
263
 
 
264
    Inequality operator. Returns true if \a o and the guarded
 
265
    pointer \a p are not pointing to the same object, otherwise
 
266
    returns false.
 
267
*/
 
268
/*!
 
269
    \fn bool operator!=(const QPointer<T> &p1, const QPointer<T> &p2)
 
270
    \relates QPointer
 
271
 
 
272
    Inequality operator. Returns true if  the guarded pointers \a p1 and
 
273
    \a p2 are not pointing to the same object, otherwise
 
274
    returns false.
 
275
*/
 
276
/*!
 
277
    \fn QPointer<T> qPointerFromVariant(const QVariant &variant)
 
278
 
 
279
    \internal
 
280
 
 
281
    Returns a guarded pointer that points to the same object that
 
282
    \a variant holds.
 
283
*/