| Home | All Classes | Main Classes | Annotated | Grouped Classes | Functions | |
The QListViewItem class implements a list view item. More...
#include <qlistview.h>
Inherits Qt.
Inherited by QCheckListItem.
A list view item is a multi-column object capable of displaying itself in a QListView. Its design has the following main goals:
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. If you delete a list view item, it will be deleted as expected, and as
usual for QObjects, all its items will be deleted too.
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 selected items of a list view, do the following:
QListViewItemIterator it( listview );
while ( it.current() ) {
QListViewItem *item = it.current();
++it;
if ( item->isSelected() )
doSomething( item );
}
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.
See also setText().
See also setText().
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().
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().
The default implementation does nothing and returns FALSE. A subclass must reimplement this to accept drops.
See also activatedPos().
Reimplemented in QCheckListItem.
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().
See also okRename().
Returns how many children this item has.
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: dirview/dirview.cpp.
See also setDragEnabled().
The default implementation does nothing, subclasses may need to reimplement this method.
The default implementation does nothing, subclasses may need to reimplement this method.
See also setDropEnabled() and acceptDrop().
The default implementation does nothing, subclasses may need to reimplement this method.
This works only if every item from the root item down to this item is already sorted.
See also sortChildItems().
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.
Note: The item(s) you insert needs to be unselected if you want to maintain the listviews consistency when it is set to Single selection mode.
See also setHeight(), height(), and totalHeight().
See also setEnabled().
Returns TRUE if this item is expandable even when it has no children; otherwise returns FALSE.
Returns TRUE if this list view item has children and they are not explicitly hidden; otherwise returns FALSE.
See also setOpen().
Returns TRUE if the item is selectable (as it is by default); otherwise returns FALSE
See also setSelectable().
Returns TRUE if this item is selected; otherwise returns FALSE.
See also setSelected(), QListView::setSelected(), and QListView::selectionChanged().
Example: listviews/listviews.cpp.
See also setVisible().
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().
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.
See also QListView::itemAt(), QListView::itemRect(), and QListView::itemPos().
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().
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.
See also cancelRename().
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().
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.
p is already clipped.
See also paintCell(), paintBranches(), and QListView::allColumnsShowFocus.
Reimplemented in QCheckListItem.
See also firstChild() and nextSibling().
Example: dirview/dirview.cpp.
See also setText() and setPixmap().
Example: dirview/dirview.cpp.
This function has been renamed takeItem().
Example: addressbook/centralwidget.cpp.
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.
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().
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().
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.
See also pixmap() and setText().
Example: dirview/dirview.cpp.
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().
This function does not maintain any invariants or repaint anything -- QListView::setSelected() does that.
See also height() and totalHeight().
Example: addressbook/centralwidget.cpp.
If text() has been reimplemented, this function may be a no-op.
Examples: addressbook/centralwidget.cpp and xml/outliner/outlinetree.cpp.
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.
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.
See also enforceSortOrder().
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.)
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.
Note: For Single selection mode, if the selected item is part of the taken item(s), it is unselected and a selectionChanged is emitted. For Multi or Extended selection, no unselection happens and no selectionChanged signals are emitted.
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().
See also key() and paintCell().
Examples: addressbook/centralwidget.cpp, dirview/dirview.cpp, network/archivesearch/archivedialog.ui.h, and network/ftpclient/ftpmainwindow.ui.h.
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().
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.
See also width().
This file is part of the Qt toolkit. Copyright © 1995-2003 Trolltech. All Rights Reserved.
| Copyright © 2003 Trolltech | Trademarks | Qt version 3.2.0b2
|