source: trunk/src/corelib/kernel/qpointer.cpp@ 67

Last change on this file since 67 was 2, checked in by Dmitry A. Kuminov, 16 years ago

Initially imported qt-all-opensource-src-4.5.1 from Trolltech.
File size: 8.1 KB
Line 
1/****************************************************************************
2**
3** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
4** Contact: Qt Software Information ([email protected])
5**
6** This file is part of the QtCore module of the Qt Toolkit.
7**
8** $QT_BEGIN_LICENSE:LGPL$
9** Commercial Usage
10** Licensees holding valid Qt Commercial licenses may use this file in
11** accordance with the Qt Commercial License Agreement provided with the
12** Software or, alternatively, in accordance with the terms contained in
13** a written agreement between you and Nokia.
14**
15** GNU Lesser General Public License Usage
16** Alternatively, this file may be used under the terms of the GNU Lesser
17** General Public License version 2.1 as published by the Free Software
18** Foundation and appearing in the file LICENSE.LGPL included in the
19** packaging of this file. Please review the following information to
20** ensure the GNU Lesser General Public License version 2.1 requirements
21** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
22**
23** In addition, as a special exception, Nokia gives you certain
24** additional rights. These rights are described in the Nokia Qt LGPL
25** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this
26** package.
27**
28** GNU General Public License Usage
29** Alternatively, this file may be used under the terms of the GNU
30** General Public License version 3.0 as published by the Free Software
31** Foundation and appearing in the file LICENSE.GPL included in the
32** packaging of this file. Please review the following information to
33** ensure the GNU General Public License version 3.0 requirements will be
34** met: http://www.gnu.org/copyleft/gpl.html.
35**
36** If you are unsure which license is appropriate for your use, please
37** contact the sales department at [email protected].
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 QObjects.
45
46 \ingroup objectmodel
47 \mainclass
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, 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.