Back to Doc.qt.io
Contact Us Blog Download Qt

TreeModel QML Type

Encapsulates a simple tree model. More...

Import Statement: import Qt.labs.qmlmodels
Since: Qt 6.10

Properties

Methods

  • appendRow(object treeRow)
  • appendRow(QModelIndex parent, object treeRow)
  • clear()
  • variant data(QModelIndex index, string role)
  • object getRow(const QModelIndex &rowIndex)
  • QModelIndex index(list<int> treeIndex, int column)
  • QModelIndex index(int row, int column, object parent)
  • removeRow(QModelIndex rowIndex)
  • bool setData(QModelIndex index, string role, variant value)
  • setRow(QModelIndex rowIndex, object treeRow)

Detailed Description

The TreeModel type stores JavaScript/JSON objects as data for a tree model that can be used with TreeView. It is intended to support very simple models without requiring the creation of a custom QAbstractItemModel subclass in C++.

import QtQuick
import QtQuick.Controls
import Qt.labs.qmlmodels

ApplicationWindow {
    visible: true
    width: 500
    height: 500

    TreeView {
        id: treeView
        anchors.fill: parent

        selectionModel: ItemSelectionModel {}

        model: TreeModel {
            id: treeModel

            TableModelColumn {
                display: "checked"
            }
            TableModelColumn {
                display: "size"
            }
            TableModelColumn {
                display: "type"
            }
            TableModelColumn {
                display: "name"
            }
            TableModelColumn {
                display: "lastModified"
            }

            rows: [{
                    checked: false,
                    size: "—",
                    type: "folder",
                    name: "Documents",
                    lastModified: "2025-07-01",
                    rows: [{
                            checked: true,
                            size: "24 KB",
                            type: "file",
                            name: "Resume.pdf",
                            lastModified: "2025-06-20",
                        }, {
                            checked: false,
                            size: "2 MB",
                            type: "folder",
                            name: "Reports",
                            lastModified: "2025-06-10",
                            rows: [{
                                    checked: true,
                                    size: "850 KB",
                                    type: "file",
                                    name: "Q2_Report.docx",
                                    lastModified: "2025-06-15",
                                }, {
                                    checked: false,
                                    size: "1.2 MB",
                                    type: "file",
                                    name: "Q3_Plan.xlsx",
                                    lastModified: "2025-06-18",
                                }]
                        }]
                },
                {
                    checked: false,
                    size: "—",
                    type: "folder",
                    name: "Pictures",
                    lastModified: "2025-05-30",
                    rows: [{
                            checked: true,
                            size: "3.5 MB",
                            type: "file",
                            name: "Vacation.jpg",
                            lastModified: "2025-05-15",
                        }, {
                            checked: false,
                            size: "2.1 MB",
                            type: "file",
                            name: "Family.png",
                            lastModified: "2025-05-20",
                        }]
                }
            ]
        }

        delegate: TreeViewDelegate {}
    }
}

The model's initial data is set with either the rows property or by calling appendRow(). Each column in the model is specified by declaring a TableModelColumn instance, where the order of each instance determines its column index. Once the model's Component::completed() signal has been emitted, the columns and roles will have been established and are then fixed for the lifetime of the model.

Supported Row Data Structures

Each row represents a node in the tree. Each node has the same type of columns. The TreeModel is designed to work with JavaScript/JSON data so each row is a list of simple key-value pairs:

                {
                    checked: false,
                    size: "—",
                    type: "folder",
                    name: "Pictures",
                    lastModified: "2025-05-30",
                    rows: [{
                            checked: true,
                            size: "3.5 MB",
                            type: "file",
                            name: "Vacation.jpg",
                            lastModified: "2025-05-15",
                        }, {
                            checked: false,
                            size: "2.1 MB",
                            type: "file",
                            name: "Family.png",
                            lastModified: "2025-05-20",
                        }]
                }

A node can have child nodes and these will be stored in an array associated with the "rows" key. "rows" is reserved for this purpose: only the list of child nodes should be associated with this key.

The model is manipulated via QModelIndices. To access a specific row/node, the getRow() function can be used. It's also possible to access the model's JavaScript data directly via the rows property, but it is not possible to modify the model data this way.

To add new rows, use appendRow(). To modify existing rows, use setRow(), removeRow() and clear().

Property Documentation

columnCount : int [read-only]

This read-only property holds the number of columns in the model.

The number of columns is fixed for the lifetime of the model after the rows property is set or appendRow() is called for the first time.


rows : object

This property holds the model data in the form of an array of rows.

See also getRow(), setRow(), appendRow(), clear(), and columnCount.


Method Documentation

appendRow(object treeRow)

Appends treeRow to the root node.

See also setRow() and removeRow().


appendRow(QModelIndex parent, object treeRow)

Appends a new treeRow to parent, with the values (cells) in treeRow.

treeModel.appendRow(index, {
    checked: false,
    size: "-",
    type: "folder",
    name: "Orders",
    lastModified: "2025-07-02",
    rows: [
        {
            checked: true,
            size: "38 KB",
            type: "file",
            name: "monitors.xlsx",
            lastModified: "2025-07-02"
        },
        {
            checked: true,
            size: "54 KB",
            type: "file",
            name: "notebooks.xlsx",
            lastModified: "2025-07-02"
        }
    ]
});

If parent is invalid, treeRow gets appended to the root node.

See also setRow() and removeRow().


clear()

Removes all rows from the model.

See also removeRow().


variant data(QModelIndex index, string role)

Returns the data from the TreeModel at the given index belonging to the given role.

See also index() and setData().


object getRow(const QModelIndex &rowIndex)

Returns the treeRow at rowIndex in the model.

Note: the returned object cannot be used to modify the contents of the model; use setTreeRow() instead.

See also setRow(), appendRow(), and removeRow().


QModelIndex index(list<int> treeIndex, int column)

Returns a QModelIndex object referencing the given treeIndex and column, which can be passed to the data() function to get the data from that cell, or to setData() to edit the contents of that cell.

The first parameter treeIndex represents a path of row numbers tracing from the root to the desired row and is used for navigation inside the tree. This is best explained through an example.

  • The root of the tree is special, as it can be referenced by an invalid QModelIndex.
  • Node A is the first child of the root and the corresponding treeIndex is [0].
  • Node B is the first child of node A. Since the treeIndex of A is [0] the treeIndex of B will be [0,0].
  • Node C is the second child of A and its treeIndex is [0,1].
  • Node D is the third child of A and its treeIndex is [0,2].
  • Node E is the second child of the root and its treeIndex is [1].
  • Node F is the third child of the root and its treeIndex is [2].

With this overload it is possible to obtain a QModelIndex to a node without having a QModelIndex to its parent node.

If no node is found by the list specified, an invalid model index is returned. Please note that an invalid model index is referencing the root of the node.

See also QModelIndex and related Classes in QML and data().


QModelIndex index(int row, int column, object parent)

Returns a QModelIndex object referencing the given row and column of a given parent which can be passed to the data() function to get the data from that cell, or to setData() to edit the contents of that cell.

See also QModelIndex and related Classes in QML and data().


removeRow(QModelIndex rowIndex)

Removes the TreeRow referenced by rowIndex from the model.

treeModel.removeTreeRow(rowIndex)

See also clear().


bool setData(QModelIndex index, string role, variant value)

Inserts or updates the data field named by role in the TreeRow at the given index with value. Returns true if sucessful, false if not.

See also data() and index().


setRow(QModelIndex rowIndex, object treeRow)

Replaces the TreeRow at rowIndex in the model with treeRow. A row with child rows will be rejected.

All columns/cells must be present in treeRow, and in the correct order. The child rows of the row remain unaffected.

treeModel.setRow(rowIndex, {
    checked: true,
    size: "-",
    type: "folder",
    name: "Subtitles",
    lastModified: "2025-07-07",
    iconColor: "blue"
});

See also appendRow().


© 2025 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.