1 files changed, 458 insertions, 0 deletions
diff --git a/doc/tqptrdict.doc b/doc/tqptrdict.doc
new file mode 100644
index 000000000..b11c2b493
--- /dev/null
+++ b/doc/tqptrdict.doc
@@ -0,0 +1,458 @@
+/****************************************************************************
+**
+** TQPtrDict and TQPtrDictIterator class documentation
+**
+** Copyright (C) 1992-2008 Trolltech ASA.  All rights reserved.
+**
+** This file is part of the TQt 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 TQt 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.
+**
+**********************************************************************/
+
+
+/*****************************************************************************
+  TQPtrDict documentation
+ *****************************************************************************/
+
+/*!
+    \class TQPtrDict
+    \brief The TQPtrDict class is a template class that provides a dictionary based on void* keys.
+
+    \ingroup collection
+    \ingroup tools
+
+    \important autoDelete setAutoDelete
+
+    TQPtrDict is implemented as a template class. Define a template
+    instance TQPtrDict\<X\> to create a dictionary that operates on
+    pointers to X (X*).
+
+    A dictionary is a collection of key-value pairs. The key is a
+    void* used for insertion, removal and lookup. The value is a
+    pointer. Dictionaries provide very fast insertion and lookup.
+
+    Example:
+    \code
+    TQPtrDict<char> fields; // void* keys, char* values
+
+    QLineEdit *le1 = new QLineEdit( this );
+    le1->setText( "Simpson" );
+    QLineEdit *le2 = new QLineEdit( this );
+    le2->setText( "Homer" );
+    QLineEdit *le3 = new QLineEdit( this );
+    le3->setText( "45" );
+
+    fields.insert( le1, "Surname" );
+    fields.insert( le2, "Forename" );
+    fields.insert( le3, "Age" );
+
+    TQPtrDictIterator<char> it( fields );
+    for( ; it.current(); ++it )
+	cout << it.current() << endl;
+    cout << endl;
+
+    if ( fields[le1] ) // Prints "Surname: Simpson"
+	cout << fields[le1] << ": " << le1->text() << endl; 
+    if ( fields[le2] ) // Prints "Forename: Homer"
+	cout << fields[le2] << ": " << le2->text() << endl; 
+
+    fields.remove( le1 ); // Removes le1 from the dictionary
+    cout << le1->text() << endl; // Prints "Simpson"
+    \endcode
+    In this example we use a dictionary to add an extra property (a
+    char*) to the line edits we're using. 
+
+    See QDict for full details, including the choice of dictionary
+    size, and how deletions are handled. 
+
+    \sa TQPtrDictIterator, QDict, QAsciiDict, QIntDict,
+	\link collection.html Collection Classes\endlink
+*/
+
+
+/*!
+    \fn TQPtrDict::TQPtrDict( int size )
+
+    Constructs a dictionary using an internal hash array with the size
+    \a size.
+
+    Setting \a size to a suitably large prime number (equal to or
+    greater than the expected number of entries) makes the hash
+    distribution better and improves lookup performance.
+*/
+
+/*!
+    \fn TQPtrDict::TQPtrDict( const TQPtrDict<type> &dict )
+
+    Constructs a copy of \a dict.
+
+    Each item in \a dict is inserted into this dictionary. Only the
+    pointers are copied (shallow copy).
+*/
+
+/*!
+    \fn TQPtrDict::~TQPtrDict()
+
+    Removes all items from the dictionary and destroys it.
+
+    All iterators that access this dictionary will be reset.
+
+    \sa setAutoDelete()
+*/
+
+/*!
+    \fn TQPtrDict<type> &TQPtrDict::operator=(const TQPtrDict<type> &dict)
+
+    Assigns \a dict to this dictionary and returns a reference to this
+    dictionary.
+
+    This dictionary is first cleared and then each item in \a dict is
+    inserted into the dictionary. Only the pointers are copied
+    (shallow copy), unless newItem() has been reimplemented.
+*/
+
+/*!
+    \fn uint TQPtrDict::count() const
+
+    Returns the number of items in the dictionary.
+
+    \sa isEmpty()
+*/
+
+/*!
+    \fn uint TQPtrDict::size() const
+
+    Returns the size of the internal hash table (as specified in the
+    constructor).
+
+    \sa count()
+*/
+
+/*!
+    \fn void TQPtrDict::resize( uint newsize )
+
+    Changes the size of the hash table to \a newsize. The contents of
+    the dictionary are preserved, but all iterators on the dictionary
+    become invalid.
+*/
+
+/*!
+    \fn bool TQPtrDict::isEmpty() const
+
+    Returns TRUE if the dictionary is empty; otherwise returns FALSE.
+
+    \sa count()
+*/
+
+/*!
+    \fn void TQPtrDict::insert( void *key, const type *item )
+
+    Inserts the \a key with the \a item into the dictionary.
+
+    Multiple items can have the same key, in which case only the last
+    item will be accessible using \l operator[]().
+
+    \a item may not be 0.
+
+    \sa replace()
+*/
+
+/*!
+    \fn void TQPtrDict::replace( void *key, const type *item )
+
+    If the dictionary has key \a key, this key's item is replaced with
+    \a item. If the dictionary doesn't contain key \a key, \a item is
+    inserted into the dictionary using key \a key. 
+
+    \a item may not be 0.
+
+    Equivalent to
+    \code
+	TQPtrDict<ItemType> dict;
+	    ...
+	if ( dict.find( key ) )
+	    dict.remove( key );
+	dict.insert( key, item );
+    \endcode
+
+    If there are two or more items with equal keys, then the most
+    recently inserted item will be replaced.
+
+    \sa insert()
+*/
+
+/*!
+    \fn bool TQPtrDict::remove( void *key ) 
+    
+    Removes the item associated with \a key from the dictionary.
+    Returns TRUE if successful, i.e. if \a key is in the dictionary;
+    otherwise returns FALSE.
+
+    If there are two or more items with equal keys, then the most
+    recently inserted item will be removed.
+
+    The removed item is deleted if \link
+    TQPtrCollection::setAutoDelete() auto-deletion\endlink is enabled.
+
+    All dictionary iterators that refer to the removed item will be
+    set to point to the next item in the dictionary traversal order.
+
+    \sa take(), clear(), setAutoDelete()
+*/
+
+/*!
+    \fn type *TQPtrDict::take( void *key )
+
+    Takes the item associated with \a key out of the dictionary
+    without deleting it (even if \link TQPtrCollection::setAutoDelete()
+    auto-deletion\endlink is enabled).
+
+    If there are two or more items with equal keys, then the most
+    recently inserted item will be removed.
+
+    Returns a pointer to the item taken out, or 0 if the key does not
+    exist in the dictionary.
+
+    All dictionary iterators that refer to the taken item will be set
+    to point to the next item in the dictionary traversal order.
+
+    \sa remove(), clear(), setAutoDelete()
+*/
+
+/*!
+    \fn void TQPtrDict::clear()
+
+    Removes all items from the dictionary.
+
+    The removed items are deleted if \link
+    TQPtrCollection::setAutoDelete() auto-deletion\endlink is enabled.
+
+    All dictionary iterators that access this dictionary will be
+    reset.
+
+    \sa remove(), take(), setAutoDelete()
+*/
+
+/*!
+    \fn type *TQPtrDict::find( void *key ) const
+
+    Returns the item associated with \a key, or 0 if the key does not
+    exist in the dictionary.
+
+    If there are two or more items with equal keys, then the most
+    recently inserted item will be found.
+
+    Equivalent to operator[].
+
+    \sa operator[]()
+*/
+
+/*!
+    \fn type *TQPtrDict::operator[]( void *key ) const
+
+    Returns the item associated with \a key, or 0 if the key does not
+    exist in the dictionary.
+
+    If there are two or more items with equal keys, then the most
+    recently inserted item will be found.
+
+    Equivalent to the find() function.
+
+    \sa find()
+*/
+
+/*!
+    \fn void TQPtrDict::statistics() const
+
+    Debugging-only function that prints out the dictionary
+    distribution using tqDebug().
+*/
+
+/*!
+    \fn QDataStream& TQPtrDict::read( QDataStream &s, TQPtrCollection::Item &item )
+
+    Reads a dictionary 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& TQPtrDict::write( QDataStream &s, TQPtrCollection::Item ) const
+
+    Writes a dictionary item to the stream \a s and returns a
+    reference to the stream.
+
+    \sa read()
+*/
+
+/*****************************************************************************
+  TQPtrDictIterator documentation
+ *****************************************************************************/
+
+/*!
+    \class TQPtrDictIterator tqptrdict.h
+    \brief The TQPtrDictIterator class provides an iterator for TQPtrDict collections.
+
+    \ingroup collection
+    \ingroup tools
+
+    TQPtrDictIterator is implemented as a template class. Define a
+    template instance TQPtrDictIterator\<X\> to create a dictionary
+    iterator that operates on TQPtrDict\<X\> (dictionary of X*).
+
+    Example:
+    \code
+    TQPtrDict<char> fields;
+
+    QLineEdit *le1 = new QLineEdit( this );
+    le1->setText( "Simpson" );
+    QLineEdit *le2 = new QLineEdit( this );
+    le2->setText( "Homer" );
+    QLineEdit *le3 = new QLineEdit( this );
+    le3->setText( "45" );
+
+    fields.insert( le1, "Surname" );
+    fields.insert( le2, "Forename" );
+    fields.insert( le3, "Age" );
+
+    TQPtrDictIterator<char> it( fields );
+    for( ; it.current(); ++it ) {
+	QLineEdit *le = (QLineEdit)it.currentKey();
+	cout << it.current() << ": " << le->text() << endl;
+    }
+    cout << endl;
+
+    // Output (random order):
+    //	Forename: Homer
+    //	Age: 45
+    //	Surname: Simpson
+    \endcode
+    In the example we insert some line edits into a dictionary,
+    associating a string with each. We then iterate over the
+    dictionary printing the associated strings.
+
+    Multiple iterators may independently traverse the same dictionary.
+    A TQPtrDict knows about all the iterators that are operating on the
+    dictionary. When an item is removed from the dictionary, TQPtrDict
+    updates all iterators that refer the removed item to point to the
+    next item in the traversing order.
+
+    \sa TQPtrDict
+*/
+
+/*!
+    \fn TQPtrDictIterator::TQPtrDictIterator( const TQPtrDict<type> &dict )
+
+    Constructs an iterator for \a dict. The current iterator item is
+    set to point on the first item in the \a dict.
+*/
+
+/*!
+    \fn TQPtrDictIterator::~TQPtrDictIterator()
+
+    Destroys the iterator.
+*/
+
+/*!
+    \fn uint TQPtrDictIterator::count() const
+
+    Returns the number of items in the dictionary this iterator
+    operates on.
+
+    \sa isEmpty()
+*/
+
+/*!
+    \fn bool TQPtrDictIterator::isEmpty() const
+
+    Returns TRUE if the dictionary is empty; otherwise returns FALSE.
+
+    \sa count()
+*/
+
+/*!
+    \fn type *TQPtrDictIterator::toFirst()
+
+    Sets the current iterator item to point to the first item in the
+    dictionary and returns a pointer to the item. If the dictionary is
+    empty, it sets the current item to 0 and returns 0.
+*/
+
+/*!
+    \fn TQPtrDictIterator::operator type *() const
+
+    Cast operator. Returns a pointer to the current iterator item.
+    Same as current().
+*/
+
+/*!
+    \fn type *TQPtrDictIterator::current() const
+
+    Returns a pointer to the current iterator item's value.
+*/
+
+/*!
+    \fn void *TQPtrDictIterator::currentKey() const
+
+    Returns the current iterator item's key.
+*/
+
+/*!
+    \fn type *TQPtrDictIterator::operator()()
+
+    Makes the succeeding item current and returns the original current
+    item.
+
+    If the current iterator item was the last item in the dictionary
+    or if it was 0, 0 is returned.
+*/
+
+/*!
+    \fn type *TQPtrDictIterator::operator++()
+
+    Prefix ++ makes the succeeding item current and returns the new
+    current item.
+
+    If the current iterator item was the last item in the dictionary
+    or if it was 0, 0 is returned.
+*/
+
+/*!
+    \fn type *TQPtrDictIterator::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 dictionary is
+    empty, it sets the current item to 0 and returns 0.
+*/