Add Qt3 development HEAD version

1 files changed, 557 insertions, 0 deletions

diff --git a/doc/qdict.doc b/doc/qdict.doc
new file mode 100644
index 0000000..c522624
--- /dev/null
+++ b/doc/qdict.doc
@@ -0,0 +1,557 @@
+/****************************************************************************
+**
+** QDict and QDictIterator 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 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.
+**
+**********************************************************************/
+
+
+/*****************************************************************************
+  QDict documentation
+ *****************************************************************************/
+
+/*!
+    \class QDict
+    \brief The QDict class is a template class that provides a
+    dictionary based on QString keys.
+
+    \ingroup collection
+    \ingroup tools
+    \mainclass
+
+    \important autoDelete setAutoDelete
+
+    QMap is an STL-compatible alternative to this class.
+
+    QDict is implemented as a template class. Define a template
+    instance QDict\<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
+    QString used for insertion, removal and lookup. The value is a
+    pointer. Dictionaries provide very fast insertion and lookup.
+
+    If you want to use non-Unicode, plain 8-bit \c char* keys, use the
+    QAsciiDict template. A QDict has the same performance as a
+    QAsciiDict. If you want to have a dictionary that maps QStrings to
+    QStrings use QMap.
+
+    The size() of the dictionary is very important. In order to get
+    good performance, you should use a suitably large prime number.
+    Suitable means equal to or larger than the maximum expected number
+    of dictionary items. Size is set in the constructor but may be
+    changed with resize().
+
+    Items are inserted with insert(); 0 pointers cannot be inserted.
+    Items are removed with remove(). All the items in a dictionary can
+    be removed with clear(). The number of items in the dictionary is
+    returned by count(). If the dictionary contains no items isEmpty()
+    returns TRUE. You can change an item's value with replace(). Items
+    are looked up with operator[](), or with find() which return a
+    pointer to the value or 0 if the given key does not exist. You can
+    take an item out of the dictionary with take().
+
+    Calling setAutoDelete(TRUE) for a dictionary tells it to delete
+    items that are removed. The default behaviour is not to delete
+    items when they are removed.
+   
+    When an item is inserted, the key is converted (hashed) to an
+    integer index into an internal hash array. This makes lookup very
+    fast.
+
+    Items with equal keys are allowed. When inserting two items with
+    the same key, only the last inserted item will be accessible (last
+    in, first out) until it is removed.
+
+    The QDictIterator class can traverse the dictionary, but only in
+    an arbitrary order. Multiple iterators may independently traverse
+    the same dictionary.
+
+    When inserting an item into a dictionary, only the pointer is
+    copied, not the item itself, i.e. a shallow copy is made. It is
+    possible to make the dictionary copy all of the item's data (a
+    deep copy) when an item is inserted. insert() calls the virtual
+    function QPtrCollection::newItem() for the item to be inserted.
+    Inherit a dictionary and reimplement newItem() if you want deep
+    copies.
+
+    When removing a dictionary item, the virtual function
+    QPtrCollection::deleteItem() is called. QDict's default
+    implementation is to delete the item if auto-deletion is enabled.
+
+    Example #1:
+    \code
+    QDict<QLineEdit> fields; // QString keys, QLineEdit* values
+    fields.insert( "forename", new QLineEdit( this ) );
+    fields.insert( "surname", new QLineEdit( this ) );
+
+    fields["forename"]->setText( "Homer" );
+    fields["surname"]->setText( "Simpson" );
+
+    QDictIterator<QLineEdit> it( fields ); // See QDictIterator
+    for( ; it.current(); ++it )
+	cout << it.currentKey() << ": " << it.current()->text() << endl;
+    cout << endl;
+
+    if ( fields["forename"] && fields["surname"] )
+	cout << fields["forename"]->text() << " " 
+	    << fields["surname"]->text() << endl;  // Prints "Homer Simpson"
+
+    fields.remove( "forename" ); // Does not delete the line edit
+    if ( ! fields["forename"] )
+	cout << "forename is not in the dictionary" << endl;
+    \endcode
+    In this example we use a dictionary to keep track of the line
+    edits we're using. We insert each line edit into the dictionary
+    with a unique name and then access the line edits via the
+    dictionary. 
+
+    Example #2:
+    \code
+    QStringList styleList = QStyleFactory::styles();
+    styleList.sort();
+    QDict<int> letterDict( 17, FALSE );
+    for ( QStringList::Iterator it = styleList.begin(); it != styleList.end(); ++it ) {
+	QString styleName = *it;
+	QString styleAccel = styleName;
+	if ( letterDict[styleAccel.left(1)] ) {
+	    for ( uint i = 0; i < styleAccel.length(); i++ ) {
+		if ( ! letterDict[styleAccel.mid( i, 1 )] ) {
+		    styleAccel = styleAccel.insert( i, '&' );
+		    letterDict.insert(styleAccel.mid( i, 1 ), (const int *)1);
+		    break;
+		}
+	    }
+	} else {
+	    styleAccel = "&" + styleAccel;
+	    letterDict.insert(styleAccel.left(1), (const int *)1);
+	}
+	(void) new QAction( styleName, QIconSet(), styleAccel, parent );
+    }
+    \endcode
+    In the example we are using the dictionary to provide fast random
+    access to the keys, and we don't care what the values are. The
+    example is used to generate a menu of QStyles, each with a unique
+    accelerator key (or no accelerator if there are no unused letters
+    left).
+
+    We first obtain the list of available styles, then sort them so
+    that the menu items will be ordered alphabetically. Next we create
+    a dictionary of int pointers. The keys in the dictionary are each
+    one character long, representing letters that have been used for
+    accelerators. We iterate through our list of style names. If the
+    first letter of the style name is in the dictionary, i.e. has been
+    used, we iterate over all the characters in the style name to see
+    if we can find a letter that hasn't been used. If we find an
+    unused letter we put the accelerator ampersand (&) in front of it
+    and add that letter to the dictionary. If we can't find an unused
+    letter the style will simply have no accelerator. If the first
+    letter of the style name is not in the dictionary we use it for
+    the accelerator and add it to the dictionary. Finally we create a
+    QAction for each style.
+
+    \sa QDictIterator, QAsciiDict, QIntDict, QPtrDict
+*/
+
+
+/*!
+    \fn QDict::QDict( int size, bool caseSensitive )
+
+    Constructs a dictionary optimized for less than \a size entries.
+
+    We recommend setting \a size to a suitably large prime number
+    (e.g. a prime that's slightly larger than the expected number of
+    entries). This makes the hash distribution better which will lead
+    to faster lookup.
+
+    If \a caseSensitive is TRUE (the default), keys which differ only
+    by case are considered different.
+*/
+
+/*!
+    \fn QDict::QDict( const QDict<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 QDict::~QDict()
+
+    Removes all items from the dictionary and destroys it. If
+    setAutoDelete() is TRUE, each value is deleted. All iterators that
+    access this dictionary will be reset.
+
+    \sa setAutoDelete()
+*/
+
+/*!
+    \fn QDict<type> &QDict::operator=(const QDict<type> &dict)
+
+    Assigns \a dict to this dictionary and returns a reference to this
+    dictionary.
+
+    This dictionary is first cleared, then each item in \a dict is
+    inserted into this dictionary. Only the pointers are copied
+    (shallow copy), unless newItem() has been reimplemented.
+*/
+
+/*!
+    \fn uint QDict::count() const
+
+    Returns the number of items in the dictionary.
+
+    \sa isEmpty()
+*/
+
+/*!
+    \fn uint QDict::size() const
+
+    Returns the size of the internal hash array (as specified in the
+    constructor).
+
+    \sa count()
+*/
+
+/*!
+    \fn void QDict::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 QDict::isEmpty() const
+
+    Returns TRUE if the dictionary is empty, i.e. count() == 0;
+    otherwise returns FALSE.
+
+    \sa count()
+*/
+
+/*!
+    \fn void QDict::insert( const QString &key, const type *item )
+
+    Inserts the key \a key with value \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 QDict::replace( const QString &key, const type *item )
+
+    Replaces the value of the key, \a key with \a item.
+
+    If the item does not already exist, it will be inserted.
+
+    \a item may not be 0.
+
+    Equivalent to:
+    \code
+	QDict<char> 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 last item
+    that was inserted will be replaced.
+
+    \sa insert()
+*/
+
+/*!
+    \fn bool QDict::remove( const QString &key )
+
+    Removes the item with \a key from the dictionary. Returns TRUE if
+    successful, i.e. if the item is in the dictionary; otherwise
+    returns FALSE.
+
+    If there are two or more items with equal keys, then the last item
+    that was inserted will be removed.
+
+    The removed item is deleted if \link
+    QPtrCollection::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's traversal order.
+
+    \sa take(), clear(), setAutoDelete()
+*/
+
+/*!
+    \fn type *QDict::take( const QString &key )
+
+    Takes the item with \a key out of the dictionary without deleting
+    it (even if \link QPtrCollection::setAutoDelete()
+    auto-deletion\endlink is enabled).
+
+    If there are two or more items with equal keys, then the last item
+    that was inserted will be taken.
+
+    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 QDict::clear()
+
+    Removes all items from the dictionary.
+
+    The removed items are deleted if \link
+    QPtrCollection::setAutoDelete() auto-deletion\endlink is enabled.
+
+    All dictionary iterators that operate on the dictionary are reset.
+
+    \sa remove(), take(), setAutoDelete()
+*/
+
+/*!
+    \fn type *QDict::find( const QString &key ) const
+
+    Returns the item with key \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 [] operator.
+
+    \sa operator[]()
+*/
+
+/*!
+    \fn type *QDict::operator[]( const QString &key ) const
+
+    Returns the item with key \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 QDict::statistics() const
+
+    Debugging-only function that prints out the dictionary
+    distribution using qDebug().
+*/
+
+/*!
+    \fn QDataStream& QDict::read( QDataStream &s, QPtrCollection::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& QDict::write( QDataStream &s, QPtrCollection::Item ) const
+
+    Writes a dictionary item to the stream \a s and returns a
+    reference to the stream.
+
+    \sa read()
+*/
+
+/*****************************************************************************
+  QDictIterator documentation
+ *****************************************************************************/
+
+/*!
+    \class QDictIterator qdict.h
+    \brief The QDictIterator class provides an iterator for QDict collections.
+
+    \ingroup collection
+    \ingroup tools
+
+    QDictIterator is implemented as a template class. Define a
+    template instance QDictIterator\<X\> to create a dictionary
+    iterator that operates on QDict\<X\> (dictionary of X*).
+
+    The traversal order is arbitrary; when we speak of the "first",
+    "last" and "next" item we are talking in terms of this arbitrary
+    order.
+
+    Multiple iterators may independently traverse the same dictionary.
+    A QDict knows about all the iterators that are operating on the
+    dictionary. When an item is removed from the dictionary, QDict
+    updates all iterators that are referring to the removed item to
+    point to the next item in the (arbitrary) traversal order.
+
+    Example:
+    \code
+    QDict<QLineEdit> fields;
+    fields.insert( "forename", new QLineEdit( this ) );
+    fields.insert( "surname", new QLineEdit( this ) );
+    fields.insert( "age", new QLineEdit( this ) );
+
+    fields["forename"]->setText( "Homer" );
+    fields["surname"]->setText( "Simpson" );
+    fields["age"]->setText( "45" );
+
+    QDictIterator<QLineEdit> it( fields );
+    for( ; it.current(); ++it )
+	cout << it.currentKey() << ": " << it.current()->text() << endl;
+    cout << endl;
+
+    // Output (random order):
+    //	age: 45
+    //	surname: Simpson
+    //	forename: Homer
+    \endcode
+    In the example we insert some pointers to line edits into a
+    dictionary, then iterate over the dictionary printing the strings
+    associated with the line edits.
+
+    \sa QDict
+*/
+
+/*!
+    \fn QDictIterator::QDictIterator( const QDict<type> &dict )
+
+    Constructs an iterator for \a dict. The current iterator item is
+    set to point to the first item in the dictionary, \a dict. First
+    in this context means first in the arbitrary traversal order.
+*/
+
+/*!
+    \fn QDictIterator::~QDictIterator()
+
+    Destroys the iterator.
+*/
+
+/*!
+    \fn uint QDictIterator::count() const
+
+    Returns the number of items in the dictionary over which the
+    iterator is operating.
+
+    \sa isEmpty()
+*/
+
+/*!
+    \fn bool QDictIterator::isEmpty() const
+
+    Returns TRUE if the dictionary is empty, i.e. count() == 0;
+    otherwise returns FALSE.
+
+    \sa count()
+*/
+
+/*!
+    \fn type *QDictIterator::toFirst()
+
+    Resets the iterator, making the first item the first current item.
+    First in this context means first in the arbitrary traversal
+    order. Returns a pointer to this item.
+
+    If the dictionary is empty it sets the current item to 0 and
+    returns 0.
+*/
+
+/*!
+  \fn type *QDictIterator::operator*()
+  \internal
+*/
+
+/*!
+    \fn QDictIterator::operator type*() const
+
+    Cast operator. Returns a pointer to the current iterator item.
+    Same as current().
+*/
+
+
+/*!
+    \fn type *QDictIterator::current() const
+
+    Returns a pointer to the current iterator item's value.
+*/
+
+/*!
+    \fn QString QDictIterator::currentKey() const
+
+    Returns the current iterator item's key.
+*/
+
+/*!
+    \fn type *QDictIterator::operator()()
+
+    Makes the next 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 *QDictIterator::operator++()
+
+    Prefix ++ makes the next 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 *QDictIterator::operator+=( uint jump )
+  \internal
+  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.
+*/