Q3ListViewItem Class Reference
[Qt3Support module]

Detailed Description

The Q3ListViewItem class implements a list view item.

A list view item is a multi-column object capable of displaying itself in a Q3ListView.

The easiest way to use Q3ListViewItem is to construct one with a few constant strings, and either a Q3ListView or another Q3ListViewItem as parent.

 (void) new Q3ListViewItem(listView, "Column 1", "Column 2");
 (void) new Q3ListViewItem(listView->firstChild(), "A", "B", "C");

We've discarded the pointers to the items since we can still access them via their parent listView. By default, Q3ListView sorts its items; this can be switched off with Q3ListView::setSorting(-1).

The parent must be another Q3ListViewItem or a Q3ListView. If the parent is a Q3ListView, the item becomes a top-level item within that Q3ListView. If the parent is another Q3ListViewItem, 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 its sub-items. You don't have to keep the pointer since you can get a pointer to any Q3ListViewItem in a Q3ListView using Q3ListView::selectedItem(), Q3ListView::currentItem(), Q3ListView::firstChild(), Q3ListView::lastItem() and Q3ListView::findItem().

If you call delete 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.

Q3CheckListItems are list view items that have a checkbox or radio button and can be used in place of plain Q3ListViewItems.

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

Here's how to traverse all of an item's children (but not its children's children, etc.): Example:

 Q3ListViewItem * myChild = myItem->firstChild();
 while(myChild) {
     doSomething(myChild);
     myChild = myChild->nextSibling();
 }

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 over an item's children (and children's children to any depth), initialize the iterator with the item:

 Q3ListViewItemIterator it(listview);
 while (it.current()) {
     Q3ListViewItem *item = it.current();
     doSomething(item);
     ++it;
 }

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; Q3ListView will always call it before it needs to show an item.

Many programs will need to reimplement Q3ListViewItem. The most commonly reimplemented functions are:

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 Q3CheckListItem and Q3ListView.

Member Function Documentation

 int MyListViewItem::compare(Q3ListViewItem *i, int col,
                              bool ascending) const
 {
     return key(col, ascending).compare(i->key(col, ascending));
 }