QTreeView Class

The QTreeView class provides a default model/view implementation of a tree view. More…

List of all members, including inherited members

Public Functions

Reimplemented Public Functions

Public Slots

Signals

Protected Functions

Reimplemented Protected Functions

Detailed Description

A QTreeView shows the items of a model as a tree with columns: each row is an item, an item with children has an arrow that opens and closes it, and a header names the columns. With a model that has no hierarchy it is a table with rows that are selected as a whole.

auto *view = new QTreeView;
view->setModel(model);
view->setSortingEnabled(true);
view->expandToDepth(0);
connect(view, &QTreeView::activated, this, &Window::open);

The user opens an item by clicking its arrow, by double-clicking it, or with the Right key; expand(), collapse(), expandAll() and their relatives do it from the program. Up, Down, Home, End and the page keys move the current item, and Left goes to the parent. Items are selected a row at a time by default; see setSelectionBehavior() and setSelectionMode().

header() is the header: its sections are the columns, which the user resizes by dragging their borders. With setSortingEnabled(), a click on a section sorts the model by that column, and a second click turns the order round; the model does the sorting, in QAbstractItemModel::sort(), so put a QSortFilterProxyModel between the view and a model that cannot sort.

Items are drawn and edited by the delegate; see QAbstractItemView and QStyledItemDelegate. A model that hands out its rows in steps, as QSqlQueryModel does, is asked for more when the view is scrolled to its end.

See also QTreeWidget, QAbstractItemView, QHeaderView and QStyledItemDelegate.

Differences from Qt

Member Function Documentation

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

Constructs a tree view with the given parent. It selects rows, and its header stretches the last column.

[override] QTreeView::~QTreeView()

Destroys the view.

[slot] void QTreeView::collapse(const QModelIndex &index)

Collapses the item index, so that its children no longer show, and emits collapsed(). If the current item was one of them, the item becomes the current item.

See also expand() and collapseAll().

[slot] void QTreeView::collapseAll()

Collapses all items.

See also expandAll().

[signal] void QTreeView::collapsed(const QModelIndex &index)

This signal is emitted when the item index was collapsed.

int QTreeView::columnAt(int x) const

Returns the column at the position x of the viewport, or -1 if there is none.

See also columnViewportPosition().

int QTreeView::columnViewportPosition(int column) const

Returns the position, on the viewport, of the left edge of the column column; it is negative for a column that is scrolled out to the left.

See also columnAt() and columnWidth().

int QTreeView::columnWidth(int column) const

Returns the width of the column column.

See also setColumnWidth().

[override, protected] void QTreeView::currentChanged(const QModelIndex &current, const QModelIndex &previous)

Reimplements QAbstractItemView::currentChanged().

Handles the change of the current item from previous to current as the base class does.

[virtual, protected] void QTreeView::drawBranches(QPainter *painter, const QRect &rect, const QModelIndex &index) const

Draws the arrow of the item index with painter, in rect: the room that the indentation leaves in front of the item. The arrow points right for an item that can be expanded and down for one that is. Nothing is drawn for an item without children. A subclass draws its own branches here.

[virtual, protected] void QTreeView::drawRow(QPainter *painter, const QStyleOptionViewItem &options, const QModelIndex &index) const

Draws the row of the item index with painter: its background, its arrow, and its item in each column, through the delegates. options has the palette, the font and the state that all items share, and in its rectangle the whole row. A subclass that draws rows in its own way reimplements this.

[slot] void QTreeView::expand(const QModelIndex &index)

Expands the item index, so that its children show, and emits expanded(). Nothing happens if it is expanded already or has no children.

See also collapse(), expandAll() and isExpanded().

[slot] void QTreeView::expandAll()

Expands all items that have children.

See also collapseAll() and expandToDepth().

[signal] void QTreeView::expanded(const QModelIndex &index)

This signal is emitted when the item index was expanded, by the user or by the program.

[slot] void QTreeView::expandRecursively(const QModelIndex &index, int depth = -1)

Expands the item index and its descendants down to depth levels below it: with 0 only the item, with -1 all of them. An invalid index stands for the top of the model.

See also expandAll() and expandToDepth().

bool QTreeView::expandsOnDoubleClick() const

Returns whether a double click on an item with children opens or closes it. The default is true.

See also setExpandsOnDoubleClick().

[slot] void QTreeView::expandToDepth(int depth)

Expands the items down to the level depth and collapses nothing: with 0 only the top items are expanded, with 1 their children too, and with -1 every item.

See also expandAll() and expandRecursively().

QHeaderView * QTreeView::header() const

Returns the header of the view, whose sections are the columns.

See also setHeaderHidden() and setSortingEnabled().

int QTreeView::indentation() const

Returns how far, in pixels, the items of each level are moved to the right of their parents. The default is 20.

See also setIndentation().

QModelIndex QTreeView::indexAbove(const QModelIndex &index) const

Returns the item that is laid out above the item index, in the same column, or an invalid index if there is none.

See also indexBelow().

[override] QModelIndex QTreeView::indexAt(const QPoint &point) const

Reimplements QAbstractItemView::indexAt().

Returns the item at point of the viewport: the one of the row and the column there, also where the indentation and the arrow of the row are.

QModelIndex QTreeView::indexBelow(const QModelIndex &index) const

Returns the item that is laid out below the item index, in the same column, or an invalid index if there is none.

See also indexAbove().

bool QTreeView::isExpanded(const QModelIndex &index) const

Returns true if the item index is expanded, so that its children show; otherwise returns false.

See also expand() and setExpanded().

bool QTreeView::isHeaderHidden() const

Returns whether the header is hidden. The default is false.

See also setHeaderHidden().

bool QTreeView::isSortingEnabled() const

Returns whether the user can sort the items by clicking on the header. The default is false.

See also setSortingEnabled().

bool QTreeView::itemsExpandable() const

Returns whether the user can open and close items. The default is true.

See also setItemsExpandable().

[override, protected] void QTreeView::keyPressEvent(QKeyEvent *event)

Reimplements QAbstractItemView::keyPressEvent().

The arrow, Home, End and page keys move the current item; Plus, Minus and the asterisk open and close items; Return and Enter activate the current item; F2 edits it, as typing does with the AnyKeyPressed trigger; Space toggles a check box or the selection; Control+A selects everything.

[override, protected] void QTreeView::mouseDoubleClickEvent(QMouseEvent *event)

Reimplements QAbstractItemView::mouseDoubleClickEvent().

A double click on an item emits doubleClicked() and edits the item if DoubleClicked is one of the edit triggers and the item can be edited; otherwise it emits activated() and, if expandsOnDoubleClick() is on, opens or closes the item.

[override, protected] void QTreeView::mousePressEvent(QMouseEvent *event)

Reimplements QAbstractItemView::mousePressEvent().

A press on the arrow of an item opens or closes the item; a press on an item makes it the current item and selects it the way the selection mode and the Shift and Control keys say.

[override, protected] void QTreeView::mouseReleaseEvent(QMouseEvent *event)

Reimplements QAbstractItemView::mouseReleaseEvent().

A release on the item that was pressed is a click: clicked() is emitted, the delegate gets the event, for a check box, and with the SelectedClicked trigger an item that was selected already is edited.

[override, protected] QModelIndex QTreeView::moveCursor(CursorAction cursorAction, Qt::KeyboardModifiers modifiers)

Reimplements QAbstractItemView::moveCursor().

Returns the item that cursorAction leads to from the current item, in the rows as they are laid out. Left closes an open item or goes to the parent; Right opens an item or goes to its first child. modifiers is not used.

[override, protected] void QTreeView::paintEvent(QPaintEvent *event)

Reimplements QAbstractItemView::paintEvent().

[override] void QTreeView::reset()

Reimplements QAbstractItemView::reset().

Collapses everything and lays the items of the model out anew.

void QTreeView::resetIndentation()

Gives the view its default indentation again.

See also setIndentation().

[slot] void QTreeView::resizeColumnToContents(int column)

Makes the column column as wide as the widest of its items that are laid out, and its header, need.

See also setColumnWidth().

[override, protected] void QTreeView::resizeEvent(QResizeEvent *event)

Reimplements QAbstractItemView::resizeEvent().

bool QTreeView::rootIsDecorated() const

Returns whether the top items have arrows for opening and closing them, and the room for them. The default is true.

See also setRootIsDecorated().

[protected] int QTreeView::rowHeight(const QModelIndex &index) const

Returns the height of the row of the item index, or 0 if index is not valid. All rows have the same height.

[override, protected] void QTreeView::rowsAboutToBeRemoved(const QModelIndex &parent, int start, int end)

Reimplements QAbstractItemView::rowsAboutToBeRemoved().

Moves the current item off the rows start to end of parent before they are removed: to the row after them, the row before them, or their parent.

[override, protected] void QTreeView::rowsInserted(const QModelIndex &parent, int start, int end)

Reimplements QAbstractItemView::rowsInserted().

Lays the items out again after the rows start to end were inserted under parent.

[override, protected] void QTreeView::scrollContentsBy(int dx, int dy)

Reimplements QAbstractItemView::scrollContentsBy().

Moves the header with the columns, and asks a model that hands out its rows in steps for more when the end is reached; dx and dy are not used.

[override] void QTreeView::scrollTo(const QModelIndex &index, ScrollHint hint = EnsureVisible)

Reimplements QAbstractItemView::scrollTo().

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

[override] void QTreeView::selectAll()

Reimplements QAbstractItemView::selectAll().

Selects all the items that are laid out, if the selection mode allows several: the items under a collapsed item are not selected.

void QTreeView::setColumnWidth(int column, int width)

Sets the width of the column column to width.

See also columnWidth() and resizeColumnToContents().

void QTreeView::setExpanded(const QModelIndex &index, bool expand)

Expands the item index if expand is true, and collapses it otherwise.

See also expand(), collapse() and isExpanded().

void QTreeView::setExpandsOnDoubleClick(bool enable)

Sets whether a double click on an item with children opens or closes it to enable. A double click that starts an editor does not.

See also expandsOnDoubleClick().

void QTreeView::setHeaderHidden(bool hide)

Hides the header if hide is true, and shows it otherwise.

See also isHeaderHidden() and header().

void QTreeView::setIndentation(int i)

Sets the indentation of each level of the tree to i pixels.

See also indentation() and resetIndentation().

void QTreeView::setItemsExpandable(bool enable)

Sets whether the user can open and close items to enable. The program still can.

See also itemsExpandable().

[override] void QTreeView::setModel(QAbstractItemModel *model)

Reimplements QAbstractItemView::setModel().

Makes the view show model. Nothing is expanded.

[override] void QTreeView::setRootIndex(const QModelIndex &index)

Reimplements QAbstractItemView::setRootIndex().

Shows the children of index as the top items of the view.

void QTreeView::setRootIsDecorated(bool show)

Sets whether the top items have arrows for opening and closing them to show. Turn it off for a model that is a plain list or table, so that its first column starts at the left edge.

See also rootIsDecorated().

void QTreeView::setSortingEnabled(bool enable)

Sets whether the user can sort the items to enable. When it is on, the header shows which column the items are sorted by and in which order, a click on a section sorts by that column, and a click on the section that is sorted by turns the order round. If the header says that a column is sorted by already, the model is sorted by it at once.

The model does the sorting; one that does not implement QAbstractItemModel::sort() stays as it is.

See also isSortingEnabled() and sortByColumn().

void QTreeView::setUniformRowHeights(bool uniform)

Keeps uniform for uniformRowHeights(). In Qt this promises that all rows have the same height, so that the view can lay them out faster; in Nt they always have.

[override, protected] void QTreeView::showEvent(QShowEvent *event)

Reimplements QAbstractItemView::showEvent().

[override] QSize QTreeView::sizeHint() const

Reimplements QAbstractItemView::sizeHint().

Returns a size for a view of a few columns and rows.

void QTreeView::sortByColumn(int column, Qt::SortOrder order)

Sorts the model by the column column in the order order, and has the header show it. A column of -1 only takes the sort indicator away.

See also setSortingEnabled() and QAbstractItemModel::sort().

bool QTreeView::uniformRowHeights() const

Returns the value that setUniformRowHeights() set. All rows of the view have the same height either way.

[override, protected] bool QTreeView::viewportEvent(QEvent *event)

Reimplements QAbstractItemView::viewportEvent().

Shows the tool tip of the item under the mouse, which the model returns for Qt::ToolTipRole; other event are handled as in the base class.

[override] QRect QTreeView::visualRect(const QModelIndex &index) const

Reimplements QAbstractItemView::visualRect().

Returns the rectangle of the item index on the viewport: its cell, which in the first column starts after the indentation of the item. It is empty if the item is not laid out, because a parent of it is collapsed.