Qt Toolkit - QListViewItem Class

# QListViewItem Class Reference

The QListViewItem class implements a list view item. More...

`#include <qlistview.h>`

Inherited by QCheckListItem.

List of all member functions.

## Public Members

- QListViewItem ( QListView * parent )
- QListViewItem ( QListViewItem * parent )
- QListViewItem ( QListView * parent, QListViewItem * after )
- QListViewItem ( QListViewItem * parent, QListViewItem * after )
- QListViewItem ( QListView * parent, const char *, const char * = 0, const char * = 0, const char * = 0, const char * = 0, const char * = 0, const char * = 0, const char * = 0 )
- QListViewItem ( QListViewItem * parent, const char *, const char * = 0, const char * = 0, const char * = 0, const char * = 0, const char * = 0, const char * = 0, const char * = 0 )
- QListViewItem ( QListView * parent, QListViewItem * after, const char *, const char * = 0, const char * = 0, const char * = 0, const char * = 0, const char * = 0, const char * = 0, const char * = 0 )
- QListViewItem ( QListViewItem * parent, QListViewItem * after, const char *, const char * = 0, const char * = 0, const char * = 0, const char * = 0, const char * = 0, const char * = 0, const char * = 0 )
- virtual ~QListViewItem ()
- virtual void insertItem ( QListViewItem * )
- virtual void removeItem ( QListViewItem * )
- 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 char * )
- virtual const char* text ( int ) const
- virtual void setPixmap ( int, const QPixmap & )
- virtual const QPixmap* pixmap ( int ) const
- virtual const char* key ( int, bool ) const
- virtual void sortChildItems ( int, bool )
- 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 ()
- void repaint () const

## Protected Members

- virtual void enforceSortOrder () const
- virtual void setHeight ( int )
- virtual void activate ()

## Detailed Description

The QListViewItem class implements a list view item.

A list viev 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.

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();
        }

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).
- 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() 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.

This example shows a number of root items in a QListView. These items are actually subclassed from QListViewItem: The file size, type etc. are computed on the fly.

The next example shows a fraction of the dirview example. Again, the Directory/Symbolic Link column is computed on the fly. None of the items are root items; the usr item is a child of the root and the X11 item is a child of the usr item.

Examples: dirview/dirview.cpp

## Member Function Documentation

### QListViewItem::QListViewItem ( QListView * parent )

Create a new list view item in the QListView parent and first in the parent's list of children.

### 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, const char * label1, const char * label2 = 0, const char * label3 = 0, const char * label4 = 0, const char * label5 = 0, const char * label6 = 0, const char * label7 = 0, const char * label8 = 0 )

Creates 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 ).

### QListViewItem::QListViewItem ( QListView * parent, const char * label1, const char * label2 = 0, const char * label3 = 0, const char * label4 = 0, const char * label5 = 0, const char * label6 = 0, const char * label7 = 0, const char * label8 = 0 )

Creates a new list view item in the QListView parent, parent, with at most 8 constant strings as contents.

         (void)new QListViewItem( lv, "/", "Root directory" );

### QListViewItem::QListViewItem ( QListViewItem * parent )

Create a new list view item which is a child of parent and first in the parent's list of children.

### 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, const char * label1, const char * label2 = 0, const char * label3 = 0, const char * label4 = 0, const char * label5 = 0, const char * label6 = 0, const char * label7 = 0, const char * label8 = 0 )

Creates 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 ).

### QListViewItem::QListViewItem ( QListViewItem * parent, const char * label1, const char * label2 = 0, const char * label3 = 0, const char * label4 = 0, const char * label5 = 0, const char * label6 = 0, const char * label7 = 0, const char * label8 = 0 )

Creates 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 );

### QListViewItem::~QListViewItem () `[virtual]`

Deletes this item and all children of it, 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. The default implementation does nothing.

Reimplemented in QCheckListItem.

### 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.

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. Called by the constructor of newChild.

### void QListViewItem::invalidateHeight () `[virtual]`

Invalidates the cached total height of this item including all open children.

See also: setHeight(), ownHeight() and totalHeight().

### bool QListViewItem::isExpandable ()

{ return expnadable; }

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: setSelection(), selectionChanged() and QListViewItem::setSelected().

### 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.

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 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, granparent's etc., or something else if anyoftheabove->height() returns 0.

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 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().

### const char * 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.

QListViewItem immediately copies the return value of this function, so it's safe to return a pointer to a static variable.

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.

### QListViewItem* QListViewItem::nextSibling () const

Returns a pointer to the next sibling (below this one) of 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().

### 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, 0,top is the top left corner of the update rectangle, w-1,top is the top right corner, 0,bottom-1 is the bottom left corner and the bottom right corner is left as an excercise for the reader.

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. pa 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 honour 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.

See also: paintBranches() and QListView::drawContentsOffset().

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.

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.

See also: setText() and setPixmap().

### void QListViewItem::removeItem ( QListViewItem * tbg ) `[virtual]`

Removes tbg from this object's list of children. This is normally called by tbg's destructor.

### 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 QListView::setRootIsDecorated() is set to TRUE.

See also: setSelectable().

Examples: dirview/dirview.cpp

### void QListViewItem::setHeight ( int height ) `[virtual protected]`

Sets this item's own height to height pixels. This implictly changes totalHeight() too.

Note that e.g. a font change causes this height to be overwitten unless you reimplement setup().

See also: ownHeight(), 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 bookeeping.

See also: ownHeight() and totalHeight().

Examples: dirview/dirview.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: ownHeight() and totalHeight().

### void QListViewItem::setText ( int column, const char * 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() and key().

### 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.).

Examples: dirview/dirview.cpp

Reimplemented in QCheckListItem.

### 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().

### const char * QListViewItem::text ( int column ) const `[virtual]`

Returns the text in column column, or else 0.

The returned pointer must be copied or used at once so that reimplementations of this function are at liberty to e.g. return a pointer into a static buffer.

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.

setOwnHeight() 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().

### 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().

Search the documentation, FAQ, qt-interest archive and more (uses www.troll.no):

This file is part of the Qt toolkit, copyright © 1995-99 Troll Tech, all rights reserved.

It was generated from the following files:

- qlistview.h: 1998/10/14
- qlistview.cpp: 1999/02/13