TableView QML Type

Provides a table view of items to display data from a model. More...

• List of all members, including inherited members

Properties

• columnSpacing : real
• columnWidthProvider : var
• columns : int
• contentHeight : real
• contentWidth : real
• delegate : Component
• model : model
• reuseItems : bool
• rowHeightProvider : var
• rowSpacing : real
• rows : int
• syncDirection : Qt::Orientations
• syncView : TableView

Attached Properties

• view : TableView

Attached Signals

• pooled()
• reused()

Methods

• forceLayout()

Detailed Description

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

TableView inherits Flickable. This means that while the model can have any number of rows and columns, only a subsection of the table is usually visible inside the viewport. As soon as you flick, new rows and columns enter the viewport, while old ones exit and are removed from the viewport. The rows and columns that move out are reused for building the rows and columns that move into the viewport. As such, the TableView support models of any size without affecting performance.

A TableView displays data from models created from built-in QML types such as ListModel and XmlListModel, which populates the first column only in a TableView. To create models with multiple columns, either use TableModel or a C++ model that inherits QAbstractItemModel.

Example Usage

C++ Models

The following example shows how to create a model from C++ with multiple columns:

 #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"} };
     }
 };

And then how to use it from QML:

 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

For prototyping and displaying very simple data (from a web API, for example), TableModel can be used:

 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
         }
     }
 }

Reusing items

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.

Note: Avoid storing any state inside a delegate. If you do, reset it manually on receiving the TableView::reused signal.

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.

Note: While an item is in the pool, it might still be alive and respond to connected signals and bindings.

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
             }
         }
     }
 }

Row heights and column widths

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.

Note: The calculated width of a column is discarded when it is flicked out of the viewport, and is recalculated if the column is flicked back in. The calculation is always based on the items that are visible when the column is flicked in. This means that column width can be different each time, depending on which row you're at when the column enters. You should therefore have the same implicitWidth for all items in a column, or set columnWidthProvider. The same logic applies for the row height calculation.

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.

Note: The size of a row or column should be a whole number to avoid sub-pixel alignment of 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();
         }
     }
 }

Overlays and underlays

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"
     }
 }

Property Documentation

Attached Property Documentation

Attached Signal Documentation

Method Documentation