Q3ListView Class Reference
[Qt3Support module]

Detailed Description

The Q3ListView class implements a list/tree view.

It can display and control a hierarchy of multi-column items, and provides the ability to add new items at any time. The user may select one or many items (depending on the SelectionMode) and sort the list in increasing or decreasing order by any column.

The simplest pattern of use is to create a Q3ListView, add some column headers using addColumn() and create one or more Q3ListViewItem or Q3CheckListItem objects with the Q3ListView as parent.

Further nodes can be added to the list view object (the root of the tree) or as child nodes to Q3ListViewItems.

The main setup functions are:

There are several functions for mapping between items and coordinates. itemAt() returns the item at a position on-screen, itemRect() returns the rectangle an item occupies on the screen, and itemPos() returns the position of any item (whether it is on-screen or not). firstChild() returns the list view's first item (not necessarily visible on-screen).

You can iterate over visible items using Q3ListViewItem::itemBelow(); over a list view's top-level items using Q3ListViewItem::firstChild() and Q3ListViewItem::nextSibling(); or every item using a Q3ListViewItemIterator. See the Q3ListViewItem documentation for examples of traversal.

An item can be moved amongst its siblings using Q3ListViewItem::moveItem(). To move an item in the hierarchy use takeItem() and insertItem(). Item's (and all their child items) are deleted with delete; to delete all the list view's items use clear().

There are a variety of selection modes described in the Q3ListView::SelectionMode documentation. The default is Single selection, which you can change using setSelectionMode().

Because Q3ListView offers multiple selection it must display keyboard focus and selection state separately. Therefore there are functions both to set the selection state of an item (setSelected()) and to set which item displays keyboard focus (setCurrentItem()).

Q3ListView emits two groups of signals; one group signals changes in selection/focus state and one indicates selection. The first group consists of selectionChanged() (applicable to all list views), selectionChanged(Q3ListViewItem*) (applicable only to a Single selection list view), and currentChanged(Q3ListViewItem*). The second group consists of doubleClicked(Q3ListViewItem*), returnPressed(Q3ListViewItem*), rightButtonClicked(Q3ListViewItem*, const QPoint&, int), etc.

Note that changing the state of the list view in a slot connected to a list view signal may cause unexpected side effects. If you need to change the list view's state in response to a signal, use a single shot timer with a time out of 0, and connect this timer to a slot that modifies the list view's state.

In Motif style, Q3ListView deviates fairly strongly from the look and feel of the Motif hierarchical tree view. This is done mostly to provide a usable keyboard interface and to make the list view look better with a white background.

If selectionMode() is Single (the default) the user can select one item at a time, e.g. by clicking an item with the mouse, see Q3ListView::SelectionMode for details.

The list view can be navigated either using the mouse or the keyboard. Clicking a - icon closes an item (hides its children) and clicking a + icon opens an item (shows its children). The keyboard controls are these:

If the user starts typing letters with the focus in the list view an incremental search will occur. For example if the user types 'd' the current item will change to the first item that begins with the letter 'd'; if they then type 'a', the current item will change to the first item that begins with 'da', and so on. If no item begins with the letters they type the current item doesn't change.

Note that the list view's size hint is calculated taking into account the height and width to produce a nice aspect ratio. This may mean that you need to reimplement sizeHint() in some cases.

Warning: The list view assumes ownership of all list view items and will delete them when it does not need them any more.

See also Q3ListViewItem and Q3CheckListItem.

Member Type Documentation

 Q3ListViewItem *i = itemAt(p);
 if (i) {
     if (p.x() > header()->sectionPos(header()->mapToIndex(0)) +
             treeStepSize() * (i->depth() + (rootIsDecorated() ? 1 : 0)) + itemMargin() ||
             p.x() < header()->sectionPos(header()->mapToIndex(0))) {
         ; // p is not on root decoration
     else
         ; // p is on the root decoration
 }

 QRect r(listView->itemRect(item));
 r.setHeight(qMin(item->totalHeight(),
                  listView->viewport->height() - r.y()))