← Back to branch summary

~oif-team/ubuntu/natty/qt4-x11/xi2.1

« back to all changes in this revision

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

  • Committer: Bazaar Package Importer
  • Author(s): Adam Conrad
  • Date: 2005-08-24 04:09:09 UTC
  • Revision ID: james.westby@ubuntu.com-20050824040909-xmxe9jfr4a0w5671
Tags: upstream-4.0.0
Import upstream version 4.0.0

Show diffs side-by-side

added added

removed removed

Lines of Context:
src/corelib/kernel/qpointer.cpp
 
1
/****************************************************************************
 
2
**
 
3
** Copyright (C) 1992-2005 Trolltech AS. All rights reserved.
 
4
**
 
5
** This file is part of the core module of the Qt Toolkit.
 
6
**
 
7
** This file may be distributed under the terms of the Q Public License
 
8
** as defined by Trolltech AS of Norway and appearing in the file
 
9
** LICENSE.QPL included in the packaging of this file.
 
10
**
 
11
** This file may be distributed and/or modified under the terms of the
 
12
** GNU General Public License version 2 as published by the Free Software
 
13
** Foundation and appearing in the file LICENSE.GPL included in the
 
14
** packaging of this file.
 
15
**
 
16
** See http://www.trolltech.com/pricing.html or email sales@trolltech.com for
 
17
**   information about Qt Commercial License Agreements.
 
18
** See http://www.trolltech.com/qpl/ for QPL licensing information.
 
19
** See http://www.trolltech.com/gpl/ for GPL licensing information.
 
20
**
 
21
** Contact info@trolltech.com if any conditions of this licensing are
 
22
** not clear to you.
 
23
**
 
24
** This file is provided AS IS with NO WARRANTY OF ANY KIND, INCLUDING THE
 
25
** WARRANTY OF DESIGN, MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
 
26
**
 
27
****************************************************************************/
 
28
 
 
29
/*!
 
30
    \class QPointer
 
31
    \brief The QPointer class is a template class that provides guarded pointers to QObjects.
 
32
 
 
33
    \ingroup objectmodel
 
34
    \mainclass
 
35
 
 
36
    A guarded pointer, QPointer<T>, behaves like a normal C++
 
37
    pointer \c{T *}, except that it is automatically set to 0 when the
 
38
    referenced object is destroyed (unlike normal C++ pointers, which
 
39
    become "dangling pointers" in such cases). \c T must be a
 
40
    subclass of QObject.
 
41
 
 
42
    Guarded pointers are useful whenever you need to store a pointer
 
43
    to a QObject that is owned by someone else, and therefore might be
 
44
    destroyed while you still hold a reference to it. You can safely
 
45
    test the pointer for validity.
 
46
 
 
47
    Example:
 
48
 
 
49
    \quotefromfile snippets/pointer/pointer.cpp
 
50
    \skipto QPointer<QLabel> label
 
51
    \printuntil setText(
 
52
    \dots
 
53
    \printline if (label)
 
54
    \printline show()
 
55
 
 
56
    If the QLabel is deleted in the meantime, the \c label variable
 
57
    will hold 0 instead of an invalid address, and the last line will
 
58
    never be executed.
 
59
 
 
60
    The functions and operators available with a QPointer are the
 
61
    same as those available with a normal unguarded pointer, except
 
62
    the pointer arithmetic operators (\c{+}, \c{-}, \c{++}, and
 
63
    \c{--}), which are normally used only with arrays of objects.
 
64
 
 
65
    Use QPointers like normal pointers and you will not need to read
 
66
    this class documentation.
 
67
 
 
68
    For creating guarded pointers, you can construct or assign to them
 
69
    from a T* or from another guarded pointer of the same type. You
 
70
    can compare them with each other using operator==() and
 
71
    operator!=(), or test for 0 with isNull(). You can dereference
 
72
    them using either the \c *x or the \c x->member notation.
 
73
 
 
74
    A guarded pointer will automatically cast to a \c T *, so you can
 
75
    freely mix guarded and unguarded pointers. This means that if you
 
76
    have a QPointer<QWidget>, you can pass it to a function that
 
77
    requires a QWidget *. For this reason, it is of little value to
 
78
    declare functions to take a QPointer as a parameter; just use
 
79
    normal pointers. Use a QPointer when you are storing a pointer
 
80
    over time.
 
81
 
 
82
    Note that class \c T must inherit QObject, or a compilation or
 
83
    link error will result.
 
84
 
 
85
    \sa QObject, QObjectCleanupHandler
 
86
*/
 
87
 
 
88
/*!
 
89
    \fn QPointer::QPointer()
 
90
 
 
91
    Constructs a 0 guarded pointer.
 
92
 
 
93
    \sa isNull()
 
94
*/
 
95
 
 
96
/*!
 
97
    \fn QPointer::QPointer(T* p)
 
98
 
 
99
    Constructs a guarded pointer that points to same object that \a p
 
100
    points to.
 
101
*/
 
102
 
 
103
/*!
 
104
    \fn QPointer::QPointer(const QPointer<T> &p)
 
105
 
 
106
    Copies one guarded pointer from another. The constructed guarded
 
107
    pointer points to the same object that \a p points to (which may
 
108
    be 0).
 
109
*/
 
110
 
 
111
/*!
 
112
    \fn QPointer::~QPointer()
 
113
 
 
114
    Destroys the guarded pointer. Just like a normal pointer,
 
115
    destroying a guarded pointer does \e not destroy the object being
 
116
    pointed to.
 
117
*/
 
118
 
 
119
/*!
 
120
    \fn QPointer<T>& QPointer::operator=(const QPointer<T> &p)
 
121
 
 
122
    Assignment operator. This guarded pointer will now point to the
 
123
    same object that \a p points to.
 
124
*/
 
125
 
 
126
/*!
 
127
    \fn QPointer<T> & QPointer::operator=(T* p)
 
128
 
 
129
    \overload
 
130
 
 
131
    Assignment operator. This guarded pointer will now point to the
 
132
    same object that \a p points to.
 
133
*/
 
134
 
 
135
/*!
 
136
    \fn bool QPointer::isNull() const
 
137
 
 
138
    Returns \c true if the referenced object has been destroyed or if
 
139
    there is no referenced object; otherwise returns false.
 
140
*/
 
141
 
 
142
/*!
 
143
    \fn T* QPointer::operator->() const
 
144
 
 
145
    Overloaded arrow operator; implements pointer semantics. Just use
 
146
    this operator as you would with a normal C++ pointer.
 
147
*/
 
148
 
 
149
/*!
 
150
    \fn T& QPointer::operator*() const
 
151
 
 
152
    Dereference operator; implements pointer semantics. Just use this
 
153
    operator as you would with a normal C++ pointer.
 
154
*/
 
155
 
 
156
/*!
 
157
    \fn QPointer::operator T*() const
 
158
 
 
159
    Cast operator; implements pointer semantics. Because of this
 
160
    function you can pass a QPointer\<T\> to a function where a T*
 
161
    is required.
 
162
*/
 
163
 
 
164
/*!
 
165
    \fn bool operator==(const T *o, const QPointer<T> &p)
 
166
 
 
167
    Equality operator. Returns true if \a o and the guarded
 
168
    pointer \a p are pointing to the same object, otherwise
 
169
    returns false.
 
170
 
 
171
*/
 
172
/*!
 
173
    \fn bool operator==(const QPointer<T> &p, const T *o)
 
174
 
 
175
    Equality operator. Returns true if \a o and the guarded
 
176
    pointer \a p are pointing to the same object, otherwise
 
177
    returns false.
 
178
 
 
179
*/
 
180
/*!
 
181
    \fn bool operator==(T *o, const QPointer<T> &p)
 
182
 
 
183
    Equality operator. Returns true if \a o and the guarded
 
184
    pointer \a p are pointing to the same object, otherwise
 
185
    returns false.
 
186
 
 
187
*/
 
188
/*!
 
189
    \fn bool operator==(const QPointer<T> &p, T *o)
 
190
 
 
191
    Equality operator. Returns true if \a o and the guarded
 
192
    pointer \a p are pointing to the same object, otherwise
 
193
    returns false.
 
194
 
 
195
*/
 
196
/*!
 
197
    \fn bool operator==(const QPointer<T> &p1, const QPointer<T> &p2)
 
198
 
 
199
    Equality operator. Returns true if the guarded pointers \a p1 and \a p2
 
200
    are pointing to the same object, otherwise
 
201
    returns false.
 
202
 
 
203
*/
 
204
 
 
205
 
 
206
/*!
 
207
    \fn bool operator!=(const T *o, const QPointer<T> &p)
 
208
 
 
209
    Inequality operator. Returns true if \a o and the guarded
 
210
    pointer \a p are not pointing to the same object, otherwise
 
211
    returns false.
 
212
*/
 
213
/*!
 
214
    \fn bool operator!=(const QPointer<T> &p, const T *o)
 
215
 
 
216
    Inequality operator. Returns true if \a o and the guarded
 
217
    pointer \a p are not pointing to the same object, otherwise
 
218
    returns false.
 
219
*/
 
220
/*!
 
221
    \fn bool operator!=(T *o, const QPointer<T> &p)
 
222
 
 
223
    Inequality operator. Returns true if \a o and the guarded
 
224
    pointer \a p are not pointing to the same object, otherwise
 
225
    returns false.
 
226
*/
 
227
/*!
 
228
    \fn bool operator!=(const QPointer<T> &p, T *o)
 
229
 
 
230
    Inequality operator. Returns true if \a o and the guarded
 
231
    pointer \a p are not pointing to the same object, otherwise
 
232
    returns false.
 
233
*/
 
234
/*!
 
235
    \fn bool operator!=(const QPointer<T> &p1, const QPointer<T> &p2)
 
236
 
 
237
    Inequality operator. Returns true if  the guarded pointers \a p1 and
 
238
    \a p2 are not pointing to the same object, otherwise
 
239
    returns false.
 
240
*/