Detailed Description
The QListViewItem class implements a list view item.
A list view item is a multi-column object capable of displaying
itself in a QListView. Its design has the following main goals:
- Work quickly and well for large sets of data.
- Be easy to use in the simple case.
The easiest way to use QListViewItem is to construct one with a
few constant strings.
(void) new QListViewItem( parent, "first column", "second column" );
Here we create a new list view item with two literal strings. The
item becomes a child of parent. We've discarded the pointer to
the item since we can still access it via its parent. This
object will be deleted when parent is deleted, as usual for
QObjects.
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.
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().
QCheckListItems are list view items that have a checkbox or
radio button and can be used in place of QListViewItems.
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).
You can also traverse it as a tree by using parent(),
firstChild(), and nextSibling().
Example:
QListViewItem * myChild = myItem->firstChild();
while( myChild ) {
doSomething( myChild );
myChild = myChild->nextSibling();
}
There is also an interator class to traverse a tree of list view
items. To iterate over all items of a list view, do the following:
QListViewItemIterator it( listview );
for ( ; it.current(); ++it )
doSomething( it.current() ); // it.current() is a QListViewItem*
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.
Many programs will need to reimplement QListViewItem. The most
commonly reimplemented functions are:
| 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()
| Is called whenever the user clicks on the item or presses
space when the item is the currently highlighted item.
|
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.
See also QCheckListItem, QListView and Advanced Widgets.
Member Function Documentation
QListViewItem::QListViewItem ( QListView * parent )
Constructs a new top-level list view item in the QListView parent.
QListViewItem::QListViewItem ( QListViewItem * parent )
Constructs a new list view item that is a child of parent and
first in the parent's list of children.
QListViewItem::QListViewItem ( QListView * parent, QListViewItem * after )
Constructs an empty list view item that is a child of parent
and is after after in the parent's list of children. Since parent is a QListView the item will be a top-level item.
Constructs an empty list view item that is a child of parent
and is after after in the parent's list of children.
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 parent, with up to eight constant strings label1, label2, label3, label4, label5, label6, label7 and label8
defining its column contents.
See also setText().
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 parent with optional constant strings label1, label2, label3, label4, label5, label6, label7 and label8
as column contents.
See also setText().
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 parent that is
included after item after and can contain up to eight column
texts label1, label2, label3, label4, label5, label6, label7 andlabel8.
Note that the order is changed according to QListViewItem::key()
unless the list view's sorting is disabled using
QListView::setSorting( -1 ).
See also setText().
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 parent. It is inserted after item after and may contain up to
eight strings label1, label2, label3, label4, label5, label6, label7 and label8 as column entries.
Note that the order is changed according to QListViewItem::key()
unless the list view's sorting is disabled using
QListView::setSorting( -1 ).
See also setText().
QListViewItem::~QListViewItem () [virtual]
Destroys the item, deleting all its children and freeing up all
allocated resources.
bool QListViewItem::acceptDrop ( const QMimeSource * mime ) const [virtual]
Returns TRUE if the item can accept drops of type QMimeSource mime; otherwise returns FALSE.
The default implementation does nothing and returns FALSE. A
subclass must reimplement this to accept drops.
void QListViewItem::activate () [virtual protected]
This virtual function is called whenever the user clicks on this
item or presses Space on it.
See also activatedPos().
Reimplemented in QCheckListItem.
bool QListViewItem::activatedPos ( QPoint & pos ) [protected]
When called from a reimplementation of activate(), this function
gives information on how the item was activated. Otherwise the
behavior is undefined.
If activate() was caused by a mouse press, the function sets pos to where the user clicked and returns TRUE; otherwise it
returns FALSE and does not change pos.
pos is relative to the top-left corner of this item.
Warning: We recommend that you ignore this function; it is
scheduled to become obsolete.
See also activate().
void QListViewItem::cancelRename ( int col ) [virtual protected]
This function is called if the user cancels in-place renaming of
this item in column col (e.g. by pressing Esc).
See also okRename().
int QListViewItem::childCount () const
Returns how many children this item has.
int QListViewItem::compare ( QListViewItem * i, int col, bool ascending ) const [virtual]
Compares this listview item to i using the column col in ascending order. Returns -1 if this item is less than i, 0 if
they are equal and 1 if this item is greater than i.
This function is used for sorting.
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:
int MyListViewItem::compare( QListViewItem *i, int col,
bool ascending ) const
{
return key( col, ascending ).compare( i->key( col, ascending) );
}
We don't recommend using ascending so your code can safely
ignore it.
See also key(), QString::localeAwareCompare() and QString::compare().
Example: network/ftpclient/ftpview.cpp.
int QListViewItem::depth () const
Returns the depth of this item.
Example: dirview/dirview.cpp.
bool QListViewItem::dragEnabled () const
Returns TRUE if this item can be dragged; otherwise returns FALSE.
See also setDragEnabled().
void QListViewItem::dragEntered () [virtual protected]
This method is called when a drag entered the item's bounding
rectangle.
The default implementation does nothing, subclasses may need to
reimplement this method.
void QListViewItem::dragLeft () [virtual protected]
This method is called when a drag left the item's bounding
rectangle.
The default implementation does nothing, subclasses may need to
reimplement this method.
bool QListViewItem::dropEnabled () const
Returns TRUE if this item accepts drops; otherwise returns FALSE.
See also setDropEnabled() and acceptDrop().
void QListViewItem::dropped ( QDropEvent * e ) [virtual protected]
This method is called when something was dropped on the item. e
contains all the information about the drop.
The default implementation does nothing, subclasses may need to
reimplement this method.
void QListViewItem::enforceSortOrder () const [virtual protected]
Makes sure that this object's children are sorted appropriately.
This works only if every item from the root item down to this item
is already sorted.
See also sortChildItems().
QListViewItem * QListViewItem::firstChild () const
Returns the first (top) child of this item, or 0 if this item has
no children.
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.
See also nextSibling().
Example: checklists/checklists.cpp.
int QListViewItem::height () const
Returns the height of this item in pixels. This does not include
the height of any children; totalHeight() returns that.
void QListViewItem::insertItem ( QListViewItem * newChild ) [virtual]
Inserts newChild 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 newChild.
void QListViewItem::invalidateHeight () [virtual]
Invalidates the cached total height of this item, including all
open children.
See also setHeight(), height() and totalHeight().
bool QListViewItem::isEnabled () const
Returns TRUE if this item is enabled; otherwise returns FALSE.
See also setEnabled().
bool QListViewItem::isExpandable () const
Returns TRUE if this item is expandable even when it has no
children; otherwise returns FALSE.
bool QListViewItem::isOpen () const
Returns TRUE if this list view item has children and they are
not explicitly hidden; otherwise returns FALSE.
See also setOpen().
bool QListViewItem::isSelectable () const
Returns TRUE if the item is selectable (as it is by default);
otherwise returns FALSE
See also setSelectable().
bool QListViewItem::isSelected () const
Returns TRUE if this item is selected; otherwise returns FALSE.
See also setSelected(), QListView::setSelected() and QListView::selectionChanged().
Example: listviews/listviews.cpp.
bool QListViewItem::isVisible () const
Returns TRUE if the item is visible; otherwise returns FALSE.
See also setVisible().
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.
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).
See also itemBelow() and QListView::itemRect().
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.
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).
See also itemAbove() and QListView::itemRect().
Example: dirview/dirview.cpp.
int QListViewItem::itemPos () const
Returns the y coordinate of this item in the list view's
coordinate system. This function is normally much slower than
QListView::itemAt(), but it works for all items whereas
QListView::itemAt() normally only works for items on the screen.
See also QListView::itemAt(), QListView::itemRect() and QListView::itemPos().
QString QListViewItem::key ( int column, bool ascending ) const [virtual]
Returns a key that can be used for sorting by column column.
The default implementation returns text(). Derived classes may
also incorporate the order indicated by ascending into this
key, although this is not recommended.
If you want to sort on non-alphabetical data, e.g. dates, numbers,
etc., reimplement compare().
See also compare() and sortChildItems().
QListView * QListViewItem::listView () const
Returns a pointer to the list view containing this item.
void QListViewItem::moveItem ( QListViewItem * after )
Moves this item after the item after. This means it will get
the sibling exactly after the item after. To move an item in
the hierarchy, use takeItem() and insertItem().
bool QListViewItem::multiLinesEnabled () const
Returns TRUE if the item can display multiple lines of text in its
columns; otherwise returns FALSE.
QListViewItem * QListViewItem::nextSibling () const
Returns the sibling item below this item, or 0 if there is no
sibling item after this item.
Note that the siblings 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.
See also firstChild().
Example: xml/tagreader-with-features/structureparser.cpp.
void QListViewItem::okRename ( int col ) [virtual protected]
This function is called if the user presses Enter during in-place
renaming of the item in column col.
See also cancelRename().
void QListViewItem::paintBranches ( QPainter * p, const QColorGroup & cg, int w, int y, int h ) [virtual]
Paints a set of branches from this item to (some of) its children.
Painter p is set up with clipping and translation so that you
can draw only in the rectangle you need to; cg is the color
group to use; the update rectangle is at (0, 0) and has size width
w by height h. The top of the rectangle you own is at y
(which is never greater than 0 but can be outside the window
system's allowed coordinate range).
The update rectangle is in an undefined state when this function
is called; this function must draw on all of the pixels.
See also paintCell() and QListView::drawContentsOffset().
void QListViewItem::paintCell ( QPainter * p, const QColorGroup & cg, int column, int width, int align ) [virtual]
This virtual function paints the contents of one column of an item
and aligns it as described by align.
p is a QPainter open on the relevant paint device. p is
translated so (0, 0) is the top-left pixel in the cell and width-1, height()-1 is the bottom-right pixel in the cell. The
other properties of p (pen, brush, etc) are undefined. cg is
the color group to use. column is the logical column number
within the item that is to be painted; 0 is the column which may
contain a tree.
This function may use QListView::itemMargin() for readability
spacing on the left and right sides of data such as text, and
should honor isSelected() and QListView::allColumnsShowFocus().
If you reimplement this function, you should also reimplement
width().
The rectangle to be painted is in an undefined state when this
function is called, so you must draw on all the pixels. The
painter p has the right font on entry.
See also paintBranches() and QListView::drawContentsOffset().
Example: listviews/listviews.cpp.
Reimplemented in QCheckListItem.
void QListViewItem::paintFocus ( QPainter * p, const QColorGroup & cg, const QRect & r ) [virtual]
Paints a focus indicator on the rectangle r using painter p
and colors cg.
p is already clipped.
See also paintCell(), paintBranches() and QListView::allColumnsShowFocus.
Reimplemented in QCheckListItem.
QListViewItem * QListViewItem::parent () const
Returns the parent of this item, or 0 if this item has no parent.
See also firstChild() and nextSibling().
Example: dirview/dirview.cpp.
const QPixmap * QListViewItem::pixmap ( int column ) const [virtual]
Returns the pixmap for column, or 0 if there is no pixmap for
column.
See also setText() and setPixmap().
Examples: dirview/dirview.cpp and network/ftpclient/ftpview.cpp.
void QListViewItem::removeItem ( QListViewItem * item ) [virtual]
This function is obsolete. It is provided to keep old source working. We strongly advise against using it in new code.
This function has been renamed takeItem().
bool QListViewItem::renameEnabled ( int col ) const
Returns TRUE if this item can be in-place renamed in column col; otherwise returns FALSE.
void QListViewItem::repaint () const
Repaints this item on the screen if it is currently visible.
Example: addressbook/centralwidget.cpp.
int QListViewItem::rtti () const [virtual]
Returns 0.
Make your derived classes return their own values for rtti(), and
you can distinguish between listview items. You should use values
greater than 1000, preferably a large random number, to allow for
extensions to this class.
Reimplemented in QCheckListItem.
void QListViewItem::setDragEnabled ( bool allow ) [virtual]
If allow is TRUE, the listview starts a drag (see
QListView::dragObject()) when the user presses and moves the mouse
on this item.
void QListViewItem::setDropEnabled ( bool allow ) [virtual]
If allow is TRUE, the listview accepts drops onto the item;
otherwise drops are not allowed.
void QListViewItem::setEnabled ( bool b ) [virtual]
If b is TRUE the item is enabled; otherwise it is disabled.
Disabled items are drawn differently (e.g. grayed-out) and are not
accessible by the user.
void QListViewItem::setExpandable ( bool enable ) [virtual]
Sets this item to be expandable even if it has no children if enable is TRUE, and to be expandable only if it has children if enable is FALSE (the default).
The dirview example uses this in the canonical fashion. It checks
whether the directory is empty in setup() and calls
setExpandable(TRUE) if not; in setOpen() it reads the contents of
the directory and inserts items accordingly. This strategy means
that dirview can display the entire file system without reading
very much at startup.
Note that root items are not expandable by the user unless
QListView::setRootIsDecorated() is set to TRUE.
See also setSelectable().
void QListViewItem::setHeight ( int height ) [virtual protected]
Sets this item's height to height pixels. This implicitly
changes totalHeight(), too.
Note that a font change causes this height to be overwritten
unless you reimplement setup().
For best results in Windows style we suggest using an even number
of pixels.
See also height(), totalHeight() and isOpen().
void QListViewItem::setMultiLinesEnabled ( bool b ) [virtual]
If b is TRUE each of the item's columns may contain multiple
lines of text; otherwise they may only contain a single line.
void QListViewItem::setOpen ( bool o ) [virtual]
Opens or closes an item, i.e. shows or hides an item's children.
If o is TRUE all child items are shown initially. The user can
hide them by clicking the - icon to the left of the item.
If o is FALSE, the children of this item are initially hidden.
The user can show them by clicking the + icon to the left
of the item.
See also height(), totalHeight() and isOpen().
Examples: checklists/checklists.cpp, dirview/dirview.cpp, dirview/main.cpp, fileiconview/mainwindow.cpp and xml/tagreader-with-features/structureparser.cpp.
void QListViewItem::setPixmap ( int column, const QPixmap & pm ) [virtual]
Sets the pixmap in column column to pm, if pm is non-null
and different from the current pixmap, and if column is
non-negative.
See also pixmap() and setText().
Example: dirview/dirview.cpp.
void QListViewItem::setRenameEnabled ( int col, bool b ) [virtual]
If b is TRUE, this item can be in-place renamed in the column
col by the user; otherwise it cannot be renamed in-place.
void QListViewItem::setSelectable ( bool enable ) [virtual]
Sets this items to be selectable if enable is TRUE (the
default) or not to be selectable if enable is FALSE.
The user is not able to select a non-selectable item using either
the keyboard or mouse. The application programmer still can, e.g.
using setSelected().
See also isSelectable().
Example: network/ftpclient/ftpview.cpp.
void QListViewItem::setSelected ( bool s ) [virtual]
If s is TRUE this item is selected; otherwise it is deselected.
This function does not maintain any invariants or repaint anything
-- QListView::setSelected() does that.
See also height() and totalHeight().
Example: addressbook/centralwidget.cpp.
void QListViewItem::setText ( int column, const QString & text ) [virtual]
Sets the text in column column to text, if column is a
valid column number and text is different from the existing
text.
If text() has been reimplemented, this function may be a no-op.
See also text() and key().
Examples: addressbook/centralwidget.cpp and xml/outliner/outlinetree.cpp.
void QListViewItem::setVisible ( bool b )
If b is TRUE, the item is made visible; otherwise it is hidden.
If the item is not visible, itemAbove() and itemBelow() will never
return this item, although you still can reach it by using e.g.
QListViewItemIterator.
void QListViewItem::setup () [virtual]
This virtual function is called before the first time QListView
needs to know the height or any other graphical attribute of this
object, and whenever the font, GUI style, or colors of the list
view change.
The default calls widthChanged() and sets the item's height to the
height of a single line of text in the list view's font. (If you
use icons, multi-line text, etc., you will probably need to call
setHeight() yourself or reimplement it.)
Example: dirview/dirview.cpp.
void QListViewItem::sort () [virtual]
(Re)sorts all child items of this item using the last sorting
configuration (sort column and direction).
See also enforceSortOrder().
void QListViewItem::sortChildItems ( int column, bool ascending ) [virtual]
Sorts this item's children using column column. This is done in
ascending order if ascending is TRUE and in descending order if
ascending is FALSE.
Asks some of the children to sort their children. (QListView and
QListViewItem ensure that all on-screen objects are properly
sorted but may avoid or defer sorting other objects in order to be
more responsive.)
See also key() and compare().
void QListViewItem::startRename ( int col ) [virtual]
If in-place renaming of this item is enabled (see
renameEnabled()), this function starts renaming the item in cloumn
col, by creating and initializing an edit box.
void QListViewItem::takeItem ( QListViewItem * item ) [virtual]
Removes item from this object's list of children and causes an
update of the screen display. The item is not deleted. You should
not normally need to call this function because
QListViewItem::~QListViewItem() calls it.
The normal way to delete an item is to use delete.
If you need to move an item from one place in the hierarchy to
another you can use takeItem() to remove the item from the list
view and then insertItem() to put the item back in its new
position.
Warning: This function leaves item and its children in a state
where most member functions are unsafe. Only a few functions work
correctly on an item in this state, most notably insertItem(). The
functions that work on detached items are explicitly documented as
such.
See also QListViewItem::insertItem().
QString QListViewItem::text ( int column ) const [virtual]
Returns the text in column column, or QString::null if there is
no text in that column.
See also key() and paintCell().
Examples: addressbook/centralwidget.cpp, dirview/dirview.cpp and network/ftpclient/ftpview.cpp.
int QListViewItem::totalHeight () const
Returns the total height of this object, including any visible
children. This height is recomputed lazily and cached for as long
as possible.
Functions which can affect the total height are, setHeight() which
is used to set an item's height, setOpen() to show or hide an
item's children, and invalidateHeight() to invalidate the cached
height.
See also height().
int QListViewItem::width ( const QFontMetrics & fm, const QListView * lv, int c ) const [virtual]
Returns the number of pixels of width required to draw column c
of list view lv, using the metrics fm without cropping. The
list view containing this item may use this information depending
on the QListView::WidthMode settings for the column.
The default implementation returns the width of the bounding
rectangle of the text of column c.
See also listView(), widthChanged(), QListView::setColumnWidthMode() and QListView::itemMargin.
void QListViewItem::widthChanged ( int c = -1 ) const
Call this function when the value of width() may have changed for
column c. Normally, you should call this if text(c) changes.
Passing -1 for c indicates that all columns may have changed.
For efficiency, you should do this if more than one call to
widthChanged() is required.
See also width().
This file is part of the Qt toolkit.
Copyright © 1995-2002
Trolltech. All Rights Reserved.
