TreeView QML Type | Qt Quick 6.3.0

- Qt 6.3
- Qt Quick
- QML Types
- TreeView QML Type
- Qt 6.3.0 Reference Documentation

# TreeView QML Type

Provides a tree view to display data from a QAbstractItemModel. More...

Import Statement: | import QtQuick
Since: | Qt 6.3
Inherits: | TableView

- List of all members, including inherited members

## Signals

- collapsed(row)
- expanded(row)

## Methods

- point cellAtIndex(modelIndex)
- collapse(row)
- int columnAtIndex(modelIndex)
- int depth(row)
- expand(row)
- bool isExpanded(row)
- QModelIndex modelIndex(point cell)
- QModelIndex modelIndex(row, column)
- int rowAtIndex(modelIndex)
- toggleExpanded(row)

## Detailed Description

A TreeView has a model that defines the data to be displayed, and a delegate that defines how the data should be displayed.

TreeView inherits TableView. This means that even if the model has a parent-child tree structure, TreeView is internally using a proxy model that converts that structure into a flat table model that can be rendered by TableView. Each node in the tree ends up occupying one row in the table, where the first column renders the tree itself. By indenting each delegate item in that column according to its parent-child depth in the model, it will end up looking like a tree, even if it's technically still just a flat list of items.

To allow for maximum flexibility, TreeView itself will not position the delegate items into a tree structure. This burden is placed on the delegate. Qt Quick Controls offers a ready-made TreeViewDelegate that can be used for this, which has the advantage that it works out-of-the-box and renders a tree which follows the style of the platform where the application runs.

Even if TreeViewDelegate is customizable, there might be situations where you want to render the tree in a different way, or ensure that the delegate ends up as mininal as possible, e.g for performance reasons. Creating your own delegate from scratch is easy, since TreeView offers a set of properties that can be used to position and render each node in the tree correctly.

An example of how a custom delegate could look like is shown below:

     import QtQuick

     Window {
         width: 600
         height: 400
         visible: true

         TreeView {
             anchors.fill: parent
             // The model needs to be a QAbstractItemModel
             // model: yourTreeModel

             delegate: Item {
                 id: root

                 implicitWidth: padding + label.x + label.implicitWidth + padding
                 implicitHeight: label.implicitHeight * 1.5

                 readonly property real indent: 20
                 readonly property real padding: 5

                 // Assigned to by TreeView:
                 required property TreeView treeView
                 required property bool isTreeNode
                 required property bool expanded
                 required property int hasChildren
                 required property int depth

                 TapHandler {
                     onTapped: treeView.toggleExpanded(row)
                 }

                 Text {
                     id: indicator
                     visible: root.isTreeNode && root.hasChildren
                     x: padding + (root.depth * root.indent)
                     text: root.expanded ? "▼" : "▶"
                 }

                 Text {
                     id: label
                     x: padding + (root.isTreeNode ? (root.depth + 1) * root.indent : 0)
                     width: root.width - root.padding - x
                     clip: true
                     text: model.display
                 }
             }
         }
     }

The properties that are marked as `required` will be filled in by TreeView, and are similar to attached properties. By marking them as required, the delegate indirectly informs TreeView that it should take responsibility for assigning them values. The following required properties can be added to a delegate:

- `required property TreeView treeView` - Points to the TreeView that contains the delegate item.
- `required property bool isTreeNode` - Is `true` if the delegate item represents a node in the tree. Only one column in the view will be used to draw the tree, and therefore, only delegate items in that column will have this property set to `true`. A node in the tree should typically be indented according to its `depth`, and show an indicator if `hasChildren` is `true`. Delegate items in other columns will have this property set to `false`, and will show data from the remaining columns in the model (and typically not be indented).
- `required property bool expanded` - Is `true` if the model item drawn by the delegate is expanded in the view.
- `required property int hasChildren` - Is `true` if the model item drawn by the delegate has children in the model.
- `required property int depth` - Contains the depth of the model item drawn by the delegate. The depth of a model item is the same as the number of ancestors it has in the model.

See also Required Properties.

Note: A TreeView only accept models that inherits QAbstractItemModel.

## Signal Documentation

collapsed(row)

This signal is emitted when a row is collapsed in the view.

Note: The corresponding handler is `onCollapsed`.

See also expanded(), expand(), collapse(), and toggleExpanded().

expanded(row)

This signal is emitted when a row is expanded in the view.

Note: The corresponding handler is `onExpanded`.

See also collapsed(), expand(), collapse(), and toggleExpanded().

## Method Documentation

point cellAtIndex(modelIndex)

Convenience function for doing:

`Qt.point(columnAtIndex(`modelIndex`), rowAtIndex(`modelIndex`))`

A cell is simply a point that combines row and column into a single type. Note that `point.x` will map to the column, and `point.y` will map to the row.

collapse(row)

Collapses the tree node at the given row in the view.

row should be the row in the view (table row), and not a row in the model.

Note: this function will not affect the model, only the visual representation in the view.

See also expand() and isExpanded().

int columnAtIndex(modelIndex)

Returns the column in the view that maps to modelIndex in the model.

The assigned model, which is a tree model, is converted to a flat table model internally so that it can be shown in a TableView (which TreeView inherits). This function can be used whenever you need to know which column in the view the given model index maps to.

Note: modelIndex must be a QModelIndex.

See also rowAtIndex() and modelIndex().

int depth(row)

Returns the depth (the number of parents up to the root) of the given row.

row should be the row in the view (table row), and not a row in the model. If row is not between `0` and rows, the return value will be `-1`.

See also modelIndex().

expand(row)

Expands the tree node at the given row in the view.

row should be the row in the view (table row), and not a row in the model.

Note: this function will not affect the model, only the visual representation in the view.

See also collapse() and isExpanded().

bool isExpanded(row)

Returns if the given row in the view is shown as expanded.

row should be the row in the view (table row), and not a row in the model. If row is not between `0` and rows, the return value will be `false`.

QModelIndex modelIndex(point cell)

Convenience function for doing:

     modelIndex(cell.y, cell.x)

A cell is simply a point that combines row and column into a single type. Note that `point.x` will map to the column, and `point.y` will map to the row.

QModelIndex modelIndex(row, column)

Returns the QModelIndex that maps to row and column in the view.

row and column should be the row and column in the view (table row and table column), and not a row and column in the model.

The assigned model, which is a tree model, is converted to a flat table model internally so that it can be shown in a TableView (which TreeView inherits). This function can be used whenever you need to know which index in the tree model maps to the given row and column in the view.

See also rowAtIndex() and columnAtIndex().

int rowAtIndex(modelIndex)

Returns the row in the view that maps to modelIndex in the model.

The assigned model, which is a tree model, is converted to a flat table model internally so that it can be shown in a TableView (which TreeView inherits). This function can be used whenever you need to know which row in the view the given model index maps to.

Note: modelIndex must be a QModelIndex.

See also columnAtIndex() and modelIndex().

toggleExpanded(row)

Toggles if the tree node at the given row should be expanded. This is a convenience for doing:

     if (isExpanded(row))
         collapse(row)
     else
         expand(row)

row should be the row in the view (table row), and not a row in the model.