QTreeWidgetItem Class

The QTreeWidgetItem class provides an item for use with the QTreeWidget convenience class. More...

Header:	#include <QTreeWidgetItem>
qmake:	QT += widgets

List of all members, including inherited members

Public Types

enum	ChildIndicatorPolicy { ShowIndicator, DontShowIndicator, DontShowIndicatorWhenChildless }
enum	ItemType { Type, UserType }

Detailed Description

Tree widget items are used to hold rows of information for tree widgets. Rows usually contain several columns of data, each of which can contain a text label and an icon.

The QTreeWidgetItem class is a convenience class that replaces the QListViewItem class in Qt 3. It provides an item for use with the QTreeWidget class.

Items are usually constructed with a parent that is either a QTreeWidget (for top-level items) or a QTreeWidgetItem (for items on lower levels of the tree). For example, the following code constructs a top-level item to represent cities of the world, and adds a entry for Oslo as a child item:

     QTreeWidgetItem *cities = new QTreeWidgetItem(treeWidget);
     cities->setText(0, tr("Cities"));
     QTreeWidgetItem *osloItem = new QTreeWidgetItem(cities);
     osloItem->setText(0, tr("Oslo"));
     osloItem->setText(1, tr("Yes"));

Items can be added in a particular order by specifying the item they follow when they are constructed:

     QTreeWidgetItem *planets = new QTreeWidgetItem(treeWidget, cities);
     planets->setText(0, tr("Planets"));

Each column in an item can have its own background brush which is set with the setBackground() function. The current background brush can be found with background(). The text label for each column can be rendered with its own font and brush. These are specified with the setFont() and setForeground() functions, and read with font() and foreground().

The main difference between top-level items and those in lower levels of the tree is that a top-level item has no parent(). This information can be used to tell the difference between items, and is useful to know when inserting and removing items from the tree. Children of an item can be removed with takeChild() and inserted at a given index in the list of children with the insertChild() function.

By default, items are enabled, selectable, checkable, and can be the source of a drag and drop operation. Each item's flags can be changed by calling setFlags() with the appropriate value (see Qt::ItemFlags). Checkable items can be checked and unchecked with the setCheckState() function. The corresponding checkState() function indicates whether the item is currently checked.

Subclassing

When subclassing QTreeWidgetItem to provide custom items, it is possible to define new types for them so that they can be distinguished from standard items. The constructors for subclasses that require this feature need to call the base class constructor with a new type value equal to or greater than UserType.

Member Type Documentation

enum QTreeWidgetItem::ChildIndicatorPolicy

Constant	Value	Description
`QTreeWidgetItem::ShowIndicator`	`0`	The controls for expanding and collapsing will be shown for this item even if there are no children.
`QTreeWidgetItem::DontShowIndicator`	`1`	The controls for expanding and collapsing will never be shown even if there are children. If the node is forced open the user will not be able to expand or collapse the item.
`QTreeWidgetItem::DontShowIndicatorWhenChildless`	`2`	The controls for expanding and collapsing will be shown if the item contains children.

This enum was introduced or modified in Qt 4.3.

enum QTreeWidgetItem::ItemType

This enum describes the types that are used to describe tree widget items.

Constant	Value	Description
`QTreeWidgetItem::Type`	`0`	The default type for tree widget items.
`QTreeWidgetItem::UserType`	`1000`	The minimum value for custom types. Values below UserType are reserved by Qt.

You can define new user types in QTreeWidgetItem subclasses to ensure that custom items are treated specially; for example, when items are sorted.

See also type().

Contents