Add Qt3 development HEAD version

1 files changed, 248 insertions, 0 deletions

diff --git a/doc/collect.doc b/doc/collect.doc
new file mode 100644
index 0000000..7e05047
--- /dev/null
+++ b/doc/collect.doc
@@ -0,0 +1,248 @@
+/****************************************************************************
+**
+** Qt collection classes documentation
+**
+** Copyright (C) 1992-2008 Trolltech ASA.  All rights reserved.
+**
+** This file is part of the Qt GUI Toolkit.
+**
+** This file may be used under the terms of the GNU General
+** Public License versions 2.0 or 3.0 as published by the Free
+** Software Foundation and appearing in the files LICENSE.GPL2
+** and LICENSE.GPL3 included in the packaging of this file.
+** Alternatively you may (at your option) use any later version
+** of the GNU General Public License if such license has been
+** publicly approved by Trolltech ASA (or its successors, if any)
+** and the KDE Free Qt Foundation.
+**
+** Please review the following information to ensure GNU General
+** Public Licensing requirements will be met:
+** http://trolltech.com/products/qt/licenses/licensing/opensource/.
+** If you are unsure which license is appropriate for your use, please
+** review the following information:
+** http://trolltech.com/products/qt/licenses/licensing/licensingoverview
+** or contact the sales department at sales@trolltech.com.
+**
+** This file may be used under the terms of the Q Public License as
+** defined by Trolltech ASA and appearing in the file LICENSE.QPL
+** included in the packaging of this file.  Licensees holding valid Qt
+** Commercial licenses may use this file in accordance with the Qt
+** Commercial License Agreement provided with the Software.
+**
+** This file is provided "AS IS" with NO WARRANTY OF ANY KIND,
+** INCLUDING THE WARRANTIES OF DESIGN, MERCHANTABILITY AND FITNESS FOR
+** A PARTICULAR PURPOSE. Trolltech reserves all rights not granted
+** herein.
+**
+**********************************************************************/
+
+/*!
+\defgroup collection
+
+\title Collection Classes
+
+\keyword collection classes
+\keyword persistent data
+
+A collection class is a container which holds a number of items in a
+data structure and provides various operations to manipulate the
+contents of the collection, such as insert item, remove item, find
+item, etc.
+
+Qt has several value-based and several pointer-based collection
+classes. The pointer-based collection classes work with pointers to
+items, while the value-based classes store copies of their items. The
+value-based collections are very similar to STL container classes, and
+can be used with STL algorithms and containers. See the \link
+qt-template-lib.html Qt Template Library\endlink documentation for
+details.
+
+The value-based collections are:
+\list
+\i \l QValueList, a value-based list.
+\i \l QValueVector, a value-based vector.
+\i \l QValueStack, a value-based stack.
+\i \l QMap, a value-based dictionary (associative array).
+\endlist
+
+The pointer-based collections are:
+\list
+\i \l QCache and \l QIntCache, LRU (least recently used) caches.
+\i \l QDict, \l QIntDict and \l QPtrDict dictionaries.
+\i \l QPtrList, a doubly linked list.
+\i \l QPtrQueue, a FIFO (first in, first out) queue.
+\i \l QPtrStack, a LIFO (last in, first out) stack.
+\i \l QPtrVector, a vector.
+\endlist
+
+\l QMemArray is exceptional; it is neither pointer nor value based,
+but memory based. For maximum efficiency with the simple data types
+usually used in arrays, it uses bitwise operations to copy and compare
+array elements.
+
+Some of these classes have corresponding iterators. An iterator
+is a class for traversing the items in a collection:
+\list
+\i \link QCacheIterator QCacheIterator\endlink and
+	\link QIntCacheIterator QIntCacheIterator\endlink
+\i \link QDictIterator QDictIterator\endlink,
+	\link QIntDictIterator QIntDictIterator\endlink, and
+	\link QPtrDictIterator QPtrDictIterator\endlink
+\i \link QPtrListIterator QPtrListIterator\endlink
+\i \link QValueListIterator QValueListIterator\endlink, and
+	\link QValueListConstIterator QValueListConstIterator\endlink
+\i \link QMapIterator QMapIterator\endlink, and
+	\link QMapConstIterator QMapConstIterator\endlink
+\endlist
+
+The value-based collections plus algorithms operating on them are
+grouped together in the \link qt-template-lib.html Qt Template
+Library\endlink; see also the \link qtl.html Qt Template
+Library Classes\endlink.
+
+The rest of this page dicusses the pointer-based containers.
+
+\section1 Architecture of the pointer-based containers
+
+There are four internal base classes for the pointer-based
+containers (QGCache, QGDict, QGList and QGVector) that operate on
+void pointers. A thin template layer implements the actual
+collections by casting item pointers to and from void pointers.
+
+This strategy allows Qt's templates to be very economical on space
+(instantiating one of these templates adds only inlinable calls to
+the base classes), without hurting performance.
+
+\section1 A QPtrList Example
+
+This example shows how to store Employee items in a list and prints
+them out in reverse order:
+
+\code
+    #include <qptrlist.h>
+    #include <qstring.h>
+    #include <stdio.h>
+
+    class Employee
+    {
+    public:
+        Employee( const char *name, int salary ) { n=name; s=salary; }
+        const char *name()   const		 { return n; }
+        int	    salary() const		 { return s; }
+    private:
+        QString     n;
+        int         s;
+    };
+
+    int main()
+    {
+	QPtrList<Employee> list;	// list of pointers to Employee
+	list.setAutoDelete( TRUE );	// delete items when they are removed
+
+	list.append( new Employee("Bill", 50000) );
+	list.append( new Employee("Steve",80000) );
+	list.append( new Employee("Ron",  60000) );
+
+	QPtrListIterator<Employee> it(list); // iterator for employee list
+	for ( it.toLast(); it.current(); --it) ) {
+	    Employee *emp = it.current();
+	    printf( "%s earns %d\n", emp->name(), emp->salary() );
+        }
+
+	return 0;
+    }
+\endcode
+
+Program output:
+\code
+    Ron earns 60000
+    Steve earns 80000
+    Bill earns 50000
+\endcode
+
+\section1 Managing Collection Items
+
+All pointer-based collections inherit the \l QPtrCollection base class.
+This class only knows about the number of items in the collection and
+the deletion strategy.
+
+By default, items in a collection are not deleted when they are
+removed from the collection. The \l QPtrCollection::setAutoDelete()
+function specifies the deletion strategy. In the list example, we
+enable auto-deletion to make the list delete the items when they are
+removed from the list.
+
+When inserting an item into a collection, only the pointer is copied,
+not the item itself. This is called a shallow copy. It is possible to
+make the collection copy all of the item's data (known as a deep copy)
+when an item is inserted. All collection functions that insert an
+item call the virtual function \l QPtrCollection::newItem() for the item
+to be inserted. Inherit a collection and reimplement it if you want
+to have deep copies in your collection.
+
+When removing an item from a list, the virtual function
+\l{QPtrCollection::deleteItem()} is called. The default implementation
+in all collection classes deletes the item if auto-deletion is
+enabled.
+
+\section1 Usage
+
+A pointer-based collection class, such as QPtrList\<type\>, defines a
+collection of \e pointers to \e type objects. The pointer (*) is
+implicit.
+
+We discuss \l QPtrList here, but the same techniques apply to all
+pointer-based collection classes and all collection class iterators.
+
+Template instantiation:
+\code
+    QPtrList<Employee> list;		// wherever the list is used
+\endcode
+
+The item's class or type, Employee in our example, must be defined prior
+to the list definition.
+
+\code
+    // Does not work: Employee is not defined
+    class Employee;
+    QPtrList<Employee> list;
+
+    // This works: Employee is defined before it is used
+    class Employee {
+        ...
+    };
+    QPtrList<Employee> list;
+\endcode
+
+\section1 Iterators
+
+Although \l QPtrList has member functions to traverse the list, it can
+often be better to make use of an iterator. \l QPtrListIterator is very
+safe and can traverse lists that are being modified at the same time.
+Multiple iterators can work independently on the same collection.
+
+A QPtrList has an internal list of all the iterators that are
+currently operating on it. When a list entry is removed, the list
+updates all iterators accordingly.
+
+The \l QDict and \l QCache collections have no traversal functions. To
+traverse these collections, you must use \l QDictIterator or \l
+QCacheIterator.
+
+\section1 Predefined Collections
+
+Qt has the following predefined collection classes:
+\list
+\i String lists: \l QStrList, \l QStrIList (\l qstrlist.h) and
+	\l QStringList (\l qstringlist.h)
+\i String vectors: QStrVec and QStrIVec (qstrvec.h); these are obsolete
+\endlist
+
+In almost all cases you would choose \l QStringList, a value
+list of implicitly shared QString Unicode strings. QPtrStrList and
+QPtrStrIList store only char pointers, not the strings themselves.
+
+\section1 List of Pointer-based Collection Classes and Related
+Iterator Classes
+
+*/