qptrlist.3qt

Linux下的基于X11的图形开发环境。

'\" t
.TH QPtrList 3qt "9 December 2002" "Trolltech AS" \" -*- nroff -*-
.\" Copyright 1992-2001 Trolltech AS.  All rights reserved.  See the
.\" license file included in the distribution for a complete license
.\" statement.
.\"
.ad l
.nh
.SH NAME
QPtrList \- Template class that provides a list
.SH SYNOPSIS
\fC#include <qptrlist.h>\fR
.PP
Inherits QPtrCollection.
.PP
Inherited by QObjectList, QSortedList, and QStrList.
.PP
.SS "Public Members"
.in +1c
.ti -1c
.BI "\fBQPtrList\fR ()"
.br
.ti -1c
.BI "\fBQPtrList\fR ( const QPtrList<type> & list )"
.br
.ti -1c
.BI "\fB~QPtrList\fR ()"
.br
.ti -1c
.BI "QPtrList<type> & \fBoperator=\fR ( const QPtrList<type> & list )"
.br
.ti -1c
.BI "bool \fBoperator==\fR ( const QPtrList<type> & list ) const"
.br
.ti -1c
.BI "bool \fBoperator!=\fR ( const QPtrList<type> & list ) const"
.br
.ti -1c
.BI "virtual uint \fBcount\fR () const"
.br
.ti -1c
.BI "bool \fBisEmpty\fR () const"
.br
.ti -1c
.BI "bool \fBinsert\fR ( uint index, const type * item )"
.br
.ti -1c
.BI "void \fBinSort\fR ( const type * item )"
.br
.ti -1c
.BI "void \fBprepend\fR ( const type * item )"
.br
.ti -1c
.BI "void \fBappend\fR ( const type * item )"
.br
.ti -1c
.BI "bool \fBremove\fR ( uint index )"
.br
.ti -1c
.BI "bool \fBremove\fR ()"
.br
.ti -1c
.BI "bool \fBremove\fR ( const type * item )"
.br
.ti -1c
.BI "bool \fBremoveRef\fR ( const type * item )"
.br
.ti -1c
.BI "void \fBremoveNode\fR ( QLNode * node )"
.br
.ti -1c
.BI "bool \fBremoveFirst\fR ()"
.br
.ti -1c
.BI "bool \fBremoveLast\fR ()"
.br
.ti -1c
.BI "type * \fBtake\fR ( uint index )"
.br
.ti -1c
.BI "type * \fBtake\fR ()"
.br
.ti -1c
.BI "type * \fBtakeNode\fR ( QLNode * node )"
.br
.ti -1c
.BI "virtual void \fBclear\fR ()"
.br
.ti -1c
.BI "void \fBsort\fR ()"
.br
.ti -1c
.BI "int \fBfind\fR ( const type * item )"
.br
.ti -1c
.BI "int \fBfindNext\fR ( const type * item )"
.br
.ti -1c
.BI "int \fBfindRef\fR ( const type * item )"
.br
.ti -1c
.BI "int \fBfindNextRef\fR ( const type * item )"
.br
.ti -1c
.BI "uint \fBcontains\fR ( const type * item ) const"
.br
.ti -1c
.BI "uint \fBcontainsRef\fR ( const type * item ) const"
.br
.ti -1c
.BI "bool \fBreplace\fR ( uint index, const type * item )"
.br
.ti -1c
.BI "type * \fBat\fR ( uint index )"
.br
.ti -1c
.BI "int \fBat\fR () const"
.br
.ti -1c
.BI "type * \fBcurrent\fR () const"
.br
.ti -1c
.BI "QLNode * \fBcurrentNode\fR () const"
.br
.ti -1c
.BI "type * \fBgetFirst\fR () const"
.br
.ti -1c
.BI "type * \fBgetLast\fR () const"
.br
.ti -1c
.BI "type * \fBfirst\fR ()"
.br
.ti -1c
.BI "type * \fBlast\fR ()"
.br
.ti -1c
.BI "type * \fBnext\fR ()"
.br
.ti -1c
.BI "type * \fBprev\fR ()"
.br
.ti -1c
.BI "void \fBtoVector\fR ( QGVector * vec ) const"
.br
.in -1c
.SS "Important Inherited Members"
.in +1c
.ti -1c
.BI "bool \fBautoDelete\fR () const"
.br
.ti -1c
.BI "void \fBsetAutoDelete\fR ( bool enable )"
.br
.in -1c
.SS "Protected Members"
.in +1c
.ti -1c
.BI "virtual int \fBcompareItems\fR ( QPtrCollection::Item item1, QPtrCollection::Item item2 )"
.br
.ti -1c
.BI "virtual QDataStream & \fBread\fR ( QDataStream & s, QPtrCollection::Item & item )"
.br
.ti -1c
.BI "virtual QDataStream & \fBwrite\fR ( QDataStream & s, QPtrCollection::Item item ) const"
.br
.in -1c
.SH DESCRIPTION
The QPtrList class is a template class that provides a list.
.PP
QValueList is an STL-compatible alternative to this class.
.PP
Define a template instance QPtrList<X> to create a list that operates on pointers to X (X*).
.PP
The list class is indexable and has a current index and a current item. The first item corresponds to index position 0. The current index is -1 if the current item is 0.
.PP
Items are inserted with prepend(), insert() or append(). Items are removed with remove(), removeRef(), removeFirst() and removeLast(). You can search for an item using find(), findNext(), findRef() or findNextRef(). The list can be sorted with sort(). You can count the number of occurrences of an item with contains() or containsRef(). You can get a pointer to the current item with current(), to an item at a particular index position in the list with at() or to the first or last item with getFirst() and getLast(). You can also iterate over the list with first(), last(), next() and prev() (which all update current()). The list's deletion property is set with setAutoDelete().
.PP
Example:
.PP
.nf
.br
    class Employee
.br
    {
.br
    public:
.br
        Employee() : sn( 0 ) { }
.br
        Employee( const QString& forename, const QString& surname, int salary )
.br
            : fn( forename ), sn( surname ), sal( salary )
.br
        { }
.br
.br
        void setSalary( int salary ) { sal = salary; }
.br
.br
        QString forename() const { return fn; }
.br
        QString surname() const { return sn; }
.br
        int salary() const { return sal; }
.br
.br
    private:
.br
        QString fn;
.br
        QString sn;
.br
        int sal;
.br
    };
.br
.br
    QPtrList<Employee> list;
.br
    list.setAutoDelete( TRUE ); // the list owns the objects
.br
.br
    list.append( new Employee("John", "Doe", 50000) );
.br
    list.append( new Employee("Jane", "Williams", 80000) );
.br
    list.append( new Employee("Tom", "Jones", 60000) );
.br
.br
    Employee *employee;
.br
    for ( employee = list.first(); employee; employee = list.next() )
.br
        cout << employee->surname().latin1() << ", " <<
.br
                employee->forename().latin1() << " earns " <<
.br
                employee->salary() << endl;
.br
    cout << endl;
.br
.br
    // very inefficient for big lists
.br
    for ( uint i = 0; i < list.count(); ++i )
.br
        if ( list.at(i) )
.br
            cout << list.at( i )->surname().latin1() << endl;
.br
.fi
.PP
The output is
.PP
.nf
.br
    Doe, John earns 50000
.br
    Williams, Jane earns 80000
.br
    Jones, Tom earns 60000
.br
.br
    Doe
.br
    Williams
.br
    Jones
.br
.fi
.PP
QPtrList has several member functions for traversing the list, but using a QPtrListIterator can be more practical. Multiple list iterators may traverse the same list, independently of each other and of the current list item.
.PP
In the example above we make the call setAutoDelete(TRUE). Enabling auto-deletion tells the list to delete items that are removed. The default is to not delete items when they are removed but this would cause a memory leak in the example because there are no other references to the list items.
.PP
When inserting an item into a list only the pointer is copied, not the item itself, i.e. a shallow copy. It is possible to make the list copy all of the item's data (deep copy) when an item is inserted. insert(), inSort() and append() call the virtual function QPtrCollection::newItem() for the item to be inserted. Inherit a list and reimplement newItem() to have deep copies.
.PP
When removing an item from a list, the virtual function QPtrCollection::deleteItem() is called. QPtrList's default implementation is to delete the item if auto-deletion is enabled.
.PP
The virtual function compareItems() can be reimplemented to compare two list items. This function is called from all list functions that need to compare list items, for instance remove(const type*). If you only want to deal with pointers, there are functions that compare pointers instead, for instance removeRef(const type*). These functions are somewhat faster than those that call compareItems().
.PP
List items are stored as \fCvoid*\fR in an internal QLNode, which also holds pointers to the next and previous list items. The functions currentNode(), removeNode(), and takeNode() operate directly on the QLNode, but they should be used with care. The data component of the node is available through QLNode::getData().
.PP
The QStrList class defined in qstrlist.h is a list of \fCchar*\fR. It reimplements newItem(), deleteItem() and compareItems(). (But see QStringList for a list of Unicode QStrings.)
.PP
See also QPtrListIterator, Collection Classes, and Non-GUI Classes.
.SH MEMBER FUNCTION DOCUMENTATION
.SH "QPtrList::QPtrList ()"
Constructs an empty list.
.SH "QPtrList::QPtrList ( const QPtrList<type> & list )"
Constructs a copy of \fIlist\fR.
.PP
Each item in \fIlist\fR is appended to this list. Only the pointers are copied (shallow copy).
.SH "QPtrList::~QPtrList ()"
Removes all items from the list and destroys the list.
.PP
All list iterators that access this list will be reset.
.PP
See also setAutoDelete().
.SH "void QPtrList::append ( const type * item )"
Inserts the \fIitem\fR at the end of the list.
.PP
The inserted item becomes the current list item. This is equivalent to \fCinsert( count(), item )\fR.
.PP
\fIitem\fR must not be 0.
.PP
See also insert(), current(), and prepend().
.PP
Examples:
.)l canvas/canvas.cpp, customlayout/border.cpp, customlayout/card.cpp, customlayout/flow.cpp, listviews/listviews.cpp, listviews/listviews.h, and qwerty/qwerty.cpp.
.SH "type * QPtrList::at ( uint index )"
Returns a pointer to the item at position \fIindex\fR in the list, or 0 if the index is out of range.
.PP
Sets the current list item to this item if \fIindex\fR is valid. The valid range is \fC0..(count() - 1)\fR inclusive.
.PP
This function is very efficient. It starts scanning from the first item, last item, or current item, whichever is closest to \fIindex\fR.
.PP
See also current().
.PP
Examples:
.)l customlayout/border.cpp, customlayout/card.cpp, customlayout/flow.cpp, dirview/dirview.cpp, fileiconview/qfileiconview.cpp, mdi/application.cpp, and qwerty/qwerty.cpp.
.SH "int QPtrList::at () const"
This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
.PP
Returns the index of the current list item. The returned value is -1 if the current item is 0.
.PP
See also current().
.SH "bool QPtrCollection::autoDelete () const"
Returns the setting of the auto-delete option. The default is FALSE.
.PP
See also setAutoDelete().
.SH "void QPtrList::clear ()\fC [virtual]\fR"
Removes all items from the list.
.PP
The removed items are deleted if auto-deletion is enabled.
.PP
All list iterators that access this list will be reset.
.PP
See also remove(), take(), and setAutoDelete().
.PP
Reimplemented from QPtrCollection.
.SH "int QPtrList::compareItems ( QPtrCollection::Item item1, QPtrCollection::Item item2 )\fC [virtual protected]\fR"
This virtual function compares two list items.
.PP
Returns:
.TP
zero if \fIitem1\fR == \fIitem2\fR
.TP
nonzero if \fIitem1\fR != \fIitem2\fR
.PP
This function returns \fIint\fR rather than \fIbool\fR so that reimplementations can return three values and use it to sort by:
.TP
0 if \fIitem1\fR == \fIitem2\fR
.TP
> 0 (positive integer) if \fIitem1\fR > \fIitem2\fR
.TP
< 0 (negative integer) if \fIitem1\fR < \fIitem2\fR
.PP