![]() |
| ||
Classes - Annotated - Tree - Functions - Home - Structure |
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. Its design has the following main goals:
The simplest way to use QListViewItem is to construct one with a few constant strings. This creates an item that 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 by 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(); }
There is also an interator class to traverse a tree of list view items. To iterate over all items of a list view, do the following:
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; 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
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.
QListView * table;
bool StructureParser::startElement( const QString& namespaceURI, const QString& , const QString& qName, const QXmlAttributes& attributes) { QListViewItem * element;
element = new QListViewItem( table, qName, namespaceURI );
}
(from xml/tagreader-with-features/structureparser.cpp )
See also setText().
QListViewItem * element;
QListViewItem * attribute; for ( int i = 0 ; i < attributes.length(); i++ ){ attribute = new QListViewItem( element, attributes.qName(i), attributes.uri(i) ); }
(from xml/tagreader-with-features/structureparser.cpp )
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 always TRUE. 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.
We recommend not using this function; it will most likely become obsolete at the first opportunity.
See also activate().
Returns the current number of children of this item.
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) ); }
See also key(), QString::localeAwareCompare() and QString::compare().
Example: dirview/dirview.cpp.
See also setDragEnabled().
The default implementation does nothing, subclasses should reimplement this method.
The default implementation does nothing, subclasses should reimplement this method.
See also setDropEnabled() and acceptDrop().
The default implementation does nothing, subclasses should reimplement this method.
This works only if every item in the chain from the root item to this item is sorted appropriately.
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.
This function works even if this item is not contained in a list view.
This function works even if this item is not contained in a list view.
See also setHeight(), height() and totalHeight().
See also setEnabled().
Returns TRUE if this item is expandable even when it has no children.
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().
Returns TRUE if the item is selectable (as it is by default), or FALSE if it is not.
See also setSelectable().
Returns TRUE if this item is selected, or FALSE if it is not.
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.
You can use this function to sort by non-alphabetic data. This code excerpt sorts 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;
For sorting, actually compare() is used, which uses in its default implementation key(). If you use non-string values for sorting, rather reimplement compare(), as this is more efficient that convering the key into a string and comparing that.
See also compare() and sortChildItems().
Example: network/ftpclient/ftpview.cpp.
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 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().
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().
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().
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.
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().
Examples: dirview/dirview.cpp and network/ftpclient/ftpview.cpp.
This function has been renamed takeItem().
Example: addressbook/centralwidget.cpp.
Although often frowned upon by purists, Run Time Type Identification is very useful in this case, as it allows a QListView to be an efficient indexed storage mechanism.
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.
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 visible initially, and the user might collapse them by clicking the - icon symbolizing the node. If o is FALSE, the children of this item are initially unvisible. The user might unhide them by clicking the + node icon.
QListViewItem * element;
element = new QListViewItem( table, qName, namespaceURI );
element->setOpen( TRUE );
(cf. xml/tagreader-with-features/structureparser.cpp)
Also does some bookkeeping.
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, of course.
See also isSelectable().
Example: network/ftpclient/ftpview.cpp.
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.
See also text(), key() and invalidate().
Examples: addressbook/centralwidget.cpp and xml/outliner/outlinetree.cpp.
If the item is not visible, itemAbove() and itemBelow() will never hit this item, while you still can reach it by using e.g. the 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.)
See also key().
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 insert(). The functions that work on detached items are explicitly documented as such.
See also QListViewItem::insertItem().
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().
Examples: addressbook/centralwidget.cpp, dirview/dirview.cpp and network/ftpclient/ftpview.cpp.
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().
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().
Search the documentation, FAQ, qt-interest archive and more (uses
www.trolltech.com):
This file is part of the Qt toolkit, copyright © 1995-2001 Trolltech, all rights reserved.
Copyright © 2001 Trolltech | Trademarks | Qt version 3.0.0-beta1-beta1
|