diff options
author | Dimitri van Heesch <dimitri@stack.nl> | 2001-10-21 18:02:53 (GMT) |
---|---|---|
committer | Dimitri van Heesch <dimitri@stack.nl> | 2001-10-21 18:02:53 (GMT) |
commit | 883b84589e5a6108dacb9f3df9f7a41369940ca5 (patch) | |
tree | f5aef68ee03709376658e93142ca5df6850e649d | |
parent | 3c05bde563408b446333fb435b443d69903b156f (diff) | |
download | Doxygen-883b84589e5a6108dacb9f3df9f7a41369940ca5.zip Doxygen-883b84589e5a6108dacb9f3df9f7a41369940ca5.tar.gz Doxygen-883b84589e5a6108dacb9f3df9f7a41369940ca5.tar.bz2 |
Release-1.2.11-20011021
-rw-r--r-- | INSTALL | 4 | ||||
-rw-r--r-- | README | 4 | ||||
-rw-r--r-- | VERSION | 2 | ||||
-rw-r--r-- | doc/install.doc | 2 | ||||
-rw-r--r-- | doc/maintainers.txt | 1 | ||||
-rw-r--r-- | doc/translator.pl | 6 | ||||
-rw-r--r-- | packages/rpm/doxygen.spec | 2 | ||||
-rw-r--r-- | qtools/Doxyfile | 19 | ||||
-rw-r--r-- | qtools/qarray.doc | 486 | ||||
-rw-r--r-- | qtools/qdict.doc | 492 | ||||
-rw-r--r-- | qtools/qintdict.doc | 475 | ||||
-rw-r--r-- | qtools/qlist.doc | 1048 | ||||
-rw-r--r-- | qtools/qptrdict.doc | 486 | ||||
-rw-r--r-- | qtools/qsortedlist.doc | 94 | ||||
-rw-r--r-- | qtools/qstack.doc | 135 | ||||
-rw-r--r-- | qtools/qstrlist.doc | 5 | ||||
-rw-r--r-- | qtools/qtl.doc | 249 | ||||
-rw-r--r-- | qtools/qvaluelist.doc | 772 | ||||
-rw-r--r-- | qtools/qvector.doc | 344 | ||||
-rw-r--r-- | src/classdef.cpp | 53 | ||||
-rw-r--r-- | src/code.l | 2 | ||||
-rw-r--r-- | src/doc.l | 2 | ||||
-rw-r--r-- | src/doxygen.cpp | 39 | ||||
-rw-r--r-- | src/doxytag.l | 1 | ||||
-rw-r--r-- | src/latexgen.cpp | 7 | ||||
-rw-r--r-- | src/scanner.l | 2 | ||||
-rw-r--r-- | src/translator_cn.h | 961 | ||||
-rw-r--r-- | src/translator_ru.h | 14 | ||||
-rw-r--r-- | src/translator_si.h | 442 | ||||
-rw-r--r-- | src/util.cpp | 21 | ||||
-rw-r--r-- | src/util.h | 2 |
31 files changed, 5833 insertions, 339 deletions
@@ -1,6 +1,6 @@ -DOXYGEN Version 1.2.11-20011014 +DOXYGEN Version 1.2.11-20011021 Please read the installation section of the manual for instructions. -------- -Dimitri van Heesch (14 October 2001) +Dimitri van Heesch (21 October 2001) @@ -1,4 +1,4 @@ -DOXYGEN Version 1.2.11_20011014 +DOXYGEN Version 1.2.11_20011021 Please read INSTALL for compilation instructions. @@ -17,4 +17,4 @@ to subscribe to the lists or to visit the archives. Enjoy, -Dimitri van Heesch (dimitri@stack.nl) (14 October 2001) +Dimitri van Heesch (dimitri@stack.nl) (21 October 2001) @@ -1 +1 @@ -1.2.11-20011014 +1.2.11-20011021 diff --git a/doc/install.doc b/doc/install.doc index d32e762..1025961 100644 --- a/doc/install.doc +++ b/doc/install.doc @@ -520,7 +520,7 @@ the <code>bin</code> directory of the distribution to the path. For running doxywizard you need to install the non-commercial version of the Qt library first. This library can be downloaded from -http://www.trolltech.com/products/download/freelicense/noncommercial-dl.html +http://www.trolltech.com/products/download/qt-win-noncomm.html \subsection build_tools Tools used to develop doxygen diff --git a/doc/maintainers.txt b/doc/maintainers.txt index 646f6c1..d0a7188 100644 --- a/doc/maintainers.txt +++ b/doc/maintainers.txt @@ -5,6 +5,7 @@ Brazilian Fabio "FJTC" Jun Takada Chino: chino@grad.icmc.sc.usp.br Chinese +Wei Liu: liuwei@asiainfo.com Wang Weihan: wangweihan@capinfo.com.cn Croatian diff --git a/doc/translator.pl b/doc/translator.pl index e031674..a3021fa 100644 --- a/doc/translator.pl +++ b/doc/translator.pl @@ -77,6 +77,11 @@ # the simplified language.doc from the template was moved to # the separate function CopyTemplateToLanguageDoc(). # +# 2001/10/17 +# - Minor update of GetInfoFrom() to ignore spaces between the +# method identifier and the opening parenthesis to match better +# the method prototype with the one in the translator.h. +# ################################################################ use 5.005; @@ -316,6 +321,7 @@ sub GetInfoFrom ##{{{ $cont =~ s{^\s+}{}s; $cont =~ s{\s+$}{}s; + $cont =~ s{\s+\(}{(}g; $cont =~ s{\)\s*}{)\n}g; # Split the string and add it to the ouptut list. diff --git a/packages/rpm/doxygen.spec b/packages/rpm/doxygen.spec index 18b7384..a901d09 100644 --- a/packages/rpm/doxygen.spec +++ b/packages/rpm/doxygen.spec @@ -1,5 +1,5 @@ Name: doxygen -Version: 1.2.11_20011014 +Version: 1.2.11_20011021 Summary: documentation system for C, C++ and IDL Release: 4 Source: doxygen-%{version}.src.tar.gz diff --git a/qtools/Doxyfile b/qtools/Doxyfile index 8a54cc9..838a299 100644 --- a/qtools/Doxyfile +++ b/qtools/Doxyfile @@ -51,21 +51,10 @@ WARN_LOGFILE = #--------------------------------------------------------------------------- # configuration options related to the input files #--------------------------------------------------------------------------- -INPUT = . \ - $(QTDIR)/src/doc/qarray.doc \ - $(QTDIR)/src/doc/qdict.doc \ - $(QTDIR)/src/doc/qintdict.doc \ - $(QTDIR)/src/doc/qlist.doc \ - $(QTDIR)/src/doc/qptrdict.doc \ - $(QTDIR)/src/doc/qsortedlist.doc \ - $(QTDIR)/src/doc/qstack.doc \ - $(QTDIR)/src/doc/qstrlist.doc \ - $(QTDIR)/src/doc/qvector.doc \ - $(QTDIR)/src/doc/qvaluelist.doc \ - $(QTDIR)/src/doc/qtl.doc +INPUT = . FILE_PATTERNS = *.h \ *.cpp \ - q*.doc + *.doc RECURSIVE = NO EXCLUDE_PATTERNS = EXAMPLE_PATH = @@ -77,8 +66,8 @@ FILTER_SOURCE_FILES = NO # configuration options related to the alphabetical class index #--------------------------------------------------------------------------- ALPHABETICAL_INDEX = YES -COLS_IN_ALPHA_INDEX = 5 -IGNORE_PREFIX = +COLS_IN_ALPHA_INDEX = 4 +IGNORE_PREFIX = Q #--------------------------------------------------------------------------- # configuration options related to the HTML output #--------------------------------------------------------------------------- diff --git a/qtools/qarray.doc b/qtools/qarray.doc new file mode 100644 index 0000000..d5a606e --- /dev/null +++ b/qtools/qarray.doc @@ -0,0 +1,486 @@ +/**************************************************************************** +** $Id$ +** +** QArray class documentation +** +** Copyright (C) 1992-2000 Trolltech AS. All rights reserved. +** +** This file is part of the Qt GUI Toolkit. +** +** This file may be distributed under the terms of the Q Public License +** as defined by Trolltech AS of Norway and appearing in the file +** LICENSE.QPL included in the packaging of this file. +** +** This file may be distributed and/or modified under the terms of the +** GNU General Public License version 2 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. +** +** Licensees holding valid Qt Enterprise Edition or Qt Professional Edition +** 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 +** WARRANTY OF DESIGN, MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. +** +** See http://www.trolltech.com/pricing.html or email sales@trolltech.com for +** information about Qt Commercial License Agreements. +** See http://www.trolltech.com/qpl/ for QPL licensing information. +** See http://www.trolltech.com/gpl/ for GPL licensing information. +** +** Contact info@trolltech.com if any conditions of this licensing are +** not clear to you. +** +**********************************************************************/ + + +/***************************************************************************** + QArray documentation + *****************************************************************************/ + +/*! + \class QArray qarray.h + \brief The QArray class is a template class that provides arrays of simple types. + + \ingroup tools + + QArray is implemented as a template class. Define a template + instance QArray\<X\> to create an array that contains X items. + + QArray stores the array elements directly in the array. It can only + deal with simple types, i.e. C++ types, structs and classes that have + no constructors, destructors or virtual functions. QArray uses + bitwise operations to copy and compare array elements. + + The QVector collection class is also a kind of array. Like most + \link collection.html collection classes\endlink, it has pointers to the + contained items. + + QArray uses explicit \link shclass.html sharing\endlink with a reference + count. If more than one array share common data, and one array is + modified, all arrays will be modified. + + The benefit of sharing is that a program does not need to duplicate + data when it is not required, which results in less memory usage and + less copying of data. + + Example: + \code + #include <qarray.h> + #include <stdio.h> + + QArray<int> fib( int num ) // returns fibonacci array + { + ASSERT( num > 2 ); + QArray<int> f( num ); // array of ints + + f[0] = f[1] = 1; // initialize first two numbers + for ( int i=2; i<num; i++ ) + f[i] = f[i-1] + f[i-2]; + + return f; + } + + void main() + { + QArray<int> a = fib( 6 ); // get 6 first fibonaccis + int i; + + for ( i=0; i<a.size(); i++ ) // print them + prinf( "%d: %d\n", i, a[i] ); + + printf( "1 is found %d time(s)\n", a.contains(1) ); + printf( "5 is found at index %d\n", a.find(5) ); + } + \endcode + + Program output: + \code + 0: 1 + 1: 1 + 2: 2 + 3: 3 + 4: 5 + 5: 8 + 1 is found 2 times + 5 is found at index 4 + \endcode + + Note about using QArray for manipulating structs or classes: + Compilers will often pad the size of structs of odd sizes up to the + nearest word boundary. This will then be the size QArray will use + for its bitwise element comparisons. Since the remaining bytes will + typically be uninitialized, this can cause find() etc. to fail to + find the element. Example: + + \code + struct MyStruct + { + short i; // 2 bytes + char c; // 1 byte + }; // sizeof(MyStruct) may be padded to 4 bytes + + QArray<MyStruct> a(1); + a[0].i = 5; + a[0].c = 't'; + + MyStruct x; + x.i = '5'; + x.c = 't'; + int i = a.find( x ); // May return -1 if the pad bytes differ + \endcode + + To workaround this, make sure that you use a struct where sizeof() + returns the same as the sum of the sizes of the members, either by + changing the types of the struct members or by adding dummy members. + + \sa \link shclass.html Shared Classes\endlink +*/ + + +/*! + \fn QArray::QArray() + Constructs a null array. + \sa isNull() +*/ + +/*! + \fn QArray::QArray( int size ) + Constructs an array with room for \e size elements. + Makes a null array if \e size == 0. + + Note that the elements are not initialized. + + \sa resize(), isNull() +*/ + +/*! + \fn QArray::QArray( const QArray<type> &a ) + Constructs a shallow copy of \e a. + \sa assign() +*/ + +/*! + \fn QArray::QArray( int, int ) + Constructs an array <em>without allocating</em> array space. + The arguments should be (0, 0). Use at own risk. +*/ + +/*! + \fn QArray::~QArray() + Dereferences the array data and deletes it if this was the last + reference. +*/ + +/*! + \fn QArray<type> &QArray::operator=( const QArray<type> &a ) + Assigns a shallow copy of \e a to this array and returns a reference + to this array. + + Equivalent to assign( a ). +*/ + +/*! + \fn type *QArray::data() const + Returns a pointer to the actual array data. + + The array is a null array if data() == 0 (null pointer). + + \sa isNull() +*/ + +/*! + \fn uint QArray::nrefs() const + Returns the reference count for the shared array data. This reference count + is always greater than zero. +*/ + +/*! + \fn uint QArray::size() const + Returns the size of the array (max number of elements). + + The array is a null array if size() == 0. + + \sa isNull(), resize() +*/ + +/*! + \fn uint QArray::count() const + Returns the same as size(). + + \sa size() +*/ + +/*! + \fn bool QArray::isEmpty() const + Returns TRUE if the array is empty, i.e. size() == 0, otherwise FALSE. + + isEmpty() is equivalent with isNull() for QArray. Note that this is not + the case for QCString::isEmpty(). +*/ + +/*! + \fn bool QArray::isNull() const + Returns TRUE if the array is null, otherwise FALSE. + + A null array has size() == 0 and data() == 0. +*/ + +/*! + \fn bool QArray::resize( uint size ) + Resizes (expands or shrinks) the array to \e size elements. The array + becomes a null array if \e size == 0. + + Returns TRUE if successful, or FALSE if the memory cannot be allocated. + + New elements will not be initialized. + + \sa size() +*/ + +/*! + \fn bool QArray::truncate( uint pos ) + Truncates the array at position \e pos. + + Returns TRUE if successful, or FALSE if the memory cannot be allocated. + + Equivalent to resize(\e pos). + + \sa resize() +*/ + +/*! + \fn bool QArray::fill( const type &v, int size ) + Fills the array with the value \e v. If \e size is specified as different + from -1, then the array will be resized before filled. + + Returns TRUE if successful, or FALSE if the memory cannot be allocated + (only when \e size != -1). + + \sa resize() +*/ + +/*! + \fn void QArray::detach() + Detaches this array from shared array data, i.e. makes a private, deep + copy of the data. + + Copying will only be performed if the + \link nrefs() reference count\endlink is greater than one. + + \sa copy() +*/ + +/*! + \fn QArray<type> QArray::copy() const + Returns a deep copy of this array. + \sa detach(), duplicate() +*/ + +/*! + \fn QArray<type> &QArray::assign( const QArray<type> &a ) + Shallow copy. Dereferences the current array and references the data + contained in \e a instead. Returns a reference to this array. + \sa operator=() +*/ + +/*! + \fn QArray<type> &QArray::assign( const type *data, uint size ) + Shallow copy. Dereferences the current array and references the + array data \e data, which contains \e size elements. + Returns a reference to this array. + + Do not delete \e data later, QArray takes care of that. +*/ + +/*! + \fn QArray<type> &QArray::duplicate( const QArray<type> &a ) + Deep copy. Dereferences the current array and obtains a copy of the data + contained in \e a instead. Returns a reference to this array. + \sa copy() +*/ + +/*! + \fn QArray<type> &QArray::duplicate( const type *data, uint size ) + Deep copy. Dereferences the current array and obtains a copy of the + array data \e data instead. Returns a reference to this array. + \sa copy() +*/ + +/*! + \fn QArray<type> &QArray::setRawData( const type *data, uint size ) + + Sets raw data and returns a reference to the array. + + Dereferences the current array and sets the new array data to \e data and + the new array size to \e size. Do not attempt to resize or re-assign the + array data when raw data has been set. + Call resetRawData(d,len) to reset the array. + + Setting raw data is useful because it sets QArray data without allocating + memory or copying data. + + Example I (intended use): + \code + static char bindata[] = { 231, 1, 44, ... }; + QByteArray a; + a.setRawData( bindata, sizeof(bindata) ); // a points to bindata + QDataStream s( a, IO_ReadOnly ); // open on a's data + s >> <something>; // read raw bindata + a.resetRawData( bindata, sizeof(bindata) ); // finished + \endcode + + Example II (you don't want to do this): + \code + static char bindata[] = { 231, 1, 44, ... }; + QByteArray a, b; + a.setRawData( bindata, sizeof(bindata) ); // a points to bindata + a.resize( 8 ); // will crash + b = a; // will crash + a[2] = 123; // might crash + // forget to resetRawData - will crash + \endcode + + \warning If you do not call resetRawData(), QArray will attempt to + deallocate or reallocate the raw data, which might not be too good. + Be careful. + + \sa resetRawData() +*/ + +/*! + \fn void QArray::resetRawData( const type *data, uint size ) + Resets raw data that was set using setRawData(). + + The arguments must be the data and length that were passed to + setRawData(). This is for consistency checking. + + \sa setRawData() +*/ + +/*! + \fn int QArray::find( const type &v, uint index ) const + Finds the first occurrence of \e v, starting at position \e index. + + Returns the position of \e v, or -1 if \e v could not be found. + + \sa contains() +*/ + +/*! + \fn int QArray::contains( const type &v ) const + Returns the number of times \e v occurs in the array. + \sa find() +*/ + +/*! + \fn void QArray::sort() + Sorts the array elements in ascending order, using bitwise + comparison (memcmp()). + + \sa bsearch() +*/ + +/*! + \fn int QArray::bsearch( const type &v ) const + In a sorted array, finds the first occurrence of \e v using binary + search. For a sorted array, this is generally much faster than + find(), which does a linear search. + + Returns the position of \e v, or -1 if \e v could not be found. + + \sa sort(), find() +*/ + +/*! + \fn type &QArray::operator[]( int index ) const + Returns a reference to the element at position \e index in the array. + + This can be used to both read and set an element. Equivalent to at(). + + \sa at() +*/ + +/*! + \fn type &QArray::at( uint index ) const + Returns a reference to the element at position \e index in the array. + + This can be used to both read and set an element. + + \sa operator[]() +*/ + +/*! + \fn QArray::operator const type *() const + Cast operator. Returns a pointer to the array. + \sa data() +*/ + +/*! + \fn bool QArray::operator==( const QArray<type> &a ) const + Returns TRUE if this array is equal to \e a, otherwise FALSE. + + The two arrays are bitwise compared. + + \sa operator!=() +*/ + +/*! + \fn bool QArray::operator!=( const QArray<type> &a ) const + Returns TRUE if this array is different from \e a, otherwise FALSE. + + The two arrays are bitwise compared. + + \sa operator==() +*/ + +/*! + \fn Iterator QArray::begin() + Returns an iterator pointing at the beginning of this array. + This iterator can be used as the iterators of QValueList and QMap + for example. In fact it does not only behave like a usual pointer: + It is a pointer. +*/ + +/*! + \fn Iterator QArray::end() + Returns an iterator pointing behind the last element of this array. + This iterator can be used as the iterators of QValueList and QMap + for example. In fact it does not only behave like a usual pointer: + It is a pointer. +*/ + +/*! + \fn ConstIterator QArray::begin() const + Returns a const iterator pointing at the beginning of this array. + This iterator can be used as the iterators of QValueList and QMap + for example. In fact it does not only behave like a usual pointer: + It is a pointer. +*/ + +/*! + \fn ConstIterator QArray::end() const + Returns a const iterator pointing behind the last element of this array. + This iterator can be used as the iterators of QValueList and QMap + for example. In fact it does not only behave like a usual pointer: + It is a pointer. +*/ + + +/***************************************************************************** + QByteArray documentation + *****************************************************************************/ + +/*! + \class QByteArray qcstring.h + \brief The QByteArray class provides an array of bytes. + + \inherit QArray + + \ingroup tools + + The QByteArray class provides an explicitly shared array of + bytes. It is useful for manipulating memory areas with custom + data. QByteArray is implemented as QArray<char>. See the QArray + documentation for further information. +*/ diff --git a/qtools/qdict.doc b/qtools/qdict.doc new file mode 100644 index 0000000..4472a3c --- /dev/null +++ b/qtools/qdict.doc @@ -0,0 +1,492 @@ +/**************************************************************************** +** $Id$ +** +** QDict and QDictIterator class documentation +** +** Copyright (C) 1992-2000 Trolltech AS. All rights reserved. +** +** This file is part of the Qt GUI Toolkit. +** +** This file may be distributed under the terms of the Q Public License +** as defined by Trolltech AS of Norway and appearing in the file +** LICENSE.QPL included in the packaging of this file. +** +** This file may be distributed and/or modified under the terms of the +** GNU General Public License version 2 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. +** +** Licensees holding valid Qt Enterprise Edition or Qt Professional Edition +** 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 +** WARRANTY OF DESIGN, MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. +** +** See http://www.trolltech.com/pricing.html or email sales@trolltech.com for +** information about Qt Commercial License Agreements. +** See http://www.trolltech.com/qpl/ for QPL licensing information. +** See http://www.trolltech.com/gpl/ for GPL licensing information. +** +** Contact info@trolltech.com if any conditions of this licensing are +** not clear to you. +** +**********************************************************************/ + + +/***************************************************************************** + QDict documentation + *****************************************************************************/ + +/*! + \class QDict qdict.h + \brief The QDict class is a template class that provides a dictionary based on \c QString keys. + + \ingroup collection + \ingroup tools + + QDict is implemented as a template class. Define a template instance + QDict\<X\> to create a dictionary that operates on pointers to X, or X*. + + A dictionary is a collection that associates an item with a key. + The key is used for inserting and looking up an item. QDict has + \l QString keys, which are Unicode strings. If you want to use + non-Unicode, plain 8-bit \c char* keys, use the QAsciiDict template. + A QDict has the same performace as a QAsciiDict. + + The dictionary has very fast insertion and lookup. + + Example: + \code + #include <qdict.h> + #include <stdio.h> + + void main() + { + // Creates a dictionary that maps QString ==> char* (case insensitive) + QDict<char> dict( 17, FALSE ); + + dict.insert( "France", "Paris" ); + dict.insert( "Russia", "Moscow" ); + dict.insert( "Norway", "Oslo" ); + + printf( "%s\n", dict["Norway"] ); + printf( "%s\n", dict["FRANCE"] ); + printf( "%s\n", dict["russia"] ); + + if ( !dict["Italy"] ) + printf( "Italy not defined\n" ); + } + \endcode + + Program output: + \code + Oslo + Paris + Moscow + Italy not defined + \endcode + + The dictionary in our example maps \c QString keys to \c char* items. + Note that the mapping is case insensitive (specified in the + \link QDict::QDict() constructor\endlink). + QDict implements the \link operator[] [] operator\endlink to lookup an item. + + QDict is implemented by QGDict as a hash array with a fixed number of + entries. Each array entry points to a singly linked list of buckets, in + which the dictionary items are stored. + + When an item is inserted with a key, the key is converted (hashed) to + an integer index into the hash array. The item is inserted before the + first bucket in the list of buckets. + + Looking up an item is normally very fast. The key is again hashed to an + array index. Then QDict scans the list of buckets and returns the item + found or null if the item was not found. You cannot insert null pointers + into a dictionary. + + The size of the hash array is very important. In order to get good + performance, you should use a suitably large \link primes.html prime + number\endlink. Suitable means equal to or larger than the maximum + expected number of dictionary items. + + Items with equal keys are allowed. When inserting two items with the + same key, only the last inserted item will be visible (last in, first out) + until it is removed. + + Example: + \code + #include <qdict.h> + #include <stdio.h> + + void main() + { + // Creates a dictionary that maps QString ==> char* (case sensitive) + QDict<char> dict; + + dict.insert( "Germany", "Berlin" ); + dict.insert( "Germany", "Bonn" ); + + printf( "%s\n", dict["Germany"] ); + dict.remove( "Germany" ); // Oct 3rd 1990 + printf( "%s\n", dict["Germany"] ); + } + \endcode + + Program output: + \code + Bonn + Berlin + \endcode + + The QDictIterator class can traverse the dictionary contents, but only + in an arbitrary order. Multiple iterators may independently traverse the + same dictionary. + + Calling setAutoDelete(TRUE) for a dictionary tells it to delete items + that are removed . The default is to not delete items when they are + removed. + + When inserting an item into a dictionary, only the pointer is copied, not + the item itself. This is called a shallow copy. It is possible to make the + dictionary copy all of the item's data (known as a deep copy) when an + item is inserted. insert() calls the virtual function + QCollection::newItem() for the item to be inserted. + Inherit a dictionary and reimplement it if you want deep copies. + + When removing a dictionary item, the virtual function + QCollection::deleteItem() is called. QDict's default implementation + is to delete the item if auto-deletion is enabled. + + \sa QDictIterator, QAsciiDict, QIntDict, QPtrDict, + \link collection.html Collection Classes\endlink +*/ + + +/*! + \fn QDict::QDict( int size, bool caseSensitive ) + Constructs a dictionary with the following properties: + \arg \e size is the size of the internal hash array. + \arg \e caseSensitive specifies whether to use case sensitive lookup or not. + + Setting \e size to a suitably large \link primes.html prime + number\endlink (equal to or greater than the expected number of entries) + makes the hash distribution better and hence the loopup faster. + + Setting \e caseSensitive to TRUE will treat "abc" and "Abc" as different + keys. Setting it to FALSE will make the dictionary ignore case. + Case insensitive comparison includes the whole Unicode alphabeth. +*/ + +/*! + \fn QDict::QDict( const QDict<type> &dict ) + Constructs a copy of \e dict. + + Each item in \e dict are inserted into this dictionary. + Only the pointers are copied (shallow copy). +*/ + +/*! + \fn QDict::~QDict() + Removes all items from the dictionary and destroys it. + All iterators that access this dictionary will be reset. + + \sa setAutoDelete() +*/ + +/*! + \fn QDict<type> &QDict::operator=(const QDict<type> &dict) + Assigns \e dict to this dictionary and returns a reference to this + dictionary. + + This dictionary is first cleared, then each item in \e 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 hashtable the \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. Returns FALSE + otherwise. + \sa count() +*/ + +/*! + \fn void QDict::insert( const QString &key, const type *item ) + + Inserts the \e key with the \e item into the dictionary. + + The key does not have to be a unique dictionary key. If multiple items + are inserted with the same key, only the last item will be visible. + + Null items are not allowed. + + \sa replace() +*/ + +/*! + \fn void QDict::replace( const QString &key, const type *item ) + + Replaces an item which has a key equal to \e key with \e item. + + If the item does not already exist, it will be inserted. + + Null items are not allowed. + + 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 inserted + of these will be replaced. + + \sa insert() +*/ + +/*! + \fn bool QDict::remove( const QString &key ) + + Removes the item associated with \e key from the dictionary. + Returns TRUE if successful, or FALSE if the key does not exist in the + dictionary. + + If there are two or more items with equal keys, then the last inserted + of these will be removed. + + The removed item is deleted if \link QCollection::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 traversing order. + + \sa take(), clear(), setAutoDelete() +*/ + +/*! + \fn type *QDict::take( const QString &key ) + + Takes the item associated with \e key out of the dictionary without + deleting it (even if \link QCollection::setAutoDelete() + auto-deletion\endlink is enabled). + + If there are two or more items with equal keys, then the last inserted + of these will be taken. + + Returns a pointer to the item taken out, or null 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 QCollection::setAutoDelete() + auto-deletion\endlink is enabled. + + All dictionary iterators that operate on dictionary are reset. + + \sa remove(), take(), setAutoDelete() +*/ + +/*! + \fn type *QDict::find( const QString &key ) const + + Returns the item associated with \e key, or null 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 last inserted + of these will be found. + + Equivalent to the [] operator. + + \sa operator[]() +*/ + +/*! + \fn type *QDict::operator[]( const QString &key ) const + + Returns the item associated with \e key, or null 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 last inserted + of these 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(). +*/ + + +/***************************************************************************** + 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*). + + Example: + \code + #include <qdict.h> + #include <stdio.h> + + void main() + { + // Creates a dictionary that maps QString ==> char* (case insensitive) + QDict<char> dict( 17, FALSE ); + + dict.insert( "France", "Paris" ); + dict.insert( "Russia", "Moscow" ); + dict.insert( "Norway", "Oslo" ); + + QDictIterator<char> it( dict ); // iterator for dict + + while ( it.current() ) { + printf( "%s -> %s\n", it.currentKey().latin1(), it.current() ); + ++it; + } + } + \endcode + + Program output: + \code + Russia -> Moscow + Norway -> Oslo + France -> Paris + \endcode + + Note that the traversal order is arbitrary, you are not guaranteed the + order above. + + Multiple iterators may independently traverse the same dictionary. + A QDict knows about all iterators that are operating on the dictionary. + When an item is removed from the dictionary, QDict update all iterators + that are referring the removed item to point to the next item in the + traversing order. + + \sa QDict, \link collection.html Collection Classes\endlink +*/ + +/*! + \fn QDictIterator::QDictIterator( const QDict<type> &dict ) + Constructs an iterator for \e dict. The current iterator item is + set to point on the first item in the \e dict. +*/ + +/*! + \fn QDictIterator::~QDictIterator() + Destroys the iterator. +*/ + +/*! + \fn uint QDictIterator::count() const + Returns the number of items in the dictionary this iterator operates on. + \sa isEmpty() +*/ + +/*! + \fn bool QDictIterator::isEmpty() const + Returns TRUE if the dictionary is empty, i.e. count() == 0, otherwise FALSE. + \sa count() +*/ + +/*! + \fn type *QDictIterator::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 null and + returns null. +*/ + +/*! + \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. +*/ + +/*! + \fn QString QDictIterator::currentKey() const + Returns a pointer to the key for the current iterator item. +*/ + +/*! + \fn type *QDictIterator::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 null, null is returned. +*/ + +/*! + \fn type *QDictIterator::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 null, null is returned. +*/ + +/*! + \fn type *QDictIterator::operator+=( uint jump ) + Sets the current item to the item \e 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 null and returns null. +*/ + + diff --git a/qtools/qintdict.doc b/qtools/qintdict.doc new file mode 100644 index 0000000..0a77398 --- /dev/null +++ b/qtools/qintdict.doc @@ -0,0 +1,475 @@ +/**************************************************************************** +** $Id$ +** +** QIntDict and QIntDictIterator class documentation +** +** Copyright (C) 1992-2000 Trolltech AS. All rights reserved. +** +** This file is part of the Qt GUI Toolkit. +** +** This file may be distributed under the terms of the Q Public License +** as defined by Trolltech AS of Norway and appearing in the file +** LICENSE.QPL included in the packaging of this file. +** +** This file may be distributed and/or modified under the terms of the +** GNU General Public License version 2 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. +** +** Licensees holding valid Qt Enterprise Edition or Qt Professional Edition +** 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 +** WARRANTY OF DESIGN, MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. +** +** See http://www.trolltech.com/pricing.html or email sales@trolltech.com for +** information about Qt Commercial License Agreements. +** See http://www.trolltech.com/qpl/ for QPL licensing information. +** See http://www.trolltech.com/gpl/ for GPL licensing information. +** +** Contact info@trolltech.com if any conditions of this licensing are +** not clear to you. +** +**********************************************************************/ + + +/***************************************************************************** + QIntDict documentation + *****************************************************************************/ + +/*! + \class QIntDict qintdict.h + \brief The QIntDict class is a template class that provides a dictionary based on \c long keys. + + \ingroup collection + \ingroup tools + + QIntDict is implemented as a template class. Define a + template instance QIntDict\<X\> to create a dictionary that operates on + pointers to X, or X*. + + A dictionary is a collection that associates an item with a key. + The key is used for inserting and looking up an item. QIntDict has + \c long keys. + + The dictionary has very fast insertion and lookup. + + Example: + \code + #include <qintdict.h> + #include <stdio.h> + + void main() + { + QIntDict<char> dict; // maps long ==> char* + + dict.insert( 33, "France" ); + dict.insert( 7, "Russia" ); + dict.insert( 49, "Norway" ); + + printf( "%s\n", dict[49] ); + printf( "%s\n", dict[33] ); + printf( "%s\n", dict[7] ); + + if ( !dict[39] ) + printf( "39 not defined\n" ); + } + \endcode + + Program output: + \code + Norway + France + Russia + 39 not defined + \endcode + + The dictionary in our example maps \c long keys to \c char* items. + QIntDict implements the \link operator[] [] operator\endlink to lookup + an item. + + QIntDict is implemented by QGDict as a hash array with a fixed number of + entries. Each array entry points to a singly linked list of buckets, in + which the dictionary items are stored. + + When an item is inserted with a key, the key is converted (hashed) to + an integer index into the hash array using the \c mod operation. The + item is inserted before the first bucket in the list of buckets. + + Looking up an item is normally very fast. The key is again hashed to an + array index. Then QIntDict scans the list of buckets and returns the item + found or null if the item was not found. You cannot insert null pointers + into a dictionary. + + The size of the hash array is very important. In order to get good + performance, you should use a suitably large \link primes.html prime + number\endlink. Suitable means equal to or larger than the maximum + expected number of dictionary items. + + Items with equal keys are allowed. When inserting two items with the + same key, only the last inserted item will be visible (last in, first out) + until it is removed. + + Example: + \code + #include <qintdict.h> + #include <stdio.h> + + void main() + { + QIntDict<char> dict; // maps long ==> char* + + dict.insert( 7, "Russia" ); + dict.insert( 7, "USSR" ); + + printf( "%s\n", dict[7] ); + dict.remove( 7 ); // Gorbie was here + printf( "%s\n", dict[7] ); + } + \endcode + + Program output: + \code + USSR + Russia + \endcode + + The QIntDictIterator class can traverse the dictionary contents, but only + in an arbitrary order. Multiple iterators may independently traverse the + same dictionary. + + Calling setAutoDelete(TRUE) for a dictionary tells it to delete items + that are removed . The default is to not delete items when they are + removed. + + When inserting an item into a dictionary, only the pointer is copied, not + the item itself. This is called a shallow copy. It is possible to make the + dictionary copy all of the item's data (known as a deep copy) when an + item is inserted. insert() calls the virtual function + QCollection::newItem() for the item to be inserted. + Inherit a dictionary and reimplement it if you want deep copies. + + When removing a dictionary item, the virtual function + QCollection::deleteItem() is called. QIntDict's default implementation + is to delete the item if auto-deletion is enabled. + + \sa QIntDictIterator, QDict, QAsciiDict, QPtrDict, + \link collection.html Collection Classes\endlink +*/ + + +/*! + \fn QIntDict::QIntDict( int size ) + Constructs a dictionary using an internal hash array with the size + \e size. + + Setting \e size to a suitably large \link primes.html prime number\endlink + (equal to or greater than the expected number of entries) makes the hash + distribution better and hence the loopup faster. +*/ + +/*! + \fn QIntDict::QIntDict( const QIntDict<type> &dict ) + Constructs a copy of \e dict. + + Each item in \e dict are inserted into this dictionary. + Only the pointers are copied (shallow copy). +*/ + +/*! + \fn QIntDict::~QIntDict() + Removes all items from the dictionary and destroys it. + + All iterators that access this dictionary will be reset. + + \sa setAutoDelete() +*/ + +/*! + \fn QIntDict<type> &QIntDict::operator=(const QIntDict<type> &dict) + Assigns \e dict to this dictionary and returns a reference to this + dictionary. + + This dictionary is first cleared, then each item in \e dict is inserted + into this dictionary. + Only the pointers are copied (shallow copy), unless newItem() has been + reimplemented. +*/ + +/*! + \fn uint QIntDict::count() const + Returns the number of items in the dictionary. + \sa isEmpty() +*/ + +/*! + \fn uint QIntDict::size() const + Returns the size of the internal hash array (as specified in the + constructor). + \sa count() +*/ + +/*! + \fn void QIntDict::resize( uint newsize ) + Changes the size of the hashtable the \a newsize. + The contents of the dictionary are preserved, + but all iterators on the dictionary become invalid. +*/ + +/*! + \fn bool QIntDict::isEmpty() const + Returns TRUE if the dictionary is empty, i.e. count() == 0. Returns FALSE + otherwise. + \sa count() +*/ + +/*! + \fn void QIntDict::insert( long key, const type *item ) + Inserts the \e key with the \e item into the dictionary. + + The key does not have to be a unique dictionary key. If multiple items + are inserted with the same key, only the last item will be visible. + + Null items are not allowed. + + \sa replace() +*/ + +/*! + \fn void QIntDict::replace( long key, const type *item ) + Replaces an item which has a key equal to \e key with \e item. + + If the item does not already exist, it will be inserted. + + Null items are not allowed. + + Equivalent to: + \code + QIntDict<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 inserted + of these will be replaced. + + \sa insert() +*/ + +/*! + \fn bool QIntDict::remove( long key ) + Removes the item associated with \e key from the dictionary. + Returns TRUE if successful, or FALSE if the key does not exist in the + dictionary. + + If there are two or more items with equal keys, then the last inserted + of these will be removed. + + The removed item is deleted if \link QCollection::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 traversing order. + + \sa take(), clear(), setAutoDelete() +*/ + +/*! + \fn type *QIntDict::take( long key ) + Takes the item associated with \e key out of the dictionary without + deleting it (even if \link QCollection::setAutoDelete() + auto-deletion\endlink is enabled). + + If there are two or more items with equal keys, then the last inserted + of these will be taken. + + Returns a pointer to the item taken out, or null 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 traversing order. + + \sa remove(), clear(), setAutoDelete() +*/ + +/*! + \fn void QIntDict::clear() + Removes all items from the dictionary. + + The removed items are deleted if \link QCollection::setAutoDelete() + auto-deletion\endlink is enabled. + + All dictionary iterators that access this dictionary will be reset. + + \sa remove(), take(), setAutoDelete() +*/ + +/*! + \fn type *QIntDict::find( long key ) const + Returns the item associated with \e key, or null 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 last inserted + of these will be found. + + Equivalent to the [] operator. + + \sa operator[]() +*/ + +/*! + \fn type *QIntDict::operator[]( long key ) const + Returns the item associated with \e key, or null 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 last inserted + of these will be found. + + Equivalent to the find() function. + + \sa find() +*/ + +/*! + \fn void QIntDict::statistics() const + Debugging-only function that prints out the dictionary distribution + using qDebug(). +*/ + + +/***************************************************************************** + QIntDictIterator documentation + *****************************************************************************/ + +/*! + \class QIntDictIterator qintdict.h + \brief The QIntDictIterator class provides an iterator for QIntDict collections. + + \ingroup collection + \ingroup tools + + QIntDictIterator is implemented as a template class. + Define a template instance QIntDictIterator\<X\> to create a + dictionary iterator that operates on QIntDict\<X\> (dictionary of X*). + + Example: + \code + #include <qintdict.h> + #include <stdio.h> + + void main() + { + QIntDict<char> dict; // maps long ==> char* + + dict.insert( 33, "France" ); + dict.insert( 7, "Russia" ); + dict.insert( 49, "Norway" ); + + QIntDictIterator<char> it( dict ); // iterator for dict + + while ( it.current() ) { + printf( "%d -> %s\n", it.currentKey(), it.current() ); + ++it; + } + } + \endcode + + Program output: + \code + 7 -> Russia + 49 -> Norway + 33 -> France + \endcode + + Note that the traversal order is arbitrary, you are not guaranteed the + order above. + + Multiple iterators may independently traverse the same dictionary. + A QIntDict knows about all iterators that are operating on the dictionary. + When an item is removed from the dictionary, QIntDict update all + iterators that are referring the removed item to point to the next item + in the traversing order. + + \sa QIntDict, \link collection.html Collection Classes\endlink +*/ + +/*! + \fn QIntDictIterator::QIntDictIterator( const QIntDict<type> &dict ) + Constructs an iterator for \e dict. The current iterator item is + set to point on the first item in the \e dict. +*/ + +/*! + \fn QIntDictIterator::~QIntDictIterator() + Destroys the iterator. +*/ + +/*! + \fn uint QIntDictIterator::count() const + Returns the number of items in the dictionary this iterator operates on. + \sa isEmpty() +*/ + +/*! + \fn bool QIntDictIterator::isEmpty() const + Returns TRUE if the dictionary is empty, i.e. count() == 0. Returns FALSE + otherwise. + \sa count() +*/ + +/*! + \fn type *QIntDictIterator::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 null and + returns null. +*/ + +/*! + \fn QIntDictIterator::operator type *() const + Cast operator. Returns a pointer to the current iterator item. + Same as current(). +*/ + +/*! + \fn type *QIntDictIterator::current() const + Returns a pointer to the current iterator item. +*/ + +/*! + \fn long QIntDictIterator::currentKey() const + Returns the key for the current iterator item. +*/ + +/*! + \fn type *QIntDictIterator::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 null, null is returned. +*/ + +/*! + \fn type *QIntDictIterator::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 null, null is returned. +*/ + +/*! + \fn type *QIntDictIterator::operator+=( uint jump ) + Sets the current item to the item \e 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 null and returns null. +*/ diff --git a/qtools/qlist.doc b/qtools/qlist.doc new file mode 100644 index 0000000..85dbf5b --- /dev/null +++ b/qtools/qlist.doc @@ -0,0 +1,1048 @@ +/**************************************************************************** +** $Id$ +** +** QList and QListIterator class documentation +** +** Copyright (C) 1992-2000 Trolltech AS. All rights reserved. +** +** This file is part of the Qt GUI Toolkit. +** +** This file may be distributed under the terms of the Q Public License +** as defined by Trolltech AS of Norway and appearing in the file +** LICENSE.QPL included in the packaging of this file. +** +** This file may be distributed and/or modified under the terms of the +** GNU General Public License version 2 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. +** +** Licensees holding valid Qt Enterprise Edition or Qt Professional Edition +** 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 +** WARRANTY OF DESIGN, MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. +** +** See http://www.trolltech.com/pricing.html or email sales@trolltech.com for +** information about Qt Commercial License Agreements. +** See http://www.trolltech.com/qpl/ for QPL licensing information. +** See http://www.trolltech.com/gpl/ for GPL licensing information. +** +** Contact info@trolltech.com if any conditions of this licensing are +** not clear to you. +** +**********************************************************************/ + + +/***************************************************************************** + QList documentation + *****************************************************************************/ + +/*! + \class QList qlist.h + \brief The QList class is a template class that provides doubly linked lists. + + \ingroup collection + \ingroup tools + + In Qt 2.0 QList is only implemented as a template class. Define a + template instance QList\<X\> to create a list that operates on pointers + to X, or X*. + + Example: + \code + #include <qlist.h> + #include <qstring.h> + #include <stdio.h> + + class Employee + { + public: + Employee( const QString& name, int salary ) { n=name; s=salary; } + QString name() const { return n; } + int salary() const { return s; } + private: + QString n; + int s; + }; + + void main() + { + QList<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) ); + + Employee *emp; + for ( emp=list.first(); emp != 0; emp=list.next() ) + printf( "%s earns %d\n", emp->name().latin1(), emp->salary() ); + } + \endcode + + Program output: + \code + Bill earns 50000 + Steve earns 80000 + Ron earns 60000 + \endcode + + 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 0. The current index is -1 if the current item is null. + + QList has several member functions for traversing the list, but using + a QListIterator can be more practical. Multiple list iterators may + traverse the same list, independent of each other and independent 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 + from the list. The default is to not delete items when they are + removed, but that would cause a memory leak in our example since we have + no other references to the list items. + + 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. + + When inserting an item into a list, only the pointer is copied, not the + item itself. This is called a shallow copy. It is possible to make the + list copy all of the item's data (known as a deep copy) when an item is + inserted. insert(), inSort() and append() call the virtual function + QCollection::newItem() for the item to be inserted. + Inherit a list and reimplement it if you want deep copies. + + When removing an item from a list, the virtual function + QCollection::deleteItem() is called. QList's default implementation + is to delete the item if auto-deletion is enabled. + + The virtual function QGList::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(). + + The QStrList class in qstrlist.h is a list of \c char*. QStrList is + a good example of a list that reimplements newItem(), deleteItem() and + compareItems() + + \sa QListIterator, \link collection.html Collection Classes\endlink +*/ + + +/*! + \fn QList::QList() + Constructs an empty list. +*/ + +/*! + \fn QList::QList( const QList<type> &list ) + Constructs a copy of \e list. + + Each item in \e list is \link append() appended\endlink to this list. + Only the pointers are copied (shallow copy). +*/ + +/*! + \fn QList::~QList() + Removes all items from the list and destroys the list. + + All list iterators that access this list will be reset. + + \sa setAutoDelete() +*/ + +/*! + \fn QList<type> &QList::operator=(const QList<type> &list) + Assigns \e list to this list and returns a reference to this list. + + This list is first cleared, then each item in \e list is + \link append() appended\endlink to this list. Only the pointers are copied + (shallow copy), unless newItem() has been reimplemented(). +*/ + +/*! + \fn bool QList::operator==(const QList<type> &list ) const + + Compares this list with \a list. Retruns TRUE if the lists + contain the same data, else FALSE. +*/ + +/*! + \fn uint QList::count() const + Returns the number of items in the list. + \sa isEmpty() +*/ + +/*! + \fn void QList::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) compares. This is the asymptotic optimal solution of the + sorting problem. + + If the items in your list support operator< and operator== then you + might be better off with QSortedList since it implements the + compareItems() function for you using these two operators. + + \sa inSort() +*/ + +/*! + \fn bool QList::isEmpty() const + Returns TRUE if the list is empty, i.e. count() == 0. Returns FALSE + otherwise. + \sa count() +*/ + +/*! + \fn bool QList::insert( uint index, const type *item ) + Inserts the \e item at the position \e index in the list. + + Returns TRUE if successful, or FALSE if \e index is out of range. + The valid range is <code>0 .. count()</code> inclusive. + The item is appended if \e index == count(). + + The inserted item becomes the current list item. + + The \e item must not be a null pointer. + + \sa append(), current() +*/ + +/*! + \fn void QList::inSort( const type *item ) + Inserts the \e item at its sorted position in the list. + + The sort order depends on the virtual QGList::compareItems() function. + All items must be inserted with inSort() to maintain the sorting order. + + The inserted item becomes the current list item. + + The \e item must not be a null pointer. + + Please note that inSort is slow. If you want to insert lots of items + in a list and sort after inserting then you should use sort(). + inSort() takes up to O(n) compares. That means inserting n items in + your list will need O(n^2) compares while sort() only needs O(n*logn) + for the same task. So you inSort() only if you already have a pre-sorted + list and want to insert only few additional items. + + \sa insert(), QGList::compareItems(), current(), sort() +*/ + +/*! + \fn void QList::append( const type *item ) + Inserts the \e item at the end of the list. + + The inserted item becomes the current list item. + This is equivalent to \c insert(count(),item). + + + The \e item must not be a null pointer. + + \sa insert(), current(), prepend() +*/ + +/*! + \fn void QList::prepend( const type *item ) + + Inserts the \e item at the start of the list. + + The inserted item becomes the current list item. + This is equivalent to \c insert(0,item). + + The \e item must not be a null pointer. + + \sa append(), insert(), current() +*/ + +/*! + \fn bool QList::remove( uint index ) + Removes the item at position \e index in the list. + + Returns TRUE if successful, or FALSE if \e index is out of range. + The valid range is <code>0 .. (count() - 1)</code> inclusive. + + The removed item is deleted if \link QCollection::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 in Qt 2.x. + In 3.0, the current item will be set to null. The current item is + set to null 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 QList::remove() + Removes the current list item. + + Returns TRUE if successful, or FALSE if the current item is null. + + The removed item is deleted if \link QCollection::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 in Qt 2.x. + In 3.0, the current item will be set to null. The current item is + set to null 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 QList::remove( const type *item ) + Removes the first occurrence of \e item from the list. + + Returns TRUE if successful, or FALSE if the item could not be found in the + list. + + The removed item is deleted if \link QCollection::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(). + + 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 in Qt 2.x. + In 3.0, the current item will be set to null. The current item is + set to null 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 QList::removeRef( const type *item ) + Removes the first occurrence of \e item from the list. + + Returns TRUE if successful, or FALSE if the item cannot be found in the + list. + + The removed item is deleted if \link QCollection::setAutoDelete() + auto-deletion\endlink is enabled. + + The list is scanned until the pointer \e item is found. It is removed + if it is found. + + 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 in Qt 2.x. + In 3.0, the current item will be set to null. The current item is + set to null 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 QList::removeNode( QLNode *node ) + Removes the \e node from the list. + + This node must exist in the list, otherwise the program may crash. + + The removed item is deleted if \link QCollection::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 null 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 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 QList::removeFirst() + Removes the first item from the list. + Returns TRUE if successful, or FALSE if the list is empty. + + The removed item is deleted if \link QCollection::setAutoDelete() + auto-deletion\endlink is enabled. + + The first item in the list becomes the new current list item. + The current item is set to null 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 QList::removeLast() + Removes the last item from the list. + Returns TRUE if successful, or FALSE if the list is empty. + + The removed item is deleted if \link QCollection::setAutoDelete() + auto-deletion\endlink is enabled. + + The last item in the list becomes the new current list item. + The current item is set to null 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 *QList::take( uint index ) + Takes the item at position \e index out of the list without + deleting it (even if \link QCollection::setAutoDelete() + auto-deletion\endlink is enabled). + + Returns a pointer to the item taken out of the list, or null if + the index is out of range. + The valid range is <code>0 .. (count() - 1)</code> inclusive. + + The item after the taken item becomes the new current list item if + the taken item is not the last item in the list. If the last item + is taken, the new last item becomes the current item in Qt 2.x. In + 3.0, the current item will be set to null. The current item is set + to null 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 *QList::take() + Takes the current item out of the list without deleting it (even if + \link QCollection::setAutoDelete() auto-deletion\endlink is enabled). + Returns a pointer to the item taken out of the list, or null if + the current item is null. + + The item after the taken item becomes the new current list item if + the taken item is not the last item in the list. If the last item + is taken, the new last item becomes the current item in Qt 2.x. In + 3.0, the current item will be set to null. The current item is set + to null 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 *QList::takeNode( QLNode *node ) + Takes the \e node out of the list without deleting its item (even if + \link QCollection::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 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 QList::clear() + Removes all items from the list. + + The removed items are deleted if \link QCollection::setAutoDelete() + auto-deletion\endlink is enabled. + + All list iterators that access this list will be reset. + + \sa remove(), take(), setAutoDelete() +*/ + +/*! + \fn int QList::find( const type *item ) + Finds the first occurrence of \e 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 null, + 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 QList::findNext( const type *item ) + Finds the next occurrence of \e 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 null, + 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 QList::findRef( const type *item ) + Finds the first occurrence of \e 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 null, + the current index to -1 and returns -1. + + Calling this function is must faster than find(), because find() + compares \e item with each list item using compareItems(). + This function only compares the pointers. + + \sa findNextRef(), find(), current() +*/ + +/*! + \fn int QList::findNextRef( const type *item ) + Finds the next occurrence of \e 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 null, + the current index to -1 and returns -1. + + Calling this function is must faster than findNext(), because findNext() + compares \e item with each list item using compareItems(). + This function only compares the pointers. + + \sa findRef(), findNext(), current() +*/ + +/*! + \fn uint QList::contains( const type *item ) const + Counts and returns the number of occurrences of \e item in the list. + + The compareItems() function is called when looking for the \e item + in the list. If compareItems() is not reimplemented, it is more + efficient to call containsRef(). + + Does not affect the current list item. + + \sa containsRef(), compareItems() +*/ + +/*! + \fn uint QList::containsRef( const type *item ) const + Counts and returns the number of occurrences of \e item in the list. + + Calling this function is must faster than contains(), because contains() + compares \e item with each list item using compareItems(). + This function only compares the pointers. + + Does not affect the current list item. + + \sa contains() +*/ + +/*! + \fn type *QList::at( uint index ) + Returns a pointer to the item at position \e index in the list, or + null if the index is out of range. + + Sets the current list item to this item if \e index is valid. + The valid range is <code>0 .. (count() - 1)</code> inclusive. + + This function is very efficient. It starts scanning from the first + item, last item or current item, whichever is closest to \e index. + + \sa current() +*/ + +/*! + \fn int QList::at() const + Returns the index of the current list item. The returned value is -1 + if the current item is null. + \sa current() +*/ + +/*! + \fn type *QList::current() const + Returns a pointer to the current list item. The current item may be + null (implies that the current index is -1). + \sa at() +*/ + +/*! + \fn QLNode *QList::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 *QList::getFirst() const + Returns a pointer to the first item in the list, or null if the + list is empty. + + Does not affect the current list item. + + \sa first(), getLast() +*/ + +/*! + \fn type *QList::getLast() const + Returns a pointer to the last item in the list, or null if the + list is empty. + + Does not affect the current list item. + + \sa last(), getFirst() +*/ + +/*! + \fn type *QList::first() + Returns a pointer to the first item in the list and makes this the + current list item, or null if the list is empty. + \sa getFirst(), last(), next(), prev(), current() +*/ + +/*! + \fn type *QList::last() + Returns a pointer to the last item in the list and makes this the + current list item, or null if the list is empty. + \sa getLast(), first(), next(), prev(), current() +*/ + +/*! + \fn type *QList::next() + Returns a pointer to the item succeeding the current item. + Returns null if the current item is null 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 null. + If the current item was null, this function does nothing. + + \sa first(), last(), prev(), current() +*/ + +/*! + \fn type *QList::prev() + Returns a pointer to the item preceding the current item. + Returns null if the current item is null 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 null. + If the current item was null, this function does nothing. + + \sa first(), last(), next(), current() +*/ + +/*! + \fn void QList::toVector( QGVector *vec ) const + Stores all list items in the vector \e vec. + + The vector must be have the same item type, otherwise the result + will be undefined. +*/ + + +/***************************************************************************** + QListIterator documentation + *****************************************************************************/ + +/*! + \class QListIterator qlist.h + \brief The QListIterator class provides an iterator for QList collections. + + \ingroup collection + \ingroup tools + + Define a template instance QListIterator\<X\> to create a list iterator + that operates on QList\<X\> (list of X*). + + Example: + \code + #include <qlist.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; + }; + + void main() + { + QList<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) ); + + QListIterator<Employee> it(list); // iterator for employee list + for ( ; it.current(); ++it ) { + Employee *emp = it.current(); + printf( "%s earns %d\n", emp->name().latin1(), emp->salary() ); + } + } + \endcode + + Program output: + \code + Bill earns 50000 + Steve earns 80000 + Ron earns 60000 + \endcode + + Although QList has member functions to traverse the doubly linked list + structure, using a list iterator is a much more robust way of traversing + the list, because multiple list iterators can operate on the same list, + independent of each other and independent of the QList's current item. + An iterator has its own current list item and can get the next and + previous list items. It can only traverse the list, never modify it. + + A QList knows about all list iterators that are operating on the list. + When an item is removed from the list, the list update all iterators + that are pointing the removed item to point to the new current list item. + + Example: + \code + #include <qlist.h> + #include <qstring.h> + #include <stdio.h> + + class Employee + { + ... // same as above + }; + + void main() + { + QList<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) ); + + QListIterator<Employee> it(list); + + list.at( 1 ); // current list item: "Steve" + it.toLast(); // it: "Ron" + --it; // it: "Steve" + + // Now, both the list and the iterator are referring the same item + + list.remove(); + printf( "%s\n", it.current()->name().latin1() ); + } + \endcode + + Program output: + \code + Ron + \endcode + + \sa QList, \link collection.html collection classes\endlink +*/ + +/*! + \fn QListIterator::QListIterator( const QList<type> &list ) + Constructs an iterator for \e list. The current iterator item is + set to point on the first item in the \e list. +*/ + +/*! + \fn QListIterator::~QListIterator() + Destroys the iterator. +*/ + +/*! + \fn uint QListIterator::count() const + Returns the number of items in the list this iterator operates on. + \sa isEmpty() +*/ + +/*! + \fn bool QListIterator::isEmpty() const + Returns TRUE if the list is empty, i.e. count() == 0, otherwise FALSE. + \sa count() +*/ + +/*! + \fn bool QListIterator::atFirst() const + Returns TRUE if the current iterator item is the first list item, otherwise + FALSE. + \sa toFirst(), atLast() +*/ + +/*! + \fn bool QListIterator::atLast() const + Returns TRUE if the current iterator item is the last list item, otherwise + FALSE. + \sa toLast(), atFirst() +*/ + +/*! + \fn type *QListIterator::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 null and returns null + if the list is empty. + \sa toLast(), atFirst() +*/ + +/*! + \fn type *QListIterator::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 null and returns null + if the list is empty. + \sa toFirst(), atLast() +*/ + +/*! + \fn QListIterator::operator type *() const + Cast operator. Returns a pointer to the current iterator item. + Same as current(). +*/ + +/*! + \fn type *QListIterator::operator*() + Asterix operator. Returns a pointer to the current iterator item. + Same as current(). +*/ + +/*! + \fn type *QListIterator::current() const + Returns a pointer to the current iterator item. +*/ + +/*! + \fn type *QListIterator::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 + null, null is returned. +*/ + +/*! + \fn char *QStrListIterator::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 + null, null is returned. +*/ + +/*! + \fn type *QListIterator::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 + null, null is returned. +*/ + +/*! + \fn type *QListIterator::operator+=( uint jump ) + Sets the current item to the item \e 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 null and returns null +*/ + +/*! + \fn type *QListIterator::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 + null, null is returned. +*/ + +/*! + \fn type *QListIterator::operator-=( uint jump ) + Returns the item \e jump positions before the current item, or null if + it is beyond the first item. Makes this the current item. +*/ + +/*! + \fn QListIterator<type>& QListIterator::operator=( const QListIterator<type> &it ) + Assignment. Makes a copy of the iterator \a it and returns a reference + to this iterator. +*/ + + +/***************************************************************************** + QStrList documentation + *****************************************************************************/ + +typedef QList<char> QStrList + +/*! + \class QStrList qstrlist.h + \brief The QStrList class provides a doubly linked list of \c char*. + + \inherit QList + + \ingroup collection + \ingroup tools + + This class is a QList\<char\> instance (a list of char*). + + QStrList can make deep or shallow copies of the strings that are inserted. + + A deep copy means to allocate space for the string and then copy the string + data into it. A shallow copy is just a copy of the pointer value and not + the string data. + + The disadvantage with shallow copies is that since a pointer can only + be deleted 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 shallow copies + 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 a sorted order. + + 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 \e deepCopies is TRUE, or uses shallow copies if \e deepCopies + is FALSE. +*/ + +/*! + \fn QStrList::QStrList( const QStrList &list ) + Constructs a copy of \e list. + + If \e 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 \e list to this list and returns a reference to this list. + + If \e 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 \c char* with +case insensitive compare. + + \ingroup collection + \ingroup tools + + This class is a QList\<char\> instance (a list of char*). + + QStrIList is similar to QStrList except that it is case insensitive. + The virtual compareItems() function is reimplemented and does a + case insensitive string comparison. + The inSort() function will insert strings in a sorted order. + + The QStrListIterator class is an iterator for QStrList. +*/ + +/*! + \fn QStrIList::QStrIList( bool deepCopies ) + Constructs a list of strings. Will make deep copies of all inserted + strings if \e deepCopies is TRUE, or uses shallow copies if \e deepCopies + is FALSE. +*/ + +/*! + \fn QStrIList::~QStrIList() + Destroys the list. All strings are removed. +*/ + + +/***************************************************************************** + QStrListIterator documentation + *****************************************************************************/ + +/*! + \class QStrListIterator qstrlist.h + \brief The QStrListIterator class is an iterator for the QStrList and QStrIList classes. + + \inherit QListIterator + + \ingroup tools + + This class is a QListIterator\<char\> instance. + It can traverse the strings in the QStrList and QStrIList classes. +*/ diff --git a/qtools/qptrdict.doc b/qtools/qptrdict.doc new file mode 100644 index 0000000..5a652d0 --- /dev/null +++ b/qtools/qptrdict.doc @@ -0,0 +1,486 @@ +/**************************************************************************** +** $Id$ +** +** QPtrDict and QPtrDictIterator class documentation +** +** Copyright (C) 1992-2000 Trolltech AS. All rights reserved. +** +** This file is part of the Qt GUI Toolkit. +** +** This file may be distributed under the terms of the Q Public License +** as defined by Trolltech AS of Norway and appearing in the file +** LICENSE.QPL included in the packaging of this file. +** +** This file may be distributed and/or modified under the terms of the +** GNU General Public License version 2 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. +** +** Licensees holding valid Qt Enterprise Edition or Qt Professional Edition +** 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 +** WARRANTY OF DESIGN, MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. +** +** See http://www.trolltech.com/pricing.html or email sales@trolltech.com for +** information about Qt Commercial License Agreements. +** See http://www.trolltech.com/qpl/ for QPL licensing information. +** See http://www.trolltech.com/gpl/ for GPL licensing information. +** +** Contact info@trolltech.com if any conditions of this licensing are +** not clear to you. +** +**********************************************************************/ + + +/***************************************************************************** + QPtrDict documentation + *****************************************************************************/ + +/*! + \class QPtrDict qptrdict.h + \brief The QPtrDict class is a template class that provides a dictionary based on \c void* keys. + + \ingroup collection + \ingroup tools + + QPtrDict is implemented as a template class. Define a + template instance QPtrDict\<X\> to create a dictionary that operates on + pointers to X, or X*. + + A dictionary is a collection that associates an item with a key. + The key is used for inserting and looking up an item. QPtrDict has + \c void* keys. + + The dictionary has very fast insertion and lookup. + + Example: + \code + #include <qptrdict.h> + #include <stdio.h> + + void main() + { + int *a = new int[12]; + int *b = new int[10]; + int *c = new int[18]; + int *d = new int[13]; + + QPtrDict<char> dict; // maps void* -> char* + + dict.insert( a, "a is int[12]" ); // describe pointers + dict.insert( b, "b is int[10]" ); + dict.insert( c, "c is int[18]" ); + + printf( "%s\n", dict[a] ); // print descriptions + printf( "%s\n", dict[b] ); + printf( "%s\n", dict[c] ); + + if ( !dict[d] ) + printf( "d not in dictionary\n" ); + } + \endcode + + Program output: + \code + a is int[12] + b is int[10] + c is int[18] + d not in dictionary + \endcode + + The dictionary in our example maps \c int* keys to \c char* items. + QPtrDict implements the \link operator[] [] operator\endlink to lookup + an item. + + QPtrDict is implemented by QGDict as a hash array with a fixed number of + entries. Each array entry points to a singly linked list of buckets, in + which the dictionary items are stored. + + When an item is inserted with a key, the key is converted (hashed) to + an integer index into the hash array using the \c mod operation. The + item is inserted before the first bucket in the list of buckets. + + Looking up an item is normally very fast. The key is again hashed to an + array index. Then QPtrDict scans the list of buckets and returns the item + found or null if the item was not found. You cannot insert null pointers + into a dictionary. + + The size of the hash array is very important. In order to get good + performance, you should use a suitably large \link primes.html prime + number\endlink. Suitable means equal to or larger than the maximum + expected number of dictionary items. + + Items with equal keys are allowed. When inserting two items with the + same key, only the last inserted item will be visible (last in, first out) + until it is removed. + + Example: + \code + #include <qptrdict.h> + #include <stdio.h> + + void main() + { + QPtrDict<char> dict; // maps char* ==> char* + + double *ptr = new double[28]; + dict.insert( ptr, "first" ); + dict.insert( ptr, "second" ); + + printf( "%s\n", dict[ptr] ); + dict.remove( ptr ); + printf( "%s\n", dict[ptr] ); + } + \endcode + + Program output: + \code + second + first + \endcode + + The QPtrDictIterator class can traverse the dictionary contents, but only + in an arbitrary order. Multiple iterators may independently traverse the + same dictionary. + + Calling setAutoDelete(TRUE) for a dictionary tells it to delete items + that are removed . The default is to not delete items when they are + removed. + + When inserting an item into a dictionary, only the pointer is copied, not + the item itself. This is called a shallow copy. It is possible to make the + dictionary copy all of the item's data (known as a deep copy) when an + item is inserted. insert() calls the virtual function + QCollection::newItem() for the item to be inserted. + Inherit a dictionary and reimplement it if you want deep copies. + + When removing a dictionary item, the virtual function + QCollection::deleteItem() is called. QPtrDict's default implementation + is to delete the item if auto-deletion is enabled. + + \sa QPtrDictIterator, QDict, QAsciiDict, QIntDict, + \link collection.html Collection Classes\endlink +*/ + + +/*! + \fn QPtrDict::QPtrDict( int size ) + Constructs a dictionary using an internal hash array with the size + \e size. + + Setting \e size to a suitably large \link primes.html prime number\endlink + (equal to or greater than the expected number of entries) makes the hash + distribution better and hence the loopup faster. +*/ + +/*! + \fn QPtrDict::QPtrDict( const QPtrDict<type> &dict ) + Constructs a copy of \e dict. + + Each item in \e dict are inserted into this dictionary. + Only the pointers are copied (shallow copy). +*/ + +/*! + \fn QPtrDict::~QPtrDict() + Removes all items from the dictionary and destroys it. + + All iterators that access this dictionary will be reset. + + \sa setAutoDelete() +*/ + +/*! + \fn QPtrDict<type> &QPtrDict::operator=(const QPtrDict<type> &dict) + Assigns \e dict to this dictionary and returns a reference to this + dictionary. + + This dictionary is first cleared, then each item in \e dict is inserted + into this dictionary. + Only the pointers are copied (shallow copy), unless newItem() has been + reimplemented(). +*/ + +/*! + \fn uint QPtrDict::count() const + Returns the number of items in the dictionary. + \sa isEmpty() +*/ + +/*! + \fn uint QPtrDict::size() const + Returns the size of the internal hash array (as specified in the + constructor). + \sa count() +*/ + +/*! + \fn void QPtrDict::resize( uint newsize ) + Changes the size of the hashtable the \a newsize. + The contents of the dictionary are preserved, + but all iterators on the dictionary become invalid. +*/ + +/*! + \fn bool QPtrDict::isEmpty() const + Returns TRUE if the dictionary is empty, i.e. count() == 0. Returns FALSE + otherwise. + \sa count() +*/ + +/*! + \fn void QPtrDict::insert( void *key, const type *item ) + Inserts the \e key with the \e item into the dictionary. + + The key does not have to be a unique dictionary key. If multiple items + are inserted with the same key, only the last item will be visible. + + Null items are not allowed. + + \sa replace() +*/ + +/*! + \fn void QPtrDict::replace( void *key, const type *item ) + Replaces an item which has a key equal to \e key with \e item. + + If the item does not already exist, it will be inserted. + + Null items are not allowed. + + Equivalent to: + \code + QPtrDict<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 inserted + of these will be replaced. + + \sa insert() +*/ + +/*! + \fn bool QPtrDict::remove( void *key ) + Removes the item associated with \e key from the dictionary. + Returns TRUE if successful, or FALSE if the key does not exist in the + dictionary. + + If there are two or more items with equal keys, then the last inserted + of these will be removed. + + The removed item is deleted if \link QCollection::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 traversing order. + + \sa take(), clear(), setAutoDelete() +*/ + +/*! + \fn type *QPtrDict::take( void *key ) + Takes the item associated with \e key out of the dictionary without + deleting it (even if \link QCollection::setAutoDelete() + auto-deletion\endlink is enabled). + + If there are two or more items with equal keys, then the last inserted + of these will be taken. + + Returns a pointer to the item taken out, or null 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 traversing order. + + \sa remove(), clear(), setAutoDelete() +*/ + +/*! + \fn void QPtrDict::clear() + Removes all items from the dictionary. + + The removed items are deleted if \link QCollection::setAutoDelete() + auto-deletion\endlink is enabled. + + All dictionary iterators that access this dictionary will be reset. + + \sa remove(), take(), setAutoDelete() +*/ + +/*! + \fn type *QPtrDict::find( void *key ) const + Returns the item associated with \e key, or null 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 last inserted + of these will be found. + + Equivalent to the [] operator. + + \sa operator[]() +*/ + +/*! + \fn type *QPtrDict::operator[]( void *key ) const + Returns the item associated with \e key, or null 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 last inserted + of these will be found. + + Equivalent to the find() function. + + \sa find() +*/ + +/*! + \fn void QPtrDict::statistics() const + Debugging-only function that prints out the dictionary distribution + using qDebug(). +*/ + + +/***************************************************************************** + QPtrDictIterator documentation + *****************************************************************************/ + +/*! + \class QPtrDictIterator qptrdict.h + \brief The QPtrDictIterator class provides an iterator for QPtrDict collections. + + \ingroup collection + \ingroup tools + + QPtrDictIterator is implemented as a template class. + Define a template instance QPtrDictIterator\<X\> to create a + dictionary iterator that operates on QPtrDict\<X\> (dictionary of X*). + + Example: + \code + #include <qptrdict.h> + #include <stdio.h> + + void main() + { + int *a = new int[12]; + int *b = new int[10]; + int *c = new int[18]; + int *d = new int[13]; + + QPtrDict<char> dict; // maps void* -> char* + + dict.insert( a, "a is int[12]" ); // describe pointers + dict.insert( b, "b is int[10]" ); + dict.insert( c, "c is int[18]" ); + + QPtrDictIterator<char> it( dict ); // iterator for dict + + while ( it.current() ) { + printf( "%x -> %s\n", it.currentKey(), it.current() ); + ++it; + } + } + \endcode + + Program output: + \code + 804a788 -> a is int[12] + 804a7f0 -> c is int[18] + 804a7c0 -> b is int[10] + \endcode + + Note that the traversal order is arbitrary, you are not guaranteed the + order above. + + Multiple iterators may independently traverse the same dictionary. + A QPtrDict knows about all iterators that are operating on the dictionary. + When an item is removed from the dictionary, QPtrDict update all + iterators that are referring the removed item to point to the next item + in the traversing order. + + \sa QPtrDict, \link collection.html Collection Classes\endlink +*/ + +/*! + \fn QPtrDictIterator::QPtrDictIterator( const QPtrDict<type> &dict ) + Constructs an iterator for \e dict. The current iterator item is + set to point on the first item in the \e dict. +*/ + +/*! + \fn QPtrDictIterator::~QPtrDictIterator() + Destroys the iterator. +*/ + +/*! + \fn uint QPtrDictIterator::count() const + Returns the number of items in the dictionary this iterator operates on. + \sa isEmpty() +*/ + +/*! + \fn bool QPtrDictIterator::isEmpty() const + Returns TRUE if the dictionary is empty, i.e. count() == 0. Returns FALSE + otherwise. + \sa count() +*/ + +/*! + \fn type *QPtrDictIterator::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 null and + returns null. +*/ + +/*! + \fn QPtrDictIterator::operator type *() const + Cast operator. Returns a pointer to the current iterator item. + Same as current(). +*/ + +/*! + \fn type *QPtrDictIterator::current() const + Returns a pointer to the current iterator item. +*/ + +/*! + \fn void *QPtrDictIterator::currentKey() const + Returns the key for the current iterator item. +*/ + +/*! + \fn type *QPtrDictIterator::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 null, null is returned. +*/ + +/*! + \fn type *QPtrDictIterator::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 null, null is returned. +*/ + +/*! + \fn type *QPtrDictIterator::operator+=( uint jump ) + Sets the current item to the item \e 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 null and returns null. +*/ diff --git a/qtools/qsortedlist.doc b/qtools/qsortedlist.doc new file mode 100644 index 0000000..12d3f02 --- /dev/null +++ b/qtools/qsortedlist.doc @@ -0,0 +1,94 @@ +/**************************************************************************** +** $Id$ +** +** QSortedList documentation +** +** Copyright (C) 1992-2000 Trolltech AS. All rights reserved. +** +** This file is part of the Qt GUI Toolkit. +** +** This file may be distributed under the terms of the Q Public License +** as defined by Trolltech AS of Norway and appearing in the file +** LICENSE.QPL included in the packaging of this file. +** +** This file may be distributed and/or modified under the terms of the +** GNU General Public License version 2 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. +** +** Licensees holding valid Qt Enterprise Edition or Qt Professional Edition +** 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 +** WARRANTY OF DESIGN, MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. +** +** See http://www.trolltech.com/pricing.html or email sales@trolltech.com for +** information about Qt Commercial License Agreements. +** See http://www.trolltech.com/qpl/ for QPL licensing information. +** See http://www.trolltech.com/gpl/ for GPL licensing information. +** +** Contact info@trolltech.com if any conditions of this licensing are +** not clear to you. +** +**********************************************************************/ + + +/***************************************************************************** + QSortedList documentation + *****************************************************************************/ + +/*! + \class QSortedList qsortedlist.h + \brief The QSortedList class provides a list sorted by operator< and operator== + + \ingroup collection + \ingroup tools + + If you want to sort a QList you have to reimplement the + QGList::compareItems() method. If the elements of your list support + operator<() and operator==() then you can use QSortedList instead. + Its compareItems() calls operator<() and operator==() and returns an + appropriate result. + + Otherwise, this is as QList. + + \sa QList, \link collection.html Collection Classes\endlink +*/ + + +/*! + \fn QSortedList::QSortedList() + Constructs an empty list. +*/ + +/*! + \fn QSortedList::QSortedList( const QSortedList<type> &list ) + Constructs a copy of \e list. + + Each item in \e list is copied to this new list. +*/ + +/*! + \fn QSortedList::~QSortedList() + Removes all items from the list and destroys the list. + + All list iterators that access this list will be reset. +*/ + +/*! + \fn QSortedList<type>& QSortedList::operator=(const QSortedList<type>& list) + Assigns \e list to this list and returns a reference to this list. + + This list is first cleared, then each item in \e list is + appended to this list. Only the pointers are copied + (shallow copy), unless newItem() has been reimplemented(). +*/ + +/*! + \fn int QSortedList::compareItems( QCollection::Item s1, QCollection::Item s2 ) + + \reimp + + This reimplementation uses operator< and operator== to compare. +*/ diff --git a/qtools/qstack.doc b/qtools/qstack.doc new file mode 100644 index 0000000..b51e7c0 --- /dev/null +++ b/qtools/qstack.doc @@ -0,0 +1,135 @@ +/**************************************************************************** +** $Id$ +** +** QStack class documentation +** +** Copyright (C) 1992-2000 Trolltech AS. All rights reserved. +** +** This file is part of the Qt GUI Toolkit. +** +** This file may be distributed under the terms of the Q Public License +** as defined by Trolltech AS of Norway and appearing in the file +** LICENSE.QPL included in the packaging of this file. +** +** This file may be distributed and/or modified under the terms of the +** GNU General Public License version 2 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. +** +** Licensees holding valid Qt Enterprise Edition or Qt Professional Edition +** 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 +** WARRANTY OF DESIGN, MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. +** +** See http://www.trolltech.com/pricing.html or email sales@trolltech.com for +** information about Qt Commercial License Agreements. +** See http://www.trolltech.com/qpl/ for QPL licensing information. +** See http://www.trolltech.com/gpl/ for GPL licensing information. +** +** Contact info@trolltech.com if any conditions of this licensing are +** not clear to you. +** +**********************************************************************/ + + +/***************************************************************************** + QStack documentation + *****************************************************************************/ + +/*! + \class QStack qstack.h + \brief The QStack class is a template class that provides a stack. + + \ingroup collection + \ingroup tools + + QStack is implemented as a template class. Define a template + instance QStack\<X\> to create a stack that operates on pointers to + X, or X*. + + A stack is a Last In, First Out (LIFO) structure. Items are added to + the top of the stack with push() and retrieved from the top + with pop(). + + \sa \link collection.html Collection Classes\endlink +*/ + +/*! \fn QStack::QStack () + Creates and empty stack. +*/ + +/*! \fn QStack::QStack (const QStack<type>& s) + Creates a stack by making a shallow copy of another stack. +*/ + +/*! \fn QStack::~QStack () + Destroys the stack. All items will be deleted if autoDelete() is TRUE. +*/ + +/*! \fn QStack<type>& QStack::operator= (const QStack<type>& s) + Sets the contents of this stack by making a shallow copy of another stack. + Elements currently in this stack will be deleted if autoDelete() is TRUE. +*/ + +/*! \fn bool QStack::isEmpty () const + Returns TRUE is the stack contains no elements to be \link pop() popped\endlink. +*/ + +/*! \fn void QStack::push (const type* d) + Adds an element to the top of the stack. Last in, first out. +*/ + +/*! \fn type* QStack::pop () + Removes the top item from the stack and returns it. +*/ + +/*! \fn bool QStack::remove () + Removes the top item from the stack and deletes it if + autoDelete() is TRUE. Returns TRUE if there was an item to pop. + + \sa clear() +*/ + +/*! \fn void QStack::clear() + Removes all items from the stack, deleting them if + autoDelete() is TRUE. + + \sa remove() +*/ + +/*! \fn uint QStack::count() const + Returns the number of items in the stack. + + \sa isEmpty() +*/ + +/*! \fn type* QStack::top () const + Returns a reference to the top item on the stack (most recently pushed). + The stack is not changed. +*/ + +/*! \fn QStack::operator type* ()const + Returns a reference to the top item on the stack (most recently pushed). + The stack is not changed. +*/ + +/*! \fn type* QStack::current () const + Returns a reference to the top item on the stack (most recently pushed). + The stack is not changed. +*/ + +/*! \fn bool QStack::autoDelete() const + + The same as QCollection::autoDelete(). + + \sa setAutoDelete() +*/ + +/*! \fn void QStack::setAutoDelete( bool enable ) + + The same as QCollection::setAutoDelete(). + + \sa autoDelete() +*/ diff --git a/qtools/qstrlist.doc b/qtools/qstrlist.doc new file mode 100644 index 0000000..81e4e46 --- /dev/null +++ b/qtools/qstrlist.doc @@ -0,0 +1,5 @@ +/**************************************************************************** +** $Id$ +*****************************************************************************/ + +//typedef QListIterator<char> QStrListIterator; diff --git a/qtools/qtl.doc b/qtools/qtl.doc new file mode 100644 index 0000000..e4ce0d0 --- /dev/null +++ b/qtools/qtl.doc @@ -0,0 +1,249 @@ +/**************************************************************************** +** $Id$ +** +** Qt template library classes documentation +** +** Copyright (C) 1992-2000 Trolltech AS. All rights reserved. +** +** This file is part of the Qt GUI Toolkit. +** +** This file may be distributed under the terms of the Q Public License +** as defined by Trolltech AS of Norway and appearing in the file +** LICENSE.QPL included in the packaging of this file. +** +** This file may be distributed and/or modified under the terms of the +** GNU General Public License version 2 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. +** +** Licensees holding valid Qt Enterprise Edition or Qt Professional Edition +** 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 +** WARRANTY OF DESIGN, MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. +** +** See http://www.trolltech.com/pricing.html or email sales@trolltech.com for +** information about Qt Commercial License Agreements. +** See http://www.trolltech.com/qpl/ for QPL licensing information. +** See http://www.trolltech.com/gpl/ for GPL licensing information. +** +** Contact info@trolltech.com if any conditions of this licensing are +** not clear to you. +** +**********************************************************************/ + +/*! +\page qtl.html + +\title Qt Template library + +Thq Qt Template Library is a set of templates within Qt dealing with +containers of objects. It provides a list of objects, a stack of +objects, a map (or dictionary) from one type to another, and +associated iterators and algorithms. + +Qt also contains similar classes that deal with pointers to objects; +\l QValueList vs. \l QList, etc. Compared to the pointer-based +templates, the QTL offers easy copying of the container, real support +for classes that e.g. require constructors, expand to much more object +code, can often be a bit faster, require that the objects stored can +be copied, and finally, have a worse record of compiler problems. + +Compared to the STL, the QTL contains only the most important features +of the STL, has more regular function naming, has no platform +differences, is often a little slower and often expands to less object +code. + + +If you can not make copies of the objects you want to store you are +better off with QCollection and friends. They were designed to handle +exactly that kind of pointer semantics. This applies for example to +all classes derived from \l QObject. A QObject does not have a copy +constructor, so using it as value is impossible. You may choose be +store pointers to QObjects in a QValueList, but using QList directly +seems to be the better choice for this kind of application +domain. QList, like all other QCollection based containers, provides +far more sanity checking than a speed-optimized value +based container. + +If you have objects that implement value semantics, use the Qt +template library. Value semantics require at least +<ul> +<li>a copy constructor, +<li>an assignment operator and +<li> a default constructor, i.e. a constructor that does not take +any arguments. +</ul> +Note that a fast copy constructor is absolutely crucial for a good +overall performance of the container, since many copy operations are +going to happen. + +Examples for value based classes are QRect, QPoint, QSize and all +simple C++ types like int, bool or double. + +The Qt template library is designed for speed. Especially iterators +are extremely fast. On the drawback side, less error checking is done +than in the QCollection based containers. A template library container +for example does not track associated iterators. This makes certain +validity checks, like on removing items, impossible to perform +automatically. + +<h2> Iterators </h2> + +The Qt template library deals with value objects, not with pointers. +For that reason, there is no other way of iterating over containers +than using iterators. This is no disadvantage as the size of an +iterator matches the size of a normal pointer - 32 or 64 bits +depending on your CPU architecture. + +To iterate over a container, use a loop like this: + +\code + typedef QValueList<int> List; + List l; + for( List::Iterator it = l.begin(); it != l.end(); ++it ) + printf("Number is %i\n",*it); +\endcode + +begin() returns the iterator pointing at the first element, while +end() returns an iterator that points \e after the last +element. end() marks an invalid position, it can never be +dereferenced. It's the break condition in any iteration, may it be +from begin() or fromLast(). For maximum speed, use increment or +decrement iterators with the prefix operator (++it, --it) instead of the the +postfix one (it++, it--), since the former is slightly faster. + +The same concept applies to the other container classes: + +\code + typedef QMap<QString,QString> Map; + Map map; + for( Map::Iterator it = map.begin(); it != map.end(); ++it ) + printf("Key=%s Data=%s\n", it.key().ascii(), it.data().ascii() ); + + typedef QArray<int> Array; + Array array; + for( Array::Iterator it = array.begin(); it != array.end(); ++it ) + printf("Data=%i\n", *it ); +\endcode + +There are two kind of iterators, the volatile iterator shown in the +examples above and a version that returns a const reference to its +current object, the ConstIterator. Const iterators are required +whenever the container itself is const, such as a member variable +inside a const function. Assigning a ConstIterator to a normal +Iterator is not allowed as it would violate const semantics. + +<h2> Algorithms </h2> + +The template library defines a number of algorithms that operate on +its containers: qHeapSort(), qBubbleSort(), qSwap() and +qCopy(). These algorithms are implemented as template functions. + +qHeapSort() and qBubbleSort() provide the well known sorting +algorithms. You can use them like this: + +\code + typedef QValueList<int> List; + List l; + l << 42 << 100 << 1234 << 12 << 8; + qHeapSort( l ); + + List l2; + l2 << 42 << 100 << 1234 << 12 << 8; + List::Iterator b = l2.find( 100 ); + List::Iterator e = l2.find( 8 ); + qHeapSort( b, e ); + + double arr[] = { 3.2, 5.6, 8.9 }; + qHeapSort( arr, arr + 3 ); +\endcode + +The first example sorts the entire list. The second one sorts all +elements enclosed in the two iterators, namely 100, 1234 and 12. The +third example shows that iterators act like pointers and can be +treated as such. + +Naturally, the sorting templates won't work with const iterators. + +Another utility is qSwap(). It exchanges the values of two variables: + +\code + QString second( "Einstein" ); + QString name( "Albert" ); + qSwap( second, name ); +\endcode + +Another template function is qCopy(). It copies a container or a slice +of it to an OutputIterator, in this case a QTextOStreamIterator: + +\code + typedef QValueList<int> List; + List l; + l << 100 << 200 << 300; + QTextOStream str( stdout ); + qCopy( l, QTextOStreamIterator( str ) ); +\endcode + +In addition, you can use any Qt template library iterator as the +OutputIterator. Just make sure that the right hand of the iterator has +as many elements present as you want to insert. The following example +illustrates this: + +\code + QStringList l1, l2; + l1 << "Weis" << "Ettrich" << "Arnt" << "Sue"; + l2 << "Torben" << "Matthias"; + qCopy( l2, l1.begin(); +\endcode + +At the end of this code fragment, the List l1 contains "Torben", +"Matthias", "Arnt" and "Sue", with the prior contents being +overwritten. Another flavor of qCopy() takes three arguments to make +it possible to copy a slice of a container: + +\code + typedef QValueList<int> List; + List l; + l << 42 << 100 << 1234 << 12 << 8; + List::Iterator b = l.find( 100 ); + List::Iterator e = l.find( 8 ); + QTextOStream str( stdout ); + qCopy( b, e, QTextOStreamIterator( str ) ); +\endcode + +If you write new algorithms, consider writing them as template +functions in order to make them usable with as many containers +possible. In the above example, you could just as easily print out a +standard C++ array with qCopy(): + +\code + int arr[] = { 100, 200, 300 }; + QTextOStream str( stdout ); + qCopy( arr, arr + 3, QTextOStreamIterator( str ) ); +\endcode + + +<h2> Streaming </h2> + +All mentioned containers can be serialized with the respective +streaming operators. Here is an example. + +\code + QDataStream str(...); + QValueList<QRect> l; + // ... fill the list here + str << l; +\endcode + +The container can be read in again with: + +\code + QValueList<QRect> l; + str >> l; +\endcode + +The same applies to QStringList, QValueStack and QMap. + +*/ diff --git a/qtools/qvaluelist.doc b/qtools/qvaluelist.doc new file mode 100644 index 0000000..6aa95d8 --- /dev/null +++ b/qtools/qvaluelist.doc @@ -0,0 +1,772 @@ +/**************************************************************************** +** $Id$ +** +** QValueList and QValueListIterator class documentation +** +** Copyright (C) 1992-2000 Trolltech AS. All rights reserved. +** +** This file is part of the Qt GUI Toolkit. +** +** This file may be distributed under the terms of the Q Public License +** as defined by Trolltech AS of Norway and appearing in the file +** LICENSE.QPL included in the packaging of this file. +** +** This file may be distributed and/or modified under the terms of the +** GNU General Public License version 2 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. +** +** Licensees holding valid Qt Enterprise Edition or Qt Professional Edition +** 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 +** WARRANTY OF DESIGN, MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. +** +** See http://www.trolltech.com/pricing.html or email sales@trolltech.com for +** information about Qt Commercial License Agreements. +** See http://www.trolltech.com/qpl/ for QPL licensing information. +** See http://www.trolltech.com/gpl/ for GPL licensing information. +** +** Contact info@trolltech.com if any conditions of this licensing are +** not clear to you. +** +**********************************************************************/ + + +/***************************************************************************** + QValueList documentation + *****************************************************************************/ + +/*! + \class QValueList qvaluelist.h + \brief The QValueList class is a value based template class that provides doubly linked lists. + + \ingroup qtl + \ingroup tools + \ingroup shared + + Define a template instance QValueList\<X\> to create a list of values which all + have the class X. Please notice that QValueList does not store pointers to the + members of the list. It holds a copy of every member. That is the reason why this + kind of classes are called "value based" while QList and QDict are "reference based". + + Some classes can not be used within a QValueList, for example everything + derived from QObject and thus all classes that implement widgets. + Only values can be used in a QValueList. To qualify as a value, the class + must provide + <ul> + <li>a copy constructor, + <li>an assignment operator and + <li> a default constructor, i.e. a constructor that does not take any arguments. + </ul> + + Note that C++ defaults to field-by-field assignment operators and + copy constructors if no explicit version is supplied. In many cases, + this is sufficient. + + Example: + \code + #include <qvaluelist.h> + #include <qstring.h> + #include <stdio.h> + + class Employee + { + public: + Employee(): s(0) {} + Employee( const QString& name, int salary ) + : n(name), s(salary) + {} + + QString name() const { return n; } + int salary() const { return s; } + void setSalary( int salary ) { s = salary; } + private: + QString n; + int s; + }; + + void main() + { + typedef QValueList<Employee> EmployeeList; + EmployeeList list; // list of Employee + + list.append( Employee("Bill", 50000) ); + list.append( Employee("Steve",80000) ); + list.append( Employee("Ron", 60000) ); + + Employee joe( "Joe", 50000 ); + list.append( joe ); + joe.setSalary( 4000 ); + + EmployeeList::Iterator it; + for( it = list.begin(); it != list.end(); ++it ) + printf( "%s earns %d\n", (*it).name().latin1(), (*it).salary().latin1() ); + } + \endcode + + Program output: + \code + Bill earns 50000 + Steve earns 80000 + Ron earns 60000 + Joe earns 50000 + \endcode + + As you can see, the latest changes to Joes salary did not affect the value + in the list because the list created a copy of Joes entry. + + There are three ways of finding items in the list. The first one is by using + the at() function. It returns an iterator. The advantages of + getting an iterator is that you can now move forward or backward from this + position by incrementing/decrementing the iterator. To get the amount of + items in the list call count(). Valid indices are 0..count(). + + The second way of accessing a list is with operator[]. That means you can address + it like an array. The return value is a reference to the value stored in the list. + There exist two versions of this operator. The first one is const and returns a + const reference to the value. The second on is non const and returns a non const + reference to the value. It is up to your compiler to choose the correct one. + + The third method is to use the functions begin() and end(). + With a simple for loop as shown in the example you can iterate over the complete list. + It is save to have multiple iterators at the same time. If some member of the list is + removed then only iterators pointing to the removed member become invalid. Inserting in + the list does not invalidate any iterator. For convenience the function last() returns + an iterator for the last and first() for the first element in the list. + + In addition you can search items in the list with the find() function. It exists in a const + and a non const version. It starts searching from the beginning of the list, but another + flavor of the find() function allows you to specify where searching should start. + If you just want to know wether a certain item is at least once in the list, then you + can use the contains() function. + + Since QValueList is value based there is no need to care about deleting elements in the + list. The list holds its own copies and will free them if the corresponding member or + the list itself is deleted. You can force the list to free all of its item with clear(). + + QValueList is implicitly shared. That means you can just make copies of the list + in time O(1). If multiple QValueList instances share the same data and one + is doing a modification of the lists data then this modifying instance makes a copy + and modifies its private copy. So it does not affect the other instances. + From a developers point of view you can think that a QValueList and a copy of this + list have nothing to do with each other. Developers may only notice that copying is + very fast. People known to a CPUs MMU architecture will know this pattern as "copy on write". + + There exist three functions to insert items in the list. append() + inserts an item at the end, prepend() inserts at the beginning + and insert() inserts in front of the position given by an iterator. + + Items can be removed from the list in two ways. The first is to pass an iterator to + the remove(). The other possibility is to pass a value to remove() which will + delete all members which match this value. + + Lists can be sorted with the algorithms provided by the <a + href="qtl.html">Qt Template Library</a>, for example with + qHeapSort(): + + Example: + \code + QValueList l; + l.append( 5 ); + l.append( 8 ); + l.append( 3 ); + l.append( 4 ); + qHeapSort( l ); + \endcode + + \sa QValueListIterator +*/ + + +/*! + \fn QValueList::QValueList() + Constructs an empty list. +*/ + +/*! + \fn QValueList::QValueList( const QValueList<T>& l ) + Constructs a copy of \e l. + + This operation costs O(1) time since QValueList is implicit shared. + The first instance applying modifications to a shared list will create + a copy which takes in turn O(n) time. However returning a QValueList from + a function is very fast. +*/ + +/*! + \fn QValueList::~QValueList() + Destroys the list. References to the values in the list and all iterators + of this list become invalidated. Since QValueList is highly tuned for performance + you wont see warnings if you use invalid iterators, + because it is impossible for + an iterator to check wether it is valid or not. +*/ + +/*! + \fn QValueList<T>& QValueList::operator= ( const QValueList<T>& l ) + Assigns \e l to this list and returns a reference to this list. + + All iterators of the current list become invalidated by this operation. + The cost of such an assignment is O(1) since QValueList is implicitly shared. +*/ + +/*! + \fn QValueList<T> QValueList::operator+ ( const QValueList<T>& l ) const + Creates a new list and fills it with the elements of this list. Then the + elements of \e l are appended. + + Returns the new list. +*/ + +/*! + \fn QValueList<T>& QValueList::operator+= ( const QValueList<T>& l ) + Adds \e list to this list. + + Returns a reference to this list. +*/ + +/*! + \fn bool QValueList::operator== ( const QValueList<T>& l ) const + Compares both lists. + + Returns TRUE if both list are equal. +*/ + +/*! + \fn bool QValueList::operator!= ( const QValueList<T>& l ) const + Compares both lists. + + Returns TRUE if both list are unequal. +*/ + +/*! + \fn QValueList<T>& QValueList::operator+= ( const T& x ) + Adds the value \e x to the end of the list. + + Returns a reference to the list. +*/ + +/*! + \fn QValueList<T>& QValueList::operator<< ( const T& x ) + Adds the value \e x to the end of the list. + + Returns a reference to the list. +*/ + +/*! + \fn const T& QValueList::operator[] ( uint i ) const + Returns a const reference to the item with index \e i in the list. + It is up to you to check wether this item really exists. You can do that easily + with the count() function. However this operator does not check wether \e i + is in range and will deliver undefined results if it does not exist. +*/ + +/*! + \fn T& QValueList::operator[] ( uint i ) + Returns a reference to the item with index \e i in the list. + It is up to you to check wether this item really exists. You can do that easily + with the count() function. However this operator does not check wether \e i + is in range and will deliver undefined results if it does not exist. + In contrast to the const operator[] you may manipulate the value returned by this + operator. +*/ + +/*! + \fn uint QValueList::count() const + Returns the number of items in the list. + \sa isEmpty() +*/ + +/*! + \fn bool QValueList::isEmpty() const + Returns TRUE if the list is empty, i.e. count() == 0. Returns FALSE + otherwise. + \sa count() +*/ + +/*! + \fn Iterator QValueList::insert( Iterator it, const T& x ) + Inserts the value \e x in front of the iterator \e it. + + Returns an iterator pointing at the inserted item. + + \sa append(), prepend() +*/ + +/*! + \fn Iterator QValueList::append( const T& x ) + Inserts the value \e x at the end of the list. + + Returns an iterator pointing at the inserted item. + + \sa insert(), prepend() +*/ + +/*! + \fn Iterator QValueList::prepend( const T& x ) + Inserts the value \e x at the beginning of the list. + + Returns an iterator pointing at the inserted item. + + \sa insert(), append() +*/ + +/*! + \fn Iterator QValueList::remove( Iterator it ) + Removes the item at position \e it in the list. + + Returns an iterator pointing to the item following the + removed on or end() if the last item was deleted. + + \sa clear() +*/ + +/*! + \fn void QValueList::remove( const T& x ) + Removes all items which have the value \e x. + + \sa clear() +*/ + +/*! + \fn void QValueList::clear() + Removes all items from the list. + + \sa remove() +*/ + +/*! + \fn Iterator QValueList::find( const T& x ) + Finds the first occurrence of \e x in the list. + + Returns end() if no item did match. +*/ + +/*! + \fn ConstIterator QValueList::find( const T& x ) const + Finds the first occurrence of \e x in the list. + + Returns end() if no item did match. +*/ + +/*! + \fn Iterator QValueList::find( Iterator it, const T& x ) + Finds the first occurrence of \e x in the list starting at + the position given by \e it. + + Returns end() if no item did match. +*/ + +/*! + \fn ConstIterator QValueList::find( ConstIterator it, const T& x ) const + Finds the first occurrence of \e x in the list starting at + the position given by \e it. + + Returns end() if no item did match. +*/ + +/*! + \fn uint QValueList::contains( const T& x ) const + Counts and returns the number of occurrences of the value \e x in the list. +*/ + +/*! + \fn int QValueList::findIndex( const T& x ) const + Returns the first index of the value \e x in the list or -1 if no such value + can be found in the list. +*/ + +/*! + \fn Iterator QValueList::at( uint i ) + Returns an iterator pointing to the item at position \e i in the list, or + end() if the index is out of range. +*/ + +/*! + \fn ConstIterator QValueList::at( uint i ) const + Returns an iterator pointing to the item at position \e i in the list, or + end() if the index is out of range. +*/ + +/*! + \fn T& QValueList::first() + Returns a reference to the first item in the list or the item + referenced by end() + if no such items exists. Please note that you may not change + the value the end() Iterator is pointing to. + + \sa begin(), last() +*/ + +/*! + \fn const T& QValueList::first() const + Returns a reference to the first item in the list or the item + referenced by end() if + no such items exists. + + \sa begin(), last() +*/ + +/*! + \fn Iterator QValueList::fromLast() + Returns an iterator pointing to the last element in the list or + end() if no such item exists. + + \sa last() +*/ + +/*! + \fn ConstIterator QValueList::fromLast() const + Returns an iterator pointing to the last element in the list or + end() if no such item exists. + + \sa last() +*/ + +/*! + \fn T& QValueList::last() + Returns a reference to the last item in the list or the item + referenced by end() if no + such item exists. Please note that you may not change + the value the end() Iterator is pointing to. + + \sa end(), first(), fromLast() +*/ + +/*! + \fn const T& QValueList::last() const + Returns a reference to the last item in the list or the item + referenced by end() if no such item exists. + + \sa end(), first(), fromLast() +*/ + +/*! + \fn Iterator QValueList::begin() + Returns an iterator pointing to the first element in the list. This + iterator equals end() if the list is empty; + \sa first(), end() +*/ + +/*! + \fn ConstIterator QValueList::begin() const + Returns an iterator pointing to the first element in the list. This + iterator equals end() if the list is empty; + \sa first(), end() +*/ + +/*! + \fn Iterator QValueList::end() + Returns an iterator pointing behind the last element in the list. This + iterator equals begin() if the list is empty. + + \sa last(), begin() +*/ + +/*! + \fn ConstIterator QValueList::end() const + Returns an iterator pointing behind the last element in the list. This + iterator equals begin() if the list is empty. + + \sa last(), begin() +*/ + +/*! + \fn void QValueList::detach() + If the list does not share its data with another QValueList instance, then nothing + happens, otherwise the function creates a new copy of this data and detaches + from the shared one. This function is called whenever the list is modified. + The implicit sharing mechanism is implemented this way. +*/ + +/*! + \fn QDataStream& operator>>( QDataStream& s, QValueList<T>& l ) + \relates QValueList + Reads a list from the stream. The type \e T stored in the list must implement + the streaming operator, too. +*/ + +/*! + \fn QDataStream& operator<<( QDataStream& s, const QValueList<T>& l ) + \relates QValueList + Writes a list to the stream. The type \e T stored in the list must implement + the streaming operator, too. +*/ + +/***************************************************************************** + QValueListIterator documentation + *****************************************************************************/ + +/*! + \class QValueListIterator qvaluelist.h + \brief The QValueListIterator class provides an iterator for QValueList. + + \ingroup qtl + \ingroup tools + + You can not create an iterator by yourself. Instead you have to + ask a list to give you one. An iterator has only the size of a pointer. + On 32 bit machines that means 4 bytes otherwise 8 bytes. That makes them + very fast. In fact they resemble the semantics of pointers as good as possible + and they are almost as fast as usual pointers. + + Example: + \code + #include <qvaluelist.h> + #include <qstring.h> + #include <stdio.h> + + class Employee + { + public: + Employee(): s(0) {} + Employee( const QString& name, int salary ) + : n(name), s(salary) + {} + + QString name() const { return n; } + int salary() const { return s; } + void setSalary( int salary ) { s = salary; } + private: + QString n; + int s; + }; + + void main() + { + typedef QValueList<Employee> EmployeeList; + EmployeeList list; // list of Employee + + list.append( Employee("Bill", 50000) ); + list.append( Employee("Steve",80000) ); + list.append( Employee("Ron", 60000) ); + + Employee joe( "Joe", 50000 ); + list.append( joe ); + joe.setSalary( 4000 ); + + EmployeeList::Iterator it; + for( it = list.begin(); it != list.end(); ++it ) + printf( "%s earns %d\n", (*it).name().latin1(), (*it).salary() ); + } + \endcode + + Program output: + \code + Bill earns 50000 + Steve earns 80000 + Ron earns 60000 + Joe earns 50000 + \endcode + + In contrast to QList there are no built in functions in QValueList to + traverse the list. The only way to do this is to use iterators. + QValueList is highly optimized for performance and memory usage. + On the other hand that means that you have to be a bit more careful + by what you are doing. QValueList does not know about all its iterators + and the iterators dont even know to which list they belong. That makes + things fast and slim but a bit dangerous because it is up to you to make + sure that iterators you are using are still valid. QListIterator will be able + to give warnings while QValueListIterator may end up in an undefined state. + + For every Iterator there is a ConstIterator. When accessing a QValueList + in a const environment or if the reference or pointer to the list is itself + const, then you have to use the ConstIterator. Its semantics are the same, + but it returns only const references to the item it points to. + + \sa QValueList, QValueListConstIterator +*/ + +/*! + \fn QValueListIterator::QValueListIterator() + Creates un uninitialized iterator. +*/ + +/*! + \fn QValueListIterator::QValueListIterator( NodePtr p ) + Internal function. +*/ + +/*! + \fn QValueListIterator::QValueListIterator( const QValueListIterator<T>& it ) + Constructs a copy of the iterator \e it. +*/ + +/*! + \fn QValueListIterator::~QValueListIterator() + Destroys the iterator. +*/ + +/* Unfortunately not with MSVC + \fn T *QValueListIterator::operator->() + Pointer operator. Returns a pointer to the current iterator item. + The great advantage of this operator is that you can treat the + iterator like a pointer. + + Example: + \code + QValueList<int>::Iterator it = list.begin(); + for( ; it != end(); ++it ) + it->show(); + \endcode +*/ + +/*! + \fn T& QValueListIterator::operator*() + Asterix operator. Returns a reference to the current iterator item. +*/ + +/*! + \fn const T& QValueListIterator::operator*() const + Asterix operator. Returns a reference to the current iterator item. +*/ + +/*! + \fn QValueListIterator<T>& QValueListIterator::operator++() + Prefix ++ makes the succeeding item current and returns + an iterator pointing to the new current item. + The iterator can not check wether it reached the end of the list. Incrementing + the iterator as returned by end() causes undefined results. +*/ + +/*! + \fn QValueListIterator<T> QValueListIterator::operator++(int) + Postfix ++ makes the succeeding item current and returns + an iterator pointing to the new current item. + The iterator can not check wether it reached the end of the list. Incrementing + the iterator as returned by end() causes undefined results. +*/ + +/*! + \fn QValueListIterator<T>& QValueListIterator::operator--() + Prefix -- makes the previous item current and returns + an iterator pointing to the new current item. + The iterator can not check wether it reached the beginning of the list. Decrementing + the iterator as returned by begin() causes undefined results. +*/ + +/*! + \fn QValueListIterator<T> QValueListIterator::operator--(int) + Postfix -- makes the previous item current and returns + an iterator pointing to the new current item. + The iterator can not check wether it reached the beginning of the list. Decrementing + the iterator as returned by begin() causes undefined results. +*/ + +/*! + \fn bool QValueListIterator::operator==( const QValueListIterator<T>& it ) const + Compares both iterators and returns TRUE if they point to the same item. +*/ + +/*! + \fn bool QValueListIterator::operator!=( const QValueListIterator<T>& it ) const + Compares both iterators and returns TRUE if they point to different items. +*/ + +/***************************************************************************** + QValueListConstIterator documentation + *****************************************************************************/ + +/*! + \class QValueListConstIterator qvaluelist.h + \brief The QValueListConstIterator class provides an iterator for QValueList. + + \ingroup qtl + \ingroup tools + + In contrast to QValueListIterator this class is used to iterate over a const + list. It does not allow to modify the values of the list since this would + break the const semantics. + + For more informations on QValueList iterators see QValueListIterator. + + \sa QValueListIterator, QValueList +*/ + +/*! + \fn QValueListConstIterator::QValueListConstIterator() + Creates un uninitialized iterator. +*/ + +/*! + \fn QValueListConstIterator::QValueListConstIterator( NodePtr p ) + Internal function. +*/ + +/*! + \fn QValueListConstIterator::QValueListConstIterator( const QValueListConstIterator<T>& it ) + Constructs a copy of the iterator \e it. +*/ + +/*! + \fn QValueListConstIterator::QValueListConstIterator( const QValueListIterator<T>& it ) + Constructs a copy of the iterator \e it. +*/ + +/*! + \fn QValueListConstIterator::~QValueListConstIterator() + Destroys the iterator. +*/ + +/* Unfortunately not with MSVC + \fn const T *QValueListConstIterator::operator->() + Pointer operator. Returns a pointer to the current iterator item. + The great advantage of this operator is that you can treat the + iterator like a pointer. + + Example: + \code + QValueList<int>::Iterator it = list.begin(); + for( ; it != end(); ++it ) + it->show(); + \endcode +*/ + +/*! + \fn const T& QValueListConstIterator::operator*() const + Asterix operator. Returns a reference to the current iterator item. +*/ + +/*! + \fn QValueListConstIterator<T>& QValueListConstIterator::operator++() + Prefix ++ makes the succeeding item current and returns + an iterator pointing to the new current item. + The iterator can not check wether it reached the end of the list. Incrementing + the iterator as returned by end() causes undefined results. +*/ + +/*! + \fn QValueListConstIterator<T> QValueListConstIterator::operator++(int) + Postfix ++ makes the succeeding item current and returns + an iterator pointing to the new current item. + The iterator can not check wether it reached the end of the list. Incrementing + the iterator as returned by end() causes undefined results. +*/ + +/*! + \fn QValueListConstIterator<T>& QValueListConstIterator::operator--() + Prefix -- makes the previous item current and returns + an iterator pointing to the new current item. + The iterator can not check wether it reached the beginning of the list. Decrementing + the iterator as returned by begin() causes undefined results. +*/ + +/*! + \fn QValueListConstIterator<T> QValueListConstIterator::operator--(int) + Postfix -- makes the previous item current and returns + an iterator pointing to the new current item. + The iterator can not check wether it reached the beginning of the list. Decrementing + the iterator as returned by begin() causes undefined results. +*/ + +/*! + \fn bool QValueListConstIterator::operator==( const QValueListConstIterator<T>& it ) const + Compares both iterators and returns TRUE if they point to the same item. +*/ + +/*! + \fn bool QValueListConstIterator::operator!=( const QValueListConstIterator<T>& it ) const + Compares both iterators and returns TRUE if they point to different items. +*/ diff --git a/qtools/qvector.doc b/qtools/qvector.doc new file mode 100644 index 0000000..24309e3 --- /dev/null +++ b/qtools/qvector.doc @@ -0,0 +1,344 @@ +/**************************************************************************** +** $Id$ +** +** QVector class documentation +** +** Copyright (C) 1992-2000 Trolltech AS. All rights reserved. +** +** This file is part of the Qt GUI Toolkit. +** +** This file may be distributed under the terms of the Q Public License +** as defined by Trolltech AS of Norway and appearing in the file +** LICENSE.QPL included in the packaging of this file. +** +** This file may be distributed and/or modified under the terms of the +** GNU General Public License version 2 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. +** +** Licensees holding valid Qt Enterprise Edition or Qt Professional Edition +** 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 +** WARRANTY OF DESIGN, MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. +** +** See http://www.trolltech.com/pricing.html or email sales@trolltech.com for +** information about Qt Commercial License Agreements. +** See http://www.trolltech.com/qpl/ for QPL licensing information. +** See http://www.trolltech.com/gpl/ for GPL licensing information. +** +** Contact info@trolltech.com if any conditions of this licensing are +** not clear to you. +** +**********************************************************************/ + + +/***************************************************************************** + QVector documentation + *****************************************************************************/ + +// BEING REVISED: ettrich +/*! + \class QVector qvector.h + + \brief The QVector class is a template collection class that + provides a vector (array). + + \ingroup tools + + QVector is implemented as a template class. Define a template + instance QVector\<X\> to create a vector that contains pointers to + X, or X*. + + A vector is the same as an array. The main difference between + QVector and QArray is that QVector stores pointers to the elements, + while QArray stores the elements themselves (i.e. QArray is + value-based). + + Unless where otherwise stated, all functions that remove items from + the vector will also delete the element pointed to if auto-deletion + is enabled - see setAutoDelete(). By default, auto-deletion is + disabled. This behaviour can be changed in a subclass by + reimplementing the virtual method deleteItem(). + + Functions that compares items, e.g. find() and sort(), will do so + using the virtual function compareItems(). The default + implementation of this function will only compare the absolute + pointer values. Reimplement compareItems() in a subclass to get + searching and sorting based on the item contents. + + \sa \link collection.html Collection Classes\endlink, QArray +*/ + +/*! + \fn QVector::QVector() + + Constructs a null vector. + + \sa isNull() +*/ + +/*! + \fn QVector::QVector( uint size ) + + Constructs an vector with room for \a size items. Makes a null + vector if \a size == 0. + + All \a size positions in the vector are initialized to 0. + + \sa size(), resize(), isNull() +*/ + +/*! + \fn QVector::QVector( const QVector<type> &v ) + + Constructs a copy of \a v. Only the pointers are copied (i.e. shallow copy). +*/ + +/*! + \fn QVector::~QVector() + + Removes all items from the vector, and destroys the vector itself. + + \sa clear() +*/ + +/*! + \fn QVector<type> &QVector::operator=( const QVector<type> &v ) + + Assigns \a v to this vector and returns a reference to this vector. + + This vector is first cleared, then all the items from \a v is copied + into this vector. Only the pointers are copied (i.e. shallow copy). + + \sa clear() +*/ + +/*! + \fn type **QVector::data() const + Returns a pointer to the actual vector data, which is an array of type*. + + The vector is a null vector if data() == 0 (null pointer). + + \sa isNull() +*/ + +/*! + \fn uint QVector::size() const + + Returns the size of the vector, i.e. the number of vector + positions. This is also the maximum number of items the vector can + hold. + + The vector is a null vector if size() == 0. + + \sa isNull(), resize(), count() +*/ + +/*! + \fn uint QVector::count() const + + Returns the number of items in the vector. The vector is empty if + count() == 0. + + \sa isEmpty(), size() +*/ + +/*! + \fn bool QVector::isEmpty() const + + Returns TRUE if the vector is empty, i.e. count() == 0, otherwise FALSE. + + \sa count() +*/ + +/*! + \fn bool QVector::isNull() const + + Returns TRUE if the vector is null, otherwise FALSE. + + A null vector has size() == 0 and data() == 0. + + \sa size() +*/ + +/*! + \fn bool QVector::resize( uint size ) + Resizes (expands or shrinks) the vector to \a size elements. The array + becomes a null array if \a size == 0. + + Any items in position \a size or beyond in the vector are removed. + New positions are initialized 0. + + Returns TRUE if successful, or FALSE if the memory cannot be allocated. + + \sa size(), isNull() +*/ + +/*! + \fn bool QVector::insert( uint i, const type *d ) + + Sets position \a i in the vector to contain the item \a d. \a i must + be less than size(). Any previous element in position \a i is removed. + + \sa at() +*/ + +/*! + \fn bool QVector::remove( uint i ) + + Removes the item at position \a i in the vector, if there is one. + \a i must be less than size(). + + Returns TRUE unless \a i is out of range. + + \sa take(), at() +*/ + +/*! + \fn type* QVector::take( uint i ) + + Returns the item at position \a i in the vector, and removes that + item from the vector. \a i must be less than size(). If there is no + item at position \a i, 0 is returned. + + In contrast to remove(), this function does \e not call deleteItem() + for the removed item. + + \sa remove(), at() +*/ + +/*! + \fn void QVector::clear() + + Removes all items from the vector, and destroys the vector + itself. + + The vector becomes a null vector. + + \sa isNull() +*/ + +/*! + \fn bool QVector::fill( const type *d, int size ) + + Inserts item \a d in all positions in the vector. Any existing items + are removed. If \a d is 0, the vector becomes empty. + + If \a size >= 0, the vector is first resized to \a size. By default, + \a size is -1. + + Returns TRUE if successful, or FALSE if the memory cannot be allocated + (only if a resize has been requested). + + \sa resize(), insert(), isEmpty() +*/ + +/*! + \fn void QVector::sort() + + Sorts the items in ascending order. Any empty positions will be put + last. + + Compares items using the virtual function compareItems(). + + \sa bsearch() +*/ + +/*! + \fn int QVector::bsearch( const type* d ) const + + In a sorted array, finds the first occurrence of \a d using binary + search. For a sorted array, this is generally much faster than + find(), which does a linear search. + + Returns the position of \a d, or -1 if \a d could not be found. \a d + may not be 0. + + Compares items using the virtual function compareItems(). + + \sa sort(), find() +*/ + + +/*! + \fn int QVector::findRef( const type *d, uint i ) const + + Finds the first occurrence of the item pointer \a d in the vector, + using linear search. The search starts at position \a i, which must + be less than size(). \a i is by default 0; i.e. the search starts at + the start of the vector. + + Returns the position of \a d, or -1 if \a d could not be found. + + This function does \e not use compareItems() to compare items. + + \sa find(), bsearch() +*/ + +/*! + \fn int QVector::find( const type *d, uint i ) const + + Finds the first occurrence of item \a d in the vector, using linear + search. The search starts at position \a i, which must be less than + size(). \a i is by default 0; i.e. the search starts at the start of + the vector. + + Returns the position of \e v, or -1 if \e v could not be found. + + Compares items using the virtual function compareItems(). + + \sa findRef(), bsearch() +*/ + + +/*! + \fn uint QVector::containsRef( const type *d ) const + + Returns the number of occurrences of the item pointer \a d in the + vector. + + This function does \e not use compareItems() to compare items. + + \sa findRef() +*/ + +/*! + \fn uint QVector::contains( const type *d ) const + + Returns the number of occurrences of item \a d in the vector. + + Compares items using the virtual function compareItems(). + + \sa containsRef() +*/ + +/*! + \fn type *QVector::operator[]( int i ) const + + Returns the item at position \a i, or 0 if there is no item at + that position. \a i must be less than size(). + + Equivalent to at( \a i ). + + \sa at() +*/ + +/*! + \fn type *QVector::at( uint i ) const + + Returns the item at position \a i, or 0 if there is no item at + that position. \a i must be less than size(). +*/ + + +/*! + \fn void QVector::toList( QGList *list ) const + + Copies all items in this vector to the list \a list. First, \a list + is cleared, then all items are appended to \a list. + + \sa QList, QStack, QQueue +*/ + diff --git a/src/classdef.cpp b/src/classdef.cpp index 8111928..24ca56f 100644 --- a/src/classdef.cpp +++ b/src/classdef.cpp @@ -1232,7 +1232,8 @@ void ClassDef::writeMemberList(OutputList &ol) ol.writeObjectLink(getReference(),getOutputFileBase(),0,name()); parseText(ol,theTranslator->trIncludingInheritedMembers()); - ol.startItemList(); + //ol.startItemList(); + ol.writeString("<table>\n"); //MemberNameInfo *mni=m_allMemberNameInfoList->first(); MemberNameInfoSDict::Iterator mnii(*m_allMemberNameInfoSDict); @@ -1244,17 +1245,6 @@ void ClassDef::writeMemberList(OutputList &ol) { MemberDef *md=mi->memberDef; ClassDef *cd=md->getClassDef(); - - // compute the protection level for this member - //Protection prot=md->protection(); - //if (mi->prot==Protected) // inherited protection: Protected - //{ - // if (prot==Public) prot=Protected; - //} - //else if (mi->prot==Private) // inherited protection: Private - //{ - // prot=Private; - //} Protection prot = mi->prot; //printf("%s: Member %s of class %s md->protection()=%d mi->prot=%d prot=%d inherited=%d\n", @@ -1268,23 +1258,15 @@ void ClassDef::writeMemberList(OutputList &ol) rmd = rmd->reimplements(); } - if (cd && !md->name().isEmpty() && md->name()[0]!='@' - // && - //( - // md->isFriend() - // || - //(/*mi->prot!=Private &&*/ - // (prot!=Private || Config_getBool("EXTRACT_PRIVATE")) - //) - //) - ) + if (cd && !md->name().isEmpty() && md->name()[0]!='@') { bool memberWritten=FALSE; if (cd->isLinkable() && md->isLinkable()) // create a link to the documentation { QCString name=mi->ambiguityResolutionScope+md->name(); - ol.writeListItem(); + //ol.writeListItem(); + ol.writeString(" <tr bgcolor=\"#f0f0f0\"><td>"); ol.writeObjectLink(cd->getReference(),cd->getOutputFileBase(), md->anchor(),name); if ( md->isFunction() || md->isSignal() || md->isSlot() || @@ -1298,13 +1280,15 @@ void ClassDef::writeMemberList(OutputList &ol) ol.docify(" typedef"); else if (md->isFriend() && !strcmp(md->typeString(),"friend class")) ol.docify(" class"); - ol.writeString("\n"); + //ol.writeString("\n"); + ol.writeString("</td>"); memberWritten=TRUE; } else if (!Config_getBool("HIDE_UNDOC_MEMBERS")) // no documentation, // generate link to the class instead. { - ol.writeListItem(); + //ol.writeListItem(); + ol.writeString(" <tr bgcolor=\"#f0f0f0\"><td>"); ol.startBold(); ol.docify(md->name()); ol.endBold(); @@ -1329,8 +1313,17 @@ void ClassDef::writeMemberList(OutputList &ol) ol.endBold(); } ol.writeString(")"); + ol.writeString("</td>"); memberWritten=TRUE; } + if (memberWritten) + { + ol.writeString("<td>"); + ol.writeObjectLink(cd->getReference(),cd->getOutputFileBase(), + 0,cd->name()); + ol.writeString("</td>"); + ol.writeString("<td>"); + } if ((prot!=Public || virt!=Normal || md->isFriend() || md->isRelated() || md->isExplicit() || md->isMutable() || (md->isInline() && Config_getBool("INLINE_INFO")) || @@ -1368,11 +1361,19 @@ void ClassDef::writeMemberList(OutputList &ol) ol.docify("]"); ol.endTypewriter(); } + if (memberWritten) + { + ol.writeString("</td>"); + ol.writeString("</tr>\n"); + } } mi=mni->next(); } } - ol.endItemList(); + //ol.endItemList(); + + ol.writeString("</table>"); + endFile(ol); ol.popGeneratorState(); } @@ -77,7 +77,6 @@ class CodeVarDef QCString classScope; }; -typedef QList<CodeClassDef> CodeClassList; typedef QDict<CodeClassDef> CodeClassDict; typedef QList<CodeVarDef> CodeVarList; @@ -86,7 +85,6 @@ typedef QList<CodeVarDef> CodeVarList; */ static OutputDocInterface * g_code; -//static CodeClassList g_codeClassList; static CodeClassDict g_codeClassDict(1009); static CodeVarList g_codeVarList; static CodeVarList g_codeParmList; @@ -864,7 +864,7 @@ FILE ({FILESCHAR}*{FILEECHAR}+("."{FILESCHAR}*{FILEECHAR}+)*)|("\""[^\n\"]+ ID [a-z_A-Z][a-z_A-Z0-9]* SCOPENAME (({ID}?{BN}*"::"{BN}*)*)((~{BN}*)?{ID}) SCOPEMASK {ID}?(("::"|"#")?(~)?{ID})+ -URLMASK [a-z_A-Z0-9\~\:\?\@\&\%\#\.\-\+\/\=]+ +URLMASK ([^\>\"\n]+)|([a-z_A-Z0-9\~\:\?\@\&\%\#\.\-\+\/\=]+) NONTERM [\{\}\[\]\`\~\@\|\-\+\#\$\/\\\!\%\^\&\*()a-z_A-Z<>0-9\x80-\xff] WORD ({NONTERM}+([^\n\t ]*{NONTERM}+)?)|("\""[^\n\"]"\"") ATTR ({B}+[^>\n]*)? diff --git a/src/doxygen.cpp b/src/doxygen.cpp index 1605da3..9d3788f 100644 --- a/src/doxygen.cpp +++ b/src/doxygen.cpp @@ -2421,6 +2421,10 @@ static void findUsedClassesForClass(Entry *root, ClassDef *usedCd = Doxygen::hiddenClasses.find(type); if (usedCd==0 && !Config_getBool("HIDE_UNDOC_RELATIONS")) { + if (type.right(2)=="(*") // type is a function pointer + { + type+=md->argsString(); + } Debug::print(Debug::Classes,0," New undocumented used class `%s'\n", type.data()); usedCd = new ClassDef( masterCd->getDefFileName(),masterCd->getDefLine(), @@ -5012,19 +5016,23 @@ static void generateClassDocs() for ( ; cli.current() ; ++cli ) { ClassDef *cd=cli.current(); - if ( cd->isLinkableInProject() && cd->templateMaster()==0 && - (cd->getOuterScope()==0 || // <-- should not happen - cd->getOuterScope()==Doxygen::globalScope - ) - ) // skip external references, anonymous compounds and - // template instances and nested classes + + if (cd->getOuterScope()==0 || // <-- should not happen, but can if we read an old tag file + cd->getOuterScope()==Doxygen::globalScope // only look at global classes + ) { - msg("Generating docs for compound %s...\n",cd->name().data()); - - cd->writeDocumentation(*outputList); - cd->writeMemberList(*outputList); + // skip external references, anonymous compounds and + // template instances + if ( cd->isLinkableInProject() && cd->templateMaster()==0) + { + msg("Generating docs for compound %s...\n",cd->name().data()); + + cd->writeDocumentation(*outputList); + cd->writeMemberList(*outputList); + } + // even for undocumented classes, the inner classes can be documented. + cd->writeDocumentationForInnerClasses(*outputList); } - cd->writeDocumentationForInnerClasses(*outputList); } } @@ -5607,6 +5615,7 @@ static void generateNamespaceDocs() NamespaceSDict::Iterator nli(Doxygen::namespaceSDict); NamespaceDef *nd; + // for each namespace... for (;(nd=nli.current());++nli) { if (nd->isLinkableInProject()) @@ -5614,12 +5623,12 @@ static void generateNamespaceDocs() msg("Generating docs for namespace %s\n",nd->name().data()); nd->writeDocumentation(*outputList); } - ClassSDict::Iterator cli(Doxygen::classSDict); + // for each class in the namespace... + ClassSDict::Iterator cli(*nd->classSDict); for ( ; cli.current() ; ++cli ) { ClassDef *cd=cli.current(); - if ( cd->getOuterScope()==nd && - cd->isLinkableInProject() && + if ( cd->isLinkableInProject() && cd->templateMaster()==0 ) // skip external references, anonymous compounds and // template instances and nested classes @@ -6965,7 +6974,7 @@ void parseInput() msg("Building page list...\n"); buildPageList(root); - msg("Buidling package list...\n"); + msg("Building package list...\n"); buildPackageList(root); msg("Search for main page...\n"); diff --git a/src/doxytag.l b/src/doxytag.l index b8f1279..1afe949 100644 --- a/src/doxytag.l +++ b/src/doxytag.l @@ -391,6 +391,7 @@ QCString unhtmlify(const char *str) <ReadArgs>"&" { memberArgs+="&"; } <ReadArgs>"<" { memberArgs+="<"; } <ReadArgs>">" { memberArgs+=">"; } +<ReadArgs>" " { memberArgs+=" "; } /* <ReadArgs>[{}] { // handle enums memberArgs.resize(0); diff --git a/src/latexgen.cpp b/src/latexgen.cpp index 1e42ee8..7b2b2bb 100644 --- a/src/latexgen.cpp +++ b/src/latexgen.cpp @@ -1265,6 +1265,7 @@ void LatexGenerator::docify(const char *str) static bool isKorean = theTranslator->idLanguage()=="korean"; static bool isRussian = theTranslator->idLanguage()=="russian"; static bool isUkrainian = theTranslator->idLanguage()=="ukrainian"; + static bool isChinese = theTranslator->idLanguage()=="chinese"; if (str) { const unsigned char *p=(const unsigned char *)str; @@ -1329,9 +1330,9 @@ void LatexGenerator::docify(const char *str) break; default: - - if (isJapanese || isKorean) - { // Japanese language uses wide characters + // Some languages uses wide characters + if (isJapanese || isKorean || isChinese) + { if (c>=128) { t << (char)c; diff --git a/src/scanner.l b/src/scanner.l index 43ed58f..5873d2e 100644 --- a/src/scanner.l +++ b/src/scanner.l @@ -3051,7 +3051,7 @@ CHARLIT (("'"\\[0-7]{1,3}"'")|("'"\\."'")|("'"[^'\\\n]{1,4}"'")) ); yyLineNr++; } -<PackageDocArg1>{SCOPENAME} { +<PackageDocArg1>{ID}("."{ID})* { current->name = yytext; newDocState(); } diff --git a/src/translator_cn.h b/src/translator_cn.h index b85aad2..30375d7 100644 --- a/src/translator_cn.h +++ b/src/translator_cn.h @@ -26,245 +26,489 @@ */ #define CN_SPC -class TranslatorChinese : public TranslatorAdapter_1_2_1 +class TranslatorChinese : public Translator { public: - QCString idLanguage() + /*! Used for identification of the language. The identification + * should not be translated. It should be replaced by the name + * of the language in English using lower-case characters only + * (e.g. "czech", "japanese", "russian", etc.). It sould be equal to + * the identification used in the language.cpp. + */ + virtual QCString idLanguage() { return "chinese"; } - QCString idLanguageCharset() + + /*! Used to get the LaTeX command(s) for the language support. + * This method should return string with commands that switch + * LaTeX to the desired language. For example + * <pre>"\\usepackage[german]{babel}\n" + * </pre> + * or + * <pre>"\\usepackage{polski}\n" + * "\\usepackage[latin2]{inputenc}\n" + * "\\usepackage[T1]{fontenc}\n" + * </pre> + * + * The English LaTeX does not use such commands. Because of this + * the empty string is returned in this implementation. + */ + virtual QCString latexLanguageSupportCommand() + { + QCString result(latexBabelPackage()); + if (!result.isEmpty()) + { + result = "\\usepackage{" + result; + result += "}\n"; + } + return result; + } + + virtual QCString latexBabelPackage() + { return "CJK"; } + + /*! return the language charset. This will be used for the HTML output */ + virtual QCString idLanguageCharset() { return "gb2312"; } - QCString latexBabelPackage() - { return "chinese"; } - QCString trRelatedFunctions() + + /*! used in the compound documentation before a list of related functions. + */ + virtual QCString trRelatedFunctions() { return "Ïà¹Øº¯Êý"; } - QCString trRelatedSubscript() - { return "£¨×¢Ò⣺ÕâЩ²»ÊdzÉÔ±º¯Êý£©"; } - QCString trDetailedDescription() - { return "ÏêϤÃèÊö"; } - QCString trMemberTypedefDocumentation() + + /*! subscript for the related functions. */ + virtual QCString trRelatedSubscript() + { return "£¨×¢Ò⣺ÕâЩ²»ÊdzÉÔ±º¯Êý¡££©"; } + + /*! header that is put before the detailed description of files, + * classes and namespaces. + */ + virtual QCString trDetailedDescription() + { return "ÏêϸÃèÊö"; } + + /*! header that is put before the list of typedefs. */ + virtual QCString trMemberTypedefDocumentation() { return "³ÉÔ±ÀàÐͶ¨ÒåÎĵµ"; } - QCString trMemberEnumerationDocumentation() + + /*! header that is put before the list of enumerations. */ + virtual QCString trMemberEnumerationDocumentation() { return "³ÉԱö¾ÙÀàÐÍÎĵµ"; } - QCString trEnumerationValueDocumentation() + + virtual QCString trEnumerationValueDocumentation() { return "³ÉԱö¾ÙÖµÎĵµ"; } - QCString trMemberFunctionDocumentation() + + /*! header that is put before the list of member function. */ + virtual QCString trMemberFunctionDocumentation() { return "³ÉÔ±º¯ÊýÎĵµ"; } - QCString trMemberDataDocumentation() - { return "³ÉÔ±Êý¾ÝÎĵµ"; } - QCString trMore() + + /*! header that is put before the list of member attributes. */ + virtual QCString trMemberDataDocumentation() + { + if (Config_getBool("OPTIMIZE_OUTPUT_FOR_C")) + { + return "×Ö¶ÎÎĵµ"; + } + else { + return "³ÉÔ±Êý¾ÝÎĵµ"; + } + } + + /*! this is the text of a link put after brief descriptions. */ + virtual QCString trMore() { return "¸ü¶à..."; } - QCString trListOfAllMembers() + + /*! put in the class documention */ + virtual QCString trListOfAllMembers() { return "ËùÓгÉÔ±µÄÁÐ±í¡£"; } - QCString trMemberList() + + /*! used as the title of the "list of all members" page of a class */ + virtual QCString trMemberList() { return "³ÉÔ±Áбí"; } - QCString trThisIsTheListOfAllMembers() + + /*! this is the first part of a sentence that is followed by a class name */ + virtual QCString trThisIsTheListOfAllMembers() { return "³ÉÔ±µÄÍêÕûÁÐ±í£¬ÕâЩ³ÉÔ±ÊôÓÚ"CN_SPC; } - QCString trIncludingInheritedMembers() + + /*! this is the remainder of the sentence after the class name */ + virtual QCString trIncludingInheritedMembers() { return "£¬°üÀ¨ËùÓм̳жøÀ´µÄ³ÉÔ±"; } - QCString trGeneratedAutomatically(const char *s) - { QCString result; + + /*! this is put at the author sections at the bottom of man pages. + * parameter s is name of the project name. + */ + virtual QCString trGeneratedAutomatically(const char *s) + { + QCString result; if (s) result=(QCString)"Ϊ"CN_SPC+s+"£¬"; result+="ÓÉ"CN_SPC"Doyxgen"CN_SPC"ͨ¹ý·ÖÎöÔ´´úÂë×Ô¶¯Éú³É¡£"; return result; } - QCString trEnumName() + + /*! put after an enum name in the list of all members */ + virtual QCString trEnumName() { return "ö¾ÙÃû³Æ"; } - QCString trEnumValue() + + /*! put after an enum value in the list of all members */ + virtual QCString trEnumValue() { return "ö¾ÙÖµ"; } - QCString trDefinedIn() + + /*! put after an undocumented member in the list of all members */ + virtual QCString trDefinedIn() { return "¶¨ÒåÓÚ"CN_SPC; } - QCString trVerbatimText(const char *f) + + // quick reference sections + + + virtual QCString trVerbatimText(const char *f) { return (QCString)"ÕâÊÇÍ·Îļþ"CN_SPC+f+CN_SPC"µÄÔ´´úÂë¡£"; } - QCString trModules() + + /*! This is put above each page as a link to the list of all groups of + * compounds or files (see the \\group command). + */ + virtual QCString trModules() { return "Ä£¿é"; } - QCString trClassHierarchy() + + /*! This is put above each page as a link to the class hierarchy */ + virtual QCString trClassHierarchy() { return "Àà¼Ì³Ð¹Øϵ"; } - QCString trCompoundList() - { return "×éºÏÀàÐÍÁбí"; } - QCString trFileList() + + /*! This is put above each page as a link to the list of annotated class */ + virtual QCString trCompoundList() + { + if (Config_getBool("OPTIMIZE_OUTPUT_FOR_C")) { + return "Êý¾Ý½á¹¹"; + } + else { + return "×éºÏÀàÐÍÁбí"; + } + } + + /*! This is put above each page as a link to the list of documented files */ + virtual QCString trFileList() { return "ÎļþÁбí"; } - QCString trHeaderFiles() + + + /*! This is put above each page as a link to the list of all verbatim headers */ + virtual QCString trHeaderFiles() { return "Í·Îļþ"; } - QCString trCompoundMembers() - { return "×éºÏÀàÐͳÉÔ±"; } - QCString trFileMembers() - { return "Îļþ³ÉÔ±"; } - QCString trRelatedPages() + + /*! This is put above each page as a link to all members of compounds. */ + virtual QCString trCompoundMembers() + { + if (Config_getBool("OPTIMIZE_OUTPUT_FOR_C")) { + return "Êý¾Ý×Ö¶Î"; + } + else { + return "×éºÏÀàÐͳÉÔ±"; + } + } + + /*! This is put above each page as a link to all member of files. */ + virtual QCString trFileMembers() + { + if (Config_getBool("OPTIMIZE_OUTPUT_FOR_C")) { + return "È«¾Ö¶¨Òå"; + } else { + return "Îļþ³ÉÔ±"; + } + } + + /*! This is put above each page as a link to all related pages. */ + virtual QCString trRelatedPages() { return "Ïà¹ØÒ³Ãæ"; } - QCString trExamples() + + /*! This is put above each page as a link to all examples. */ + virtual QCString trExamples() { return "ʾÀý"; } - QCString trSearch() + + virtual QCString trSearch() { return "ËÑË÷"; } - QCString trClassHierarchyDescription() + + virtual QCString trClassHierarchyDescription() { return "´ËÁбí»ù±¾°´×Öµä˳ÐòÅÅÐò£º"; } - QCString trFileListDescription(bool extractAll) + + virtual QCString trFileListDescription(bool extractAll) { - QCString result="ÕâÀïÁгöËùÓÐ"; + QCString result="ÕâÀïÁгöËùÓÐ"; if (!extractAll) result+="Îĵµ»¯µÄ"; result+="Îļþ£¬¸½´ø¼òҪ˵Ã÷£º"; return result; } - QCString trCompoundListDescription() - { return "ÕâÀïÁгöËùÓÐÀà¡¢½á¹¹¡¢ÁªºÏÒÔ¼°½Ó¿Ú¶¨Ò壬¸½´ø¼òҪ˵Ã÷£º"; + + virtual QCString trCompoundListDescription() + { + + if (Config_getBool("OPTIMIZE_OUTPUT_FOR_C")) + { + return "ÕâÀïÁгöËùÓÐÊý¾Ý½á¹¹£¬¸½´ø¼òҪ˵Ã÷£º"; + } + else + { + return "ÕâÀïÁгöËùÓÐÀà¡¢½á¹¹¡¢ÁªºÏÒÔ¼°½Ó¿Ú¶¨Ò壬¸½´ø¼òҪ˵Ã÷£º"; + } } - QCString trCompoundMembersDescription(bool extractAll) + + virtual QCString trCompoundMembersDescription(bool extractAll) { - QCString result="ÕâÀïÁгöËùÓÐ"; - if (!extractAll) result+="Îĵµ»¯µÄ"; - result+="Àà³ÉÔ±£¬¸½´ø"; - if (extractAll) result+="ËùÔÚÀàµÄÎĵµµÄÁ´½Ó£º"; - else result+="ËùÔÚÀàµÄÁ´½Ó£º"; + QCString result="ÕâÀïÁгöËùÓÐ"; + if (!extractAll) { + result+="Îĵµ»¯µÄ"; + } + if (Config_getBool("OPTIMIZE_OUTPUT_FOR_C")) { + result+="½á¹¹ºÍÁªºÏµÄ³ÉÔ±£¬¸½´ø"; + } + else { + result+="Àà³ÉÔ±£¬¸½´ø"; + } + + if (extractAll) { + if (Config_getBool("OPTIMIZE_OUTPUT_FOR_C")) { + result+="ËùÔڽṹ£¯ÁªºÏµÄÎĵµµÄÁ´½Ó£º"; + } + else { + result+="ËùÔÚÀàµÄÎĵµµÄÁ´½Ó£º"; + } + } + else { + if (Config_getBool("OPTIMIZE_OUTPUT_FOR_C")) { + result+="ËùÊô½á¹¹£¯ÁªºÏµÄÁ´½Ó£º"; + } + else { + result+="ËùÊôÀàµÄÁ´½Ó£º"; + } + } return result; } - QCString trFileMembersDescription(bool extractAll) + + virtual QCString trFileMembersDescription(bool extractAll) { - QCString result="ÕâÀïÁгöËùÓÐ"; - if (!extractAll) result+="Îĵµ»¯µÄ"; - result+="Îļþ³ÉÔ±£¬¸½´ø"; - if (extractAll) result+="ËùÔÚÎļþµÄÎĵµµÄÁ´½Ó£º"; - else result+="ËùÔÚÎļþµÄÁ´½Ó£º"; + QCString result="ÕâÀïÁгöËùÓÐ"; + if (!extractAll) + result +="Îĵµ»¯µÄ"; + + if (Config_getBool("OPTIMIZE_OUTPUT_FOR_C")) { + result +="º¯Êý£¬±äÁ¿£¬ºê£¬Ã¶¾ÙºÍÀàÐͶ¨Ò壬¸½´ø"; + } + else { + result +="Îļþ³ÉÔ±£¬¸½´ø"; + } + + if (extractAll) + result+="ËùÔÚÎļþµÄÎĵµµÄÁ´½Ó£º"; + else + result+="ËùÔÚÎļþµÄÁ´½Ó£º"; return result; } - QCString trHeaderFilesDescription() + + virtual QCString trHeaderFilesDescription() { return "ÕâÀïÁгö×é³ÉAPIµÄÍ·Îļþ£º"; } - QCString trExamplesDescription() + + virtual QCString trExamplesDescription() { return "ÕâÀïÁгöËùÓÐʾÀý£º"; } - QCString trRelatedPagesDescription() + + virtual QCString trRelatedPagesDescription() { return "ÕâÀïÁгöËùÓÐÏà¹ØµÄÒ³Ã棺"; } - QCString trModulesDescription() + + virtual QCString trModulesDescription() { return "ÕâÀïÁгöËùÓÐÄ£¿é"; } - QCString trNoDescriptionAvailable() + + virtual QCString trNoDescriptionAvailable() { return "ÎÞ¿ÉÓÃÎĵµ"; } - QCString trDocumentation() + virtual QCString trDocumentation() { return "Îĵµ"; } - QCString trModuleIndex() + + virtual QCString trModuleIndex() { return "Ä£¿éË÷Òý"; } - QCString trHierarchicalIndex() + + virtual QCString trHierarchicalIndex() { return "¼Ì³Ð¹ØϵË÷Òý"; } - QCString trCompoundIndex() - { return "×éºÏÀàÐÍË÷Òý"; } - QCString trFileIndex() + + virtual QCString trCompoundIndex() + { + if (Config_getBool("OPTIMIZE_OUTPUT_FOR_C")) + { + return "Êý¾Ý½á¹¹Ë÷Òý"; + } + else { + return "×éºÏÀàÐÍË÷Òý"; + } + } + + virtual QCString trFileIndex() { return "ÎļþË÷Òý"; } - QCString trModuleDocumentation() + + virtual QCString trModuleDocumentation() { return "Ä£¿éÎĵµ"; } - QCString trClassDocumentation() - { return "ÀàÎĵµ"; } - QCString trFileDocumentation() + + virtual QCString trClassDocumentation() + { + if (Config_getBool("OPTIMIZE_OUTPUT_FOR_C")) + { + return "Êý¾Ý½á¹¹Îĵµ"; + } + else { + return "ÀàÎĵµ"; + } + } + + virtual QCString trFileDocumentation() { return "ÎļþÎĵµ"; } - QCString trExampleDocumentation() + + virtual QCString trExampleDocumentation() { return "ʾÀýÎĵµ"; } - QCString trPageDocumentation() + + virtual QCString trPageDocumentation() { return "Ò³ÃæÎĵµ"; } - QCString trReferenceManual() + + virtual QCString trReferenceManual() { return "²Î¿¼ÊÖ²á"; } - QCString trDefines() + virtual QCString trDefines() { return "ºê¶¨Òå"; } - QCString trFuncProtos() + + virtual QCString trFuncProtos() { return "º¯ÊýÔÐÍ"; } - QCString trTypedefs() + + virtual QCString trTypedefs() { return "ÀàÐͶ¨Òå"; } - QCString trEnumerations() + + virtual QCString trEnumerations() { return "ö¾Ù"; } - QCString trFunctions() + + virtual QCString trFunctions() { return "º¯Êý"; } - QCString trVariables() + + virtual QCString trVariables() { return "±äÁ¿"; } - QCString trEnumerationValues() + + virtual QCString trEnumerationValues() { return "ö¾ÙÖµ"; } - QCString trAuthor() + + virtual QCString trAuthor() { return "×÷Õß"; } - QCString trDefineDocumentation() + + virtual QCString trDefineDocumentation() { return "ºê¶¨ÒåÎĵµ"; } - QCString trFunctionPrototypeDocumentation() + + virtual QCString trFunctionPrototypeDocumentation() { return "º¯ÊýÔÐÍÎĵµ"; } - QCString trTypedefDocumentation() + + virtual QCString trTypedefDocumentation() { return "ÀàÐͶ¨ÒåÎĵµ"; } - QCString trEnumerationTypeDocumentation() + + virtual QCString trEnumerationTypeDocumentation() { return "ö¾ÙÀàÐÍÎĵµ"; } - QCString trFunctionDocumentation() + + virtual QCString trFunctionDocumentation() { return "º¯ÊýÎĵµ"; } - QCString trVariableDocumentation() + + virtual QCString trVariableDocumentation() { return "±äÁ¿Îĵµ"; } - QCString trCompounds() - { return "×éºÏÀàÐÍ"; } - QCString trFiles() + + virtual QCString trCompounds() + { + if (Config_getBool("OPTIMIZE_OUTPUT_FOR_C")) + { + return "Êý¾Ý½á¹¹"; + } + else { + return "×éºÏÀàÐÍ"; + } + } + + virtual QCString trFiles() { return "Îļþ"; } - QCString trGeneratedAt(const char *date,const char *projName) + + virtual QCString trGeneratedAt(const char *date,const char *projName) { - QCString result=(QCString)"Generated at "+date; + QCString result=(QCString)"Generated at "+date; if (projName) result+=(QCString)" for "+projName; result+=(QCString)" by"; return result; } - QCString trWrittenBy() + + virtual QCString trWrittenBy() { return "written by"; } - QCString trClassDiagram(const char *clName) + + virtual QCString trClassDiagram(const char *clName) { return (QCString)"¼Ì³Ðͼ£¬Àà"CN_SPC+clName; } - QCString trForInternalUseOnly() + + virtual QCString trForInternalUseOnly() { return "½öÏÞÄÚ²¿Ê¹Óá£"; } - QCString trReimplementedForInternalReasons() + + virtual QCString trReimplementedForInternalReasons() { return "ÓÉÓÚÄÚ²¿ÔÒò±»ÖØÔØ£»µ«²»Ó°ÏìAPI"; } - QCString trWarning() + + virtual QCString trWarning() { return "¾¯¸æ"; } - QCString trBugsAndLimitations() + + virtual QCString trBugsAndLimitations() { return "BUG"CN_SPC"Óë¾ÖÏÞ"; } - QCString trVersion() + + virtual QCString trVersion() { return "°æ±¾"; } - QCString trDate() + + virtual QCString trDate() { return "ÈÕÆÚ"; } - QCString trAuthors() + + virtual QCString trAuthors() { return "×÷Õß"; } - QCString trReturns() + + virtual QCString trReturns() { return "·µ»Ø"; } - QCString trSeeAlso() + + virtual QCString trSeeAlso() { return "²Î¼û"; } - QCString trParameters() + + virtual QCString trParameters() { return "²ÎÊý"; } - QCString trExceptions() + + virtual QCString trExceptions() { return "Òì³£"; } - QCString trGeneratedBy() + + virtual QCString trGeneratedBy() { return "ÖÆ×÷Õß"; } ////////////////////////////////////////////////////////////////////////// // new since 0.49-990307 ////////////////////////////////////////////////////////////////////////// - QCString trNamespaceList() - { return "ÃüÃû¿Õ¼äÁбí"; } - QCString trNamespaceListDescription(bool extractAll) + virtual QCString trNamespaceList() + { return "Ãû×Ö¿Õ¼äÁбí"; } + + virtual QCString trNamespaceListDescription(bool extractAll) { - QCString result="ÕâÀïÁгöËùÓÐ"; + QCString result="ÕâÀïÁгöËùÓÐ"; if (!extractAll) result+="Îĵµ»¯µÄ"; - result+="ÃüÃû¿Õ¼ä¶¨Ò壬¸½´ø¼òҪ˵Ã÷£º"; + result+="Ãû×ֿռ䶨Ò壬¸½´ø¼òҪ˵Ã÷£º"; return result; } - QCString trFriends() + + virtual QCString trFriends() { return "ÓÑÔª"; } ////////////////////////////////////////////////////////////////////////// // new since 0.49-990405 ////////////////////////////////////////////////////////////////////////// - QCString trRelatedFunctionDocumentation() + virtual QCString trRelatedFunctionDocumentation() { return "ÓÑÔª¼°Ïà¹Øº¯ÊýÎĵµ"; } ////////////////////////////////////////////////////////////////////////// // new since 0.49-990425 ////////////////////////////////////////////////////////////////////////// - QCString trCompoundReference(const char *clName, + virtual QCString trCompoundReference(const char *clName, ClassDef::CompoundType compType, bool isTemplate) // used as the title of the HTML page of a class/struct/union { - QCString result=(QCString)clName; + QCString result=(QCString)clName; if (isTemplate) result+=CN_SPC"Ä£°å"; switch(compType) { @@ -277,49 +521,61 @@ class TranslatorChinese : public TranslatorAdapter_1_2_1 result+="²Î¿¼"; return result; } - QCString trFileReference(const char *fileName) + + virtual QCString trFileReference(const char *fileName) // used as the title of the HTML page of a file { - QCString result=fileName; + QCString result=fileName; result+=CN_SPC"Îļþ²Î¿¼"; return result; } - QCString trNamespaceReference(const char *namespaceName) + + virtual QCString trNamespaceReference(const char *namespaceName) // used as the title of the HTML page of a namespace { - QCString result=namespaceName; - result+=CN_SPC"ÃüÃû¿Õ¼ä²Î¿¼"; + QCString result=namespaceName; + result+=CN_SPC"Ãû×Ö¿Õ¼ä²Î¿¼"; return result; } // these are for the member sections of a class, struct or union - QCString trPublicMembers() + virtual QCString trPublicMembers() { return "¹«ÓгÉÔ±"; } - QCString trPublicSlots() + + virtual QCString trPublicSlots() { return "¹«ÓвÛ"; } - QCString trSignals() + + virtual QCString trSignals() { return "ÐźÅ"; } - QCString trStaticPublicMembers() + + virtual QCString trStaticPublicMembers() { return "¾²Ì¬¹«ÓгÉÔ±"; } - QCString trProtectedMembers() + + virtual QCString trProtectedMembers() { return "±£»¤³ÉÔ±"; } - QCString trProtectedSlots() + + virtual QCString trProtectedSlots() { return "±£»¤²Û"; } - QCString trStaticProtectedMembers() + + virtual QCString trStaticProtectedMembers() { return "¾²Ì¬±£»¤³ÉÔ±"; } - QCString trPrivateMembers() + + virtual QCString trPrivateMembers() { return "˽ÓгÉÔ±"; } - QCString trPrivateSlots() + + virtual QCString trPrivateSlots() { return "˽ÓвÛ"; } - QCString trStaticPrivateMembers() + + virtual QCString trStaticPrivateMembers() { return "¾²Ì¬Ë½ÓгÉÔ±"; } + // end of member sections - QCString trWriteList(int numEntries) + virtual QCString trWriteList(int numEntries) { // this function is used to produce a comma-separated list of items. // use generateMarker(i) to indicate where item i should be put. - QCString result; + QCString result; int i; // the inherits list contain `numEntries' classes for (i=0;i<numEntries;i++) @@ -339,54 +595,60 @@ class TranslatorChinese : public TranslatorAdapter_1_2_1 return result; } - QCString trInheritsList(int numEntries) + virtual QCString trInheritsList(int numEntries) // used in class documentation to produce a list of base classes, // if class diagrams are disabled. { return "¼Ì³Ð×Ô"CN_SPC+trWriteList(numEntries)+"¡£"; } - QCString trInheritedByList(int numEntries) + + virtual QCString trInheritedByList(int numEntries) // used in class documentation to produce a list of super classes, // if class diagrams are disabled. { return "±»"CN_SPC+trWriteList(numEntries)+CN_SPC"¼Ì³Ð."; } - QCString trReimplementedFromList(int numEntries) + + virtual QCString trReimplementedFromList(int numEntries) // used in member documentation blocks to produce a list of // members that are hidden by this one. { return "ÖØÔØ"CN_SPC+trWriteList(numEntries)+"¡£"; } - QCString trReimplementedInList(int numEntries) + + virtual QCString trReimplementedInList(int numEntries) { // used in member documentation blocks to produce a list of // all member that overwrite the implementation of this member. return "±»"CN_SPC+trWriteList(numEntries)+CN_SPC"ÖØÔØ¡£"; } - QCString trNamespaceMembers() + virtual QCString trNamespaceMembers() // This is put above each page as a link to all members of namespaces. - { return "ÃüÃû¿Õ¼ä³ÉÔ±"; } - QCString trNamespaceMemberDescription(bool extractAll) + { return "Ãû×Ö¿Õ¼ä³ÉÔ±"; } + + virtual QCString trNamespaceMemberDescription(bool extractAll) // This is an introduction to the page with all namespace members { - QCString result="ÕâÀïÁгöÁËËùÓÐ"; + QCString result="ÕâÀïÁгöÁËËùÓÐ"; if (!extractAll) result+="Îĵµ»¯µÄ"; - result+="ÃüÃû¿Õ¼ä³ÉÔ±£¬¸½´ø"; + result+="Ãû×Ö¿Õ¼ä³ÉÔ±£¬¸½´ø"; if (extractAll) result+="ËùÔÚÀàµÄÎĵµµÄÁ´½Ó£º"; else result+="ËùÔÚÀàµÄÁ´½Ó£º"; return result; } - QCString trNamespaceIndex() + + virtual QCString trNamespaceIndex() // This is used in LaTeX as the title of the chapter with the // index of all namespaces. - { return "ÃüÃû¿Õ¼äË÷Òý"; } - QCString trNamespaceDocumentation() + { return "Ãû×Ö¿Õ¼äË÷Òý"; } + + virtual QCString trNamespaceDocumentation() // This is used in LaTeX as the title of the chapter containing // the documentation of all namespaces. - { return "ÃüÃû¿Õ¼äÎĵµ"; } + { return "Ãû×Ö¿Õ¼äÎĵµ"; } ////////////////////////////////////////////////////////////////////////// // new since 0.49-990522 @@ -395,7 +657,7 @@ class TranslatorChinese : public TranslatorAdapter_1_2_1 /*! This is used in the documentation before the list of all * namespaces in a file. */ - QCString trNamespaces() + virtual QCString trNamespaces() { return "Namespaces"; } @@ -407,11 +669,11 @@ class TranslatorChinese : public TranslatorAdapter_1_2_1 /*! This is put at the bottom of a class documentation page and is * followed by a list of files that were used to generate the page. */ - QCString trGeneratedFromFiles(ClassDef::CompoundType compType, + virtual QCString trGeneratedFromFiles(ClassDef::CompoundType compType, bool) { // here s is one of " Class", " Struct" or " Union" // single is true implies a single file - QCString result=(QCString)"¸Ã"; + QCString result=(QCString)"¸Ã"; switch(compType) { case ClassDef::Class: result+="Àà"; break; @@ -427,7 +689,7 @@ class TranslatorChinese : public TranslatorAdapter_1_2_1 /*! This is in the (quick) index as a link to the alphabetical compound * list. */ - QCString trAlphabeticalList() + virtual QCString trAlphabeticalList() { return "°´×Öµä˳ÐòÅÅÐòµÄÁбí"; } ////////////////////////////////////////////////////////////////////////// @@ -435,33 +697,35 @@ class TranslatorChinese : public TranslatorAdapter_1_2_1 ////////////////////////////////////////////////////////////////////////// /*! This is used as the heading text for the retval command. */ - QCString trReturnValues() + virtual QCString trReturnValues() { return "·µ»ØÖµ"; } /*! This is in the (quick) index as a link to the main page (index.html) */ - QCString trMainPage() + virtual QCString trMainPage() { return "Ê×Ò³"; } /*! This is used in references to page that are put in the LaTeX * documentation. It should be an abbreviation of the word page. */ - QCString trPageAbbreviation() + virtual QCString trPageAbbreviation() { return "p."; } ////////////////////////////////////////////////////////////////////////// // new since 0.49-991106 ////////////////////////////////////////////////////////////////////////// - QCString trSources() + virtual QCString trSources() { return "Ô´´úÂë"; } - QCString trDefinedAtLineInSourceFile() + + virtual QCString trDefinedAtLineInSourceFile() { return "ÔÚÎļþ"CN_SPC"@1"CN_SPC"µÚ"CN_SPC"@0"CN_SPC"Ðж¨Òå¡£"; } - QCString trDefinedInSourceFile() + + virtual QCString trDefinedInSourceFile() { return "ÔÚÎļþ"CN_SPC"@0"CN_SPC"Öж¨Òå¡£"; } @@ -470,7 +734,7 @@ class TranslatorChinese : public TranslatorAdapter_1_2_1 // new since 0.49-991205 ////////////////////////////////////////////////////////////////////////// - QCString trDeprecated() + virtual QCString trDeprecated() { return "Deprecated"; } @@ -480,68 +744,81 @@ class TranslatorChinese : public TranslatorAdapter_1_2_1 ////////////////////////////////////////////////////////////////////////// /*! this text is put before a collaboration diagram */ - QCString trCollaborationDiagram(const char *clName) + virtual QCString trCollaborationDiagram(const char *clName) { return (QCString)clName+CN_SPC"ºÏ×÷ͼ£º"; } + /*! this text is put before an include dependency graph */ - QCString trInclDepGraph(const char *fName) + virtual QCString trInclDepGraph(const char *fName) { return (QCString)fName+CN_SPC"°üº¬/ÒÀÀµ¹Øϵͼ£º"; } + /*! header that is put before the list of constructor/destructors. */ - QCString trConstructorDocumentation() + virtual QCString trConstructorDocumentation() { return "¹¹Ôì¼°Îö¹¹º¯ÊýÎĵµ"; } + /*! Used in the file documentation to point to the corresponding sources. */ - QCString trGotoSourceCode() + virtual QCString trGotoSourceCode() { return "ä¯ÀÀ¸ÃÎļþµÄÔ´´úÂë¡£"; } + /*! Used in the file sources to point to the corresponding documentation. */ - QCString trGotoDocumentation() + virtual QCString trGotoDocumentation() { return "ä¯ÀÀ¸ÃÎļþµÄÎĵµ¡£"; } + /*! Text for the \\pre command */ - QCString trPrecondition() + virtual QCString trPrecondition() { return "Ç°ÖÃÌõ¼þ"; } + /*! Text for the \\post command */ - QCString trPostcondition() + virtual QCString trPostcondition() { return "ºóÖÃÌõ¼þ"; } + /*! Text for the \\invariant command */ - QCString trInvariant() + virtual QCString trInvariant() { return "²»±äÐÔ"; } + /*! Text shown before a multi-line variable/enum initialization */ - QCString trInitialValue() + virtual QCString trInitialValue() { return "³õʼ»¯ÐòÁУº"; } + /*! Text used the source code in the file index */ - QCString trCode() + virtual QCString trCode() { return "´úÂë"; } - QCString trGraphicalHierarchy() + + virtual QCString trGraphicalHierarchy() { return "Àà¼Ì³Ð¹Øϵͼ"; } - QCString trGotoGraphicalHierarchy() + + virtual QCString trGotoGraphicalHierarchy() { return "ä¯ÀÀÀà¼Ì³Ð¹Øϵͼ"; } - QCString trGotoTextualHierarchy() + + virtual QCString trGotoTextualHierarchy() { return "ä¯ÀÀÀà¼Ì³Ð¹Øϵ±í"; } - QCString trPageIndex() + + virtual QCString trPageIndex() { return "Ò³ÃæË÷Òý"; } @@ -550,43 +827,58 @@ class TranslatorChinese : public TranslatorAdapter_1_2_1 // new since 1.1.0 ////////////////////////////////////////////////////////////////////////// - QCString trNote() + virtual QCString trNote() { return "×¢½â"; } - QCString trPublicTypes() + + virtual QCString trPublicTypes() { return "¹«ÓÐÀàÐÍ"; } - QCString trPublicAttribs() + + virtual QCString trPublicAttribs() { - return "¹«ÓÐÊôÐÔ"; + if (Config_getBool("OPTIMIZE_OUTPUT_FOR_C")) + { + return "Êý¾Ý³ÉÔ±"; + } + else { + return "¹«ÓÐÊôÐÔ"; + } } - QCString trStaticPublicAttribs() + + virtual QCString trStaticPublicAttribs() { return "¾²Ì¬¹«ÓÐÊôÐÔ"; } - QCString trProtectedTypes() + + virtual QCString trProtectedTypes() { return "±£»¤ÀàÐÍ"; } - QCString trProtectedAttribs() + + virtual QCString trProtectedAttribs() { return "±£»¤ÊôÐÔ"; } - QCString trStaticProtectedAttribs() + + virtual QCString trStaticProtectedAttribs() { return "¾²Ì¬±£»¤ÊôÐÔ"; } - QCString trPrivateTypes() + + virtual QCString trPrivateTypes() { return "˽ÓÐÀàÐÍ"; } - QCString trPrivateAttribs() + + virtual QCString trPrivateAttribs() { return "˽ÓÐÊôÐÔ"; } - QCString trStaticPrivateAttribs() + + virtual QCString trStaticPrivateAttribs() { return "¾²Ì¬Ë½ÓÐÊôÐÔ"; } @@ -597,12 +889,13 @@ class TranslatorChinese : public TranslatorAdapter_1_2_1 ////////////////////////////////////////////////////////////////////////// /*! Used as a marker that is put before a todo item */ - QCString trTodo() + virtual QCString trTodo() { return "TODO"; } + /*! Used as the header of the todo list */ - QCString trTodoList() + virtual QCString trTodoList() { return "TODO"CN_SPC"Áбí"; } @@ -611,23 +904,27 @@ class TranslatorChinese : public TranslatorAdapter_1_2_1 // new since 1.1.4 ////////////////////////////////////////////////////////////////////////// - QCString trReferencedBy() + virtual QCString trReferencedBy() { return "²Î¿¼×Ô"; } - QCString trRemarks() + + virtual QCString trRemarks() { return "ÆÀÂÛ"; } - QCString trAttention() + + virtual QCString trAttention() { return "×¢Òâ"; } - QCString trInclByDepGraph() + + virtual QCString trInclByDepGraph() { return "´Ëͼչʾֱ½Ó»ò¼ä½Ó°üº¬¸ÃÎļþµÄÎļþ£º"; } - QCString trSince() + + virtual QCString trSince() { return "×Ô´Ó"; } @@ -637,12 +934,13 @@ class TranslatorChinese : public TranslatorAdapter_1_2_1 ////////////////////////////////////////////////////////////////////////// /*! title of the graph legend page */ - QCString trLegendTitle() + virtual QCString trLegendTitle() { return "ͼÀý"; } + /*! page explaining how the dot graph's should be interpreted */ - QCString trLegendDocs() + virtual QCString trLegendDocs() { return "±¾Ò³ÏòÄúչʾÈçºÎÀí½âÓÉ"CN_SPC"Doxygen"CN_SPC"Éú³ÉµÄͼÐΡ£<p>\n" @@ -694,7 +992,7 @@ class TranslatorChinese : public TranslatorAdapter_1_2_1 "</ul>\n"; } /*! text for the link to the legend page */ - QCString trLegend() + virtual QCString trLegend() { return "ͼÀý"; } @@ -708,12 +1006,289 @@ class TranslatorChinese : public TranslatorAdapter_1_2_1 { return "²âÊÔ"; } + /*! Used as the header of the test list */ virtual QCString trTestList() { return "²âÊÔÁбí"; } +////////////////////////////////////////////////////////////////////////// +//// new since 1.2.1 +//////////////////////////////////////////////////////////////////////////// + /*! Used as a section header for KDE-2 IDL methods */ + virtual QCString trDCOPMethods() + { + return "DCOP"CN_SPC"·½·¨"; + } + +////////////////////////////////////////////////////////////////////////// +//// new since 1.2.2 +//////////////////////////////////////////////////////////////////////////// + + /*! Used as a section header for IDL properties */ + virtual QCString trProperties() + { + return "ÊôÐÔ"; + } + + /*! Used as a section header for IDL property documentation */ + virtual QCString trPropertyDocumentation() + { + return "ÊôÐÔÎĵµ"; + } + +////////////////////////////////////////////////////////////////////////// +// new since 1.2.4 +////////////////////////////////////////////////////////////////////////// + + /*! Used for Java interfaces in the summary section of Java packages */ + virtual QCString trInterfaces() + { + return "½Ó¿Ú"; + } + + /*! Used for Java classes in the summary section of Java packages */ + virtual QCString trClasses() + { + if (Config_getBool("OPTIMIZE_OUTPUT_FOR_C")) + { + return "Êý¾Ý½á¹¹"; + } + else + { + return "Àà"; + } + } + + /*! Used as the title of a Java package */ + virtual QCString trPackage(const char *name) + { + return (QCString)"°ü "+name; + } + + /*! Title of the package index page */ + virtual QCString trPackageList() + { + return "°üÁбí"; + } + + /*! The description of the package index page */ + virtual QCString trPackageListDescription() + { + return "ÕâÀïÁгöËùÓеİü£¬¸½´ø¼òҪ˵Ã÷(Èç¹ûÓеĻ°)£º"; + } + + /*! The link name in the Quick links header for each page */ + virtual QCString trPackages() + { + return "°ü"; + } + + /*! Used as a chapter title for Latex & RTF output */ + virtual QCString trPackageDocumentation() + { + return "°üµÄÎĵµ"; + } + + /*! Text shown before a multi-line define */ + virtual QCString trDefineValue() + { + return "Öµ:"; + } + +//////////////////////////////////////////////////////////////////////////// +//// new since 1.2.6 +//////////////////////////////////////////////////////////////////////////// + virtual QCString trBug () + { + return "ȱÏÝ"; + } + + virtual QCString trBugList () + { + return "ȱÏÝÁбí"; + } + +////////////////////////////////////////////////////////////////////////// +// new since 1.2.6 +////////////////////////////////////////////////////////////////////////// + + /*! Used as ansicpg for RTF file + * + * The following table shows the correlation of Charset name, Charset Value and + * <pre> + * Codepage number: + * Charset Name Charset Value(hex) Codepage number + * ------------------------------------------------------ + * DEFAULT_CHARSET 1 (x01) + * SYMBOL_CHARSET 2 (x02) + * OEM_CHARSET 255 (xFF) + * ANSI_CHARSET 0 (x00) 1252 + * RUSSIAN_CHARSET 204 (xCC) 1251 + * EE_CHARSET 238 (xEE) 1250 + * GREEK_CHARSET 161 (xA1) 1253 + * TURKISH_CHARSET 162 (xA2) 1254 + * BALTIC_CHARSET 186 (xBA) 1257 + * HEBREW_CHARSET 177 (xB1) 1255 + * ARABIC _CHARSET 178 (xB2) 1256 + * SHIFTJIS_CHARSET 128 (x80) 932 + * HANGEUL_CHARSET 129 (x81) 949 + * GB2313_CHARSET 134 (x86) 936 + * CHINESEBIG5_CHARSET 136 (x88) 950 + * </pre> + * + */ + virtual QCString trRTFansicp() + { + return "936"; + } + + /*! Used as ansicpg for RTF fcharset + * \see trRTFansicp() for a table of possible values. + */ + virtual QCString trRTFCharSet() + { + return "134"; + } + + + /*! Used as header RTF general index */ + virtual QCString trRTFGeneralIndex() + { + return "Ë÷Òý"; + } + + + /*! This is used for translation of the word that will possibly + * be followed by a single name or by a list of names + * of the category. + */ + virtual QCString trClass(bool /*first_capital*/, bool /*singular*/) + { + /* + QCString result((first_capital ? "Class" : "class")); + if (!singular) result+="es"; + return result; + */ + return "Àà"; + } + + /*! This is used for translation of the word that will possibly + * be followed by a single name or by a list of names + * of the category. + */ + virtual QCString trFile(bool /*first_capital*/, bool /*singular*/) + { + /* + QCString result((first_capital ? "File" : "file")); + if (!singular) result+="s"; + return result; + */ + return "Îļþ"; + + } + + /*! This is used for translation of the word that will possibly + * be followed by a single name or by a list of names + * of the category. + */ + virtual QCString trNamespace(bool /*first_capital*/, bool /*singular*/) + { + /* + QCString result((first_capital ? "Namespace" : "namespace")); + if (!singular) result+="s"; + return result; + */ + return "Ãû×Ö¿Õ¼ä"; + } + + /*! This is used for translation of the word that will possibly + * be followed by a single name or by a list of names + * of the category. + */ + virtual QCString trGroup(bool /*first_capital*/, bool /*singular*/) + { + /* + QCString result((first_capital ? "Group" : "group")); + if (!singular) result+="s"; + return result; + */ + return "×é"; + } + + /*! This is used for translation of the word that will possibly + * be followed by a single name or by a list of names + * of the category. + */ + virtual QCString trPage(bool /*first_capital*/, bool /*singular*/) + { + /* + QCString result((first_capital ? "Page" : "page")); + if (!singular) result+="s"; + return result; + */ + return "Ò³"; + } + + /*! This is used for translation of the word that will possibly + * be followed by a single name or by a list of names + * of the category. + */ + virtual QCString trMember(bool /*first_capital*/, bool /*singular*/) + { + /* + QCString result((first_capital ? "Member" : "member")); + if (!singular) result+="s"; + return result; + */ + return "³ÉÔ±"; + } + + /*! This is used for translation of the word that will possibly + * be followed by a single name or by a list of names + * of the category. + */ + virtual QCString trField(bool /*first_capital*/, bool /*singular*/) + { + /* + QCString result((first_capital ? "Field" : "field")); + if (!singular) result+="s"; + return result; + */ + return "×Ö¶Î"; + } + + /*! This is used for translation of the word that will possibly + * be followed by a single name or by a list of names + * of the category. + */ + virtual QCString trGlobal(bool /*first_capital*/, bool /*singular*/) + { + /* + QCString result((first_capital ? "Global" : "global")); + if (!singular) result+="s"; + return result; + */ + return "È«¾Ö¶¨Òå"; + } + +////////////////////////////////////////////////////////////////////////// +// new since 1.2.7 +////////////////////////////////////////////////////////////////////////// + + /*! This text is generated when the \\author command is used and + * for the author section in man pages. */ + virtual QCString trAuthor(bool /*first_capital*/, bool /*singular*/) + { + /* + QCString result((first_capital ? "Author" : "author")); + if (!singular) result+="s"; + return result; + */ + return "×÷Õß"; + } + }; #endif diff --git a/src/translator_ru.h b/src/translator_ru.h index 392c684..1473cf0 100644 --- a/src/translator_ru.h +++ b/src/translator_ru.h @@ -1069,6 +1069,8 @@ class TranslatorRussian : public Translator "class Undocumented { };\n\n" "/*! ïÔËÒÙÔÏÅ ÎÁÓÌÅÄÏ×ÁÎÉÅ */\n" "class PublicBase : public Truncated { };\n\n" + "/*! ûÁÂÌÏÎ ËÌÁÓÓÁ */\n" + "template<class T> class Templ {};\n\n" "/*! úÁÝÉÝÅÎÎÏÅ ÎÁÓÌÅÄÏ×ÁÎÉÅ */\n" "class ProtectedBase { };\n\n" "/*! úÁËÒÙÔÏÅ ÎÁÓÌÅÄÏ×ÁÎÉÅ */\n" @@ -1079,25 +1081,26 @@ class TranslatorRussian : public Translator "class Inherited : public PublicBase,\n" " protected ProtectedBase,\n" " private PrivateBase,\n" - " public Undocumented\n" + " public Undocumented,\n" + " public Templ<int>\n" "{\n" " private:\n" " Used *m_usedClass;\n" "};\n" "\\endcode\n" "åÓÌÉ \\c MAX_DOT_GRAPH_HEIGHT × ËÏÎÆÉÇÕÒÁÃÉÏÎÎÏÍ ÆÁÊÌÅ " - "ÕÓÔÁÎÏ×ÌÅÎ × 200, ÐÏÌÕÞÉÔÓÑ ÓÌÅÄÕÀÝÉÊ ÇÒÁÆ:" + "ÕÓÔÁÎÏ×ÌÅÎ × 240, ÐÏÌÕÞÉÔÓÑ ÓÌÅÄÕÀÝÉÊ ÇÒÁÆ:" "<p><center><img src=\"graph_legend.gif\"></center>\n" "<p>\n" "ðÒÑÍÏÕÇÏÌØÎÉËÉ × ÜÔÏÍ ÇÒÁÆÅ ÉÍÅÀÔ ÓÌÅÄÕÀÝÅÅ ÚÎÁÞÅÎÉÅ:\n" "<ul>\n" - "<li>úÁÐÏÌÎÅÎÎÙÊ ÞÅÒÎÎÙÊ ÐÒÑÍÏÕÇÏÌØÎÉË ÐÒÅÄÓÔÁ×ÌÑÅÔ ÓÔÒÕËÔÕÒÕ ÉÌÉ ËÌÁÓÓ, " + "<li>úÁÐÏÌÎÅÎÎÙÊ ÞÅÒÎÙÊ ÐÒÑÍÏÕÇÏÌØÎÉË ÐÒÅÄÓÔÁ×ÌÑÅÔ ÓÔÒÕËÔÕÒÕ ÉÌÉ ËÌÁÓÓ, " "ÄÌÑ ËÏÔÏÒÏÇÏ ÓÏÚÄÁÎ ÇÒÁÆ.\n" "<li>ðÒÑÍÏÕÇÏÌØÎÉË Ó ÞÅÒÎÏÊ ÇÒÁÎÉÃÅÊ ÏÂÏÚÎÁÞÁÅÔ ÄÏËÕÍÅÎÔÉÒÏ×ÁÎÎÕÀ ÓÔÒÕËÔÕÒÕ ÉÌÉ ËÌÁÓÓ.\n" "<li>ðÒÑÍÏÕÇÏÌØÎÉË Ó ÓÅÒÏÊ ÇÒÁÎÉÃÅÊ ÏÂÏÚÎÁÞÁÅÔ ÎÅÄÏËÕÍÅÎÔÉÒÏ×ÁÎÎÕÀ ÓÔÒÕËÔÕÒÕ ÉÌÉ ËÌÁÓÓ.\n" "<li>ðÒÑÍÏÕÇÏÌØÎÉË Ó ËÒÁÓÎÏÊ ÇÒÁÎÉÃÅÊ ÏÂÏÚÎÁÞÁÅÔ ÄÏËÕÍÅÎÔÉÒÏ×ÁÎÎÕÀ ÓÔÒÕËÔÕÒÕ ÉÌÉ ËÌÁÓÓ, ÄÌÑ ËÏÔÏÒÏÇÏ\n" " ÎÅ ×ÓÅ ÏÔÎÏÛÅÎÉÑ ÎÁÓÌÅÄÏ×ÁÎÉÑ/ÓÏÄÅÒÖÁÎÉÑ ÐÏËÁÚÁÎÙ. çÒÁÆ ÕÓÅÞÅÎ, " - "ÅÓÌÉ ÏÎ ÎÅ ÐÏÍÅÓÔÉÌÓÑ × ÕËÁÚÁÎÎÙÈ ÇÒÁÎÉÃÁÈ." + "ÅÓÌÉ ÏÎ ÎÅ ÐÏÍÅÓÔÉÌÓÑ × ÕËÁÚÁÎÎÙÈ ÇÒÁÎÉÃÁÈ.\n" "</ul>\n" "óÔÒÅÌËÉ ÉÍÅÀÔ ÓÌÅÄÕÀÝÅÅ ÚÎÁÞÅÎÉÅ:\n" "<ul>\n" @@ -1109,6 +1112,9 @@ class TranslatorRussian : public Translator "ÄÒÕÇÏÍ ËÌÁÓÅ ÉÌÉ ÉÓÐÏÌØÚÕÅÔÓÑ ÄÒÕÇÉÍ ËÌÁÓÓÏÍ." "óÏ ÓÔÒÅÌËÏÊ ÕËÁÚÙ×ÁÅÔÓÑ ÐÅÒÅÍÅÎÎÁÑ, " "ÞÅÒÅÚ ËÏÔÏÒÕÀ ÄÏÓÔÕÐÅÎ ÕËÁÚÙ×ÁÅÍÙÊ ËÌÁÓÓ ÉÌÉ ÓÔÒÕËÔÕÒÁ. \n" + "<li>öÅÌÔÁÑ ÓÔÒÅÌËÁ ÉÓÐÏÌØÚÕÅÔÓÑ ÄÌÑ Ó×ÑÚÉ ÐÏÄÓÔÁÎÏ×ËÉ ÛÁÂÌÏÎÁ É " + "ÛÁÂÌÏÎÁ, ÎÁ ÏÓÎÏ×Å ËÏÔÏÒÏÇÏ ÜÔÁ ÐÏÄÓÔÁÎÏ×ËÁ ×ÙÐÌÄÎÅÎÁ. ó ÛÁÂÌÏÎÏÍ" + "ÕËÁÚÙ×ÁÅÔÓÑ ÐÁÒÁÍÅÔÒ ÐÏÄÓÔÁÎÏ×ËÉ.\n" "</ul>\n"); } /*! text for the link to the legend page */ diff --git a/src/translator_si.h b/src/translator_si.h index 74efad5..0e7bf6e 100644 --- a/src/translator_si.h +++ b/src/translator_si.h @@ -2,7 +2,7 @@ * * * - * Copyright (C) 1997-2001 by Dimitri van Heesch. + * Copyright (C) 1997-2000 by Dimitri van Heesch. * * Permission to use, copy, modify, and distribute this software and its * documentation under the terms of the GNU General Public License is hereby @@ -20,9 +20,8 @@ #ifndef TRANSLATOR_SI_H #define TRANSLATOR_SI_H -#include "translator_adapter.h" -class TranslatorSlovene : public TranslatorAdapter_1_1_5 +class TranslatorSlovene : public Translator { public: QCString idLanguage() @@ -36,8 +35,6 @@ class TranslatorSlovene : public TranslatorAdapter_1_1_5 { return "\\usepackage[slovene]{babel} \n\\usepackage[latin2]{inputenc} \n\\usepackage[T1]{fontenc}\n"; } - QCString latexBabelPackage() - { return "slovene"; } QCString idLanguageCharset() { #ifdef _WIN32 @@ -55,9 +52,9 @@ class TranslatorSlovene : public TranslatorAdapter_1_1_5 QCString trMemberTypedefDocumentation() { return "Opis <code> uporabni¹ko definiranih tipov (typedef) </code>"; } QCString trMemberEnumerationDocumentation() - { return "Opis <code> na¹tevnih tipov </code> èlanova"; } + { return "Opis komponent <code> na¹tevnih tipov </code>"; } QCString trEnumerationValueDocumentation() - { return "Opis <code> na¹tevnih vednosti (enum) </code> "; } + { return "Opis vrednosti <code> na¹tevnih tipov (enum) </code> "; } QCString trMemberFunctionDocumentation() { return "Opis metod"; } QCString trMemberDataDocumentation() @@ -67,27 +64,25 @@ class TranslatorSlovene : public TranslatorAdapter_1_1_5 QCString trListOfAllMembers() { return "Seznam vseh metod / atributov."; } QCString trMemberList() - { return " - Seznam metod in atributov."; } + { return " - seznam metod in atributov."; } QCString trThisIsTheListOfAllMembers() - { return "To je seznam metod razreda "; } + { return "Seznam metod razreda "; } QCString trIncludingInheritedMembers() { return ", vkljuèujoè dedovane metode in atribute."; } QCString trGeneratedAutomatically(const char *s) - { QCString result="zgenerirano avtomatièno z Doxygen-om"; + { QCString result="zgenerirano z Doxygen-om"; if (s) result+=(QCString)" za "+s; - result+=" iz programskog koda."; + result+=" iz izvorne kode."; return result; } QCString trEnumName() - { return "enum ime"; } + { return "na¹tevno ime"; } QCString trEnumValue() - { return "enum vrednost"; } + { return "na¹tevna vrednost"; } QCString trDefinedIn() { return "definirano v"; } - QCString trVerbatimText(const char *f) - { return (QCString)"Ovo je citirani tekst iz include datoteke "+f+"."; } QCString trModules() - { return "Moduli"; } + { return "moduli"; } QCString trClassHierarchy() { return "dedovalna hierarhija"; } QCString trCompoundList() @@ -95,13 +90,13 @@ class TranslatorSlovene : public TranslatorAdapter_1_1_5 QCString trFileList() { return "seznam datotek"; } QCString trHeaderFiles() - { return "\"Header\" datoteka"; } + { return "'Header' datoteka"; } QCString trCompoundMembers() { return "metode in atributi"; } QCString trFileMembers() { return "komponente v datotekah"; } QCString trRelatedPages() - { return "Povezane strani"; } + { return "dodatni opisi"; } QCString trExamples() { return "Primeri"; } QCString trSearch() @@ -113,7 +108,7 @@ class TranslatorSlovene : public TranslatorAdapter_1_1_5 { QCString result="Seznam vseh "; if (!extractAll) result+="dokumentiranih "; - result+="datotek, s kratkim opisom:"; + result+="datotek s kratkim opisom:"; return result; } QCString trCompoundListDescription() @@ -133,17 +128,17 @@ class TranslatorSlovene : public TranslatorAdapter_1_1_5 { QCString result="Seznam "; if (!extractAll) result+="dokumentiranih "; - result+="entite v datotekah "; + result+="entitet v datotekah "; if (extractAll) result+="skupaj z opisom datoteke v kateri se nahajajo:"; - else result+="z linki na datoteke v katerih se nahajajo:"; + else result+="s povezavami na datoteke v katerih se nahajajo:"; return result; } QCString trHeaderFilesDescription() - { return "Seznam header datotek, ki tvoriju aplikacijski vmesnik (API) :"; } + { return "Seznam header datotek, ki tvorijo aplikacijski vmesnik (API) :"; } QCString trExamplesDescription() { return "Seznam primerov :"; } QCString trRelatedPagesDescription() - { return "Seznam povezanih strani:"; } + { return "Seznam strani z dodatnimi opisi:"; } QCString trModulesDescription() { return "Seznam modulov:"; } QCString trNoDescriptionAvailable() @@ -168,7 +163,7 @@ class TranslatorSlovene : public TranslatorAdapter_1_1_5 QCString trExampleDocumentation() { return "Opis primera"; } QCString trPageDocumentation() - { return "Dokumentacija povezanih strani"; } + { return "Opis povezanih strani"; } QCString trReferenceManual() { return "Priroènik"; } @@ -186,8 +181,6 @@ class TranslatorSlovene : public TranslatorAdapter_1_1_5 { return "Spremenljivke"; } QCString trEnumerationValues() { return "Vrednosti na¹tevnih tipov"; } - QCString trAuthor() - { return "avtor"; } QCString trDefineDocumentation() { return "Opis makro definicije"; } QCString trFunctionPrototypeDocumentation() @@ -202,8 +195,6 @@ class TranslatorSlovene : public TranslatorAdapter_1_1_5 { return "Opis spremenljivke"; } QCString trCompounds() { return "Strukture"; } - QCString trFiles() - { return "Datoteke"; } QCString trGeneratedAt(const char *date,const char *projName) { QCString result=(QCString)"Generirano "+date; @@ -222,8 +213,8 @@ class TranslatorSlovene : public TranslatorAdapter_1_1_5 QCString trForInternalUseOnly() { return "Samo za interno uporabo."; } QCString trReimplementedForInternalReasons() - { return "Reimplementirano zbog internih razloga; " - "Nema utjecaja na API."; + { return "Ponovno implementirano zaradi internih razlogov. " + "Nima vpliva na API."; } QCString trWarning() { return "Opozorilo"; } @@ -233,8 +224,6 @@ class TranslatorSlovene : public TranslatorAdapter_1_1_5 { return "Verzija"; } QCString trDate() { return "Datum"; } - QCString trAuthors() - { return "Avtor(ji)"; } QCString trReturns() { return "Rezultat(i)"; } QCString trSeeAlso() @@ -242,7 +231,7 @@ class TranslatorSlovene : public TranslatorAdapter_1_1_5 QCString trParameters() { return "Parametri"; } QCString trExceptions() - { return "Izjeme (Exceptions)"; } + { return "Prekinitve (Exceptions)"; } QCString trGeneratedBy() { return "Izdelano s pomoèjo"; } @@ -251,7 +240,7 @@ class TranslatorSlovene : public TranslatorAdapter_1_1_5 ////////////////////////////////////////////////////////////////////////// QCString trNamespaceList() - { return "Seznam imenskih prostorov"; } + { return "seznam imenskih prostorov"; } QCString trNamespaceListDescription(bool extractAll) { QCString result="Seznam "; @@ -285,7 +274,7 @@ class TranslatorSlovene : public TranslatorAdapter_1_1_5 case ClassDef::Struct: result+=" strukture "; break; case ClassDef::Union: result+=" unije "; break; case ClassDef::Interface: result+=" vmesnika (interface) "; break; - case ClassDef::Exception: result+=" izjeme (exception) "; break; + case ClassDef::Exception: result+=" prekinitve (exception) "; break; } result += (QCString)clName; @@ -370,39 +359,38 @@ class TranslatorSlovene : public TranslatorAdapter_1_1_5 // used in member documentation blocks to produce a list of // members that are hidden by this one. { - return "Redefinirano v "+trWriteList(numEntries)+"."; + return "Skrije implementacijo iz "+trWriteList(numEntries)+"."; } QCString trReimplementedInList(int numEntries) { // used in member documentation blocks to produce a list of // all member that overwrite the implementation of this member. - return "Reimplementacija u "+trWriteList(numEntries)+"."; + return "Metodo skrijejo implementacije v razredih "+trWriteList(numEntries)+"."; } QCString trNamespaceMembers() // This is put above each page as a link to all members of namespaces. - { return "Namespace èlanovi"; } + { return "elementi imenskega prostora"; } QCString trNamespaceMemberDescription(bool extractAll) // This is an introduction to the page with all namespace members { - QCString result="Lista svih "; + QCString result="Seznam vseh "; if (!extractAll) result+="dokumentiranih "; - result+="namespace èlanova s linkovima na "; + result+="elementov imenskega prostora s povezavami na "; if (extractAll) - result+="namespace dokumentaciju svakog èlana:"; + result+="opis vsakega elementa:"; else - result+="namespace kojima pripadaju:"; + result+="imenski prostor, ki mu pripadajo:"; return result; } QCString trNamespaceIndex() // This is used in LaTeX as the title of the chapter with the // index of all namespaces. - { return "Indeks namespace-a"; } + { return "Indeks imenskih prostorov"; } QCString trNamespaceDocumentation() // This is used in LaTeX as the title of the chapter containing // the documentation of all namespaces. - { return "Podati o imenskih prostorih"; } - + { return "Podatki o imenskih prostorih"; } ////////////////////////////////////////////////////////////////////////// // new since 0.49-990522 ////////////////////////////////////////////////////////////////////////// @@ -410,10 +398,9 @@ class TranslatorSlovene : public TranslatorAdapter_1_1_5 /*! This is used in the documentation before the list of all * namespaces in a file. */ - QCString trNamespaces() - { - return "Namespaces"; - } + virtual QCString trNamespaces() + { return "Imenski prostori"; } + ////////////////////////////////////////////////////////////////////////// // new since 0.49-990728 @@ -433,7 +420,7 @@ class TranslatorSlovene : public TranslatorAdapter_1_1_5 case ClassDef::Struct: result+="strukture"; break; case ClassDef::Union: result+="unije"; break; case ClassDef::Interface: result+="vmesnika (interface)"; break; - case ClassDef::Exception: result+="izjeme (exception)"; break; + case ClassDef::Exception: result+="prekinitve (exception)"; break; } result+=" je zgrajen na podlagi naslednj"; if (single) result+="e "; else result+="ih"; @@ -510,8 +497,7 @@ class TranslatorSlovene : public TranslatorAdapter_1_1_5 "direktno ali indirektno vkljuèuje. Pravokotniki ponazarjajo datoteke, pu¹èice " "predstavljajo relacije med njimi. " "Èrn pravokotnik ponazarja datoteko "+fName+". Pu¹èice A->B ponazarjajo " - "usmerjeno relacijo \"A vkljuèuje B\"." -; + "usmerjeno relacijo \"A vkljuèuje B\"."; } /*! header that is put before the list of constructor/destructors. */ QCString trConstructorDocumentation() @@ -528,17 +514,17 @@ class TranslatorSlovene : public TranslatorAdapter_1_1_5 { return "dokumenacija tekoèe datoteke."; } - /*! Text for the \\pre command */ + /*! Text for the \pre command */ QCString trPrecondition() { return "Predpogoji (preconditions)"; } - /*! Text for the \\post command */ + /*! Text for the \post command */ QCString trPostcondition() { return "Naknadni pogoji (posconditions)"; } - /*! Text for the \\invariant command */ + /*! Text for the \invariant command */ QCString trInvariant() { return "Invarianta"; @@ -619,12 +605,12 @@ class TranslatorSlovene : public TranslatorAdapter_1_1_5 ////////////////////////////////////////////////////////////////////////// /*! Used as a marker that is put before a todo item */ - QCString trTodo() + virtual QCString trTodo() { return "TODO"; } /*! Used as the header of the todo list */ - QCString trTodoList() + virtual QCString trTodoList() { return "Seznam nedokonèanih opravil"; } @@ -633,19 +619,19 @@ class TranslatorSlovene : public TranslatorAdapter_1_1_5 // new since 1.1.4 ////////////////////////////////////////////////////////////////////////// - QCString trReferencedBy() + virtual QCString trReferencedBy() { return "Uporabniki entitete: "; } - QCString trRemarks() + virtual QCString trRemarks() { return "Opomba"; } - QCString trAttention() + virtual QCString trAttention() { return "Pozor"; } - QCString trInclByDepGraph() + virtual QCString trInclByDepGraph() { return "Graf prikazuje datoteke, ki posredno ali neposredno " "vkljuèujejo tekoèo datoteko. Pravokotniki simbolizirajo datoteke, " @@ -657,11 +643,343 @@ class TranslatorSlovene : public TranslatorAdapter_1_1_5 "le posredno. " ; } - QCString trSince() + virtual QCString trSince() { return "Od"; } +////////////////////////////////////////////////////////////////////////// +// new since 1.1.5 +////////////////////////////////////////////////////////////////////////// + + /*! title of the graph legend page */ + virtual QCString trLegendTitle() + { + return "Legenda grafa"; + } + /*! page explaining how the dot graph's should be interpreted + * The %A in the text below are to prevent link to classes called "A". + */ + virtual QCString trLegendDocs() + { + return + "Tekoèa stran pojasnjuje naèin interpretacije grafov, ki jih izri¹e " + "doxygen.<p>\n" + "Poglejmo si naslednji primer:\n" + "\\code\n" + "/*! Nevide razred zaradi rezanja */\n" + "class Invisible { };\n\n" + "/*! Odrezan razred, dedovalna relacija je skrita */\n" + "class Truncated : public Invisible { };\n\n" + "/* razred, ki ni opisan z doxygen komentarji */\n" + "class Undocumented { };\n\n" + "/*! Razred, ki ga dedujemo s pomoèjo javnega dedovanja */\n" + "class PublicBase : public Truncated { };\n\n" + "/*! Razred, ki ga dedujemo s pomoèjo za¹èitenega dedovanja */\n" + "class ProtectedBase { };\n\n" + "/*! Razred, ki ga dedujemo s pomoèjo skritega dedovanja */\n" + "class PrivateBase { };\n\n" + "/*! Razred, ki ga uporablja dedovani razred */\n" + "class Used { };\n\n" + "/*! Super class that inherits a number of other classes */\n" + "class Inherited : public PublicBase,\n" + " protected ProtectedBase,\n" + " private PrivateBase,\n" + " public Undocumented\n" + "{\n" + " private:\n" + " Used *m_usedClass;\n" + "};\n" + "\\endcode\n" + "If the \\c MAX_DOT_GRAPH_HEIGHT tag in the configuration file " + "is set to 200 this will result in the following graph:" + "<p><center><img src=\"graph_legend.gif\"></center>\n" + "<p>\n" + "The boxes in the above graph have the following meaning:\n" + "<ul>\n" + "<li>%A filled black box represents the struct or class for which the " + "graph is generated.\n" + "<li>%A box with a black border denotes a documented struct or class.\n" + "<li>%A box with a grey border denotes an undocumented struct or class.\n" + "<li>%A box with a red border denotes a documented struct or class for\n" + "which not all inheritance/containment relations are shown. %A graph is " + "truncated if it does not fit within the specified boundaries." + "</ul>\n" + "The arrows have the following meaning:\n" + "<ul>\n" + "<li>%A dark blue arrow is used to visualize a public inheritance " + "relation between two classes.\n" + "<li>%A dark green arrow is used for protected inheritance.\n" + "<li>%A dark red arrow is used for private inheritance.\n" + "<li>%A purple dashed arrow is used if a class is contained or used " + "by another class. The arrow is labeled with the variable(s) " + "through which the pointed class or struct is accessible. \n" + "</ul>\n"; + } + /*! text for the link to the legend page */ + virtual QCString trLegend() + { + return "legenda"; + } + +////////////////////////////////////////////////////////////////////////// +// new since 1.2.0 +////////////////////////////////////////////////////////////////////////// + + /*! Used as a marker that is put before a test item */ + virtual QCString trTest() + { + return "Test"; + } + /*! Used as the header of the test list */ + virtual QCString trTestList() + { + return "Test List"; + } + +////////////////////////////////////////////////////////////////////////// +// new since 1.2.1 +////////////////////////////////////////////////////////////////////////// + + /*! Used as a section header for KDE-2 IDL methods */ + virtual QCString trDCOPMethods() + { + return "DCOP metode"; + } + +////////////////////////////////////////////////////////////////////////// +// new since 1.2.2 +////////////////////////////////////////////////////////////////////////// + + /*! Used as a section header for IDL properties */ + virtual QCString trProperties() + { + return "IDL Lastnosti"; + } + /*! Used as a section header for IDL property documentation */ + virtual QCString trPropertyDocumentation() + { + return "Opis IDL lastnosti"; + } + +////////////////////////////////////////////////////////////////////////// +// new since 1.2.4 +////////////////////////////////////////////////////////////////////////// + + /*! Used for Java interfaces in the summary section of Java packages */ + virtual QCString trInterfaces() + { + return "Vmesniki"; + } + /*! Used for Java classes in the summary section of Java packages */ + virtual QCString trClasses() + { + if (Config_getBool("OPTIMIZE_OUTPUT_FOR_C")) + { + return "Podatkovne strukture"; + } + else + { + return "Razredi"; + } + } + /*! Used as the title of a Java package */ + virtual QCString trPackage(const char *name) + { + return (QCString)"JAVA paket "+name; + } + /*! Title of the package index page */ + virtual QCString trPackageList() + { + return "Seznam JAVA paketov"; + } + /*! The description of the package index page */ + virtual QCString trPackageListDescription() + { + return "Seznam JAVA paketov in njihovih kratkih opisov v primeru, da obstajajo:"; + } + /*! The link name in the Quick links header for each page */ + virtual QCString trPackages() + { + return "JAVA paketi"; + } + /*! Used as a chapter title for Latex & RTF output */ + virtual QCString trPackageDocumentation() + { + return "Opisi JAVA paketov"; + } + /*! Text shown before a multi-line define */ + virtual QCString trDefineValue() + { + return "Vrednost:"; + } + +////////////////////////////////////////////////////////////////////////// +// new since 1.2.5 +////////////////////////////////////////////////////////////////////////// + + /*! Used as a marker that is put before a \\bug item */ + virtual QCString trBug() + { + return "Programska napaka"; + } + /*! Used as the header of the bug list */ + virtual QCString trBugList() + { + return "Seznam programskih napak"; + } + +////////////////////////////////////////////////////////////////////////// +// new since 1.2.6 +////////////////////////////////////////////////////////////////////////// + + /*! Used as ansicpg for RTF file + * + * The following table shows the correlation of Charset name, Charset Value and + * <pre> + * Codepage number: + * Charset Name Charset Value(hex) Codepage number + * ------------------------------------------------------ + * DEFAULT_CHARSET 1 (x01) + * SYMBOL_CHARSET 2 (x02) + * OEM_CHARSET 255 (xFF) + * ANSI_CHARSET 0 (x00) 1252 + * RUSSIAN_CHARSET 204 (xCC) 1251 + * EE_CHARSET 238 (xEE) 1250 + * GREEK_CHARSET 161 (xA1) 1253 + * TURKISH_CHARSET 162 (xA2) 1254 + * BALTIC_CHARSET 186 (xBA) 1257 + * HEBREW_CHARSET 177 (xB1) 1255 + * ARABIC _CHARSET 178 (xB2) 1256 + * SHIFTJIS_CHARSET 128 (x80) 932 + * HANGEUL_CHARSET 129 (x81) 949 + * GB2313_CHARSET 134 (x86) 936 + * CHINESEBIG5_CHARSET 136 (x88) 950 + * </pre> + * + */ + virtual QCString trRTFansicp() + { + return "1250"; + } + + + /*! Used as ansicpg for RTF fcharset + * \see trRTFansicp() for a table of possible values. + */ + virtual QCString trRTFCharSet() + { + return "0"; + } + + /*! Used as header RTF general index */ + virtual QCString trRTFGeneralIndex() + { + return "Indeks"; + } + + /*! This is used for translation of the word that will possibly + * be followed by a single name or by a list of names + * of the category. + */ + virtual QCString trClass(bool first_capital, bool singular) + { + QCString result((first_capital ? "Razred" : "razred")); + if (!singular) result+="i"; + return result; + } + + /*! This is used for translation of the word that will possibly + * be followed by a single name or by a list of names + * of the category. + */ + virtual QCString trFile(bool first_capital, bool singular) + { + QCString result((first_capital ? "Datotek" : "datotek")); + if (!singular) result+="e"; + else result += "a"; + return result; + } + + /*! This is used for translation of the word that will possibly + * be followed by a single name or by a list of names + * of the category. + */ + virtual QCString trNamespace(bool first_capital, bool singular) + { + QCString result((first_capital ? "Imenski prostor" : "imenski prostor")); + if (!singular) result+="i"; + return result; + } + + /*! This is used for translation of the word that will possibly + * be followed by a single name or by a list of names + * of the category. + */ + virtual QCString trGroup(bool first_capital, bool singular) + { + QCString result((first_capital ? "Skupina" : "skupina")); + if (!singular) result+="s"; + return result; + } + + /*! This is used for translation of the word that will possibly + * be followed by a single name or by a list of names + * of the category. + */ + virtual QCString trPage(bool first_capital, bool singular) + { + QCString result((first_capital ? "Stran" : "stran")); + if (!singular) result+="i"; + return result; + } + + /*! This is used for translation of the word that will possibly + * be followed by a single name or by a list of names + * of the category. + */ + virtual QCString trMember(bool first_capital, bool singular) + { + QCString result((first_capital ? "Element" : "element")); + if (!singular) result+="i"; + return result; + } + + /*! This is used for translation of the word that will possibly + * be followed by a single name or by a list of names + * of the category. + */ + virtual QCString trField(bool first_capital, bool singular) + { + QCString result((first_capital ? "Polj" : "polj")); + if (!singular) result+="a"; + else result += "e"; + return result; + } + + /*! This is used for translation of the word that will possibly + * be followed by a single name or by a list of names + * of the category. + */ + virtual QCString trGlobal(bool first_capital, bool singular) + { + QCString result((first_capital ? "Global" : "global")); + if (!singular) result+="s"; + return result; + } + +////////////////////////////////////////////////////////////////////////// +// new since 1.2.7 +////////////////////////////////////////////////////////////////////////// + + /*! This text is generated when the \\author command is used and + * for the author section in man pages. */ + virtual QCString trAuthor(bool first_capital, bool singular) + { + QCString result((first_capital ? "Avtor" : "avtor")); + if (!singular) result+="ji"; + return result; + } }; diff --git a/src/util.cpp b/src/util.cpp index f1fa9c6..4d2e130 100644 --- a/src/util.cpp +++ b/src/util.cpp @@ -2638,12 +2638,15 @@ bool generateLink(OutputDocInterface &od,const char *clName, } else if ((gd=Doxygen::groupSDict[linkRef])) // link to a group { - od.startTextLink(gd->getOutputFileBase(),0); - if (lt) - od.docify(lt); - else - od.docify(gd->groupTitle()); - od.endTextLink(); + //od.startTextLink(gd->getOutputFileBase(),0); + //if (lt) + // od.docify(lt); + //else + // od.docify(gd->groupTitle()); + //od.endTextLink(); + QCString title; + if (lt) title=lt; else title=gd->groupTitle(); + od.writeObjectLink(gd->getReference(),gd->getOutputFileBase(),0,title); if (gd->isLinkableInProject()) { writePageRef(od,gd->getOutputFileBase(),0); @@ -3436,8 +3439,8 @@ found: void addRelatedPage(const char *name,const QCString &ptitle, const QCString &doc,QList<QCString> *anchors, const char *fileName,int startLine, - int todoId,int testId,int bugId,GroupDef *gd=0, - TagInfo *tagInfo=0 + int todoId,int testId,int bugId,GroupDef *gd, + TagInfo *tagInfo ) { PageInfo *pi=0; @@ -3509,7 +3512,7 @@ void addRelatedPage(const char *name,const QCString &ptitle, //---------------------------------------------------------------------------- void addRefItem(int todoId,int testId,int bugId,const char *prefix, - const char *name,const char *title,const char *args=0) + const char *name,const char *title,const char *args) { //printf("addRefItem(%s) todoId=%d testId=%d bugId=%d\n",name,todoId,testId,bugId); @@ -42,7 +42,7 @@ class ClassList; class MemberGroupList; class MemberGroupDict; class Definition; -class TagInfo; +struct TagInfo; //-------------------------------------------------------------------- |