TreeView QML Type

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

• List of all members, including inherited members

Properties

• rootIndex : QModelIndex (since 6.6)

Signals

• collapsed(row, recursively)
• expanded(row, depth)

Methods

• collapse(row)
• collapseRecursively(row) (since 6.4)
• int depth(row)
• expand(row)
• expandRecursively(row, depth) (since 6.4)
• expandToIndex(QModelIndex index) (since 6.4)
• bool isExpanded(row)
• 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.

Declare a TreeView

TreeView is a data bound control, so it cannot show anything without a data model. You cannot declare tree nodes in QML.

When you declare a TreeView, you need to specify:

• A data model. TreeView can work with data models that derive from QAbstractItemModel.
• A delegate. A delegate is a template that specifies how the tree nodes are displayed in the UI.

TreeView {
    // The model needs to be a QAbstractItemModel
    model: myTreeModel
    // You can set a custom delegate or use a built-in TreeViewDelegate
    delegate: TreeViewDelegate {}
}

Creating a data model

A TreeView only accepts a model that inherits QAbstractItemModel.

For information on how to create and use a custom tree model, see the example: Qt Quick Controls - Table of Contents.

Customize tree nodes

For better flexibility, TreeView itself doesn't 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 minimal as possible, perhaps 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 a custom delegate with an animating indicator is shown below:

import QtQuick
import QtQuick.Controls

ApplicationWindow {
    width: 800
    height: 600
    visible: true

    TreeView {
        id: treeView
        anchors.fill: parent
        anchors.margins: 10
        clip: true

        selectionModel: ItemSelectionModel {}

        // The model needs to be a QAbstractItemModel
        // model: yourTreeModel

        delegate: Item {
            implicitWidth: padding + label.x + label.implicitWidth + padding
            implicitHeight: label.implicitHeight * 1.5

            readonly property real indentation: 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
            required property int row
            required property int column
            required property bool current

            // Rotate indicator when expanded by the user
            // (requires TreeView to have a selectionModel)
            property Animation indicatorAnimation: NumberAnimation {
                target: indicator
                property: "rotation"
                from: expanded ? 0 : 90
                to: expanded ? 90 : 0
                duration: 100
                easing.type: Easing.OutQuart
            }
            TableView.onPooled: indicatorAnimation.complete()
            TableView.onReused: if (current) indicatorAnimation.start()
            onExpandedChanged: indicator.rotation = expanded ? 90 : 0

            Rectangle {
                id: background
                anchors.fill: parent
                color: row === treeView.currentRow ? palette.highlight : "black"
                opacity: (treeView.alternatingRows && row % 2 !== 0) ? 0.3 : 0.1
            }

            Label {
                id: indicator
                x: padding + (depth * indentation)
                anchors.verticalCenter: parent.verticalCenter
                visible: isTreeNode && hasChildren
                text: "▶"

                TapHandler {
                    onSingleTapped: {
                        let index = treeView.index(row, column)
                        treeView.selectionModel.setCurrentIndex(index, ItemSelectionModel.NoUpdate)
                        treeView.toggleExpanded(row)
                    }
                }
            }

            Label {
                id: label
                x: padding + (isTreeNode ? (depth + 1) * indentation : 0)
                anchors.verticalCenter: parent.verticalCenter
                width: parent.width - 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 bool 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.

End-user interaction

By default, TreeView toggles the expanded state of a row when you double tap on it. Since this is in conflict with double tapping to edit a cell, TreeView sets editTriggers to TableView.EditKeyPressed by default (which is different from TableView, which uses TableView.EditKeyPressed | TableView.DoubleTapped. If you change editTriggers to also contain TableView.DoubleTapped, toggling the expanded state with a double tap will be disabled.

Property Documentation

Signal Documentation

Method Documentation

expandToIndex(index)
forceLayout()
positionViewAtRow(rowAtIndex(index), Qt.AlignVCenter)

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