QListViewItem(3qt)QListViewItem(3qt)NAMEQListViewItem - Implements a list view item
#include <qlistview.h>
Inherits Qt.
Inherited by QCheckListItem.
Public Members
QListViewItem ( QListView * parent )
QListViewItem ( QListViewItem * parent )
QListViewItem ( QListView * parent, QListViewItem * after
)
QListViewItem ( QListViewItem * parent, QListViewItem *
after )
QListViewItem ( QListView * parent, QString, QString =
QString::null, QString = QString::null, QString =
QString::null, QString = QString::null, QString =
QString::null, QString = QString::null, QString =
QString::null )
QListViewItem ( QListViewItem * parent, QString, QString =
QString::null, QString = QString::null, QString =
QString::null, QString = QString::null, QString =
QString::null, QString = QString::null, QString =
QString::null )
QListViewItem ( QListView * parent, QListViewItem * after,
QString, QString = QString::null, QString =
QString::null, QString = QString::null, QString =
QString::null, QString = QString::null, QString =
QString::null, QString = QString::null )
QListViewItem ( QListViewItem * parent, QListViewItem *
after, QString, QString = QString::null, QString =
QString::null, QString = QString::null, QString =
QString::null, QString = QString::null, QString =
QString::null, QString = QString::null )
virtual ~QListViewItem ()
virtual void insertItem ( QListViewItem * )
virtual void takeItem ( QListViewItem * )
virtual void removeItem ( QListViewItem * ) (obsolete)
int height () const
virtual void invalidateHeight ()
int totalHeight () const
virtual int width ( const QFontMetrics &, const QListView
*, int column ) const
void widthChanged ( int column=-1 ) const
int depth () const
virtual void setText ( int, const QString & )
virtual QString text ( int ) const
virtual void setPixmap ( int, const QPixmap & )
virtual const QPixmap* pixmap ( int ) const
virtual QString key ( int, bool ) const
virtual void sortChildItems ( int, bool )
Trolltech AS 13 June 2001 1
QListViewItem(3qt)QListViewItem(3qt)
int childCount () const
bool isOpen () const
virtual void setOpen ( bool )
virtual void setup ()
virtual void setSelected ( bool )
bool isSelected () const
virtual void paintCell ( QPainter *, const QColorGroup &
cg, int column, int width, int alignment )
virtual void paintBranches ( QPainter * p, const
QColorGroup & cg, int w, int y, int h, GUIStyle s )
virtual void paintFocus ( QPainter *, const QColorGroup &
cg, const QRect & r )
QListViewItem* firstChild () const
QListViewItem* nextSibling () const
QListViewItem* parent () const
QListViewItem* itemAbove ()
QListViewItem* itemBelow ()
int itemPos () const
QListView* listView () const
virtual void setSelectable ( bool enable )
bool isSelectable () const
virtual void setExpandable ( bool )
bool isExpandable () const
void repaint () const
void sort ()
void moveItem ( QListViewItem * after )
Protected Members
virtual void enforceSortOrder () const
virtual void setHeight ( int )
virtual void activate ()
bool activatedPos ( QPoint & )
DESCRIPTION
The QListViewItem class implements a list view item.
A list view item is a multi-column object capable of
displaying itself. 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 simplest way to use QListViewItem is to construct one
with a few constant strings. This creates an item which is
a child of parent, with two fixed-content strings, and
discards the pointer to it:
(void) new QListViewItem( parent, "first column", "second column" );
This object will be deleted when parent is deleted, as for
QObjects.
Trolltech AS 13 June 2001 2
QListViewItem(3qt)QListViewItem(3qt)
The parent is either another QListViewItem or a QListView.
If the parent is a QListView, this item is a top-level
item within that QListView. If the parent is another
QListViewItem, this item becomes a child of the parent
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(), change its height using setHeight(), and
do much tree traversal. The set* functions in QListView
also affect QListViewItem, of course.
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, using parent(),
firstChild() and nextSibling(). This code does something
to each of an item's children:
QListViewItem * myChild = myItem->firstChild();
while( myChild ) {
doSomething( myChild );
myChild = myChild->nextSibling();
}
Also there is now an iterator class to traverse a tree of
list view items. To iterate over all items of a list view,
do:
QListViewItemIterator it( listview );
for ( ; it.current(); ++it )
do_something_with_the_item( it.current() );
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, and 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:
text() returns the text in a column. Many subclasses will
compute that 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
e.g. date (as QFileDialog does).
Trolltech AS 13 June 2001 3
QListViewItem(3qt)QListViewItem(3qt)setup() is called before showing the item, and whenever
e.g. the font changes.
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 precisely this technique to start up quickly:
The files and subdirectories in a directory aren't entered
into the tree until they need to.
MEMBER FUNCTION DOCUMENTATIONQListViewItem::QListViewItem ( QListView * parent )
Constructs a new top-level list view item in the QListView
parent.
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 list view item in the QListView parent,
parent, with at most 8 constant strings as contents.
(void)new QListViewItem( lv, "/", "Root directory" );
See also setText().
QListViewItem::QListViewItem ( QListView * parent, QListViewItem
* after )
Constructs an empty list view item which is a child of
parent and is after after in the parent's list of
children.
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,
after item after, with at most 8 constant strings as
contents.
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().
Trolltech AS 13 June 2001 4
QListViewItem(3qt)QListViewItem(3qt)QListViewItem::QListViewItem ( QListViewItem * parent )
Constructs a new list view item which is a child of parent
and first in the parent's list of children.
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 that's a child of the
QListViewItem parent, with at most 8 constant strings as
contents. Possible example in a threaded news or e-mail
reader:
(void)new QListViewItem( parentMessage, author, subject );
See also setText().
QListViewItem::QListViewItem ( QListViewItem * parent,
QListViewItem * after )
Constructs an empty list view item which is a child of
parent and is after after in the parent's list of
children.
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 that's a child of the
QListViewItem parent, after item after, with at most 8
constant strings as contents.
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, freeing up
all allocated resources.
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.
Trolltech AS 13 June 2001 5
QListViewItem(3qt)QListViewItem(3qt)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 behaviour 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.
We recommend not using this function; it will most likely
be obsoleted at the first opportunity.
See also activate().
int QListViewItem::childCount () const
Returns the current number of children of this item.
int QListViewItem::depth () const
Returns the depth of this item.
void QListViewItem::enforceSortOrder () const [virtual protected]
Makes sure that this object's children are sorted
appropriately.
This only works if every item in the chain from the root
item to this item is sorted appropriately.
See also sortChildItems().
QListViewItem* QListViewItem::firstChild () const
Returns a pointer to the first (top) child of this item,
or a null pointer 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().
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 its list of children. You should not
need to call this function; it is called automatically by
the constructor of newChild.
This function works even if this item is not contained in
Trolltech AS 13 June 2001 6
QListViewItem(3qt)QListViewItem(3qt)
a list view.
void QListViewItem::invalidateHeight () [virtual]
Invalidates the cached total height of this item including
all open children.
This function works even if this item is not contained in
a list view.
See also setHeight(), height() and totalHeight().
bool QListViewItem::isExpandable () const
Returns TRUE if this item is expandable even when it has
no children.
bool QListViewItem::isOpen () const
Returns TRUE if this list view item has children and they
are potentially visible, or FALSE if the item has no
children or they are hidden.
See also setOpen().
bool QListViewItem::isSelectable () const
Returns TRUE if the item is selectable (as it is by
default) and FALSE if it isn't.
See also setSelectable().
bool QListViewItem::isSelected () const
Returns TRUE if this item is selected, or FALSE if it is
not.
See also setSelected(), QListView::setSelected() and
QListView::selectionChanged().
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 may also be its parent or its next older
sibling's youngest child, or something else if
anyoftheabove->height() returns 0. Returns a null pointer
if there is no item immediately above this item.
This function assumes that all parents of this item are
open (ie. 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 may also be its next younger sibling, its parent's
next younger sibling, grandparent's etc., or something
Trolltech AS 13 June 2001 7
QListViewItem(3qt)QListViewItem(3qt)
else if anyoftheabove->height() returns 0. Returns a null
pointer if there is no item immediately above this item.
This function assumes that all parents of this item are
open (ie. that this item is visible, or can be made
visible by scrolling).
See also itemAbove() and QListView::itemRect().
int QListViewItem::itemPos () const
Returns the y coordinate of item in the list view's
coordinate system. This functions is normally much slower
than QListView::itemAt(), but it works for all items,
while QListView::itemAt() normally works only 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.
You can use this function to sort by non-alphabetic data.
This code excerpt sort by file modification date, for
example
if ( column == 3 ) {
QDateTime epoch( QDate( 1980, 1, 1 ) );
tmpString.sprintf( "%08d", epoch.secsTo( myFile.lastModified() ) );
} else {
// ....
}
return tmpString;
See also sortChildItems().
QListView * QListViewItem::listView () const
Returns a pointer to the listview 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().
QListViewItem* QListViewItem::nextSibling () const
Returns a pointer to the sibling item below this item, or
a null pointer if there is no sibling item after this
item.
Note that the siblings are not guaranteed to be sorted
Trolltech AS 13 June 2001 8
QListViewItem(3qt)QListViewItem(3qt)
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().
void QListViewItem::paintBranches ( QPainter * p, const
QColorGroup & cg, int w, int y, int h, GUIStyle s )
[virtual]
Paints a set of branches from this item to (some of) its
children.
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
w, 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().
Reimplemented in QCheckListItem.
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
one item.
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
information 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().
Trolltech AS 13 June 2001 9
QListViewItem(3qt)QListViewItem(3qt)
Reimplemented in QCheckListItem.
void QListViewItem::paintFocus ( QPainter * p, const QColorGroup
& cg, const QRect & r ) [virtual]
Paints a focus indication on the rectangle r using painter
p and colors cg.
p is already clipped.
See also paintCell(), paintBranches() and
QListView::setAllColumnsShowFocus().
QListViewItem* QListViewItem::parent () const
Returns a pointer to the parent of this item, or a null
pointer if this item has no parent.
See also firstChild() and nextSibling().
const QPixmap * QListViewItem::pixmap ( int column ) const
[virtual]
Returns a pointer to the pixmap for column, or a null
pointer if there is no pixmap for column.
This function works even if this item is not contained in
a list view, but reimplementations of it are not required
to work properly in that case.
See also setText() and setPixmap().
void QListViewItem::removeItem ( QListViewItem * item ) [virtual]
This function is obsolete. It is provided to keep old
source working, and will probably be removed in a future
version of Qt. We strongly advise against using it in new
code.
This function has been renamed takeItem().
void QListViewItem::repaint () const
Repaints this item on the screen, if it is currently
visible.
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, and 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 start-up.
Note that root items are not expandable by the user unless
Trolltech AS 13 June 2001 10
QListViewItem(3qt)QListViewItem(3qt)QListView::setRootIsDecorated() is set to TRUE.
See also setSelectable().
void QListViewItem::setHeight ( int height ) [virtual protected]
Sets this item's own height to height pixels. This
implicitly changes totalHeight() too.
Note that e.g. 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::setOpen ( bool o ) [virtual]
Sets this item to be open (its children are visible) if o
is TRUE, and to be closed (its children are not visible)
if o is FALSE.
Also does some bookkeeping.
See also height() and totalHeight().
Examples: dirview/main.cpp
void QListViewItem::setPixmap ( int column, const QPixmap & pm )
[virtual]
Sets the pixmap in column column to pm, if pm is non-null
and column is non-negative.
See also pixmap() and setText().
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, of course.
See also isSelectable().
void QListViewItem::setSelected ( bool s ) [virtual]
Sets this item to be selected s is TRUE, and to not be
selected if o is FALSE.
This function does not maintain any invariants or repaint
anything - QListView::setSelected() does that.
See also height() and totalHeight().
Trolltech AS 13 June 2001 11
QListViewItem(3qt)QListViewItem(3qt)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 non-null.
If text() has been reimplemented, this function may be a
no-op.
See also text(), key() and invalidate().
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 this.).
Reimplemented in QCheckListItem.
void QListViewItem::sort ()
(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 the children of this item by the return values of
key(column, ascending), in ascending order if ascending is
TRUE and in descending order of descending 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().
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 normally not need to call this
function, as QListViewItem::~QListViewItem() calls it. The
normal way to delete an item is delete.
Warning: This function leaves item and its children in a
state where most member functions are unsafe. Only the few
functions that are explicitly documented to work in this
state may be used then.
Trolltech AS 13 June 2001 12
QListViewItem(3qt)QListViewItem(3qt)
See also QListViewItem::insertItem().
QString QListViewItem::text ( int column ) const [virtual]
Returns the text in column column, or a null string if
there is no text in that column.
This function works even if this item is not contained in
a list view, but reimplementations of it are not required
to work properly in that case.
See also key() and paintCell().
Reimplemented in QCheckListItem.
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.
setHeight() can be used to set the item's own height,
setOpen() to show or hide its 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 listview 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().
Reimplemented in QCheckListItem.
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 all columns
may have changed. For efficiency, you should do this if
more than one call to widthChanged() is required.
See also width().
SEE ALSO
http://doc.trolltech.com/qlistviewitem.html
http://www.trolltech.com/faq/tech.html
Trolltech AS 13 June 2001 13
QListViewItem(3qt)QListViewItem(3qt)COPYRIGHT
Copyright 1992-2001 Trolltech AS,
http://www.trolltech.com. See the license file included
in the distribution for a complete license statement.
AUTHOR
Generated automatically from the source code.
BUGS
If you find a bug in Qt, please report it as described in
http://doc.trolltech.com/bughowto.html. Good bug reports
make our job much simpler. Thank you.
In case of content or formattting problems with this
manual page, please report them to qt-bugs@trolltech.com.
Please include the name of the manual page
(qlistviewitem.3qt) and the Qt version (2.3.1).
Trolltech AS 13 June 2001 14
