- Qt 6.10
- Qt Widgets
- C++ Classes
- QTreeWidget
- Qt 6.10.2 Reference Documentation

# QTreeWidget Class

The QTreeWidget class provides a tree view that uses a predefined tree model. More...

Header: | `#include <QTreeWidget>`
CMake: | `find_package(Qt6 REQUIRED COMPONENTS Widgets)` `target_link_libraries(mytarget PRIVATE Qt6::Widgets)`
qmake: | `QT += widgets`
Inherits: | QTreeView

- List of all members, including inherited members

## Properties

- columnCount : int
- topLevelItemCount : const int

## Public Functions

| QTreeWidget(QWidget *parent = nullptr)
| ~QTreeWidget()
void | addTopLevelItem(QTreeWidgetItem *item)
void | addTopLevelItems(const QList<QTreeWidgetItem *> &items)
void | closePersistentEditor(QTreeWidgetItem *item, int column = 0)
int | columnCount() const
int | currentColumn() const
QTreeWidgetItem * | currentItem() const
void | editItem(QTreeWidgetItem *item, int column = 0)
QList<QTreeWidgetItem *> | findItems(const QString &text, Qt::MatchFlags flags, int column = 0) const
QTreeWidgetItem * | headerItem() const
QModelIndex | indexFromItem(const QTreeWidgetItem *item, int column = 0) const
int | indexOfTopLevelItem(QTreeWidgetItem *item) const
void | insertTopLevelItem(int index, QTreeWidgetItem *item)
void | insertTopLevelItems(int index, const QList<QTreeWidgetItem *> &items)
QTreeWidgetItem * | invisibleRootItem() const
bool | isPersistentEditorOpen(QTreeWidgetItem *item, int column = 0) const
QTreeWidgetItem * | itemAbove(const QTreeWidgetItem *item) const
QTreeWidgetItem * | itemAt(const QPoint &p) const
QTreeWidgetItem * | itemBelow(const QTreeWidgetItem *item) const
QTreeWidgetItem * | itemFromIndex(const QModelIndex &index) const
QWidget * | itemWidget(QTreeWidgetItem *item, int column) const
void | openPersistentEditor(QTreeWidgetItem *item, int column = 0)
QList<QTreeWidgetItem *> | selectedItems() const
void | setColumnCount(int columns)
void | setCurrentItem(QTreeWidgetItem *item)
void | setCurrentItem(QTreeWidgetItem *item, int column)
void | setCurrentItem(QTreeWidgetItem *item, int column, QItemSelectionModel::SelectionFlags command)
void | setHeaderItem(QTreeWidgetItem *item)
void | setHeaderLabels(const QStringList &labels)
void | setItemWidget(QTreeWidgetItem *item, int column, QWidget *widget)
int | sortColumn() const
void | sortItems(int column, Qt::SortOrder order)
QTreeWidgetItem * | takeTopLevelItem(int index)
QTreeWidgetItem * | topLevelItem(int index) const
int | topLevelItemCount() const
QRect | visualItemRect(const QTreeWidgetItem *item) const

## Reimplemented Public Functions

virtual void | setSelectionModel(QItemSelectionModel *selectionModel) override

## Public Slots

void | clear()
void | collapseItem(const QTreeWidgetItem *item)
void | expandItem(const QTreeWidgetItem *item)
void | scrollToItem(const QTreeWidgetItem *item, QAbstractItemView::ScrollHint hint = EnsureVisible)

## Protected Functions

virtual bool | dropMimeData(QTreeWidgetItem *parent, int index, const QMimeData *data, Qt::DropAction action)
bool | event(QEvent *e)
virtual QMimeData * | mimeData(const QList<QTreeWidgetItem *> &items) const
virtual QStringList | mimeTypes() const
virtual Qt::DropActions | supportedDropActions() const

## Detailed Description

The QTreeWidget class is a convenience class that provides a standard tree widget with a classic item-based interface similar to that used by the QListView class in Qt 3. This class is based on Qt's Model/View architecture and uses a default model to hold items, each of which is a QTreeWidgetItem.

Developers who do not need the flexibility of the Model/View framework can use this class to create simple hierarchical lists very easily. A more flexible approach involves combining a QTreeView with a standard item model. This allows the storage of data to be separated from its representation.

In its simplest form, a tree widget can be constructed in the following way:

     QTreeWidget *treeWidget = new QTreeWidget();
     treeWidget->setColumnCount(1);
     QList<QTreeWidgetItem *> items;
     for (int i = 0; i < 10; ++i)
         items.append(new QTreeWidgetItem(static_cast<QTreeWidget *>(nullptr), QStringList(QString("item: %1").arg(i))));
     treeWidget->insertTopLevelItems(0, items);

Before items can be added to the tree widget, the number of columns must be set with setColumnCount(). This allows each item to have one or more labels or other decorations. The number of columns in use can be found with the columnCount() function.

The tree can have a header that contains a section for each column in the widget. It is easiest to set up the labels for each section by supplying a list of strings with setHeaderLabels(), but a custom header can be constructed with a QTreeWidgetItem and inserted into the tree with the setHeaderItem() function.

The items in the tree can be sorted by column according to a predefined sort order. If sorting is enabled, the user can sort the items by clicking on a column header. Sorting can be enabled or disabled by calling setSortingEnabled(). The isSortingEnabled() function indicates whether sorting is enabled.

See also QTreeWidgetItem, QTreeWidgetItemIterator, QTreeView, and Model/View Programming.

## Property Documentation

### columnCount : int

This property holds the number of columns displayed in the tree widget

By default, this property has a value of 1.

Access functions:

int | columnCount() const
void | setColumnCount(int columns)

### `[read-only]` topLevelItemCount : const int

This property holds the number of top-level items

By default, this property has a value of 0.

Access functions:

int | topLevelItemCount() const

See also columnCount() and currentItem().

## Member Function Documentation

### `[explicit]` QTreeWidget::QTreeWidget(QWidget *parent = nullptr)

Constructs a tree widget with the given parent.

### `[noexcept]` QTreeWidget::~QTreeWidget()

Destroys the tree widget and all its items.

### void QTreeWidget::addTopLevelItem(QTreeWidgetItem *item)

Appends the item as a top-level item in the widget.

See also insertTopLevelItem().

### void QTreeWidget::addTopLevelItems(const QList<QTreeWidgetItem *> &items)

Appends the list of items as a top-level items in the widget.

See also insertTopLevelItems().

### `[slot]` void QTreeWidget::clear()

Clears the tree widget by removing all of its items and selections.

Note: Since each item is removed from the tree widget before being deleted, the return value of QTreeWidgetItem::treeWidget() will be invalid when called from an item's destructor.

See also takeTopLevelItem(), topLevelItemCount(), and columnCount().

### void QTreeWidget::closePersistentEditor(QTreeWidgetItem *item, int column = 0)

Closes the persistent editor for the item in the given column.

This function has no effect if no persistent editor is open for this combination of item and column.

See also openPersistentEditor() and isPersistentEditorOpen().

### `[slot]` void QTreeWidget::collapseItem(const QTreeWidgetItem *item)

Closes the item. This causes the tree containing the item's children to be collapsed.

See also expandItem(), currentItem(), itemAt(), and topLevelItem().

### int QTreeWidget::currentColumn() const

Returns the current column in the tree widget.

See also setCurrentItem() and columnCount().

### QTreeWidgetItem *QTreeWidget::currentItem() const

Returns the current item in the tree widget.

See also setCurrentItem() and currentItemChanged().

### `[virtual protected]` bool QTreeWidget::dropMimeData(QTreeWidgetItem *parent, int index, const QMimeData *data, Qt::DropAction action)

Handles the data supplied by a drag and drop operation that ended with the given action in the index in the given parent item.

The default implementation returns `true` if the drop was successfully handled by decoding the mime data and inserting it into the model; otherwise it returns `false`.

See also supportedDropActions() and supportedDragActions.

### void QTreeWidget::editItem(QTreeWidgetItem *item, int column = 0)

Starts editing the item in the given column if it is editable.

### `[protected]` bool QTreeWidget::event(QEvent *e)

### `[slot]` void QTreeWidget::expandItem(const QTreeWidgetItem *item)

Expands the item. This causes the tree containing the item's children to be expanded.

See also collapseItem(), currentItem(), itemAt(), topLevelItem(), and itemExpanded().

### QList<QTreeWidgetItem *> QTreeWidget::findItems(const QString &text, Qt::MatchFlags flags, int column = 0) const

Returns a list of items that match the given text, using the given flags, in the given column.

### QTreeWidgetItem *QTreeWidget::headerItem() const

Returns the item used for the tree widget's header.

See also setHeaderItem().

### QModelIndex QTreeWidget::indexFromItem(const QTreeWidgetItem *item, int column = 0) const

Returns the QModelIndex associated with the given item in the given column.

Note: In Qt versions prior to 5.7, this function took a non-`const` item.

See also itemFromIndex() and topLevelItem().

### int QTreeWidget::indexOfTopLevelItem(QTreeWidgetItem *item) const

Returns the index of the given top-level item, or -1 if the item cannot be found.

See also sortItems() and topLevelItemCount().

### void QTreeWidget::insertTopLevelItem(int index, QTreeWidgetItem *item)

Inserts the item at index in the top level in the view.

If the item has already been inserted somewhere else it won't be inserted.

See also addTopLevelItem() and columnCount().

### void QTreeWidget::insertTopLevelItems(int index, const QList<QTreeWidgetItem *> &items)

Inserts the list of items at index in the top level in the view.

Items that have already been inserted somewhere else won't be inserted.

See also addTopLevelItems().

### QTreeWidgetItem *QTreeWidget::invisibleRootItem() const

Returns the tree widget's invisible root item.

The invisible root item provides access to the tree widget's top-level items through the QTreeWidgetItem API, making it possible to write functions that can treat top-level items and their children in a uniform way; for example, recursive functions.

### bool QTreeWidget::isPersistentEditorOpen(QTreeWidgetItem *item, int column = 0) const

Returns whether a persistent editor is open for item item in column column.

See also openPersistentEditor() and closePersistentEditor().

### QTreeWidgetItem *QTreeWidget::itemAbove(const QTreeWidgetItem *item) const

Returns the item above the given item.

### QTreeWidgetItem *QTreeWidget::itemAt(const QPoint &p) const

Returns a pointer to the item at the coordinates p. The coordinates are relative to the tree widget's viewport().

See also visualItemRect().

### QTreeWidgetItem *QTreeWidget::itemBelow(const QTreeWidgetItem *item) const

Returns the item visually below the given item.

### QTreeWidgetItem *QTreeWidget::itemFromIndex(const QModelIndex &index) const

Returns a pointer to the QTreeWidgetItem associated with the given index.

See also indexFromItem().

### QWidget *QTreeWidget::itemWidget(QTreeWidgetItem *item, int column) const

Returns the widget displayed in the cell specified by item and the given column.

See also setItemWidget() and removeItemWidget().

### `[virtual protected]` QMimeData *QTreeWidget::mimeData(const QList<QTreeWidgetItem *> &items) const

Returns an object that contains a serialized description of the specified items. The format used to describe the items is obtained from the mimeTypes() function.

If the list of items is empty, `nullptr` is returned rather than a serialized empty list.

### `[virtual protected]` QStringList QTreeWidget::mimeTypes() const

Returns a list of MIME types that can be used to describe a list of treewidget items.

See also mimeData().

### void QTreeWidget::openPersistentEditor(QTreeWidgetItem *item, int column = 0)

Opens a persistent editor for the item in the given column.

See also closePersistentEditor() and isPersistentEditorOpen().

### `[slot]` void QTreeWidget::scrollToItem(const QTreeWidgetItem *item, QAbstractItemView::ScrollHint hint = EnsureVisible)

Ensures that the item is visible, scrolling the view if necessary using the specified hint.

See also currentItem(), itemAt(), and topLevelItem().

### QList<QTreeWidgetItem *> QTreeWidget::selectedItems() const

Returns a list of all selected non-hidden items.

See also itemSelectionChanged().

### void QTreeWidget::setCurrentItem(QTreeWidgetItem *item)

Sets the current item in the tree widget.

Unless the selection mode is NoSelection, the item is also selected.

See also currentItem() and currentItemChanged().

### void QTreeWidget::setCurrentItem(QTreeWidgetItem *item, int column)

Sets the current item in the tree widget and the current column to column.

See also currentItem().

### void QTreeWidget::setCurrentItem(QTreeWidgetItem *item, int column, QItemSelectionModel::SelectionFlags command)

Sets the current item in the tree widget and the current column to column, using the given command.

See also currentItem().

### void QTreeWidget::setHeaderItem(QTreeWidgetItem *item)

Sets the header item for the tree widget. The label for each column in the header is supplied by the corresponding label in the item.

The tree widget takes ownership of the item.

See also headerItem() and setHeaderLabels().

### void QTreeWidget::setHeaderLabels(const QStringList &labels)

Adds a column in the header for each item in the labels list, and sets the label for each column.

Note that setHeaderLabels() won't remove existing columns.

See also setHeaderItem() and setHeaderLabel().

### void QTreeWidget::setItemWidget(QTreeWidgetItem *item, int column, QWidget *widget)

Sets the given widget to be displayed in the cell specified by the given item and column.

The given widget's autoFillBackground property must be set to true, otherwise the widget's background will be transparent, showing both the model data and the tree widget item.

This function should only be used to display static content in the place of a tree widget item. If you want to display custom dynamic content or implement a custom editor widget, use QTreeView and subclass QStyledItemDelegate instead.

This function cannot be called before the item hierarchy has been set up, i.e., the QTreeWidgetItem that will hold widget must have been added to the view before widget is set.

Note: The tree takes ownership of widget.

See also itemWidget(), removeItemWidget(), and Delegate Classes.

### `[override virtual]` void QTreeWidget::setSelectionModel(QItemSelectionModel *selectionModel)

Reimplements: QTreeView::setSelectionModel(QItemSelectionModel *selectionModel).

### int QTreeWidget::sortColumn() const

Returns the column used to sort the contents of the widget.

See also sortItems().

### void QTreeWidget::sortItems(int column, Qt::SortOrder order)

Sorts the items in the widget in the specified order by the values in the given column.

See also sortColumn().

### `[virtual protected]` Qt::DropActions QTreeWidget::supportedDropActions() const

Returns the drop actions supported by this view.

See also Qt::DropActions, supportedDragActions, and dropMimeData().

### QTreeWidgetItem *QTreeWidget::takeTopLevelItem(int index)

Removes the top-level item at the given index in the tree and returns it, otherwise returns `nullptr`;

See also insertTopLevelItem(), topLevelItem(), and topLevelItemCount().

### QTreeWidgetItem *QTreeWidget::topLevelItem(int index) const

Returns the top level item at the given index, or `nullptr` if the item does not exist.

See also topLevelItemCount() and insertTopLevelItem().

### QRect QTreeWidget::visualItemRect(const QTreeWidgetItem *item) const

Returns the rectangle on the viewport occupied by the item at item.

See also itemAt().