Contents

• Public Functions
• Protected Functions
• Detailed Description

Detailed Description

TheQ3ListViewItem class implements a list view item.

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

The easiest way to useQ3ListViewItem is to construct one with a few constant strings, and either aQ3ListView or anotherQ3ListViewItem as parent.

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

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

The parent must be anotherQ3ListViewItem or aQ3ListView. If the parent is aQ3ListView, the item becomes a top-level item within thatQ3ListView. If the parent is anotherQ3ListViewItem, the item becomes a child of that list view item.

If you keep the pointer, you can set or change the texts usingsetText(), add pixmaps usingsetPixmap(), change its mode usingsetSelectable(),setSelected(),setOpen() andsetExpandable(). You'll also be able to change its height usingsetHeight(), and traverse its sub-items. You don't have to keep the pointer since you can get a pointer to anyQ3ListViewItem in aQ3ListView usingQ3ListView::selectedItem(),Q3ListView::currentItem(),Q3ListView::firstChild(),Q3ListView::lastItem() andQ3ListView::findItem().

If you calldelete on a list view item, it will be deleted as expected, and as usual forQObjects, 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 usingitemAbove() anditemBelow(); 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, callenforceSortOrder() at any time;Q3ListView will always call it before it needs to show an item.

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

Some subclasses callsetExpandable(true) even when they have no children, and populate themselves whensetup() orsetOpen(true) is called. Thedirview/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.

Member Function Documentation

Q3ListViewItem::Q3ListViewItem(Q3ListView * parent)

Constructs a new top-level list view item in theQ3ListViewparent.

Q3ListViewItem::Q3ListViewItem(Q3ListViewItem * parent)

Constructs a new list view item that is a child ofparent and first in the parent's list of children.

Q3ListViewItem::Q3ListViewItem(Q3ListView * parent,Q3ListViewItem * after)

Constructs an empty list view item that is a child ofparent and is after itemafter in the parent's list of children. Sinceparent is aQ3ListView the item will be a top-level item.

Q3ListViewItem::Q3ListViewItem(Q3ListViewItem * parent,Q3ListViewItem * after)

Constructs an empty list view item that is a child ofparent and is after itemafter in the parent's list of children.

Q3ListViewItem::Q3ListViewItem(Q3ListView * parent, constQString & label1, constQString & label2 = QString(), constQString & label3 = QString(), constQString & label4 = QString(), constQString & label5 = QString(), constQString & label6 = QString(), constQString & label7 = QString(), constQString & label8 = QString())

Constructs a new top-level list view item in theQ3ListViewparent, with up to eight constant strings,label1,label2,label3,label4,label5,label6,label7 andlabel8 defining its columns' contents.

See alsosetText().

Q3ListViewItem::Q3ListViewItem(Q3ListViewItem * parent, constQString & label1, constQString & label2 = QString(), constQString & label3 = QString(), constQString & label4 = QString(), constQString & label5 = QString(), constQString & label6 = QString(), constQString & label7 = QString(), constQString & label8 = QString())

Constructs a new list view item as a child of theQ3ListViewItemparent with up to eight constant strings,label1,label2,label3,label4,label5,label6,label7 andlabel8 as columns' contents.

See alsosetText().

Q3ListViewItem::Q3ListViewItem(Q3ListView * parent,Q3ListViewItem * after, constQString & label1, constQString & label2 = QString(), constQString & label3 = QString(), constQString & label4 = QString(), constQString & label5 = QString(), constQString & label6 = QString(), constQString & label7 = QString(), constQString & label8 = QString())

Constructs a new list view item in theQ3ListViewparent that is included after itemafter and that has up to eight column texts,label1,label2,label3,label4,label5,label6,label7 andlabel8.

Note that the order is changed according toQ3ListViewItem::key() unless the list view's sorting is disabled usingQ3ListView::setSorting(-1).

See alsosetText().

Q3ListViewItem::Q3ListViewItem(Q3ListViewItem * parent,Q3ListViewItem * after, constQString & label1, constQString & label2 = QString(), constQString & label3 = QString(), constQString & label4 = QString(), constQString & label5 = QString(), constQString & label6 = QString(), constQString & label7 = QString(), constQString & label8 = QString())

Constructs a new list view item as a child of theQ3ListViewItemparent. It is inserted after itemafter and may contain up to eight strings,label1,label2,label3,label4,label5,label6,label7 andlabel8 as column entries.

Note that the order is changed according toQ3ListViewItem::key() unless the list view's sorting is disabled usingQ3ListView::setSorting(-1).

See alsosetText().

[virtual]Q3ListViewItem::~Q3ListViewItem()

Destroys the item, deleting all its children and freeing up all allocated resources.

[virtual]bool Q3ListViewItem::acceptDrop(constQMimeSource * mime) const

Returns true if the item can accept drops of type QMimeSourcemime; otherwise returns false.

The default implementation does nothing and returns false. A subclass must reimplement this to accept drops.

[virtual protected]void Q3ListViewItem::activate()

This virtual function is called whenever the user presses the mouse on this item or presses Space on it.

See alsoactivatedPos().

[protected]bool Q3ListViewItem::activatedPos(QPoint & pos)

When called from a reimplementation ofactivate(), this function gives information on how the item was activated. Otherwise the behavior is undefined.

Ifactivate() was caused by a mouse press, the function setspos to where the user clicked and returns true; otherwise it returns false and does not changepos.

pos is relative to the top-left corner of this item.

See alsoactivate().

[virtual protected]void Q3ListViewItem::cancelRename(int col)

This function is called if the user cancels in-place renaming of this item in columncol (e.g. by pressing Esc).

See alsookRename().

int Q3ListViewItem::childCount() const

Returns how many children this item has. The count only includes the item's immediate children.

[virtual]int Q3ListViewItem::compare(Q3ListViewItem * i,int col,bool ascending) const

Compares this list view item toi using the columncol inascending order. Returns < 0 if this item is less thani, 0 if they are equal and > 0 if this item is greater thani.

This function is used for sorting.

The default implementation compares the item keys (key()) usingQString::localeAwareCompare(). A reimplementation can use different values and a different comparison function. Here is a reimplementation that uses plain Unicode comparison:

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

We don't recommend usingascending so your code can safely ignore it.

See alsokey(),QString::localeAwareCompare(), andQString::compare().

int Q3ListViewItem::depth() const

Returns the depth of this item.

bool Q3ListViewItem::dragEnabled() const

Returns true if this item can be dragged; otherwise returns false.

See alsosetDragEnabled().

[virtual protected]void Q3ListViewItem::dragEntered()

This function is called when a drag enters the item's bounding rectangle.

The default implementation does nothing, subclasses may need to reimplement this function.

[virtual protected]void Q3ListViewItem::dragLeft()

This function is called when a drag leaves the item's bounding rectangle.

The default implementation does nothing, subclasses may need to reimplement this function.

bool Q3ListViewItem::dropEnabled() const

Returns true if this item accepts drops; otherwise returns false.

See alsosetDropEnabled() andacceptDrop().

[virtual protected]void Q3ListViewItem::dropped(QDropEvent * e)

This function is called when something was dropped on the item.e contains all the information about the drop.

The default implementation does nothing, subclasses may need to reimplement this function.

[virtual protected]void Q3ListViewItem::enforceSortOrder() const

Makes sure that this object's children are sorted appropriately.

This only works if every item from the root item down to this item is already sorted.

See alsosortChildItems().

Q3ListViewItem * Q3ListViewItem::firstChild() const

Returns the first (top) child of this item, or 0 if this item has no children.

Note that the children are not guaranteed to be sorted properly.Q3ListView andQ3ListViewItem try to postpone or avoid sorting to the greatest degree possible, in order to keep the user interface snappy.

See alsonextSibling() andsortChildItems().

int Q3ListViewItem::height() const

Returns the height of this item in pixels. This does not include the height of any children;totalHeight() returns that.

See alsosetHeight().

[virtual]void Q3ListViewItem::insertItem(Q3ListViewItem * newChild)

InsertsnewChild into this list view item's list of children. You should not need to call this function; it is called automatically by the constructor ofnewChild.

Warning: If you are usingSingle selection mode, then you should only insert unselected items.

[virtual]void Q3ListViewItem::invalidateHeight()

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

See alsosetHeight(),height(), andtotalHeight().

bool Q3ListViewItem::isEnabled() const

Returns true if this item is enabled; otherwise returns false.

See alsosetEnabled().

bool Q3ListViewItem::isExpandable() const

Returns true if this item is expandable even when it has no children; otherwise returns false.

bool Q3ListViewItem::isOpen() const

Returns true if this list view item has childrenand they are not explicitly hidden; otherwise returns false.

See alsosetOpen().

bool Q3ListViewItem::isSelectable() const

Returns true if the item is selectable (as it is by default); otherwise returns false

See alsosetSelectable().

bool Q3ListViewItem::isSelected() const

Returns true if this item is selected; otherwise returns false.

See alsosetSelected(),Q3ListView::setSelected(), andQ3ListView::selectionChanged().

bool Q3ListViewItem::isVisible() const

Returns true if the item is visible; otherwise returns false.

See alsosetVisible().

Q3ListViewItem * Q3ListViewItem::itemAbove() const

Returns a pointer to the item immediately above this item on the screen. This is usually the item's closest older sibling, but it may also be its parent or its next older sibling's youngest child, or something else if anyoftheabove->height() returns 0. Returns 0 if there is no item immediately above this item.

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

This function might be relatively slow because of the tree traversions needed to find the correct item.

See alsoitemBelow() andQ3ListView::itemRect().

Q3ListViewItem * Q3ListViewItem::itemBelow() const

Returns a pointer to the item immediately below this item on the screen. This is usually the item's eldest child, but it may also be its next younger sibling, its parent's next younger sibling, grandparent's, etc., or something else if anyoftheabove->height() returns 0. Returns 0 if there is no item immediately below this item.

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 alsoitemAbove() andQ3ListView::itemRect().

int Q3ListViewItem::itemPos() const

Returns the y coordinate of this item in the list view's coordinate system. This function is normally much slower thanQ3ListView::itemAt(), but it works for all items whereasQ3ListView::itemAt() normally only works for items on the screen.

See alsoQ3ListView::itemAt(),Q3ListView::itemRect(), andQ3ListView::itemPos().

[virtual]QString Q3ListViewItem::key(int column,bool ascending) const

Returns a key that can be used for sorting by columncolumn. The default implementation returnstext(). Derived classes may also incorporate the order indicated byascending into this key, although this is not recommended.

If you want to sort on non-alphabetical data, e.g. dates, numbers, etc., it is more efficient to reimplementcompare().

See alsocompare() andsortChildItems().

Q3ListView * Q3ListViewItem::listView() const

Returns a pointer to the list view containing this item.

Note that this function traverses the items to the root to find the listview. This function will return 0 for taken items - seeQ3ListViewItem::takeItem()

void Q3ListViewItem::moveItem(Q3ListViewItem * after)

Move the item to be after itemafter, which must be one of the item's siblings. To move an item in the hierarchy, usetakeItem() andinsertItem().

Note that this function will have no effect if sorting is enabled in the list view.

bool Q3ListViewItem::multiLinesEnabled() const

Returns true if the item can display multiple lines of text in its columns; otherwise returns false.

See alsosetMultiLinesEnabled().

Q3ListViewItem * Q3ListViewItem::nextSibling() const

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.Q3ListView andQ3ListViewItem try to postpone or avoid sorting to the greatest degree possible, in order to keep the user interface snappy.

See alsofirstChild() andsortChildItems().

[virtual protected]void Q3ListViewItem::okRename(int col)

This function is called if the user presses Enter during in-place renaming of the item in columncol.

See alsocancelRename().

[virtual]void Q3ListViewItem::paintBranches(QPainter * p, constQColorGroup & cg,int w,int y,int h)

Paints a set of branches from this item to (some of) its children.

Painterp is set up with clipping and translation so that you can only draw in the rectangle that needs redrawing;cg is the color group to use; the update rectangle is at (0, 0) and has size widthw by heighth. The top of the rectangle you own is aty (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 onall of the pixels.

See alsopaintCell() andQ3ListView::drawContentsOffset().

[virtual]void Q3ListViewItem::paintCell(QPainter * painter, constQColorGroup & cg,int column,int width,int align)

This virtual function paints the contents of one column of an item and aligns it as described byalign.

Thepainter is aQ3Painter open on the relevant paint device. It is translated so (0, 0) is the top-left pixel in the cell andwidth - 1,height() - 1 is the bottom-right pixelin the cell. The other properties of thepainter (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 useQ3ListView::itemMargin() for readability spacing on the left and right sides of data such as text, and should honorisSelected() andQ3ListView::allColumnsShowFocus().

If you reimplement this function, you should also reimplementwidth().

The rectangle to be painted is in an undefined state when this function is called, so youmust draw on all the pixels. Thepainter has the right font on entry.

See alsopaintBranches() andQ3ListView::drawContentsOffset().

[virtual]void Q3ListViewItem::paintFocus(QPainter * p, constQColorGroup & cg, constQRect & r)

Paints a focus indicator on the rectangler using painterp and colorscg.

p is already clipped.

See alsopaintCell(),paintBranches(), andQ3ListView::setAllColumnsShowFocus().

Q3ListViewItem * Q3ListViewItem::parent() const

Returns the parent of this item, or 0 if this item has no parent.

See alsofirstChild() andnextSibling().

[virtual]constQPixmap * Q3ListViewItem::pixmap(int column) const

Returns the pixmap forcolumn, or 0 if there is no pixmap forcolumn.

See alsosetText() andsetPixmap().

[virtual]void Q3ListViewItem::removeItem(Q3ListViewItem * item)

Removes the givenitem. UsetakeItem() instead.

bool Q3ListViewItem::renameEnabled(int col) const

Returns true if this item can be in-place renamed in columncol; otherwise returns false.

See alsosetRenameEnabled().

void Q3ListViewItem::repaint() const

Repaints this item on the screen if it is currently visible.

[virtual]int Q3ListViewItem::rtti() const

Returns 0.

Make your derived classes return their own values for rtti(), so that you can distinguish between different kinds of list view items. You should use values greater than 1000 to allow for extensions to this class.

[virtual]void Q3ListViewItem::setDragEnabled(bool allow)

Ifallow is true, the list view starts a drag (seeQ3ListView::dragObject()) when the user presses and moves the mouse on this item.

See alsodragEnabled().

[virtual]void Q3ListViewItem::setDropEnabled(bool allow)

Ifallow is true, the list view accepts drops onto the item; otherwise drops are not allowed.

See alsodropEnabled().

[virtual]void Q3ListViewItem::setEnabled(bool b)

Ifb is true the item is enabled; otherwise it is disabled. Disabled items are drawn differently (e.g. grayed-out) and are not accessible by the user.

See alsoisEnabled().

[virtual]void Q3ListViewItem::setExpandable(bool enable)

Sets this item to be expandable even if it has no children ifenable is true, and to be expandable only if it has children ifenable is false (the default).

The dirview example uses this in the canonical fashion. It checks whether the directory is empty insetup() and calls setExpandable(true) if not; insetOpen() 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 unlessQ3ListView::setRootIsDecorated() is set to true.

See alsoisExpandable() andsetSelectable().

[virtual protected]void Q3ListViewItem::setHeight(int height)

Sets this item's height toheight pixels. This implicitly changestotalHeight(), too.

Note that a font change causes this height to be overwritten unless you reimplementsetup().

For best results in Windows style we suggest using an even number of pixels.

See alsoheight(),totalHeight(), andisOpen().

[virtual]void Q3ListViewItem::setMultiLinesEnabled(bool b)

Ifb is true each of the item's columns may contain multiple lines of text; otherwise each of them may only contain a single line.

See alsomultiLinesEnabled().

[virtual]void Q3ListViewItem::setOpen(bool o)

Opens or closes an item, i.e. shows or hides an item's children.

Ifo is true all child items are shown initially. The user can hide them by clicking the- icon to the left of the item. Ifo 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 alsoheight(),totalHeight(), andisOpen().

[virtual]void Q3ListViewItem::setPixmap(int column, constQPixmap & pm)

Sets the pixmap in columncolumn topm, ifpm is non-null and different from the current pixmap, and ifcolumn is non-negative.

See alsopixmap() andsetText().

[virtual]void Q3ListViewItem::setRenameEnabled(int col,bool b)

Ifb is true, this item can be in-place renamed in the columncol by the user; otherwise it cannot be renamed in-place.

See alsorenameEnabled().

[virtual]void Q3ListViewItem::setSelectable(bool enable)

Sets this items to be selectable ifenable is true (the default) or not to be selectable ifenable is false.

The user is not able to select a non-selectable item using either the keyboard or the mouse. The application programmer still can though, e.g. usingsetSelected().

See alsoisSelectable().

[virtual]void Q3ListViewItem::setSelected(bool s)

Ifs is true this item is selected; otherwise it is deselected.

This function does not maintain any invariants or repaint anything --Q3ListView::setSelected() does that.

See alsoisSelected(),height(), andtotalHeight().

[virtual]void Q3ListViewItem::setText(int column, constQString & text)

Sets the text in columncolumn totext, ifcolumn is a valid column number andtext is different from the existing text.

If thetext() function has been reimplemented, this function may be a no-op.

See alsotext() andkey().

void Q3ListViewItem::setVisible(bool b)

Ifb is true, the item is made visible; otherwise it is hidden.

If the item is not visible,itemAbove() anditemBelow() will never return this item, although you still can reach it by using e.g.Q3ListViewItemIterator.

See alsoisVisible().

[virtual]void Q3ListViewItem::setup()

This virtual function is called before the first timeQ3ListView 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 callswidthChanged() 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 callsetHeight() yourself or reimplement it.)

[virtual]void Q3ListViewItem::sort()

Sorts all this item's child items using the current sorting configuration (sort column and direction).

See alsoenforceSortOrder().

[virtual]void Q3ListViewItem::sortChildItems(int column,bool ascending)

Sorts this item's children using columncolumn. This is done in ascending order ifascending is true and in descending order ifascending is false.

Asks some of the children to sort their children. (Q3ListView andQ3ListViewItem ensure that all on-screen objects are properly sorted but may avoid or defer sorting other objects in order to be more responsive.)

See alsokey() andcompare().

[virtual]void Q3ListViewItem::startRename(int col)

If in-place renaming of this item is enabled (seerenameEnabled()), this function starts renaming the item in columncol, by creating and initializing an edit box.

[virtual]void Q3ListViewItem::takeItem(Q3ListViewItem * item)

Removesitem from this object's list of children and causes an update of the screen display. The item is not deleted. You should not normally need to call this function because Q3ListViewItem::~Q3ListViewItem() calls it.

The normal way to delete an item is to usedelete.

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 theninsertItem() to put the item back in its new position.

If a taken item is part of a selection inSingle selection mode, it is unselected and selectionChanged() is emitted. If a taken item is part of a selection inMulti orExtended selection mode, it remains selected.

Warning: This function leavesitem 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 notablyinsertItem(). The functions that work on taken items are explicitly documented as such.

See alsoQ3ListViewItem::insertItem().

[virtual]QString Q3ListViewItem::text(int column) const

Returns the text in columncolumn, or an empty string if there is no text in that column.

See alsosetText(),key(), andpaintCell().

int Q3ListViewItem::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.

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, andinvalidateHeight() to invalidate the cached height.

See alsoheight().

[virtual]int Q3ListViewItem::width(constQFontMetrics & fm, constQ3ListView * lv,int c) const

Returns the number of pixels of width required to draw columnc of list viewlv, using the metricsfm without cropping. The list view containing this item may use this information depending on theQ3ListView::WidthMode settings for the column.

The default implementation returns the width of the bounding rectangle of the text of columnc.

Q3ListView::itemMargin()

See alsolistView(),widthChanged(), andQ3ListView::setColumnWidthMode().

void Q3ListViewItem::widthChanged(int c = -1) const

Call this function when the value ofwidth() may have changed for columnc. Normally, you should call this if text(c) changes. Passing -1 forc indicates that all columns may have changed. It is more efficient to pass -1 if two or more columns have changed than to call widthChanged() separately for each one.

See alsowidth().