Test conversion to TQt3 from Qt3 8c6fc1f8e35fd264dd01c582ca5e7549b32ab731

1 files changed, 475 insertions, 0 deletions

diff --git a/doc/qasciidict.doc b/doc/qasciidict.doc
new file mode 100644
index 000000000..ce5cf8416
--- /dev/null
+++ b/doc/qasciidict.doc
@@ -0,0 +1,475 @@
+/****************************************************************************
+**
+** QAsciiDict and QAsciiDictIterator 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.
+**
+**********************************************************************/
+
+
+/*****************************************************************************
+  QAsciiDict documentation
+ *****************************************************************************/
+
+/*!
+    \class QAsciiDict qasciidict.h
+    \brief The QAsciiDict class is a template class that provides a dictionary based on char* keys.
+
+    \ingroup collection
+    \ingroup tools
+
+    \important autoDelete setAutoDelete
+
+    QAsciiDict is implemented as a template class. Define a template
+    instance QAsciiDict\<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
+    char* used for insertion, removal and lookup. The value is a
+    pointer. Dictionaries provide very fast insertion and lookup.
+
+    QAsciiDict cannot handle Unicode keys; use the QDict template
+    instead, which uses \l QString keys. A QDict has the same
+    performace as a QAsciiDict.
+
+    Example:
+    \code
+    QAsciiDict<QLineEdit> fields; // char* keys, QLineEdit* values
+    fields.insert( "forename", new QLineEdit( this ) );
+    fields.insert( "surname", new QLineEdit( this ) );
+
+    fields["forename"]->setText( "Homer" );
+    fields["surname"]->setText( "Simpson" );
+
+    QAsciiDictIterator<QLineEdit> it( fields ); // See QAsciiDictIterator
+    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. See QPtrDict, QIntDict and QDict.
+
+    See QDict for full details, including the choice of dictionary
+    size, and how deletions are handled. 
+
+    \sa QAsciiDictIterator, QDict, QIntDict, QPtrDict,
+	\link collection.html Collection Classes\endlink
+*/
+
+
+/*!
+    \fn QAsciiDict::QAsciiDict( int size, bool caseSensitive, bool copyKeys )
+
+    Constructs a dictionary optimized for less than \a size entries.
+
+    We recommend setting \a size to a suitably large prime number (a
+    bit larger than the expected number of entries). This makes the
+    hash distribution better and will improve lookup performance.
+
+    When \a caseSensitive is TRUE (the default) QAsciiDict treats
+    "abc" and "Abc" as different keys; when it is FALSE "abc" and
+    "Abc" are the same. Case-insensitive comparison only considers the
+    26 letters in US-ASCII.
+
+    If \a copyKeys is TRUE (the default), the dictionary copies keys
+    using strcpy(); if it is FALSE, the dictionary just copies the
+    pointers.
+*/
+
+/*!
+    \fn QAsciiDict::QAsciiDict( const QAsciiDict<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 QAsciiDict::~QAsciiDict()
+
+    Removes all items from the dictionary and destroys it.
+
+    The items are deleted if auto-delete is enabled.
+
+    All iterators that access this dictionary will be reset.
+
+    \sa setAutoDelete()
+*/
+
+/*!
+    \fn QAsciiDict<type> &QAsciiDict::operator=(const QAsciiDict<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 this dictionary. Only the pointers are copied
+    (shallow copy) unless newItem() has been reimplemented().
+*/
+
+/*!
+    \fn uint QAsciiDict::count() const
+
+    Returns the number of items in the dictionary.
+
+    \sa isEmpty()
+*/
+
+/*!
+    \fn uint QAsciiDict::size() const
+
+    Returns the size of the internal hash array (as specified in the
+    constructor).
+
+    \sa count()
+*/
+
+/*!
+    \fn void QAsciiDict::resize( uint newsize )
+
+    Changes the size of the hashtable to \a newsize. The contents of
+    the dictionary are preserved but all iterators on the dictionary
+    become invalid.
+*/
+
+/*!
+    \fn bool QAsciiDict::isEmpty() const
+
+    Returns TRUE if the dictionary is empty, i.e. count() == 0;
+    otherwise it returns FALSE.
+
+    \sa count()
+*/
+
+/*!
+    \fn void QAsciiDict::insert( const char *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 QAsciiDict::replace( const char *key, const type *item )
+
+    Replaces an item that has a key equal to \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
+	QAsciiDict<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 most
+    recently inserted item will be replaced.
+
+    \sa insert()
+*/
+
+/*!
+    \fn bool QAsciiDict::remove( const char *key )
+
+    Removes the item associated with \a key from the dictionary.
+    Returns TRUE if successful, i.e. if the key existed 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
+    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 traversal order.
+
+    \sa take(), clear(), setAutoDelete()
+*/
+
+/*!
+    \fn type *QAsciiDict::take( const char *key )
+
+    Takes the item associated 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 most
+    recently inserted item 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 QAsciiDict::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 dictionary are reset.
+
+    \sa remove(), take(), setAutoDelete()
+*/
+
+/*!
+    \fn type *QAsciiDict::find( const char *key ) const
+
+    Returns the item associated with \a key, or 0 if the key does not
+    exist in the dictionary.
+
+    This function uses an internal hashing algorithm to optimize
+    lookup.
+
+    If there are two or more items with equal keys, then the item that
+    was most recently inserted will be found.
+
+    Equivalent to the [] operator.
+
+    \sa operator[]()
+*/
+
+/*!
+    \fn type *QAsciiDict::operator[]( const char *key ) const
+
+    Returns the item associated with \a key, or 0 if the key does
+    not exist in the dictionary.
+
+    This function uses an internal hashing algorithm to optimize
+    lookup.
+
+    If there are two or more items with equal keys, then the item that
+    was most recently inserted will be found.
+
+    Equivalent to the find() function.
+
+    \sa find()
+*/
+
+/*!
+    \fn void QAsciiDict::statistics() const
+
+    Debugging-only function that prints out the dictionary
+    distribution using qDebug().
+*/
+
+/*!
+    \fn QDataStream& QAsciiDict::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& QAsciiDict::write( QDataStream &s,
+					QPtrCollection::Item ) const
+
+    Writes a dictionary item to the stream \a s and returns a
+    reference to the stream.
+
+    \sa read()
+*/
+
+/*****************************************************************************
+  QAsciiDictIterator documentation
+ *****************************************************************************/
+
+/*!
+    \class QAsciiDictIterator qasciidict.h
+    \brief The QAsciiDictIterator class provides an iterator for QAsciiDict collections.
+
+    \ingroup collection
+    \ingroup tools
+
+    QAsciiDictIterator is implemented as a template class. Define a
+    template instance QAsciiDictIterator\<X\> to create a dictionary
+    iterator that operates on QAsciiDict\<X\> (dictionary of X*).
+
+    Example:
+    \code
+    QAsciiDict<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" );
+
+    QAsciiDictIterator<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 line edits into a dictionary, then
+    iterate over the dictionary printing the strings associated with
+    those line edits.
+
+    Note that the traversal order is arbitrary; you are not guaranteed
+    any particular order.
+
+    Multiple iterators may independently traverse the same dictionary.
+    A QAsciiDict knows about all the iterators that are operating on
+    the dictionary. When an item is removed from the dictionary,
+    QAsciiDict updates all the iterators that are referring to the
+    removed item to point to the next item in the (arbitrary)
+    traversal order.
+
+    \sa QAsciiDict
+*/
+
+/*!
+    \fn QAsciiDictIterator::QAsciiDictIterator( const QAsciiDict<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 QAsciiDictIterator::~QAsciiDictIterator()
+
+    Destroys the iterator.
+*/
+
+/*!
+    \fn uint QAsciiDictIterator::count() const
+
+    Returns the number of items in the dictionary this iterator
+    operates over.
+
+    \sa isEmpty()
+*/
+
+/*!
+    \fn bool QAsciiDictIterator::isEmpty() const
+
+    Returns TRUE if the dictionary is empty, i.e. count() == 0,
+    otherwise returns FALSE.
+    
+    \sa count()
+*/
+
+/*!
+    \fn type *QAsciiDictIterator::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 QAsciiDictIterator::operator type *() const
+
+    Cast operator. Returns a pointer to the current iterator item.
+    Same as current().
+*/
+
+/*!
+    \fn type *QAsciiDictIterator::current() const
+
+    Returns a pointer to the current iterator item.
+*/
+
+/*!
+    \fn const char *QAsciiDictIterator::currentKey() const
+
+    Returns a pointer to the key for the current iterator item.
+*/
+
+/*!
+    \fn type *QAsciiDictIterator::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 *QAsciiDictIterator::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 *QAsciiDictIterator::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.
+*/