qtools/qcollection.cpp

   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 }