|
1 /**************************************************************************** |
|
2 ** |
|
3 ** |
|
4 ** Implementation of base class for all collection classes |
|
5 ** |
|
6 ** Created : 920820 |
|
7 ** |
|
8 ** Copyright (C) 1992-2000 Trolltech AS. All rights reserved. |
|
9 ** |
|
10 ** This file is part of the tools module of the Qt GUI Toolkit. |
|
11 ** |
|
12 ** This file may be distributed under the terms of the Q Public License |
|
13 ** as defined by Trolltech AS of Norway and appearing in the file |
|
14 ** LICENSE.QPL included in the packaging of this file. |
|
15 ** |
|
16 ** This file may be distributed and/or modified under the terms of the |
|
17 ** GNU General Public License version 2 as published by the Free Software |
|
18 ** Foundation and appearing in the file LICENSE.GPL included in the |
|
19 ** packaging of this file. |
|
20 ** |
|
21 ** Licensees holding valid Qt Enterprise Edition or Qt Professional Edition |
|
22 ** licenses may use this file in accordance with the Qt Commercial License |
|
23 ** Agreement provided with the Software. |
|
24 ** |
|
25 ** This file is provided AS IS with NO WARRANTY OF ANY KIND, INCLUDING THE |
|
26 ** WARRANTY OF DESIGN, MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. |
|
27 ** |
|
28 ** See http://www.trolltech.com/pricing.html or email sales@trolltech.com for |
|
29 ** information about Qt Commercial License Agreements. |
|
30 ** See http://www.trolltech.com/qpl/ for QPL licensing information. |
|
31 ** See http://www.trolltech.com/gpl/ for GPL licensing information. |
|
32 ** |
|
33 ** Contact info@trolltech.com if any conditions of this licensing are |
|
34 ** not clear to you. |
|
35 ** |
|
36 **********************************************************************/ |
|
37 |
|
38 #include "qcollection.h" |
|
39 |
|
40 // NOT REVISED |
|
41 /*! |
|
42 \class QCollection qcollection.h |
|
43 \brief The QCollection class is the base class of all Qt collections. |
|
44 |
|
45 \ingroup collection |
|
46 \ingroup tools |
|
47 |
|
48 The QCollection class is an abstract base class for the Qt \link |
|
49 collection.html collection classes\endlink QDict, QList etc. via QGDict, |
|
50 QGList etc. |
|
51 |
|
52 A QCollection knows only about the number of objects in the |
|
53 collection and the deletion strategy (see setAutoDelete()). |
|
54 |
|
55 A collection is implemented using the \c Item (generic collection |
|
56 item) type, which is a \c void*. The template classes that create |
|
57 the real collections cast the \c Item to the required type. |
|
58 |
|
59 \sa \link collection.html Collection Classes\endlink |
|
60 */ |
|
61 |
|
62 |
|
63 /*! \enum QCollection::Item |
|
64 |
|
65 This type is the generic "item" in a QCollection. |
|
66 */ |
|
67 |
|
68 |
|
69 /*! |
|
70 \fn QCollection::QCollection() |
|
71 |
|
72 Constructs a collection. The constructor is protected because |
|
73 QCollection is an abstract class. |
|
74 */ |
|
75 |
|
76 /*! |
|
77 \fn QCollection::QCollection( const QCollection & source ) |
|
78 |
|
79 Constructs a copy of \a source with autoDelete() set to FALSE. The |
|
80 constructor is protected because QCollection is an abstract class. |
|
81 |
|
82 Note that if \a source has autoDelete turned on, copying it is a |
|
83 good way to get memory leaks, reading freed memory, or both. |
|
84 */ |
|
85 |
|
86 /*! |
|
87 \fn QCollection::~QCollection() |
|
88 Destroys the collection. The destructor is protected because QCollection |
|
89 is an abstract class. |
|
90 */ |
|
91 |
|
92 |
|
93 /*! |
|
94 \fn bool QCollection::autoDelete() const |
|
95 Returns the setting of the auto-delete option (default is FALSE). |
|
96 \sa setAutoDelete() |
|
97 */ |
|
98 |
|
99 /*! |
|
100 \fn void QCollection::setAutoDelete( bool enable ) |
|
101 |
|
102 Sets the auto-delete option of the collection. |
|
103 |
|
104 Enabling auto-delete (\e enable is TRUE) will delete objects that |
|
105 are removed from the collection. This can be useful if the |
|
106 collection has the only reference to the objects. (Note that the |
|
107 object can still be copied using the copy constructor - copying such |
|
108 objects is a good way to get memory leaks, reading freed memory or |
|
109 both.) |
|
110 |
|
111 Disabling auto-delete (\e enable is FALSE) will \e not delete objects |
|
112 that are removed from the collection. This is useful if the objects |
|
113 are part of many collections. |
|
114 |
|
115 The default setting is FALSE. |
|
116 |
|
117 \sa autoDelete() |
|
118 */ |
|
119 |
|
120 |
|
121 /*! |
|
122 \fn virtual uint QCollection::count() const |
|
123 Returns the number of objects in the collection. |
|
124 */ |
|
125 |
|
126 /*! |
|
127 \fn virtual void QCollection::clear() |
|
128 Removes all objects from the collection. The objects will be deleted |
|
129 if auto-delete has been enabled. |
|
130 \sa setAutoDelete() |
|
131 */ |
|
132 |
|
133 |
|
134 /*! |
|
135 Virtual function that creates a copy of an object that is about to |
|
136 be inserted into the collection. |
|
137 |
|
138 The default implementation returns the \e d pointer, i.e. no copy |
|
139 is made. |
|
140 |
|
141 This function is seldom reimplemented in the collection template |
|
142 classes. It is not common practice to make a copy of something |
|
143 that is being inserted. |
|
144 |
|
145 \sa deleteItem() |
|
146 */ |
|
147 |
|
148 QCollection::Item QCollection::newItem( Item d ) |
|
149 { |
|
150 return d; // just return reference |
|
151 } |
|
152 |
|
153 /*! |
|
154 Virtual function that deletes an item that is about to be removed from |
|
155 the collection. |
|
156 |
|
157 The default implementation deletes \e d pointer if and only if |
|
158 auto-delete has been enabled. |
|
159 |
|
160 This function is always reimplemented in the collection template |
|
161 classes. |
|
162 |
|
163 \warning If you reimplement this function you must also reimplement |
|
164 the destructor and call the virtual function clear() from your |
|
165 destructor. This is due to the way virtual functions and |
|
166 destructors work in C++: virtual functions in derived classes cannot |
|
167 be called from a destructor. If you do not do this your |
|
168 deleteItem() function will not be called when the container is |
|
169 destructed. |
|
170 |
|
171 \sa newItem(), setAutoDelete() |
|
172 */ |
|
173 |
|
174 void QCollection::deleteItem( Item d ) |
|
175 { |
|
176 if ( del_item ) |
|
177 #if defined(Q_DELETING_VOID_UNDEFINED) |
|
178 delete (char *)d; // default operation |
|
179 #else |
|
180 delete d; // default operation |
|
181 #endif |
|
182 } |