TableView QML Type

C++ Models▲

#include <qqml.h>
#include <QAbstractTableModel>

class TableModel : public QAbstractTableModel
{
    Q_OBJECT
    QML_ELEMENT
    QML_ADDED_IN_MINOR_VERSION(1)

public:
    int rowCount(const QModelIndex & = QModelIndex()) const override
    {
        return 200;
    }

    int columnCount(const QModelIndex & = QModelIndex()) const override
    {
        return 200;
    }

    QVariant data(const QModelIndex &index, int role) const override
    {
        switch (role) {
            case Qt::DisplayRole:
                return QString("%1, %2").arg(index.column()).arg(index.row());
            default:
                break;
        }

        return QVariant();
    }

    QHash<int, QByteArray> roleNames() const override
    {
        return { {Qt::DisplayRole, "display"} };
    }
};

import QtQuick 2.12
import TableModel 0.1

TableView {
    anchors.fill: parent
    columnSpacing: 1
    rowSpacing: 1
    clip: true

    model: TableModel {}

    delegate: Rectangle {
        implicitWidth: 100
        implicitHeight: 50
        Text {
            text: display
        }
    }
}

QML Models▲

import QtQuick 2.14
import Qt.labs.qmlmodels 1.0

TableView {
    anchors.fill: parent
    columnSpacing: 1
    rowSpacing: 1
    clip: true

    model: TableModel {
        TableModelColumn { display: "name" }
        TableModelColumn { display: "color" }

        rows: [
            {
                "name": "cat",
                "color": "black"
            },
            {
                "name": "dog",
                "color": "brown"
            },
            {
                "name": "bird",
                "color": "white"
            }
        ]
    }

    delegate: Rectangle {
        implicitWidth: 100
        implicitHeight: 50
        border.width: 1

        Text {
            text: display
            anchors.centerIn: parent
        }
    }
}

TableView recycles delegate items by default, instead of instantiating from the delegate whenever new rows and columns are flicked into view. This approach gives a huge performance boost, depending on the complexity of the delegate.

When an item is flicked out, it moves to the reuse pool, which is an internal cache of unused items. When this happens, the TableView::pooled signal is emitted to inform the item about it. Likewise, when the item is moved back from the pool, the TableView::reused signal is emitted.

Any item properties that come from the model are updated when the item is reused. This includes index, row, and column, but also any model roles.

If an item has timers or animations, consider pausing them on receiving the TableView::pooled signal. That way you avoid using the CPU resources for items that are not visible. Likewise, if an item has resources that cannot be reused, they could be freed up.

If you don't want to reuse items or if the delegate cannot support it, you can set the reuseItems property to false.

The following example shows a delegate that animates a spinning rectangle. When it is pooled, the animation is temporarily paused:

Component {
    id: tableViewDelegate
    Rectangle {
        implicitWidth: 100
        implicitHeight: 50

        TableView.onPooled: rotationAnimation.pause()
        TableView.onReused: rotationAnimation.resume()

        Rectangle {
            id: rect
            anchors.centerIn: parent
            width: 40
            height: 5
            color: "green"

            RotationAnimation {
                id: rotationAnimation
                target: rect
                duration: (Math.random() * 2000) + 200
                from: 0
                to: 359
                running: true
                loops: Animation.Infinite
            }
        }
    }
}

When a new column is flicked into view, TableView will determine its width by calling the columnWidthProvider function. TableView does not store row height or column width, as it's designed to support large models containing any number of rows and columns. Instead, it will ask the application whenever it needs to know.

TableView uses the largest implicitWidth among the items as the column width, unless the columnWidthProvider property is explicitly set. Once the column width is found, all other items in the same column are resized to this width, even if new items that are flicked in later have larger implicitWidth. Setting an explicit width on an item is ignored and overwritten.

If you change the values that a rowHeightProvider or a columnWidthProvider return for rows and columns inside the viewport, you must call forceLayout. This informs TableView that it needs to use the provider functions again to recalculate and update the layout.

Since Qt 5.13, if you want to hide a specific column, you can return 0 from the columnWidthProvider for that column. Likewise, you can return 0 from the rowHeightProvider to hide a row. If you return a negative number, TableView will fall back to calculate the size based on the delegate items.

The following example shows how to set a simple columnWidthProvider together with a timer that modifies the values the function returns. When the array is modified, forceLayout is called to let the changes take effect:

TableView {
    id: tableView

    property var columnWidths: [100, 50, 80, 150]
    columnWidthProvider: function (column) { return columnWidths[column] }

    Timer {
        running: true
        interval: 2000
        onTriggered: {
            tableView.columnWidths[2] = 150
            tableView.forceLayout();
        }
    }
}

All new items that are instantiated from the delegate are parented to the contentItem with the z value, 1. You can add your own items inside the Tableview, as child items of the Flickable. By controlling their z value, you can make them be on top of or underneath the table items.

Here is an example that shows how to add some text on top of the table, that moves together with the table as you flick:

TableView {
    id: tableView

    topMargin: header.implicitHeight

    Text {
        id: header
        text: "A table header"
    }
}

You can add selection support to TableView by assigning an ItemSelectionModel to the selectionModel property. It will then use this model to control which delegate items should be shown as selected, and which item should be shown as current. You can set selectionBehavior to control if the user should be allowed to select individual cells, rows, or columns.

To find out whether a delegate is selected or current, declare the following properties:

delegate: Item {
    required property bool selected
    required property bool current
    // ...
}

The following snippet shows how an application can render the delegate differently depending on the selected property:

    TableView {
        id: tableView
        anchors.fill: parent
        clip: true

        model: TableModel {
            TableModelColumn { display: "name" }
            rows: [ { "name": "Harry" }, { "name": "Hedwig" } ]
        }

        selectionModel: ItemSelectionModel {}

        delegate: Rectangle {
            implicitWidth: 100
            implicitHeight: 30
            color: selected ? "blue" : "lightgray"

            required property bool selected

            Text { text: display }
        }
    }

The currentRow and currentColumn properties can also be useful if you need to render a delegate differently depending on if it lies on the same row or column as the current item.

In order to support keyboard navigation, you need to assign an ItemSelectionModel to the selectionModel property. TableView will then use this model to manipulate the model's currentIndex. You can disable keyboard navigation fully (in case you want to implement your own key handlers) by setting keyNavigationEnabled to false.

Implementing copy and paste operations for a TableView usually also includes using a QUndoStack (or some other undo/redo framework). The QUndoStack can be used to store the different operations done on the model, like adding or removing rows, or pasting data from the clipboard, with a way to undo it again later. However, an accompanying QUndoStack that describes the possible operations, and how to undo them, should be designed according to the needs of the model and the application. As such, TableView doesn't offer a built-in API for handling copy and paste.

The following snippet can be used as a reference for how to add copy and paste support to your model and TableView. It uses the existing mime data API in QAbstractItemModel, together with QClipboard. The snippet will work as it is, but can also be extended to use a QUndoStack.