qlistviewitem.3qt

qt专门用于嵌入式的图形开发GUI

A list view item is a multi-column object capable of displaying itself in a QListView.
.PP
The easiest way to use QListViewItem is to construct one with a few constant strings, and either a QListView or another QListViewItem as parent.
.PP
.nf
.br
        (void) new QListViewItem( listView, "Column 1", "Column 2" );
.br
        (void) new QListViewItem( listView->firstChild(), "A", "B", "C" );
.br
.fi
We've discarded the pointers to the items since we can still access them via their parent \fIlistView\fR. By default, QListView sorts its items; this can be switched off with QListView::setSorting(-1).
.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 its sub-items. 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
If you call \fCdelete\fR on a list view item, it will be deleted as expected, and as usual for QObjects, if it has any child items (to any depth), all these will be deleted too.
.PP
QCheckListItems are list view items that have a checkbox or radio button and can be used in place of plain 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 them are actually visible at the moment).
.PP
Here's how to traverse all of an item's children (but not its children's children, etc.): Example:
.PP
.nf
.br
        QListViewItem * myChild = myItem->firstChild();
.br
        while( myChild ) {
.br
            doSomething( myChild );
.br
            myChild = myChild->nextSibling();
.br
        }
.br
.fi
.PP
If you want to iterate over every item, to any level of depth use an iterator. To iterate over the entire tree, initialize the iterator with the list view itself; to iterate starting from a particular item, initialize the iterator with the item:
.PP
.nf
.br
        QListViewItemIterator it( listview );
.br
        while ( it.current() ) {
.br
            QListViewItem *item = it.current();
.br
            doSomething( item );
.br
            ++it;
.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() Used for sorting. The default key() simply calls text(), but judicious use of key() can give you fine control over sorting; for example, QFileDialog reimplements key() to sort by date. setup() Called before showing the item and whenever the list view's 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 item \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 item \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 columns' 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 up to eight constant strings, \fIlabel1\fR, \fIlabel2\fR, \fIlabel3\fR, \fIlabel4\fR, \fIlabel5\fR, \fIlabel6\fR, \fIlabel7\fR and \fIlabel8\fR as columns' 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 that has 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 presses the mouse 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. The count only includes the item's immediate children.
.SH "int QListViewItem::compare ( QListViewItem * i, int col, bool ascending ) const\fC [virtual]\fR"
Compares this list view item to \fIi\fR using the column \fIcol\fR in \fIascending\fR order. Returns < 0 if this item is less than \fIi\fR, 0 if they are equal and > 0 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 can 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 function is called when a drag enters the item's bounding rectangle.
.PP
The default implementation does nothing, subclasses may need to reimplement this function.
.SH "void QListViewItem::dragLeft ()\fC [virtual protected]\fR"
This function is called when a drag leaves the item's bounding rectangle.
.PP
The default implementation does nothing, subclasses may need to reimplement this function.
.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 function 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 function.
.SH "void QListViewItem::enforceSortOrder () const\fC [virtual protected]\fR"
Makes sure that this object's children are sorted appropriately.
.PP
This only works 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() and sortChildItems().
.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.
.PP
\fBWarning:\fR If you are using \fCSingle\fR selection mode, then you should only insert unselected items.
.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
This function might be relatively slow because of the tree traversions needed to find the correct item.
.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.
.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 itemAbove() and QListView::itemRect().
.PP