Test conversion to TQt3 from Qt3 8c6fc1f8e35fd264dd01c582ca5e7549b32ab731

1 files changed, 1259 insertions, 0 deletions

diff --git a/doc/qptrlist.doc b/doc/qptrlist.doc
new file mode 100644
index 000000000..ef5427d18
--- /dev/null
+++ b/doc/qptrlist.doc
@@ -0,0 +1,1259 @@
+/****************************************************************************
+**
+** QPtrList and QPtrListIterator class 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 retquirements 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.
+**
+**********************************************************************/
+
+
+/*****************************************************************************
+  QPtrList documentation
+ *****************************************************************************/
+
+/*!
+    \class QPtrList
+    \brief The QPtrList class is a template class that provides a list.
+
+    \ingroup collection
+    \ingroup tools
+
+    \important autoDelete setAutoDelete
+
+    QValueList is an STL-compatible alternative to this class.
+
+    Define a template instance QPtrList\<X\> to create a list that
+    operates on pointers to X (X*).
+
+    The list class is indexable and has a \link at() current
+    index\endlink and a \link current() current item\endlink. The
+    first item corresponds to index position 0. The current index is
+    -1 if the current item is 0.
+
+    Items are inserted with prepend(), insert() or append(). Items are
+    removed with remove(), removeRef(), removeFirst() and
+    removeLast(). You can search for an item using find(), findNext(),
+    findRef() or findNextRef(). The list can be sorted with sort().
+    You can count the number of occurrences of an item with contains()
+    or containsRef(). You can get a pointer to the current item with
+    current(), to an item at a particular index position in the list
+    with at() or to the first or last item with getFirst() and
+    getLast(). You can also iterate over the list with first(),
+    last(), next() and prev() (which all update current()). The list's
+    deletion property is set with setAutoDelete().
+
+    \target example
+    Example:
+    \code
+    class Employee
+    {
+    public:
+	Employee() : sn( 0 ) { }
+	Employee( const QString& forename, const QString& surname, int salary )
+	    : fn( forename ), sn( surname ), sal( salary )
+	{ }
+
+	void setSalary( int salary ) { sal = salary; }
+
+	QString forename() const { return fn; }
+	QString surname() const { return sn; }
+	int salary() const { return sal; }
+
+    private:
+	QString fn;
+	QString sn;
+	int sal;
+    };
+
+    QPtrList<Employee> list;
+    list.setAutoDelete( TRUE ); // the list owns the objects
+
+    list.append( new Employee("John", "Doe", 50000) );
+    list.append( new Employee("Jane", "Williams", 80000) );
+    list.append( new Employee("Tom", "Jones", 60000) );
+
+    Employee *employee;
+    for ( employee = list.first(); employee; employee = list.next() )
+	cout << employee->surname().latin1() << ", " <<
+		employee->forename().latin1() << " earns " <<
+		employee->salary() << endl;
+    cout << endl;
+
+    // very inefficient for big lists
+    for ( uint i = 0; i < list.count(); ++i )
+	if ( list.at(i) )
+	    cout << list.at( i )->surname().latin1() << endl;
+    \endcode
+
+    The output is
+    \code
+    Doe, John earns 50000
+    Williams, Jane earns 80000
+    Jones, Tom earns 60000
+
+    Doe
+    Williams
+    Jones
+    \endcode
+
+    QPtrList has several member functions for traversing the list, but
+    using a QPtrListIterator can be more practical. Multiple list
+    iterators may traverse the same list, independently of each other
+    and of the current list item.
+
+    In the example above we make the call setAutoDelete(TRUE).
+    Enabling auto-deletion tells the list to delete items that are
+    removed. The default is to not delete items when they are removed
+    but this would cause a memory leak in the example because there
+    are no other references to the list items.
+
+    When inserting an item into a list only the pointer is copied, not
+    the item itself, i.e. a shallow copy. It is possible to make the
+    list copy all of the item's data (deep copy) when an item is
+    inserted. insert(), inSort() and append() call the virtual
+    function QPtrCollection::newItem() for the item to be inserted.
+    Inherit a list and reimplement newItem() to have deep copies.
+
+    When removing an item from a list, the virtual function
+    QPtrCollection::deleteItem() is called. QPtrList's default
+    implementation is to delete the item if auto-deletion is enabled.
+
+    The virtual function compareItems() can be reimplemented to
+    compare two list items. This function is called from all list
+    functions that need to compare list items, for instance
+    remove(const type*). If you only want to deal with pointers, there
+    are functions that compare pointers instead, for instance
+    removeRef(const type*). These functions are somewhat faster than
+    those that call compareItems().
+
+    List items are stored as \c void* in an internal QLNode, which
+    also holds pointers to the next and previous list items. The
+    functions currentNode(), removeNode(), and takeNode() operate
+    directly on the QLNode, but they should be used with care. The
+    data component of the node is available through QLNode::getData().
+
+    The QStrList class defined in \l qstrlist.h is a list of \c char*.
+    It reimplements newItem(), deleteItem() and compareItems(). (But
+    see QStringList for a list of Unicode QStrings.)
+
+    \sa QPtrListIterator
+*/
+
+
+/*!
+    \fn QPtrList::QPtrList()
+
+    Constructs an empty list.
+*/
+
+/*!
+    \fn QPtrList::QPtrList( const QPtrList<type> &list )
+
+    Constructs a copy of \a list.
+
+    Each item in \a list is \link append() appended\endlink to this
+    list. Only the pointers are copied (shallow copy).
+*/
+
+/*!
+    \fn QPtrList::~QPtrList()
+
+    Removes all items from the list and destroys the list.
+
+    All list iterators that access this list will be reset.
+
+    \sa setAutoDelete()
+*/
+
+/*!
+    \fn QPtrList<type> &QPtrList::operator=(const QPtrList<type> &list)
+
+    Assigns \a list to this list and returns a reference to this list.
+
+    This list is first cleared and then each item in \a list is \link
+    append() appended\endlink to this list. Only the pointers are
+    copied (shallow copy) unless newItem() has been reimplemented.
+*/
+
+/*!
+    \fn bool QPtrList::operator==(const QPtrList<type> &list ) const
+
+    Compares this list with \a list. Returns TRUE if the lists contain
+    the same data; otherwise returns FALSE.
+*/
+
+/*!
+    \fn uint QPtrList::count() const
+
+    Returns the number of items in the list.
+
+    \sa isEmpty()
+*/
+
+/*!
+    \fn bool QPtrList::operator!=(const QPtrList<type> &list ) const
+
+    Compares this list with \a list. Returns TRUE if the lists contain
+    different data; otherwise returns FALSE.
+*/
+
+
+/*!
+    \fn void QPtrList::sort()
+
+    Sorts the list by the result of the virtual compareItems()
+    function.
+
+    The heap sort algorithm is used for sorting. It sorts n items with
+    O(n*log n) comparisons. This is the asymptotic optimal solution of
+    the sorting problem.
+
+    If the items in your list support operator<() and operator==(),
+    you might be better off with QSortedList because it implements the
+    compareItems() function for you using these two operators.
+
+    \sa inSort()
+*/
+
+/*!
+    \fn bool QPtrList::isEmpty() const
+
+    Returns TRUE if the list is empty; otherwise returns FALSE.
+
+    \sa count()
+*/
+
+/*!
+    \fn bool QPtrList::insert( uint index, const type *item )
+
+    Inserts the \a item at position \a index in the list.
+
+    Returns TRUE if successful, i.e. if \a index is in range;
+    otherwise returns FALSE. The valid range is 0 to count()
+    (inclusively). The item is appended if \a index == count().
+
+    The inserted item becomes the current list item.
+
+    \a item must not be 0.
+
+    \sa append(), current(), replace()
+*/
+
+/*!
+    \fn bool QPtrList::replace( uint index, const type *item )
+
+    Replaces the item at position \a index with the new \a item. 
+
+    Returns TRUE if successful, i.e. \a index is in the range 0 to
+    count()-1.
+
+    \sa append(), current(), insert()
+*/
+
+/*!
+    \fn void QPtrList::inSort( const type *item )
+
+    Inserts the \a item at its sorted position in the list.
+
+    The sort order depends on the virtual compareItems() function. All
+    items must be inserted with inSort() to maintain the sorting
+    order.
+
+    The inserted item becomes the current list item.
+
+    \a item must not be 0.
+
+    \warning Using inSort() is slow. An alternative, especially if you
+    have lots of items, is to simply append() or insert() them and
+    then use sort(). inSort() takes up to O(n) compares. That means
+    inserting n items in your list will need O(n^2) compares whereas
+    sort() only needs O(n*log n) for the same task. So use inSort()
+    only if you already have a presorted list and want to insert just
+    a few additional items.
+
+    \sa insert(), compareItems(), current(), sort()
+*/
+
+/*!
+    \fn void QPtrList::append( const type *item )
+
+    Inserts the \a item at the end of the list.
+
+    The inserted item becomes the current list item. This is
+    equivalent to \c{insert( count(), item )}.
+
+    \a item must not be 0.
+
+    \sa insert(), current(), prepend()
+*/
+
+/*!
+    \fn void QPtrList::prepend( const type *item )
+
+    Inserts the \a item at the start of the list.
+
+    The inserted item becomes the current list item. This is
+    equivalent to \c{insert( 0, item )}.
+
+    \a item must not be 0.
+
+    \sa append(), insert(), current()
+*/
+
+/*!
+    \fn bool QPtrList::remove( uint index )
+
+    Removes the item at position \a index in the list.
+
+    Returns TRUE if successful, i.e. if \a index is in range;
+    otherwise returns FALSE. The valid range is \c{0..(count() - 1)}
+    inclusive.
+
+    The removed item is deleted if \link setAutoDelete()
+    auto-deletion\endlink is enabled.
+
+    The item after the removed item becomes the new current list item
+    if the removed item is not the last item in the list. If the last
+    item is removed, the new last item becomes the current item.
+
+    All list iterators that refer to the removed item will be set to
+    point to the new current item.
+
+    \sa take(), clear(), setAutoDelete(), current() removeRef()
+*/
+
+/*!
+    \fn bool QPtrList::remove()
+
+    \overload
+
+    Removes the current list item.
+
+    Returns TRUE if successful, i.e. if the current item isn't 0;
+    otherwise returns FALSE.
+
+    The removed item is deleted if \link setAutoDelete()
+    auto-deletion\endlink is enabled.
+
+    The item after the removed item becomes the new current list item
+    if the removed item is not the last item in the list. If the last
+    item is removed, the new last item becomes the current item. The
+    current item is set to 0 if the list becomes empty.
+
+    All list iterators that refer to the removed item will be set to
+    point to the new current item.
+
+    \sa take(), clear(), setAutoDelete(), current() removeRef()
+*/
+
+/*!
+    \fn bool QPtrList::remove( const type *item )
+
+    \overload
+
+    Removes the first occurrence of \a item from the list.
+
+    Returns TRUE if successful, i.e. if \a item is in the list;
+    otherwise returns FALSE.
+
+    The removed item is deleted if \link setAutoDelete()
+    auto-deletion\endlink is enabled.
+
+    The compareItems() function is called when searching for the item
+    in the list. If compareItems() is not reimplemented, it is more
+    efficient to call removeRef().
+
+    If \a item is NULL then the current item is removed from the list.
+
+    The item after the removed item becomes the new current list item
+    if the removed item is not the last item in the list. If the last
+    item is removed, the new last item becomes the current item. The
+    current item is set to 0 if the list becomes empty.
+
+    All list iterators that refer to the removed item will be set to
+    point to the new current item.
+
+    \sa removeRef(), take(), clear(), setAutoDelete(), compareItems(),
+    current()
+*/
+
+/*!
+    \fn bool QPtrList::removeRef( const type *item )
+
+    Removes the first occurrence of \a item from the list.
+
+    Returns TRUE if successful, i.e. if \a item is in the list;
+    otherwise returns FALSE.
+
+    The removed item is deleted if \link setAutoDelete()
+    auto-deletion\endlink is enabled.
+
+    Equivalent to:
+    \code
+	if ( list.findRef( item ) != -1 )
+	    list.remove();
+    \endcode
+
+    The item after the removed item becomes the new current list item
+    if the removed item is not the last item in the list. If the last
+    item is removed, the new last item becomes the current item. The
+    current item is set to 0 if the list becomes empty.
+
+    All list iterators that refer to the removed item will be set to
+    point to the new current item.
+
+    \sa remove(), clear(), setAutoDelete(), current()
+*/
+
+/*!
+    \fn void QPtrList::removeNode( QLNode *node )
+
+    Removes the \a node from the list.
+
+    This node must exist in the list, otherwise the program may crash.
+
+    The removed item is deleted if \link setAutoDelete()
+    auto-deletion\endlink is enabled.
+
+    The first item in the list will become the new current list item.
+    The current item is set to 0 if the list becomes empty.
+
+    All list iterators that refer to the removed item will be set to
+    point to the item succeeding this item or to the preceding item if
+    the removed item was the last item.
+
+    \warning Do not call this function unless you are an expert.
+
+    \sa takeNode(), currentNode() remove() removeRef()
+*/
+
+/*!
+    \fn bool QPtrList::removeFirst()
+
+    Removes the first item from the list. Returns TRUE if successful,
+    i.e. if the list isn't empty; otherwise returns FALSE.
+
+    The removed item is deleted if \link setAutoDelete()
+    auto-deletion\endlink is enabled.
+
+    The first item in the list becomes the new current list item. The
+    current item is set to 0 if the list becomes empty.
+
+    All list iterators that refer to the removed item will be set to
+    point to the new current item.
+
+    \sa removeLast(), setAutoDelete(), current() remove()
+*/
+
+/*!
+    \fn bool QPtrList::removeLast()
+
+    Removes the last item from the list. Returns TRUE if successful,
+    i.e. if the list isn't empty; otherwise returns FALSE.
+
+    The removed item is deleted if \link setAutoDelete()
+    auto-deletion\endlink is enabled.
+
+    The last item in the list becomes the new current list item. The
+    current item is set to 0 if the list becomes empty.
+
+    All list iterators that refer to the removed item will be set to
+    point to the new current item.
+
+    \sa removeFirst(), setAutoDelete(), current()
+*/
+
+/*!
+    \fn type *QPtrList::take( uint index )
+
+    Takes the item at position \a index out of the list without
+    deleting it (even if \link setAutoDelete() auto-deletion\endlink
+    is enabled).
+
+    Returns a pointer to the item taken out of the list, or 0 if the
+    index is out of range. The valid range is \c{0..(count() - 1)}
+    inclusive.
+
+    The item after the removed item becomes the new current list item
+    if the removed item is not the last item in the list. If the last
+    item is removed, the new last item becomes the current item. The
+    current item is set to 0 if the list becomes empty.
+
+    All list iterators that refer to the taken item will be set to
+    point to the new current item.
+
+    \sa remove(), clear(), current()
+*/
+
+/*!
+    \fn type *QPtrList::take()
+
+    \overload
+
+    Takes the current item out of the list without deleting it (even
+    if \link setAutoDelete() auto-deletion\endlink is enabled).
+
+    Returns a pointer to the item taken out of the list, or 0 if
+    the current item is 0.
+
+    The item after the removed item becomes the new current list item
+    if the removed item is not the last item in the list. If the last
+    item is removed, the new last item becomes the current item. The
+    current item is set to 0 if the list becomes empty.
+
+    All list iterators that refer to the taken item will be set to
+    point to the new current item.
+
+    \sa remove(), clear(), current()
+*/
+
+/*!
+    \fn type *QPtrList::takeNode( QLNode *node )
+
+    Takes the \a node out of the list without deleting its item (even
+    if \link setAutoDelete() auto-deletion\endlink is enabled).
+    Returns a pointer to the item taken out of the list.
+
+    This node must exist in the list, otherwise the program may crash.
+
+    The first item in the list becomes the new current list item.
+
+    All list iterators that refer to the taken item will be set to
+    point to the item succeeding this item or to the preceding item if
+    the taken item was the last item.
+
+    \warning Do not call this function unless you are an expert.
+
+    \sa removeNode(), currentNode()
+*/
+
+/*!
+    \fn void QPtrList::clear()
+
+    Removes all items from the list.
+
+    The removed items are deleted if \link setAutoDelete()
+    auto-deletion\endlink is enabled.
+
+    All list iterators that access this list will be reset.
+
+    \sa remove(), take(), setAutoDelete()
+*/
+
+/*!
+    \fn int QPtrList::find( const type *item )
+
+    Finds the first occurrence of \a item in the list.
+
+    If the item is found, the list sets the current item to point to
+    the found item and returns the index of this item. If the item is
+    not found, the list sets the current item to 0, the current
+    index to -1, and returns -1.
+
+    The compareItems() function is called when searching for the item
+    in the list. If compareItems() is not reimplemented, it is more
+    efficient to call findRef().
+
+    \sa findNext(), findRef(), compareItems(), current()
+*/
+
+/*!
+    \fn int QPtrList::findNext( const type *item )
+
+    Finds the next occurrence of \a item in the list, starting from
+    the current list item.
+
+    If the item is found, the list sets the current item to point to
+    the found item and returns the index of this item. If the item is
+    not found, the list sets the current item to 0, the current
+    index to -1, and returns -1.
+
+    The compareItems() function is called when searching for the item
+    in the list. If compareItems() is not reimplemented, it is more
+    efficient to call findNextRef().
+
+    \sa find(), findNextRef(), compareItems(), current()
+*/
+
+/*!
+    \fn int QPtrList::findRef( const type *item )
+
+    Finds the first occurrence of \a item in the list.
+
+    If the item is found, the list sets the current item to point to
+    the found item and returns the index of this item. If the item is
+    not found, the list sets the current item to 0, the current
+    index to -1, and returns -1.
+
+    Calling this function is much faster than find() because find()
+    compares \a item with each list item using compareItems(), whereas
+    this function only compares the pointers.
+
+    \sa findNextRef(), find(), current()
+*/
+
+/*!
+    \fn int QPtrList::findNextRef( const type *item )
+
+    Finds the next occurrence of \a item in the list, starting from
+    the current list item.
+
+    If the item is found, the list sets the current item to point to
+    the found item and returns the index of this item. If the item is
+    not found, the list sets the current item to 0, the current
+    index to -1, and returns -1.
+
+    Calling this function is much faster than findNext() because
+    findNext() compares \a item with each list item using
+    compareItems(), whereas this function only compares the pointers.
+
+    \sa findRef(), findNext(), current()
+*/
+
+/*!
+    \fn uint QPtrList::contains( const type *item ) const
+
+    Returns the number of occurrences of \a item in the list.
+
+    The compareItems() function is called when looking for the \a item
+    in the list. If compareItems() is not reimplemented, it is more
+    efficient to call containsRef().
+
+    This function does not affect the current list item.
+
+    \sa containsRef(), compareItems()
+*/
+
+/*!
+    \fn uint QPtrList::containsRef( const type *item ) const
+
+    Returns the number of occurrences of \a item in the list.
+
+    Calling this function is much faster than contains() because
+    contains() compares \a item with each list item using
+    compareItems(), whereas his function only compares the pointers.
+
+    This function does not affect the current list item.
+
+    \sa contains()
+*/
+
+/*!
+    \fn type *QPtrList::at( uint index )
+
+    Returns a pointer to the item at position \a index in the list, or
+    0 if the index is out of range.
+
+    Sets the current list item to this item if \a index is valid. The
+    valid range is \c{0..(count() - 1)} inclusive.
+
+    This function is very efficient. It starts scanning from the first
+    item, last item, or current item, whichever is closest to \a
+    index.
+
+    \sa current()
+*/
+
+/*!
+    \fn int QPtrList::at() const
+
+    \overload
+
+    Returns the index of the current list item. The returned value is
+    -1 if the current item is 0.
+
+    \sa current()
+*/
+
+/*!
+    \fn type *QPtrList::current() const
+
+    Returns a pointer to the current list item. The current item may
+    be 0 (implies that the current index is -1). 
+
+    \sa at()
+*/
+
+/*!
+    \fn QLNode *QPtrList::currentNode() const
+
+    Returns a pointer to the current list node.
+
+    The node can be kept and removed later using removeNode(). The
+    advantage is that the item can be removed directly without
+    searching the list.
+
+    \warning Do not call this function unless you are an expert.
+
+    \sa removeNode(), takeNode(), current()
+*/
+
+/*!
+    \fn type *QPtrList::getFirst() const
+
+    Returns a pointer to the first item in the list, or 0 if the list
+    is empty.
+
+    This function does not affect the current list item.
+
+    \sa first(), getLast()
+*/
+
+/*!
+    \fn type *QPtrList::getLast() const
+
+    Returns a pointer to the last item in the list, or 0 if the list
+    is empty.
+
+    This function does not affect the current list item.
+
+    \sa last(), getFirst()
+*/
+
+/*!
+    \fn type *QPtrList::first()
+
+    Returns a pointer to the first item in the list and makes this the
+    current list item; returns 0 if the list is empty.
+
+    \sa getFirst(), last(), next(), prev(), current()
+*/
+
+/*!
+    \fn type *QPtrList::last()
+
+    Returns a pointer to the last item in the list and makes this the
+    current list item; returns 0 if the list is empty.
+
+    \sa getLast(), first(), next(), prev(), current()
+*/
+
+/*!
+    \fn type *QPtrList::next()
+
+    Returns a pointer to the item succeeding the current item. Returns
+    0 if the current item is 0 or equal to the last item.
+
+    Makes the succeeding item current. If the current item before this
+    function call was the last item, the current item will be set to
+    0. If the current item was 0, this function does nothing.
+
+    \sa first(), last(), prev(), current()
+*/
+
+/*!
+    \fn type *QPtrList::prev()
+
+    Returns a pointer to the item preceding the current item. Returns
+    0 if the current item is 0 or equal to the first item.
+
+    Makes the preceding item current. If the current item before this
+    function call was the first item, the current item will be set to
+    0. If the current item was 0, this function does nothing.
+
+    \sa first(), last(), next(), current()
+*/
+
+/*!
+    \fn void QPtrList::toVector( QGVector *vec ) const
+
+    Stores all list items in the vector \a vec.
+
+    The vector must be of the same item type, otherwise the result
+    will be undefined.
+*/
+
+/*!
+    \enum QPtrList::iterator
+
+    \internal
+*/
+
+/*!
+    \enum QPtrList::Iterator
+
+    \internal
+*/
+
+/*!
+    \enum QPtrList::ConstIterator
+
+    \internal
+*/
+
+/*!
+    \enum QPtrList::const_iterator
+
+    \internal
+*/
+
+/*!
+    \fn QPtrList::constBegin() const
+
+    \internal
+*/
+
+/*!
+    \fn QPtrList::constEnd() const
+
+    \internal
+*/
+
+/*!
+    \fn QPtrList::erase(Iterator)
+
+    \internal
+*/
+
+
+/*****************************************************************************
+  QPtrListIterator documentation
+ *****************************************************************************/
+
+/*!
+    \class QPtrListIterator
+    \brief The QPtrListIterator class provides an iterator for
+    QPtrList collections.
+
+    \ingroup collection
+    \ingroup tools
+
+    Define a template instance QPtrListIterator\<X\> to create a list
+    iterator that operates on QPtrList\<X\> (list of X*).
+
+    The following example is similar to the \link
+    qptrlist.html#example example in the QPtrList class documentation
+    \endlink, but it uses QPtrListIterator. The class Employee is
+    defined there.
+
+    \code
+    QPtrList<Employee> list;
+
+    list.append( new Employee("John", "Doe", 50000) );
+    list.append( new Employee("Jane", "Williams", 80000) );
+    list.append( new Employee("Tom", "Jones", 60000) );
+
+    QPtrListIterator<Employee> it( list );
+    Employee *employee;
+    while ( (employee = it.current()) != 0 ) {
+	++it;
+	cout << employee->surname().latin1() << ", " <<
+		employee->forename().latin1() << " earns " <<
+		employee->salary() << endl;
+    }
+    \endcode
+
+    The output is
+    \code
+    Doe, John earns 50000
+    Williams, Jane earns 80000
+    Jones, Tom earns 60000
+    \endcode
+
+    Using a list iterator is a more robust way of traversing the list
+    than using the QPtrList member functions \link QPtrList::first()
+    first\endlink(), \link QPtrList::next() next\endlink(), \link
+    QPtrList::current() current\endlink(), etc., as many iterators can
+    traverse the same list independently.
+
+    An iterator has its own current list item and can get the next and
+    previous list items. It doesn't modify the list in any way.
+
+    When an item is removed from the list, all iterators that point to
+    that item are updated to point to QPtrList::current() instead to
+    avoid dangling references.
+
+    \sa QPtrList
+*/
+
+/*!
+    \fn QPtrListIterator::QPtrListIterator( const QPtrList<type> &list )
+
+    Constructs an iterator for \a list. The current iterator item is
+    set to point on the first item in the \a list.
+*/
+
+/*!
+    \fn QPtrListIterator::~QPtrListIterator()
+
+    Destroys the iterator.
+*/
+
+/*!
+    \fn uint QPtrListIterator::count() const
+
+    Returns the number of items in the list this iterator operates on.
+
+    \sa isEmpty()
+*/
+
+/*!
+    \fn bool QPtrListIterator::isEmpty() const
+
+    Returns TRUE if the list is empty; otherwise returns FALSE.
+
+    \sa count()
+*/
+
+/*!
+    \fn bool QPtrListIterator::atFirst() const
+
+    Returns TRUE if the current iterator item is the first list item;
+    otherwise returns FALSE.
+
+    \sa toFirst(), atLast()
+*/
+
+/*!
+    \fn bool QPtrListIterator::atLast() const
+
+    Returns TRUE if the current iterator item is the last list item;
+    otherwise returns FALSE.
+
+    \sa toLast(), atFirst()
+*/
+
+/*!
+    \fn type *QPtrListIterator::toFirst()
+
+    Sets the current iterator item to point to the first list item and
+    returns a pointer to the item. Sets the current item to 0 and
+    returns 0 if the list is empty.
+
+    \sa toLast(), atFirst()
+*/
+
+/*!
+    \fn type *QPtrListIterator::toLast()
+
+    Sets the current iterator item to point to the last list item and
+    returns a pointer to the item. Sets the current item to 0 and
+    returns 0 if the list is empty.
+
+    \sa toFirst(), atLast()
+*/
+
+/*!
+    \fn QPtrListIterator::operator type *() const
+
+    Cast operator. Returns a pointer to the current iterator item.
+    Same as current().
+*/
+
+/*!
+    \fn type *QPtrListIterator::operator*()
+
+    Asterisk operator. Returns a pointer to the current iterator item.
+    Same as current().
+*/
+
+/*!
+    \fn type *QPtrListIterator::current() const
+
+    Returns a pointer to the current iterator item. If the iterator is
+    positioned before the first item in the list or after the last
+    item in the list, 0 is returned.
+*/
+
+/*!
+    \fn type *QPtrListIterator::operator()()
+
+    Makes the succeeding item current and returns the original current
+    item.
+
+    If the current iterator item was the last item in the list or if
+    it was 0, 0 is returned.
+*/
+
+/*!
+    \fn type *QPtrListIterator::operator++()
+
+    Prefix ++ makes the succeeding item current and returns the new
+    current item.
+
+    If the current iterator item was the last item in the list or if
+    it was 0, 0 is returned.
+*/
+
+/*!
+    \fn type *QPtrListIterator::operator+=( uint jump )
+
+    Sets the current item to the item \a jump positions after the
+    current item and returns a pointer to that item.
+
+    If that item is beyond the last item or if the list is empty, it
+    sets the current item to 0 and returns 0
+*/
+
+/*!
+    \fn type *QPtrListIterator::operator--()
+
+    Prefix - makes the preceding item current and returns the new
+    current item.
+
+    If the current iterator item was the first item in the list or if
+    it was 0, 0 is returned.
+*/
+
+/*!
+    \fn type *QPtrListIterator::operator-=( uint jump )
+
+    Returns the item \a jump positions before the current item or 0
+    if it is beyond the first item. Makes this the current item.
+*/
+
+/*!
+    \fn QPtrListIterator<type>& QPtrListIterator::operator=( const QPtrListIterator<type> &it )
+
+    Assignment. Makes a copy of the iterator \a it and returns a
+    reference to this iterator.
+*/
+
+
+/*****************************************************************************
+  QStrList documentation
+ *****************************************************************************/
+
+/*!
+    \class QStrList qstrlist.h
+    \brief The QStrList class provides a doubly-linked list of char*.
+
+    \ingroup collection
+    \ingroup tools
+    \ingroup text
+
+    If you want a string list of \l{QString}s use QStringList.
+
+    This class is a QPtrList\<char\> instance (a list of char*).
+
+    QStrList can make deep or shallow copies of the strings that are
+    inserted.
+
+    A deep copy means that memory is allocated for the string and then
+    the string data is copied into that memory. A shallow copy is just
+    a copy of the pointer value and not of the string data itself.
+
+    The disadvantage of shallow copies is that because a pointer can
+    be deleted only once, the program must put all strings in a
+    central place and know when it is safe to delete them (i.e. when
+    the strings are no longer referenced by other parts of the
+    program). This can make the program more complex. The advantage of
+    shallow copies is that they consume far less memory than deep
+    copies. It is also much faster to copy a pointer (typically 4 or 8
+    bytes) than to copy string data.
+
+    A QStrList that operates on deep copies will, by default, turn on
+    auto-deletion (see setAutoDelete()). Thus, by default QStrList
+    will deallocate any string copies it allocates.
+
+    The virtual compareItems() function is reimplemented and does a
+    case-sensitive string comparison. The inSort() function will
+    insert strings in sorted order. In general it is fastest to insert
+    the strings as they come and sort() at the end; inSort() is useful
+    when you just have to add a few extra strings to an already sorted
+    list.
+
+    The QStrListIterator class is an iterator for QStrList.
+*/
+
+/*!
+    \fn QStrList::QStrList( bool deepCopies )
+
+    Constructs an empty list of strings. Will make deep copies of all
+    inserted strings if \a deepCopies is TRUE, or use shallow copies
+    if \a deepCopies is FALSE.
+*/
+
+/*!
+    \fn QStrList::QStrList( const QStrList &list )
+
+    Constructs a copy of \a list.
+
+    If \a list has deep copies, this list will also get deep copies.
+    Only the pointers are copied (shallow copy) if the other list does
+    not use deep copies.
+*/
+
+/*!
+    \fn QStrList::~QStrList()
+
+    Destroys the list. All strings are removed.
+*/
+
+/*!
+    \fn QStrList& QStrList::operator=( const QStrList& list )
+
+    Assigns \a list to this list and returns a reference to this list.
+
+    If \a list has deep copies, this list will also get deep copies.
+    Only the pointers are copied (shallow copy) if the other list does
+    not use deep copies.
+*/
+
+
+/*****************************************************************************
+  QStrIList documentation
+ *****************************************************************************/
+
+/*!
+    \class QStrIList qstrlist.h
+    \brief The QStrIList class provides a doubly-linked list of char*
+    with case-insensitive comparison.
+
+    \ingroup collection
+    \ingroup tools
+
+    This class is a QPtrList\<char\> instance (a list of char*).
+
+    QStrIList is identical to QStrList except that the virtual
+    compareItems() function is reimplemented to compare strings
+    case-insensitively. The inSort() function inserts strings in a
+    sorted order. In general it is fastest to insert the strings as
+    they come and sort() at the end; inSort() is useful when you just
+    have to add a few extra strings to an already sorted list.
+
+    The QStrListIterator class works for QStrIList.
+
+    \sa QStringList
+*/
+
+/*!
+    \fn QStrIList::QStrIList( bool deepCopies )
+
+    Constructs a list of strings. Will make deep copies of all
+    inserted strings if \a deepCopies is TRUE, or use shallow copies
+    if \a deepCopies is FALSE.
+*/
+
+/*!
+    \fn QStrIList::~QStrIList()
+
+    Destroys the list. All strings are removed.
+*/
+
+/*!
+    \fn int QPtrList::compareItems( QPtrCollection::Item item1,
+				    QPtrCollection::Item item2 )
+
+    This virtual function compares two list items.
+
+    Returns:
+    \list
+    \i zero if \a item1 == \a item2
+    \i nonzero if \a item1 != \a item2
+    \endlist
+
+    This function returns \e int rather than \e bool so that
+    reimplementations can return three values and use it to sort by:
+
+    \list
+    \i 0 if \a item1 == \a item2
+    \i \> 0 (positive integer) if \a item1 \> \a item2
+    \i \< 0 (negative integer) if \a item1 \< \a item2
+    \endlist
+
+    inSort() retquires that compareItems() is implemented as described
+    here.
+
+    This function should not modify the list because some const
+    functions call compareItems().
+
+    The default implementation compares the pointers.
+*/
+
+/*!
+    \fn QDataStream& QPtrList::read( QDataStream& s,
+				    QPtrCollection::Item& item )
+
+    Reads a list item from the stream \a s and returns a reference to
+    the stream.
+
+    The default implementation sets \a item to 0.
+
+    \sa write()
+*/
+
+/*!
+    \fn QDataStream& QPtrList::write( QDataStream& s,
+					QPtrCollection::Item item ) const
+
+    Writes a list item, \a item to the stream \a s and returns a
+    reference to the stream.
+
+    The default implementation does nothing.
+
+    \sa read()
+*/
+
+/*! \fn iterator QPtrList::begin() 
+\internal
+*/
+/*! \fn const_iterator QPtrList::begin() const
+\internal
+*/
+/*! \fn iterator QPtrList::end() 
+\internal
+*/
+/*! \fn const_iterator QPtrList::end() const
+\internal
+*/
+
+/*****************************************************************************
+  QStrListIterator documentation
+ *****************************************************************************/
+
+/*!
+    \class QStrListIterator qstrlist.h
+    \brief The QStrListIterator class is an iterator for the QStrList
+    and QStrIList classes.
+
+    \ingroup tools
+
+    This class is a QPtrListIterator\<char\> instance. It can traverse
+    the strings in the QStrList and QStrIList classes.
+*/
+
+
+/*****************************************************************************
+  QPtrListAutoDelete documentation
+ *****************************************************************************/
+/*
+    \class QPtrListAutoDelete
+    \brief The QPtrListAutoDelete class is a template class that provides a list that auto-deletes its data.
+
+    \ingroup collection
+    \ingroup tools
+
+    A QPtrListAutoDelete is identical to a QPtrList with
+    setAutoDelete(TRUE).
+*/