qlistviewitem.3qt

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

The QListViewItem class implements a list view item.
.PP
A list view item is a multi-column object capable of displaying itself in a QListView. Its design has the following main goals:
.TP
Work quickly and well for \fIlarge\fR sets of data.
.TP
Be easy to use in the simple case.
.PP
The easiest way to use QListViewItem is to construct one with a few constant strings.
.PP
.nf
.br
        (void) new QListViewItem( parent, "first column", "second column" );
.br
.fi
Here we create a new list view item with two literal strings. The item becomes a child of \fIparent\fR. We've discarded the pointer to the item since we can still access it via its \fIparent\fR. This object will be deleted when \fIparent\fR is deleted, as usual for QObjects.
.PP
The parent must be another QListViewItem or a QListView. If the parent is a QListView, the item becomes a top-level item within that QListView. If the parent is another QListViewItem, the item becomes a child of that list view item.
.PP
If you keep the pointer, you can set or change the texts using setText(), add pixmaps using setPixmap(), change its mode using setSelectable(), setSelected(), setOpen() and setExpandable(). You'll also be able to change its height using setHeight(), and traverse the tree. You don't have to keep the pointer since you can get a pointer to any QListViewItem in a QListView using QListView::selectedItem(), QListView::currentItem(), QListView::firstChild(), QListView::lastItem() and QListView::findItem().
.PP
QCheckListItems are list view items that have a checkbox or radio button and can be used in place of QListViewItems.
.PP
You can traverse the tree as if it were a doubly-linked list using itemAbove() and itemBelow(); they return pointers to the items directly above and below this item on the screen (even if none of the three are actually visible at the moment).
.PP
You can also traverse it as a tree by using parent(), firstChild(), and nextSibling().
.PP
Example:
.PP
.nf
.br
        QListViewItem * myChild = myItem->firstChild();
.br
        while( myChild ) {
.br
            doSomething( myChild );
.br
            myChild = myChild->nextSibling();
.br
        }
.br
.fi
.PP
There is also an interator class to traverse a tree of list view items. To iterate over all selected items of a list view, do the following:
.PP
.nf
.br
        QListViewItemIterator it( listview );
.br
        while ( it.current() ) {
.br
            QListViewItem *item = it.current();
.br
            ++it;
.br
.br
            if ( item->isSelected() )
.br
                doSomething( item );
.br
        }
.br
.fi
.PP
Note that the order of the children will change when the sorting order changes and is undefined if the items are not visible. You can, however, call enforceSortOrder() at any time; QListView will always call it before it needs to show an item.
.PP
Many programs will need to reimplement QListViewItem. The most commonly reimplemented functions are: <center>.nf
.TS
l - l. Function Description text() Returns the text in a column. Many subclasses will compute this on the fly. key() Is used for sorting. The default key() simply calls text(), but judicious use of key can be used to sort by date, for example (as QFileDialog does). setup() Is called before showing the item and whenever the font changes, for example. activate()
.TE
.fi
</center>
.PP
Some subclasses call setExpandable(TRUE) even when they have no children, and populate themselves when setup() or setOpen(TRUE) is called. The dirview/dirview.cpp example program uses this technique to start up quickly: The files and subdirectories in a directory aren't inserted into the tree until they're actually needed.
.PP
<center>
.ce 1
.B "[Image Omitted]"
.PP
</center>
.PP
See also QCheckListItem, QListView, and Advanced Widgets.
.SH MEMBER FUNCTION DOCUMENTATION
.SH "QListViewItem::QListViewItem ( QListView * parent )"
Constructs a new top-level list view item in the QListView \fIparent\fR.
.SH "QListViewItem::QListViewItem ( QListViewItem * parent )"
Constructs a new list view item that is a child of \fIparent\fR and first in the parent's list of children.
.SH "QListViewItem::QListViewItem ( QListView * parent, QListViewItem * after )"
Constructs an empty list view item that is a child of \fIparent\fR and is after \fIafter\fR in the parent's list of children. Since \fIparent\fR is a QListView the item will be a top-level item.
.SH "QListViewItem::QListViewItem ( QListViewItem * parent, QListViewItem * after )"
Constructs an empty list view item that is a child of \fIparent\fR and is after \fIafter\fR in the parent's list of children.
.SH "QListViewItem::QListViewItem ( QListView * parent, QString label1, QString label2 = QString::null, QString label3 = QString::null, QString label4 = QString::null, QString label5 = QString::null, QString label6 = QString::null, QString label7 = QString::null, QString label8 = QString::null )"
Constructs a new top-level list view item in the QListView \fIparent\fR, with up to eight constant strings \fIlabel1\fR, \fIlabel2\fR, \fIlabel3\fR, \fIlabel4\fR, \fIlabel5\fR, \fIlabel6\fR, \fIlabel7\fR and \fIlabel8\fR defining its column contents.
.PP
See also setText().
.SH "QListViewItem::QListViewItem ( QListViewItem * parent, QString label1, QString label2 = QString::null, QString label3 = QString::null, QString label4 = QString::null, QString label5 = QString::null, QString label6 = QString::null, QString label7 = QString::null, QString label8 = QString::null )"
Constructs a new list view item as a child of the QListViewItem \fIparent\fR with optional constant strings \fIlabel1\fR, \fIlabel2\fR, \fIlabel3\fR, \fIlabel4\fR, \fIlabel5\fR, \fIlabel6\fR, \fIlabel7\fR and \fIlabel8\fR as column contents.
.PP
See also setText().
.SH "QListViewItem::QListViewItem ( QListView * parent, QListViewItem * after, QString label1, QString label2 = QString::null, QString label3 = QString::null, QString label4 = QString::null, QString label5 = QString::null, QString label6 = QString::null, QString label7 = QString::null, QString label8 = QString::null )"
Constructs a new list view item in the QListView \fIparent\fR that is included after item \fIafter\fR and can contain up to eight column texts \fIlabel1\fR, \fIlabel2\fR, \fIlabel3\fR, \fIlabel4\fR, \fIlabel5\fR, \fIlabel6\fR, \fIlabel7\fR and\fIlabel8\fR.
.PP
Note that the order is changed according to QListViewItem::key() unless the list view's sorting is disabled using QListView::setSorting( -1 ).
.PP
See also setText().
.SH "QListViewItem::QListViewItem ( QListViewItem * parent, QListViewItem * after, QString label1, QString label2 = QString::null, QString label3 = QString::null, QString label4 = QString::null, QString label5 = QString::null, QString label6 = QString::null, QString label7 = QString::null, QString label8 = QString::null )"
Constructs a new list view item as a child of the QListViewItem \fIparent\fR. It is inserted after item \fIafter\fR and may contain up to eight strings \fIlabel1\fR, \fIlabel2\fR, \fIlabel3\fR, \fIlabel4\fR, \fIlabel5\fR, \fIlabel6\fR, \fIlabel7\fR and \fIlabel8\fR as column entries.
.PP
Note that the order is changed according to QListViewItem::key() unless the list view's sorting is disabled using QListView::setSorting( -1 ).
.PP
See also setText().
.SH "QListViewItem::~QListViewItem ()\fC [virtual]\fR"
Destroys the item, deleting all its children and freeing up all allocated resources.
.SH "bool QListViewItem::acceptDrop ( const QMimeSource * mime ) const\fC [virtual]\fR"
Returns TRUE if the item can accept drops of type QMimeSource \fImime\fR; otherwise returns FALSE.
.PP
The default implementation does nothing and returns FALSE. A subclass must reimplement this to accept drops.
.SH "void QListViewItem::activate ()\fC [virtual protected]\fR"
This virtual function is called whenever the user clicks on this item or presses Space on it.
.PP
See also activatedPos().
.PP
Reimplemented in QCheckListItem.
.SH "bool QListViewItem::activatedPos ( QPoint & pos )\fC [protected]\fR"
When called from a reimplementation of activate(), this function gives information on how the item was activated. Otherwise the behavior is undefined.
.PP
If activate() was caused by a mouse press, the function sets \fIpos\fR to where the user clicked and returns TRUE; otherwise it returns FALSE and does not change \fIpos\fR.
.PP
\fIpos\fR is relative to the top-left corner of this item.
.PP
\fBWarning:\fR We recommend that you ignore this function; it is scheduled to become obsolete.
.PP
See also activate().
.SH "void QListViewItem::cancelRename ( int col )\fC [virtual protected]\fR"
This function is called if the user cancels in-place renaming of this item in column \fIcol\fR (e.g. by pressing Esc).
.PP
See also okRename().
.SH "int QListViewItem::childCount () const"
Returns how many children this item has.
.SH "int QListViewItem::compare ( QListViewItem * i, int col, bool ascending ) const\fC [virtual]\fR"
Compares this listview item to \fIi\fR using the column \fIcol\fR in \fIascending\fR order. Returns -1 if this item is less than \fIi\fR, 0 if they are equal and 1 if this item is greater than \fIi\fR.
.PP
This function is used for sorting.
.PP
The default implementation compares the item keys (key()) using QString::localeAwareCompare(). A reimplementation may use different values and a different comparison function. Here is a reimplementation that uses plain Unicode comparison:
.PP
.nf
.br
    int MyListViewItem::compare( QListViewItem *i, int col,
.br
                                 bool ascending ) const
.br
    {
.br
        return key( col, ascending ).compare( i->key( col, ascending) );
.br
    }
.br
.fi
We don't recommend using \fIascending\fR so your code can safely ignore it.
.PP
See also key(), QString::localeAwareCompare(), and QString::compare().
.SH "int QListViewItem::depth () const"
Returns the depth of this item.
.PP
Example: dirview/dirview.cpp.
.SH "bool QListViewItem::dragEnabled () const"
Returns TRUE if this item can be dragged; otherwise returns FALSE.
.PP
See also setDragEnabled().
.SH "void QListViewItem::dragEntered ()\fC [virtual protected]\fR"
This method is called when a drag entered the item's bounding rectangle.
.PP
The default implementation does nothing, subclasses may need to reimplement this method.
.SH "void QListViewItem::dragLeft ()\fC [virtual protected]\fR"
This method is called when a drag left the item's bounding rectangle.
.PP
The default implementation does nothing, subclasses may need to reimplement this method.
.SH "bool QListViewItem::dropEnabled () const"
Returns TRUE if this item accepts drops; otherwise returns FALSE.
.PP
See also setDropEnabled() and acceptDrop().
.SH "void QListViewItem::dropped ( QDropEvent * e )\fC [virtual protected]\fR"
This method is called when something was dropped on the item. \fIe\fR contains all the information about the drop.
.PP
The default implementation does nothing, subclasses may need to reimplement this method.
.SH "void QListViewItem::enforceSortOrder () const\fC [virtual protected]\fR"
Makes sure that this object's children are sorted appropriately.
.PP
This works only if every item from the root item down to this item is already sorted.
.PP
See also sortChildItems().
.SH "QListViewItem * QListViewItem::firstChild () const"
Returns the first (top) child of this item, or 0 if this item has no children.
.PP
Note that the children are not guaranteed to be sorted properly. QListView and QListViewItem try to postpone or avoid sorting to the greatest degree possible, in order to keep the user interface snappy.
.PP
See also nextSibling().
.PP
Example: checklists/checklists.cpp.
.SH "int QListViewItem::height () const"
Returns the height of this item in pixels. This does not include the height of any children; totalHeight() returns that.
.SH "void QListViewItem::insertItem ( QListViewItem * newChild )\fC [virtual]\fR"
Inserts \fInewChild\fR into this list view item's list of children. You should not need to call this function; it is called automatically by the constructor of \fInewChild\fR.
.SH "void QListViewItem::invalidateHeight ()\fC [virtual]\fR"
Invalidates the cached total height of this item, including all open children.
.PP
See also setHeight(), height(), and totalHeight().
.SH "bool QListViewItem::isEnabled () const"
Returns TRUE if this item is enabled; otherwise returns FALSE.
.PP
See also setEnabled().
.SH "bool QListViewItem::isExpandable () const"
Returns TRUE if this item is expandable even when it has no children; otherwise returns FALSE.
.SH "bool QListViewItem::isOpen () const"
Returns TRUE if this list view item has children \fIand\fR they are not explicitly hidden; otherwise returns FALSE.
.PP
See also setOpen().
.SH "bool QListViewItem::isSelectable () const"
Returns TRUE if the item is selectable (as it is by default); otherwise returns FALSE
.PP
See also setSelectable().
.SH "bool QListViewItem::isSelected () const"
Returns TRUE if this item is selected; otherwise returns FALSE.
.PP
See also setSelected(), QListView::setSelected(), and QListView::selectionChanged().
.PP
Example: listviews/listviews.cpp.
.SH "bool QListViewItem::isVisible () const"
Returns TRUE if the item is visible; otherwise returns FALSE.
.PP
See also setVisible().
.SH "QListViewItem * QListViewItem::itemAbove ()"
Returns a pointer to the item immediately above this item on the screen. This is usually the item's closest older sibling, but it may also be its parent or its next older sibling's youngest child, or something else if anyoftheabove->height() returns 0. Returns 0 if there is no item immediately above this item.
.PP
This function assumes that all parents of this item are open (i.e. that this item is visible, or can be made visible by scrolling).
.PP
See also itemBelow() and QListView::itemRect().
.SH "QListViewItem * QListViewItem::itemBelow ()"
Returns a pointer to the item immediately below this item on the screen. This is usually the item's eldest child, but it may also be its next younger sibling, its parent's next younger sibling, grandparent's, etc., or something else if anyoftheabove->height() returns 0. Returns 0 if there is no item immediately below this item.