TableView QML Type

Fournit une vue en tableau des éléments pour afficher les données d'un modèle. Plus d'informations...

• Liste de tous les membres, y compris les membres hérités
• Membres obsolètes

Propriétés

• alternatingRows : bool
• animate : bool (since 6.4)
• bottomRow : int
• columnSpacing : real
• columnWidthProvider : var
• columns : int
• contentHeight : real
• contentWidth : real
• currentColumn : int
• currentRow : int
• delegate : Component
• delegateModelAccess : enumeration (since 6.10)
• editTriggers : enumeration (since 6.5)
• keyNavigationEnabled : bool (since 6.4)
• leftColumn : int
• model : model
• pointerNavigationEnabled : bool (since 6.4)
• resizableColumns : bool (since 6.5)
• resizableRows : bool (since 6.5)
• reuseItems : bool
• rightColumn : int
• rowHeightProvider : var
• rowSpacing : real
• rows : int
• selectionBehavior : enumeration (since 6.4)
• selectionMode : enumeration (since 6.6)
• selectionModel : ItemSelectionModel (since 6.2)
• syncDirection : Qt::Orientations
• syncView : TableView
• topRow : int

Propriétés rattachées

• editDelegate : Component
• view : TableView

Signaux

• columnMoved(int logicalIndex, int oldVisualIndex, int newVisualIndex) (since 6.8)
• layoutChanged() (since 6.5)
• rowMoved(int logicalIndex, int oldVisualIndex, int newVisualIndex) (since 6.8)

Signaux attachés

• commit()
• pooled()
• reused()

Méthodes

• point cellAtIndex(QModelIndex modelIndex) (since 6.4)
• Point cellAtPosition(point position, bool includeSpacing)
• Point cellAtPosition(real x, real y, bool includeSpacing)
• void clearColumnReordering() (since 6.8)
• void clearColumnWidths()
• void clearRowHeights()
• void clearRowReordering() (since 6.8)
• void closeEditor() (since 6.5)
• int columnAtIndex(QModelIndex modelIndex) (since 6.4)
• real columnWidth(int column) (since 6.2)
• void edit(QModelIndex modelIndex) (since 6.5)
• real explicitColumnWidth(int column)
• real explicitRowHeight(int row)
• void forceLayout()
• real implicitColumnWidth(int column) (since 6.2)
• real implicitRowHeight(int row) (since 6.2)
• QModelIndex index(int row, int column) (since 6.4.3)
• bool isColumnLoaded(int column) (since 6.2)
• bool isRowLoaded(int row) (since 6.2)
• Item itemAtCell(point cell)
• Item itemAtIndex(QModelIndex index) (since 6.5)
• QModelIndex modelIndex(point cell) (since 6.4)
• void moveColumn(int source, int destination) (since 6.8)
• void moveRow(int source, int destination) (since 6.8)
• void positionViewAtCell(point cell, PositionMode mode, point offset, rect subRect)
• void positionViewAtColumn(int column, PositionMode mode, real offset, rect subRect)
• void positionViewAtIndex(QModelIndex index, PositionMode mode, point offset, rect subRect) (since 6.5)
• void positionViewAtRow(int row, PositionMode mode, real offset, rect subRect)
• int rowAtIndex(QModelIndex modelIndex) (since 6.4)
• real rowHeight(int row) (since 6.2)
• void setColumnWidth(int column, real size)
• void setRowHeight(int row, real size)

Description détaillée

Un TableView possède un model qui définit les données à afficher et un delegate qui définit la manière dont les données doivent être affichées.

TableView hérite de Flickable. Cela signifie que, bien que le modèle puisse avoir un nombre illimité de lignes et de colonnes, seule une sous-section du tableau est généralement visible à l'intérieur de la fenêtre de visualisation. Dès que vous cliquez, de nouvelles lignes et colonnes entrent dans la fenêtre de visualisation, tandis que les anciennes en sortent et sont supprimées de la fenêtre de visualisation. Les lignes et les colonnes qui sortent sont réutilisées pour construire les lignes et les colonnes qui entrent dans la fenêtre. Ainsi, le TableView prend en charge des modèles de toute taille sans affecter les performances.

Une table-vue affiche des données provenant de modèles créés à partir de types QML intégrés tels que ListModel et XmlListModel, qui ne remplissent que la première colonne d'une table-vue. Pour créer des modèles à plusieurs colonnes, il faut utiliser TableModel ou un modèle C++ qui hérite de QAbstractItemModel.

Par défaut, un TableView n'inclut pas d'en-têtes. Vous pouvez ajouter des en-têtes à l'aide des contrôles HorizontalHeaderView et VerticalHeaderView de Qt Quick.

Exemple d'utilisation

Modèles C++

L'exemple suivant montre comment créer un modèle en C++ avec plusieurs colonnes :

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

class TableModel : public QAbstractTableModel
{
    Q_OBJECT
    QML_ELEMENT

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

Ensuite, le site TableViewDelegate utilise automatiquement le modèle pour définir/obtenir des données vers/depuis le modèle. Le site TableViewDelegate utilise le site Qt::DisplayRole pour afficher le texte et le site Qt::EditRole pour modifier les données du modèle.

L'extrait suivant montre comment utiliser le modèle QML dans un délégué personnalisé :

import QtQuick
import TableModel

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

    model: TableModel {}

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

Modèles QML

Pour le prototypage et l'affichage de données très simples (provenant d'une API web, par exemple), TableModel peut être utilisé :

import QtQuick
import Qt.labs.qmlmodels

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

Comme TableViewDelegate utilise Qt::EditRole pour définir les données, il est nécessaire de spécifier le rôle d'édition dans TableModelColumn lorsque le délégué est TableViewDelegate:

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

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

Réutilisation des éléments

TableView recycle les éléments du délégué par défaut, au lieu de les instancier à partir de delegate chaque fois que de nouvelles lignes et colonnes sont affichées. Cette approche permet d'améliorer considérablement les performances, en fonction de la complexité du délégué.

Lorsqu'un élément est supprimé, il est transféré dans le pool de réutilisation, qui est un cache interne d'éléments inutilisés. Dans ce cas, le signal TableView::pooled est émis pour en informer l'élément. De même, lorsque l'élément est retiré de la réserve, le signal TableView::reused est émis.

Toutes les propriétés de l'élément qui proviennent du modèle sont mises à jour lorsque l'élément est réutilisé. Cela inclut index, row, et column, mais aussi tous les rôles du modèle.

Si un élément comporte des minuteries ou des animations, pensez à les mettre en pause lors de la réception du signal TableView::pooled. Vous éviterez ainsi d'utiliser les ressources de l'unité centrale pour des éléments qui ne sont pas visibles. De même, si un élément a des ressources qui ne peuvent pas être réutilisées, elles peuvent être libérées.

Si vous ne souhaitez pas réutiliser les éléments ou si le site delegate ne le permet pas, vous pouvez définir la propriété reuseItems sur false.

L'exemple suivant montre un délégué qui anime un rectangle en rotation. Lorsqu'il est mis en commun, l'animation est temporairement interrompue :

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

Hauteur des lignes et largeur des colonnes

Lorsqu'une nouvelle colonne est affichée, TableView détermine sa largeur en appelant la fonction columnWidthProvider. Si elle est définie, cette fonction décidera seule de la largeur de la colonne. Sinon, elle vérifiera si une largeur explicite a été définie avec setColumnWidth(). Si ce n'est pas le cas, implicitColumnWidth() sera utilisé. La largeur implicite d'une colonne est la même que la plus grande valeur de implicit width trouvée parmi les éléments délégués actuellement chargés dans cette colonne. Essayer de définir un width explicite directement sur un délégué n'a aucun effet, et sera ignoré et écrasé. La même logique s'applique à la hauteur des lignes.

Une implémentation de columnWidthProvider équivalente à la logique par défaut serait la suivante :

columnWidthProvider: function(column) {
    let w = explicitColumnWidth(column)
    if (w >= 0)
        return w;
    return implicitColumnWidth(column)
}

Une fois que la largeur de la colonne est résolue, tous les autres éléments de la même colonne sont redimensionnés en fonction de cette largeur, y compris les éléments qui sont affichés ultérieurement.

Si vous modifiez les valeurs renvoyées par rowHeightProvider ou columnWidthProvider pour les lignes et les colonnes à l'intérieur de la fenêtre de visualisation, vous devez appeler forceLayout. Cela informe TableView qu'il doit utiliser à nouveau les fonctions du fournisseur pour recalculer et mettre à jour la disposition.

Depuis Qt 5.13, si vous souhaitez masquer une colonne spécifique, vous pouvez renvoyer 0 à partir de columnWidthProvider pour cette colonne. De même, vous pouvez renvoyer 0 à partir de rowHeightProvider pour masquer une ligne. Si vous renvoyez un nombre négatif ou undefined, TableView se rabattra sur le calcul de la taille en fonction des éléments délégués.

L'exemple suivant montre comment définir un simple columnWidthProvider avec un minuteur qui modifie les valeurs renvoyées par la fonction. Lorsque le tableau est modifié, forceLayout est appelé pour que les changements soient pris en compte :

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();
        }
    }
}

Édition de cellules

Vous pouvez permettre à l'utilisateur de modifier les cellules d'un tableau en lui fournissant un délégué d'édition. Le délégué d'édition sera instancié en fonction de editTriggers, ce qui se produit par défaut lorsque l'utilisateur double-clique sur une cellule ou appuie sur Qt::Key_Enter ou Qt::Key_Return. Le délégué d'édition est défini à l'aide de TableView::editDelegate, qui est une propriété attachée que vous définissez sur delegate. L'extrait suivant montre comment procéder :

    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: 50

            Text {
                anchors.centerIn: parent
                text: display
            }

            TableView.editDelegate: TextField {
                anchors.fill: parent
                text: display
                horizontalAlignment: TextInput.AlignHCenter
                verticalAlignment: TextInput.AlignVCenter
                Component.onCompleted: selectAll()

                TableView.onCommit: {
                    display = text
                    // 'display = text' is short-hand for:
                    // let index = TableView.view.index(row, column)
                    // TableView.view.model.setData(index, "display", text)
                }
            }
        }
    }

Si l'utilisateur appuie sur Qt::Key_Enter ou Qt::Key_Return alors que le délégué à l'édition est actif, TableView émettra le signal TableView::commit au délégué à l'édition, afin qu'il puisse réécrire les données modifiées dans le modèle.

Qt::ItemFlags QAbstractItemModelSubClass::flags(const QModelIndex &index) const override
{
    Q_UNUSED(index)
    return Qt::ItemIsSelectable | Qt::ItemIsEnabled | Qt::ItemIsEditable;
}

Si la propriété required property bool editing est définie dans TableView delegate, elle sera définie à true pour le délégué en cours d'édition. Voir la documentation de editDelegate pour un exemple d'utilisation.

Superpositions et sous-positions

Tous les nouveaux éléments qui sont instanciés à partir du délégué sont rattachés à contentItem avec la valeur z, 1. Vous pouvez ajouter vos propres éléments à l'intérieur de la vue de tableau, en tant qu'éléments enfants du Flickable. En contrôlant leur valeur z, vous pouvez les placer au-dessus ou au-dessous des éléments de la table.

Voici un exemple qui montre comment ajouter un texte au-dessus du tableau, qui se déplace en même temps que le tableau lorsque l'on clique dessus :

TableView {
    id: tableView

    topMargin: header.implicitHeight

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

Voici un autre exemple qui montre comment créer un élément superposé qui reste au-dessus d'une cellule particulière. Cela nécessite un peu plus de code, car l'emplacement d'une cellule sera change si l'utilisateur, par exemple, redimensionne une colonne devant elle.

Rectangle {
    id: overlay
    width: 20
    height: 20
    radius: 10
    color: "blue"

    z: 10
    parent: tableView.contentItem

    Connections {
        target: tableView
        function onLayoutChanged() {
            let item = tableView.itemAtCell(5, 5)
            let insideViewport = item !== null

            overlay.visible = insideViewport
            if (insideViewport) {
                overlay.x = item.x
                overlay.y = item.y
            }
        }
    }
}

Vous pouvez également rattacher l'élément superposé directement à la cellule plutôt qu'à l'adresse contentItem. Mais cette méthode est fragile, car la cellule est déchargée ou réutilisée chaque fois qu'elle sort de la fenêtre de visualisation.

Sélection d'éléments

Vous pouvez ajouter la prise en charge de la sélection à TableView en attribuant un modèle ItemSelectionModel à la propriété selectionModel. Il utilisera alors ce modèle pour contrôler les éléments délégués qui doivent être affichés comme étant sélectionnés et ceux qui doivent être affichés comme étant en cours. Vous pouvez définir selectionBehavior pour contrôler si l'utilisateur doit être autorisé à sélectionner des cellules, des lignes ou des colonnes individuelles.

Pour savoir si un délégué est sélectionné ou en cours, déclarez les propriétés suivantes (sauf si le délégué est un TableViewDelegate, auquel cas les propriétés ont déjà été ajoutées) :

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

L'extrait suivant montre comment une application peut rendre le délégué différemment en fonction de la propriété selected:

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

Les propriétés currentRow et currentColumn peuvent également être utiles si vous devez rendre un délégué différemment selon qu'il se trouve sur la même ligne ou la même colonne que l'élément actuel.

Navigation au clavier

Pour prendre en charge la navigation au clavier, vous devez attribuer une adresse ItemSelectionModel à la propriété selectionModel. TableView utilisera alors ce modèle pour manipuler le modèle currentIndex.

Il incombe au délégué de se rendre lui-même en tant que current. Vous pouvez le faire en lui ajoutant une propriété required property bool current et en laissant l'apparence dépendre de son état. La valeur de la propriété current est définie par le TableView. Vous pouvez également désactiver complètement la navigation au clavier (au cas où vous souhaiteriez mettre en œuvre vos propres gestionnaires de touches) en définissant keyNavigationEnabled sur false.

L'exemple suivant montre comment vous pouvez utiliser la navigation au clavier avec les propriétés current et selected dans un délégué personnalisé :

ApplicationWindow {
    width: 800
    height: 600
    visible: true
    ScrollView {
        anchors.fill: parent
        TableView {
            id: tableView
            clip: true
            interactive: true
            rowSpacing: 1
            columnSpacing: 1
            model: TableModel {
                TableModelColumn { display: "checked" }
                TableModelColumn { display: "amount" }
                TableModelColumn { display: "fruitType" }
                TableModelColumn { display: "fruitName" }
                TableModelColumn { display: "fruitPrice" }

                rows: [
                    {
                        checked: false,
                        amount: 1,
                        fruitType: "Apple",
                        fruitName: "Granny Smith",
                        fruitPrice: 1.50
                    },
                    {
                        checked: true,
                        amount: 4,
                        fruitType: "Orange",
                        fruitName: "Navel",
                        fruitPrice: 2.50
                    },
                    {
                        checked: false,
                        amount: 1,
                        fruitType: "Banana",
                        fruitName: "Cavendish",
                        fruitPrice: 3.50
                    }
                ]
            }
            selectionModel: ItemSelectionModel {}
            delegate: Rectangle {
                implicitWidth: 100
                implicitHeight: 50
                required property bool selected
                required property bool current
                border.width: current ? 2 : 0
                color: selected ? "lightblue" : palette.base
                Text{
                    text: model.display
                    padding: 12
                }
            }
        }
    }
    SelectionRectangle {
        target: tableView
    }
}

Copier et coller

La mise en œuvre d'opérations de copier-coller pour un TableView implique généralement l'utilisation de QUndoStack (ou d'un autre cadre d'annulation/rétablissement). Le site QUndoStack peut être utilisé pour stocker les différentes opérations effectuées sur le modèle, comme l'ajout ou la suppression de lignes, ou le collage de données à partir du presse-papiers, avec la possibilité de les annuler ultérieurement. Toutefois, un document d'accompagnement QUndoStack décrivant les opérations possibles et la manière de les annuler doit être conçu en fonction des besoins du modèle et de l'application. En tant que tel, TableView n'offre pas d'API intégrée pour gérer le copier-coller.

L'extrait suivant peut être utilisé comme référence pour ajouter la prise en charge du copier-coller à votre modèle et à TableView. Il utilise l'API de données mime existante dans QAbstractItemModel, ainsi que QClipboard. L'extrait fonctionnera tel quel, mais il peut également être étendu pour utiliser QUndoStack.

// Inside your C++ QAbstractTableModel subclass:

Q_INVOKABLE void copyToClipboard(const QModelIndexList &indexes) const
{
    QGuiApplication::clipboard()->setMimeData(mimeData(indexes));
}

Q_INVOKABLE bool pasteFromClipboard(const QModelIndex &targetIndex)
{
    const QMimeData *mimeData = QGuiApplication::clipboard()->mimeData();
    // Consider using a QUndoCommand for the following call. It should store
    // the (mime) data for the model items that are about to be overwritten, so
    // that a later call to undo can revert it.
    return dropMimeData(mimeData, Qt::CopyAction, -1, -1, targetIndex);
}

Les deux fonctions peuvent, par exemple, être utilisées à partir de QML comme suit :

TableView {
    id: tableView
    model: tableModel
    selectionModel: ItemSelectionModel {}

    Shortcut {
       sequence: StandardKey.Copy
       onActivated: {
           let indexes = tableView.selectionModel.selectedIndexes
           tableView.model.copyToClipboard(indexes)
       }
    }

    Shortcut {
       sequence: StandardKey.Paste
       onActivated: {
           let targetIndex = tableView.selectionModel.currentIndex
           tableView.model.pasteFromClipboard(targetIndex)
       }
    }
}

Voir aussi TableView::editDelegate, TableView::commit, editTriggers, edit(), closeEditor(), layoutChanged(), QAbstractItemModel::mimeData(), QAbstractItemModel::dropMimeData(), QUndoStack, QUndoCommand, et QClipboard.

Documentation sur les propriétés

alternatingRows : bool

Cette propriété détermine si la couleur d'arrière-plan des lignes doit être alternée. La valeur par défaut dépend du style.

background: Rectangle {
    color: control.row === control.tableView.currentRow
           ? control.palette.highlight
           : (control.tableView.alternatingRows && control.row % 2 !== 0
           ? control.palette.alternateBase
           : control.palette.base)
}

animate : bool [since 6.4]

Cette propriété peut être définie pour contrôler si TableView doit animer les pages contentItem (contentX et contentY). Elle est utilisée par positionViewAtCell() et lors de la navigation sur the current index à l'aide du clavier. La valeur par défaut est true.

Si la valeur est false, toute animation en cours s'arrêtera immédiatement.

Cette propriété a été introduite dans Qt 6.4.

Voir également positionViewAtCell().

bottomRow : int

Cette propriété contient la ligne la plus basse actuellement visible dans la vue.

Voir aussi leftColumn, rightColumn, et topRow.

columnSpacing : real

Cette propriété définit l'espacement entre les colonnes.

La valeur par défaut est 0.

columnWidthProvider : var

Cette propriété peut contenir une fonction qui renvoie la largeur de chaque colonne du modèle. Elle est appelée chaque fois que TableView a besoin de connaître la largeur d'une colonne spécifique. La fonction prend un argument, column, pour lequel TableView doit connaître la largeur.

Depuis Qt 5.13, si vous souhaitez masquer une colonne spécifique, vous pouvez renvoyer 0 la largeur de cette colonne. Si vous renvoyez un nombre négatif ou undefined, TableView calcule la largeur en fonction des éléments du délégué.

Voir aussi rowHeightProvider, isColumnLoaded(), et Row heights and column widths.

columns : int [read-only]

Cette propriété indique le nombre de colonnes du tableau.

Si le modèle est une liste, les colonnes seront 1.

Cette propriété est en lecture seule.

contentHeight : real

Cette propriété indique la hauteur de la table nécessaire pour tenir compte du nombre de lignes dans le modèle de données. Cette hauteur n'est généralement pas identique à celle de height de view, ce qui signifie que la hauteur de la table peut être supérieure ou inférieure à la hauteur de la fenêtre d'affichage. Comme TableView ne peut pas toujours connaître la hauteur exacte de la table sans charger toutes les lignes du modèle, contentHeight est généralement une estimation basée sur la table initialement chargée.

Si vous connaissez la hauteur du tableau, attribuez une valeur à contentHeight, afin d'éviter des calculs et des mises à jour inutiles de TableView.

Voir également contentWidth et rowHeightProvider.

contentWidth : real

Cette propriété indique la largeur du tableau nécessaire pour tenir compte du nombre de colonnes dans le modèle. Cette largeur n'est généralement pas identique à celle de width de view, ce qui signifie que la largeur de la table peut être supérieure ou inférieure à la largeur de la fenêtre de visualisation. Comme TableView ne peut pas toujours connaître la largeur exacte du tableau sans charger toutes les colonnes du modèle, contentWidth est généralement une estimation basée sur le tableau initialement chargé.

Si vous connaissez la largeur du tableau, attribuez une valeur à contentWidth, afin d'éviter des calculs et des mises à jour inutiles de TableView.

Voir également contentHeight et columnWidthProvider.

currentColumn : int [read-only]

Cette propriété en lecture seule contient la colonne de la vue qui contient l'élément qui est current.. Si aucun élément n'est courant, il s'agira de -1.

Voir également currentRow, selectionModel, et Selecting items.

currentRow : int [read-only]

Cette propriété en lecture seule indique la ligne de la vue qui contient l'élément qui est current.. Si aucun élément n'est en cours, il s'agira de -1.

Voir également currentColumn, selectionModel, et Selecting items.

delegate : Component

Le délégué fournit un modèle définissant chaque élément de cellule instancié par la vue. Il peut s'agir de n'importe quel composant personnalisé, mais il est recommandé d'utiliser TableViewDelegate, car il est stylisé en fonction du style de l'application et offre des fonctionnalités prêtes à l'emploi.

Pour utiliser TableViewDelegate, il suffit de le définir comme délégué :

delegate: TableViewDelegate { }

L'index du modèle est exposé en tant que propriété index accessible. Il en va de même pour row et column. Les propriétés du modèle sont également disponibles en fonction du type de modèle de données.

Un délégué doit spécifier sa taille en utilisant implicitWidth et implicitHeight. Le site TableView dispose les éléments en fonction de ces informations. Les paramètres explicites de largeur ou de hauteur sont ignorés et remplacés.

Dans le délégué, vous pouvez éventuellement ajouter une ou plusieurs des propriétés suivantes (sauf si le délégué est un TableViewDelegate, auquel cas les propriétés ont déjà été ajoutées). TableView modifie les valeurs de ces propriétés pour informer le délégué de l'état dans lequel il se trouve. Cela peut être utilisé par le délégué pour se rendre différemment en fonction de son propre état.

• propriété obligatoire bool current - true si le délégué est dans l'état suivant current.
• required property bool selected - true si le délégué est selected.
• required property bool editing - true si le délégué est en cours d'édition edited.
• required property bool containsDrag - true si une colonne ou une ligne est en train d'être glissée sur ce délégué. Cette propriété n'est prise en charge que pour HorizontalHeaderView et VerticalHeaderView. (depuis Qt 6.8)

L'exemple suivant montre comment utiliser ces propriétés dans un délégué personnalisé :

delegate: Rectangle {
    required property bool current
    required property bool selected
    border.width: current ? 1 : 0
    color: selected ? palette.highlight : palette.base
}

Voir également Row heights and column widths, Reusing items, Propriétés requises, TableViewDelegate, et Personnaliser TableViewDelegate.

delegateModelAccess : enumeration [since 6.10]

Cette propriété détermine comment les délégués peuvent accéder au modèle.

La valeur par défaut est DelegateModel.Qt5ReadWrite.

Cette propriété a été introduite dans Qt 6.10.

Voir aussi Modèles et vues dans Qt Quick#ChangingModel Data.

editTriggers : enumeration [default: TableView.DoubleTapped | TableView.EditKeyPressed., since 6.5]

Cette propriété contient les différentes façons dont l'utilisateur peut commencer à modifier une cellule. Il peut s'agir d'une combinaison des valeurs suivantes :

Pour que TableView.SelectedTapped, TableView.EditKeyPressed et TableView.AnyKeyPressed aient un effet, TableView doit avoir un selection model assigné, puisqu'ils dépendent de l'activation d'un current index. Pour pouvoir recevoir des événements de touche, TableView doit également être associé à QQuickItem::activeFocus.

Lors de la modification d'une cellule, l'utilisateur peut appuyer sur Qt::Key_Tab ou Qt::Key_Backtab pour commit les données et passer à la cellule suivante. Ce comportement peut être désactivé en réglant QQuickItem::activeFocusOnTab sur TableView à false.

Qt::ItemFlags QAbstractItemModelSubClass::flags(const QModelIndex &index) const override
{
    Q_UNUSED(index)
    return Qt::ItemIsSelectable | Qt::ItemIsEnabled | Qt::ItemIsEditable;
}

Cette propriété a été introduite dans Qt 6.5.

Voir aussi TableView::editDelegate, TableView::commit, et Editing cells.

keyNavigationEnabled : bool [since 6.4]

Cette propriété peut être définie pour contrôler si l'utilisateur doit pouvoir changer the current index à l'aide du clavier. La valeur par défaut est true.

Cette propriété a été introduite dans Qt 6.4.

Voir aussi Keyboard navigation, selectionModel, selectionBehavior, pointerNavigationEnabled, et interactive.

leftColumn : int

Cette propriété contient la colonne la plus à gauche actuellement visible dans la vue.

Voir aussi rightColumn, topRow, et bottomRow.

model : model

Cette propriété contient le modèle qui fournit les données de la table.

Le modèle fournit l'ensemble des données utilisées pour créer les éléments de la vue. Les modèles peuvent être créés directement en QML à l'aide de TableModel, ListModel, ObjectModel, ou fournis par une classe de modèle C++ personnalisée. Le modèle C++ doit être une sous-classe de QAbstractItemModel ou une simple liste.

Voir aussi Modèles de données.

pointerNavigationEnabled : bool [since 6.4]

Cette propriété peut être définie pour contrôler si l'utilisateur doit pouvoir modifier the current index à l'aide de la souris ou du toucher. La valeur par défaut est true.

Cette propriété a été introduite dans Qt 6.4.

Voir également selectionModel, keyNavigationEnabled, et interactive.

resizableColumns : bool [since 6.5]

Cette propriété indique si l'utilisateur est autorisé à redimensionner les colonnes en les faisant glisser entre les cellules. La valeur par défaut est false.

Cette propriété a été introduite dans Qt 6.5.

resizableRows : bool [since 6.5]

Cette propriété indique si l'utilisateur est autorisé à redimensionner les lignes en les faisant glisser entre les cellules. La valeur par défaut est false.

Cette propriété a été introduite dans Qt 6.5.

reuseItems : bool

Cette propriété indique si les éléments instanciés à partir de delegate doivent être réutilisés ou non. Si elle vaut false, tous les éléments actuellement mis en commun sont détruits.

Voir également Reusing items, TableView::pooled, et TableView::reused.

rightColumn : int

Cette propriété contient la colonne la plus à droite actuellement visible dans la vue.

Voir aussi leftColumn, topRow, et bottomRow.

rowHeightProvider : var

Cette propriété peut contenir une fonction qui renvoie la hauteur de chaque ligne du modèle. Elle est appelée chaque fois que TableView a besoin de connaître la hauteur d'une ligne spécifique. La fonction prend un argument, row, pour lequel TableView doit connaître la hauteur.

Depuis Qt 5.13, si vous souhaitez masquer une ligne spécifique, vous pouvez renvoyer 0 la hauteur de cette ligne. Si vous renvoyez un nombre négatif, TableView calcule la hauteur en fonction des éléments du délégué.

Voir aussi columnWidthProvider, isRowLoaded(), et Row heights and column widths.

rowSpacing : real

Cette propriété définit l'espacement entre les lignes.

La valeur par défaut est 0.

rows : int [read-only]

Cette propriété contient le nombre de lignes du tableau.

Cette propriété est en lecture seule.

selectionBehavior : enumeration [since 6.4]

Cette propriété indique si l'utilisateur peut sélectionner des cellules, des lignes ou des colonnes.

Cette propriété a été introduite dans Qt 6.4.

Voir aussi Selecting items, selectionMode, selectionModel, et keyNavigationEnabled.

selectionMode : enumeration [since 6.6]

Si selectionBehavior est défini sur TableView.SelectCells, cette propriété indique si l'utilisateur peut sélectionner une cellule à la fois ou plusieurs cellules. Si selectionBehavior est défini sur TableView.SelectRows, cette propriété indique si l'utilisateur peut sélectionner une ligne à la fois ou plusieurs lignes. Si selectionBehavior est défini sur TableView.SelectColumns, cette propriété indique si l'utilisateur peut sélectionner une colonne à la fois ou plusieurs colonnes.

Les modes suivants sont disponibles :

Cette propriété a été introduite dans Qt 6.6.

Voir aussi Selecting items, selectionBehavior, selectionModel, et keyNavigationEnabled.

selectionModel : ItemSelectionModel [since 6.2]

Cette propriété peut être définie pour contrôler les éléments du délégué qui doivent être affichés comme étant sélectionnés et ceux qui doivent être affichés comme étant en cours. Si le délégué a un required property bool selected défini, TableView le maintiendra en synchronisation avec l'état de sélection de l'élément de modèle correspondant dans le modèle de sélection. Si le délégué a une required property bool current définie, TableView la gardera synchronisée avec selectionModel.currentIndex.

Cette propriété a été introduite dans Qt 6.2.

Voir aussi Selecting items, SelectionRectangle, keyNavigationEnabled, et pointerNavigationEnabled.

syncDirection : Qt::Orientations

Si syncView est défini sur TableView, cette propriété contrôle la synchronisation de la (des) direction(s) de la pichenette pour les deux tables. La valeur par défaut est Qt.Horizontal | Qt.Vertical, ce qui signifie que si vous donnez une pichenette à l'un des tableaux dans l'une ou l'autre direction, l'autre tableau sera également donné une pichenette de la même quantité dans la même direction.

Cette propriété et syncView peuvent être utilisées pour que deux tableViews se synchronisent l'une avec l'autre en douceur lors de la pichenette, quelles que soient les différences de dépassement/dépassement, de vitesse, d'accélération/décélération ou d'animation de rebond, et ainsi de suite.

Un cas d'utilisation typique consiste à faire clignoter plusieurs en-têtes en même temps que le tableau.

Voir aussi syncView.

syncView : TableView

Si cette propriété d'un TableView est attribuée à un autre TableView, les deux tables se synchroniseront en ce qui concerne le flicking, les largeurs de colonnes/hauteurs de lignes et l'espacement conformément à syncDirection.

Si syncDirection contient Qt.Horizontal, la largeur et l'espacement des colonnes de la tableView actuelle, ainsi que le mouvement horizontal de la pichenette, sont synchronisés avec ceux de la syncView.

Si syncDirection contient Qt.Vertical, la hauteur et l'espacement des lignes de la tableView actuelle, ainsi que le mouvement vertical, sont synchronisés avec ceux de syncView.

Voir également syncDirection.

topRow : int

Cette propriété contient la ligne la plus haute actuellement visible dans la vue.

Voir aussi leftColumn, rightColumn, et bottomRow.

Documentation sur les propriétés attachées

TableView.editDelegate : Component

Cette propriété attachée contient le délégué d'édition. Il est instancié au début de l'édition et rattaché au délégué qu'il édite. Il prend en charge les mêmes propriétés requises que TableView delegate, y compris index, row et column. Les propriétés du modèle, comme display et edit, sont également disponibles (en fonction de role names exposé par le modèle).

L'édition commence lorsque les actions spécifiées par editTriggers sont satisfaites et que la cellule en cours est modifiable.

Vous pouvez également ouvrir et fermer manuellement le délégué à l'édition en appelant respectivement edit() et closeEditor().

L'édition se termine lorsque l'utilisateur appuie sur Qt::Key_Enter ou Qt::Key_Return (ainsi que sur Qt::Key_Tab ou Qt::Key_Backtab, si TableView est associé à QQuickItem::activeFocusOnTab ). Dans ce cas, le signal TableView::commit sera émis, de sorte que le délégué à l'édition puisse répondre en écrivant toutes les données modifiées dans le modèle. Si l'édition se termine pour d'autres raisons (par exemple, si l'utilisateur appuie sur Qt::Key_Escape), le signal ne sera pas émis. Dans tous les cas, destruction() sera émis à la fin.

Lorsque le délégué d'édition est affiché, la cellule située en dessous est toujours visible et transparaît donc si le délégué d'édition est translucide ou ne couvre pas l'intégralité de la cellule. Si cela n'est pas souhaité, vous pouvez soit laisser l'élément racine du délégué d'édition être un solide Rectangle, soit cacher certains des éléments à l'intérieur du TableView delegate.. Ce dernier peut être réalisé en définissant une propriété required property bool editing à l'intérieur, que vous liez à la propriété visible de certains des éléments enfants. L'extrait suivant montre comment procéder dans un délégué personnalisé :

        delegate: Rectangle {
            implicitWidth: 100
            implicitHeight: 50

            required property bool editing

            Text {
                id: textField
                anchors.fill: parent
                anchors.margins: 5
                text: display
                visible: !editing
            }

            TableView.editDelegate: TextField {
                x: textField.x
                y: textField.y
                width: textField.width
                height: textField.height
                text: display
                TableView.onCommit: display = text
            }
        }

Lorsque le délégué d'édition est instancié, TableView appelle QQuickItem::forceActiveFocus(). Si vous souhaitez que le focus actif soit placé sur un enfant du délégué d'édition à la place, faites en sorte que le délégué d'édition soit un FocusScope.

Par défaut, TableViewDelegate fournit un délégué d'édition, mais vous pouvez également définir le vôtre :

delegate: TableViewDelegate {
    TableView.editDelegate: TextField {
        width: parent.width
        height: parent.height
        text: display
        TableView.onCommit: display = text
    }
}

Voir également editTriggers, TableView::commit, edit(), closeEditor(), Editing cells, et TableViewDelegate.

TableView.view : TableView

Cette propriété attachée contient la vue qui gère l'instance de délégué. Elle est attachée à chaque instance de délégué.

Documentation sur les signaux

[since 6.8] columnMoved(int logicalIndex, int oldVisualIndex, int newVisualIndex)

Ce signal est émis lorsqu'une colonne est déplacée. L'index logique de la colonne est spécifié par logicalIndex, l'ancien index par oldVisualIndex, et la nouvelle position d'index par newVisualIndex.

Ce signal a été introduit dans Qt 6.8.

[since 6.5] layoutChanged()

Ce signal est émis chaque fois que la disposition des lignes et des colonnes de loaded a potentiellement changé. C'est notamment le cas lorsque forceLayout() est appelé, mais aussi lorsque, par exemple, une ligne ou une colonne est redimensionnée, ou lorsqu'une ligne ou une colonne est entrée ou sortie de la fenêtre de visualisation.

Ce signal peut être utilisé, par exemple, pour mettre à jour la géométrie des superpositions.

Ce signal a été introduit dans Qt 6.5.

Voir aussi forceLayout() et Overlays and underlays.

[since 6.8] rowMoved(int logicalIndex, int oldVisualIndex, int newVisualIndex)

Ce signal est émis lorsqu'une ligne est déplacée. L'indice logique de la ligne est spécifié par logicalIndex, l'ancien indice par oldVisualIndex, et la nouvelle position d'indice par newVisualIndex.

Ce signal a été introduit dans Qt 6.8.

Documentation sur les signaux attachés

commit()

Ce signal est émis par l'application edit delegate

Ce signal est émis lorsque le site edit delegate est actif et que l'utilisateur appuie sur Qt::Key_Enter ou Qt::Key_Return. Il sera également émis si TableView a défini QQuickItem::activeFocusOnTab et que l'utilisateur appuie sur Qt::Key_Tab ou Qt::Key_Backtab.

Ce signal ne sera pas émis si l'édition se termine pour des raisons autres que celles mentionnées. C'est le cas, par exemple, si l'utilisateur appuie sur Qt::Key_Escape, s'il tape en dehors du délégué, si la ligne ou la colonne en cours d'édition est supprimée ou si l'application appelle closeEditor().

Dès réception du signal, le délégué à l'édition doit réécrire toutes les données modifiées dans le modèle.

Voir aussi TableView::editDelegate, editTriggers, et Editing cells.

pooled()

Ce signal est émis après qu'un élément a été ajouté au pool de réutilisation. Vous pouvez l'utiliser pour mettre en pause les minuteries ou les animations en cours à l'intérieur de l'élément, ou pour libérer les ressources qui ne peuvent pas être réutilisées.

Ce signal n'est émis que si la propriété reuseItems est true.

Voir également Reusing items, reuseItems, et reused.

reused()

Ce signal est émis après la réutilisation d'un élément. À ce stade, l'élément a été retiré du pool et placé dans la vue de contenu, et les propriétés du modèle telles que l'index, la ligne et la colonne ont été mises à jour.

Les autres propriétés qui ne sont pas fournies par le modèle ne changent pas lorsqu'un élément est réutilisé. Vous devez éviter de stocker un état dans un délégué, mais si vous le faites, réinitialisez manuellement cet état à la réception de ce signal.

Ce signal est émis lorsque l'élément est réutilisé, et non lors de sa première création.

Ce signal n'est émis que si la propriété reuseItems est true.

Voir également Reusing items, reuseItems, et pooled.

Documentation de la méthode

[since 6.4] point cellAtIndex(QModelIndex modelIndex)

Renvoie la cellule de la vue qui correspond à modelIndex dans le modèle. Fonction de commodité :

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

Une cellule est simplement un point qui combine la ligne et la colonne en un seul type.

Cette méthode a été introduite dans Qt 6.4.

Point cellAtPosition(point position, bool includeSpacing)

Renvoie la cellule située à l'adresse position dans le tableau. position doit être relatif à contentItem. Si aucune cellule loaded n'intersecte position, la valeur de retour sera point(-1, -1).

Si includeSpacing est défini sur true, la boîte de délimitation d'une cellule sera considérée comme incluant la moitié des rowSpacing et columnSpacing adjacents de chaque côté. La valeur par défaut est false.

Voir également columnSpacing et rowSpacing.

Point cellAtPosition(real x, real y, bool includeSpacing)

Pratique pour appeler cellAtPosition(Qt.point(x, y), includeSpacing).

[since 6.8] void clearColumnReordering()

Réinitialise toute réorganisation des colonnes précédemment appliquée.

Cette méthode a été introduite dans Qt 6.8.

void clearColumnWidths()

Efface toutes les largeurs de colonnes définies avec setColumnWidth().

Voir également setColumnWidth(), clearRowHeights() et Row heights and column widths.

void clearRowHeights()

Efface toutes les hauteurs de ligne définies avec setRowHeight().

Voir également setRowHeight(), clearColumnWidths() et Row heights and column widths.

[since 6.8] void clearRowReordering()

Réinitialise toute réorganisation des lignes précédemment appliquée.

Cette méthode a été introduite dans Qt 6.8.

[since 6.5] void closeEditor()

Si l'utilisateur est en train d'éditer une cellule, l'appel de cette fonction arrêtera l'édition et détruira l'instance du délégué à l'édition.

Cette méthode a été introduite dans Qt 6.5.

Voir aussi edit(), TableView::editDelegate, et Editing cells.

[since 6.4] int columnAtIndex(QModelIndex modelIndex)

Renvoie la colonne de la vue qui correspond à modelIndex dans le modèle.

Cette méthode a été introduite dans Qt 6.4.

Voir aussi rowAtIndex() et index().

[since 6.2] real columnWidth(int column)

Renvoie la largeur de la colonne donnée column. Si la colonne n'est pas chargée (et donc pas visible), la valeur de retour sera -1.

Cette méthode a été introduite dans Qt 6.2.

Voir aussi setColumnWidth(), columnWidthProvider, implicitColumnWidth(), isColumnLoaded(), et Row heights and column widths.

[since 6.5] void edit(QModelIndex modelIndex)

Cette fonction lance une session d'édition pour la cellule qui représente modelIndex. Si l'utilisateur est déjà en train d'éditer une autre cellule, cette session se termine.

Normalement, vous pouvez spécifier les différentes façons de démarrer une session d'édition en utilisant plutôt editTriggers. Si cela ne suffit pas, vous pouvez utiliser cette fonction. Pour prendre le contrôle total de l'édition des cellules et empêcher TableView d'interférer, définissez editTriggers sur TableView.NoEditTriggers.

Cette méthode a été introduite dans Qt 6.5.

Voir aussi closeEditor(), editTriggers, TableView::editDelegate, et Editing cells.

real explicitColumnWidth(int column)

Renvoie la largeur de la colonne column définie avec setColumnWidth(). Cette largeur peut être différente de la largeur réelle de la colonne, si un columnWidthProvider est utilisé. Pour obtenir la largeur réelle d'une colonne, utilisez columnWidth().

Une valeur de retour égale à 0 signifie qu'il a été demandé à la colonne de se cacher. Une valeur de retour égale à -1 signifie qu'aucune largeur explicite n'a été définie pour la colonne.

Voir également setColumnWidth(), columnWidth() et Row heights and column widths.

real explicitRowHeight(int row)

Renvoie la hauteur de la colonne row définie avec setRowHeight(). Cette hauteur peut être différente de la hauteur réelle de la colonne, si un rowHeightProvider est utilisé. Pour obtenir la hauteur réelle d'une ligne, utilisez rowHeight().

Une valeur de retour égale à 0 signifie qu'il a été demandé à la ligne de se cacher. Une valeur de retour égale à -1 signifie qu'aucune hauteur explicite n'a été définie pour la ligne.

Voir également setRowHeight(), rowHeight() et Row heights and column widths.

void forceLayout()

Les réponses aux modifications du modèle sont regroupées de manière à n'être traitées qu'une seule fois par image. Cela signifie que TableView retarde l'affichage de tout changement pendant l'exécution d'un script. Il en va de même lors de la modification de propriétés, telles que rowSpacing ou leftMargin.

Cette méthode oblige le site TableView à mettre immédiatement à jour la présentation afin que les modifications récentes soient prises en compte.

L'appel de cette fonction réévalue la taille et la position de chaque ligne et colonne visible. Cette fonction est nécessaire si les fonctions attribuées à rowHeightProvider ou columnWidthProvider renvoient des valeurs différentes de celles déjà attribuées.

[since 6.2] real implicitColumnWidth(int column)

Renvoie la largeur implicite de la colonne donnée column. Il s'agit de la plus grande implicitWidth trouvée parmi les éléments délégués actuellement loaded à l'intérieur de cette colonne.

Si column n'est pas chargé (et donc pas visible), la valeur de retour est -1.

Cette méthode a été introduite dans Qt 6.2.

Voir aussi columnWidth(), isRowLoaded(), et Row heights and column widths.

[since 6.2] real implicitRowHeight(int row)

Renvoie la hauteur implicite de l'élément row donné. Il s'agit de la plus grande implicitHeight trouvée parmi les éléments délégués actuellement loaded à l'intérieur de cette ligne.

Si row n'est pas chargé (et donc pas visible), la valeur de retour est -1.

Cette méthode a été introduite dans Qt 6.2.

Voir aussi rowHeight(), isColumnLoaded(), et Row heights and column widths.

[since 6.4.3] QModelIndex index(int row, int column)

Renvoie l'adresse QModelIndex qui correspond à row et column dans la vue.

row et column doivent être la ligne et la colonne de la vue (ligne et colonne de la table), et non une ligne et une colonne du modèle. Pour un simple TableView, cela équivaut à appeler model.index(row, column). Mais pour une sous-classe de TableView, comme TreeView, où le modèle de données est enveloppé dans un modèle proxy interne qui aplatit la structure de l'arbre en une table, vous devez utiliser cette fonction pour résoudre l'index du modèle.

Cette méthode a été introduite dans Qt 6.4.3.

Voir aussi rowAtIndex() et columnAtIndex().

[since 6.2] bool isColumnLoaded(int column)

Renvoie true si la colonne column est chargée.

Une colonne est chargée lorsque TableView a chargé les éléments délégués nécessaires pour afficher la colonne dans la vue. Cela signifie généralement que la colonne est visible pour l'utilisateur, mais pas toujours.

Cette fonction peut être utilisée chaque fois que vous devez itérer sur les éléments délégués d'une colonne, par exemple à partir d'un site columnWidthProvider, pour vous assurer que les éléments délégués sont disponibles pour l'itération.

Cette méthode a été introduite dans Qt 6.2.

[since 6.2] bool isRowLoaded(int row)

Renvoie true si le site row est chargé.

Une ligne est chargée lorsque TableView a chargé les éléments délégués nécessaires pour afficher la ligne dans la vue. Cela signifie généralement que la ligne est visible pour l'utilisateur, mais pas toujours.

Cette fonction peut être utilisée chaque fois que vous devez itérer sur les éléments délégués d'une ligne, par exemple à partir d'un site rowHeightProvider, pour vous assurer que les éléments délégués sont disponibles pour l'itération.

Cette méthode a été introduite dans Qt 6.2.

Item itemAtCell(point cell)

Renvoie l'élément délégué à cell s'il est chargé, sinon null.

[since 6.5] Item itemAtIndex(QModelIndex index)

Renvoie l'élément délégué instancié pour la cellule qui représente index. Si l'élément n'est pas loaded, la valeur sera null.

Cette méthode a été introduite dans Qt 6.5.

[since 6.4] QModelIndex modelIndex(point cell)

Fonction de commodité pour faire :

index(cell.y, cell.x)

Un cell est simplement un point qui combine la ligne et la colonne en un seul type.

Cette méthode a été introduite dans Qt 6.4.

Voir aussi index().

[since 6.8] void moveColumn(int source, int destination)

Déplace une colonne de la position source à la position destination.

Cette méthode a été introduite dans Qt 6.8.

[since 6.8] void moveRow(int source, int destination)

Déplace une ligne de la position source à la position destination.

Cette méthode a été introduite dans Qt 6.8.

void positionViewAtCell(point cell, PositionMode mode, point offset, rect subRect)

Positionne contentX et contentY de telle sorte que cell se trouve à la position spécifiée par mode. mode peut être une combinaison ou une combinaison des éléments suivants :

Si aucun alignement vertical n'est spécifié, le positionnement vertical sera ignoré. Il en va de même pour l'alignement horizontal.

En option, vous pouvez spécifier offset pour déplacer le contenuX et le contenuY d'un nombre supplémentaire de pixels au-delà de l'alignement cible. Par exemple, si vous souhaitez positionner la vue de manière à ce que la cellule [10, 10] se retrouve dans le coin supérieur gauche avec une marge de 5px, vous pouvez le faire :

positionViewAtCell(Qt.point(10, 10), TableView.AlignLeft | TableView.AlignTop, Qt.point(-5, -5))

Depuis Qt Positioning 6.4, vous pouvez spécifier une subRect à positionner sur un rectangle à l'intérieur de la cell, plutôt que sur le rectangle de délimitation de la cellule entière. Cela peut être utile si la cellule est, par exemple, plus grande que la vue et que vous voulez vous assurer qu'une partie spécifique de la cellule est visible. Le site subRect doit être valid pour être pris en considération.

Les méthodes ne doivent être appelées qu'une fois le composant terminé. Pour positionner la vue au démarrage, cette méthode doit être appelée par Component.onCompleted. Par exemple, pour positionner la vue à la fin :

Component.onCompleted: positionViewAtCell(Qt.point(columns - 1, rows - 1), TableView.AlignRight | TableView.AlignBottom)

Voir aussi animate.

void positionViewAtColumn(int column, PositionMode mode, real offset, rect subRect)

Positionne contentX de telle sorte que column soit à la position spécifiée par mode, offset et subRect.

Méthode pratique pour appeler

positionViewAtCell(Qt.point(column, 0), mode & Qt.AlignHorizontal_Mask, offset, subRect)

[since 6.5] void positionViewAtIndex(QModelIndex index, PositionMode mode, point offset, rect subRect)

Positionne la vue de telle sorte que index se trouve à la position spécifiée par mode, offset et subRect.

Méthode pratique d'appel

positionViewAtRow(rowAtIndex(index), mode & Qt.AlignVertical_Mask, offset.y, subRect)
positionViewAtColumn(columnAtIndex(index), mode & Qt.AlignVertical_Mask, offset.x, subRect)

Cette méthode a été introduite dans Qt 6.5.

void positionViewAtRow(int row, PositionMode mode, real offset, rect subRect)

Positionne contentY de telle sorte que row soit à la position spécifiée par mode, offset et subRect.

Méthode pratique pour appeler

positionViewAtCell(Qt.point(0, row), mode & Qt.AlignVertical_Mask, offset, subRect)

[since 6.4] int rowAtIndex(QModelIndex modelIndex)

Renvoie la ligne de la vue qui correspond à modelIndex dans le modèle.

Cette méthode a été introduite dans Qt 6.4.

Voir aussi columnAtIndex() et index().

[since 6.2] real rowHeight(int row)

Renvoie la hauteur de la ligne donnée row. Si la ligne n'est pas chargée (et donc pas visible), la valeur de retour sera -1.

Cette méthode a été introduite dans Qt 6.2.

Voir aussi setRowHeight(), rowHeightProvider, implicitRowHeight(), isRowLoaded() et Row heights and column widths.

void setColumnWidth(int column, real size)

Définit la largeur explicite de la colonne column à size.

Si vous souhaitez relire les valeurs que vous avez définies avec cette fonction, vous devez utiliser explicitColumnWidth(). columnWidth() renverra la taille réelle de la colonne, qui peut être différente si un columnWidthProvider est défini.

Lorsque TableView doit déterminer la largeur de column, il essaiera d'abord d'appeler columnWidthProvider. Ce n'est que si aucun fournisseur n'est défini que les largeurs définies avec cette fonction seront utilisées par défaut. Vous pouvez toutefois appeler explicitColumnWidth() à partir du fournisseur et, si nécessaire, modérer les valeurs pour qu'elles soient toujours comprises dans un certain intervalle, par exemple. L'extrait suivant montre un exemple de la manière de procéder :

columnWidthProvider: function(column) {
    let w = explicitColumnWidth(column)
    if (w >= 0)
        return Math.max(100, w);
    return implicitColumnWidth(column)
}

Si size est égal à 0, la colonne sera cachée. Si size est égal à -1, la colonne sera réinitialisée pour utiliser implicitColumnWidth(). Vous êtes autorisé à spécifier la taille des colonnes qui ne correspondent pas à la taille du modèle.

Voir aussi columnWidth(), explicitColumnWidth(), setRowHeight(), clearColumnWidths() et Row heights and column widths.

void setRowHeight(int row, real size)

Définit la hauteur de ligne explicite de la ligne row à size.

Si vous souhaitez relire les valeurs que vous avez définies avec cette fonction, vous devez utiliser explicitRowHeight(). rowHeight() renverra la hauteur réelle de la ligne, qui peut être différente si un rowHeightProvider est défini.

Lorsque TableView doit déterminer la hauteur de row, il essaie d'abord d'appeler rowHeightProvider. Ce n'est que si aucun fournisseur n'est défini que les hauteurs définies avec cette fonction sont utilisées par défaut. Vous pouvez cependant appeler explicitRowHeight() à partir du fournisseur et, si nécessaire, modérer les valeurs pour qu'elles soient toujours comprises dans un certain intervalle, par exemple. L'extrait suivant montre un exemple de la manière de procéder :

rowHeightProvider: function(row) {
    let h = explicitRowHeight(row)
    if (h >= 0)
        return Math.max(100, h);
    return implicitRowHeight(row)
}

Si size est égal à 0, la ligne sera cachée. Si size est égal à -1, la ligne sera réinitialisée pour utiliser implicitRowHeight(). Vous êtes autorisé à spécifier des tailles de ligne pour les lignes qui sont en dehors de la taille du modèle.

Voir aussi rowHeight(), explicitRowHeight(), setColumnWidth() et Row heights and column widths.