QTreeWidget Class

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

List of all members, including inherited members

Public Functions

Reimplemented Public Functions

Public Slots

Signals

Detailed Description

A QTreeWidget is a QTreeView that keeps its own items, QTreeWidgetItem objects, so that a tree can be filled without writing a model:

auto *tree = new QTreeWidget;
tree->setHeaderLabels({"Name", "Size"});
auto *folder = new QTreeWidgetItem(tree, {"Documents", ""});
new QTreeWidgetItem(folder, {"notes.txt", "2 KiB"});
tree->expandAll();
connect(tree, &QTreeWidget::itemActivated, this, &Window::open);

Everything that QTreeView does is there: columns with a header, sorting by a click on the header with setSortingEnabled(), selection, and editing in place through the delegate for the items that are Qt::ItemIsEditable. The signals tell about items instead of model indexes, and itemChanged() is emitted for every change of an item.

Use QTreeView with a model of your own when the data is already somewhere else, or is large.

See also QTreeWidgetItem and QTreeView.

Differences from Qt

Member Function Documentation

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

Constructs an empty tree with one column and the given parent.

[override] QTreeWidget::~QTreeWidget()

Destroys the tree and all its items.

void QTreeWidget::addTopLevelItem(QTreeWidgetItem *item)

Adds item as the last top-level item. The tree takes ownership of it.

See also insertTopLevelItem().

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

Adds items as the last top-level items.

[slot] void QTreeWidget::clear()

Removes and deletes all the items of the tree. The columns and the header stay.

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

Collapses item.

See also expandItem().

int QTreeWidget::columnCount() const

Returns the number of columns of the tree.

See also setColumnCount().

int QTreeWidget::currentColumn() const

Returns the column of the current item that is current, or -1 if there is no current item.

QTreeWidgetItem * QTreeWidget::currentItem() const

Returns the current item, or nullptr if there is none.

See also setCurrentItem() and currentColumn().

[signal] void QTreeWidget::currentItemChanged(QTreeWidgetItem *current, QTreeWidgetItem *previous)

This signal is emitted when the current item changed from previous to current; either can be nullptr.

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

Starts editing item in the column column, if the item is enabled and Qt::ItemIsEditable.

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

Expands item.

See also collapseItem() and QTreeWidgetItem::setExpanded().

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

Returns the items whose text in the column column matches text the way flags says: the top-level items, or with Qt::MatchRecursive the items of all levels, in the order of the tree. Matching ignores case unless flags has Qt::MatchCaseSensitive or is Qt::MatchExactly.

QTreeWidgetItem * QTreeWidget::headerItem() const

Returns the item whose texts are the labels of the header. The tree owns it.

See also setHeaderLabels().

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

Returns the model index of item in the column column, or an invalid index if the item is not in this tree.

See also itemFromIndex().

int QTreeWidget::indexOfTopLevelItem(QTreeWidgetItem *item) const

Returns the position of item among the top-level items, or -1 if it is not one of them.

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

Inserts item at position index of the top-level items. The tree takes ownership of it. Nothing happens if the item is in a tree or has a parent already.

See also addTopLevelItem().

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

Inserts items at position index of the top-level items, in their order.

QTreeWidgetItem * QTreeWidget::invisibleRootItem() const

Returns the item that the top-level items are the children of. It does not show; with it, code that walks the tree treats the top level like every other level.

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

Returns the item that is laid out above item, or nullptr.

See also itemBelow().

[signal] void QTreeWidget::itemActivated(QTreeWidgetItem *item, int column)

This signal is emitted when the user activates item, in the column column: with a double click, or with Return or Enter.

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

Returns the item at the position p of the viewport, or nullptr if there is none.

QTreeWidgetItem * QTreeWidget::itemAt(int x, int y) const

This is an overloaded function.

Returns the item at the position (x, y) of the viewport.

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

Returns the item that is laid out below item, or nullptr.

See also itemAbove().

[signal] void QTreeWidget::itemChanged(QTreeWidgetItem *item, int column)

This signal is emitted when the data of item changed in the column column: its text, its check state or anything else, by the user or by the program.

[signal] void QTreeWidget::itemClicked(QTreeWidgetItem *item, int column)

This signal is emitted when item is clicked, in the column column.

[signal] void QTreeWidget::itemCollapsed(QTreeWidgetItem *item)

This signal is emitted when item was collapsed.

[signal] void QTreeWidget::itemDoubleClicked(QTreeWidgetItem *item, int column)

This signal is emitted when item is double-clicked, in the column column.

[signal] void QTreeWidget::itemExpanded(QTreeWidgetItem *item)

This signal is emitted when item was expanded.

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

Returns the item of the model index index, or nullptr if index is not valid.

See also indexFromItem().

[signal] void QTreeWidget::itemPressed(QTreeWidgetItem *item, int column)

This signal is emitted when a mouse button is pressed on item, in the column column.

[signal] void QTreeWidget::itemSelectionChanged()

This signal is emitted when the selection changed; selectedItems() tells what is selected now.

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

Scrolls so that item shows, where hint says, after expanding the items above it.

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

Returns the items that are selected, each of them once.

See also QTreeWidgetItem::isSelected() and itemSelectionChanged().

void QTreeWidget::setColumnCount(int columns)

Sets the number of columns of the tree to columns. Items keep the data that they have for columns that are taken away.

See also columnCount() and setHeaderLabels().

void QTreeWidget::setCurrentItem(QTreeWidgetItem *item)

Makes item the current item, and selects it unless the selection mode is NoSelection.

See also currentItem().

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

This is an overloaded function.

Makes the column column of item current.

void QTreeWidget::setHeaderLabel(const QString &label)

Sets the label of the first column of the header to label.

See also setHeaderLabels().

void QTreeWidget::setHeaderLabels(const QStringList &labels)

Sets the labels of the header to labels, one for each column from the first. The tree gets more columns if labels has more than it has.

See also setHeaderLabel() and setColumnCount().

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

Reimplements QTreeView::setSelectionModel().

Sets the selection model to selectionModel, and tells about its changes with currentItemChanged() and itemSelectionChanged().

int QTreeWidget::sortColumn() const

Returns the column that the items are sorted by, as the header shows it, or -1 if they are not sorted.

See also sortItems().

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

Sorts the items of all levels by the column column in the order order.

See also sortColumn() and QTreeWidgetItem::sortChildren().

QTreeWidgetItem * QTreeWidget::takeTopLevelItem(int index)

Removes the top-level item at position index and returns it, or nullptr if there is none. The caller owns it.

QTreeWidgetItem * QTreeWidget::topLevelItem(int index) const

Returns the top-level item at position index, or nullptr if there is none.

See also topLevelItemCount().

int QTreeWidget::topLevelItemCount() const

Returns the number of top-level items.

See also topLevelItem().

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

Returns the rectangle that item takes on the viewport, over all the columns, or an empty rectangle if it is not laid out.