TableView QML Type

Fournit une vue sous forme de tableau des éléments permettant d'afficher les données d'un modèle. En savoir plus...

• 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 associé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 associé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 dispose d'un modèle ( model ) qui définit les données à afficher, et d'une vue ( delegate ) qui définit la manière dont ces données doivent être affichées.

TableView hérite de Flickable. Cela signifie que, bien que le modèle puisse comporter un nombre illimité de lignes et de colonnes, seule une partie du tableau est généralement visible dans la fenêtre d'affichage. Dès que vous effectuez un balayage, de nouvelles lignes et colonnes apparaissent dans la zone d’affichage, tandis que les anciennes disparaissent et sont supprimées de celle-ci. Les lignes et colonnes qui sortent sont réutilisées pour construire celles qui entrent dans la zone d’affichage. Ainsi, TableView prend en charge des modèles de toute taille sans affecter les performances.

Une TableView affiche les 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 TableView. Pour créer des modèles comportant plusieurs colonnes, utilisez soit ` TableModel `, soit un modèle C++ héritant de ` QAbstractItemModel`.

Par défaut, une TableView n'inclut pas d'en-têtes. Vous pouvez ajouter des en-têtes à l'aide des méthodes HorizontalHeaderView et VerticalHeaderView de Qt Quick Controls.

Exemple d’utilisation

Modèles C++

L'exemple suivant montre comment créer un modèle en C++ comportant 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"} };
    }
};

L’ TableViewDelegate utilise alors automatiquement ce modèle pour définir ou récupérer des données. L’ TableViewDelegate utilise la propriété ` Qt::DisplayRole ` pour afficher du texte et la propriété ` Qt::EditRole ` pour modifier les données du modèle.

L'extrait de code suivant montre comment utiliser le modèle depuis 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), il est possible d’utiliser TableModel:

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 l’ TableViewDelegate utilise l’ Qt::EditRole pour définir les données, il est nécessaire de spécifier le rôle d’édition dans l’ TableModelColumn lorsque le délégué est de type 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

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

Lorsqu’un élément est fait disparaître d’un geste, il est déplacé vers le pool de réutilisation, qui est un cache interne d’éléments inutilisés. Lorsque cela se produit, le signal ` TableView::pooled ` est émis pour en informer l’élément. De même, lorsque l’élément est récupéré depuis le pool, le signal ` TableView::reused ` est émis.

Toutes les propriétés de l’élément provenant du modèle sont mises à jour lorsque l’élément est réutilisé. Cela inclut « index », « row » et « column », mais également tous les rôles du modèle.

Si un élément comporte des temporisateurs ou des animations, pensez à les mettre en pause à la réception du signal « TableView::pooled ». Vous éviterez ainsi de mobiliser les ressources du processeur pour des éléments qui ne sont pas visibles. De même, si un élément dispose de ressources qui ne peuvent pas être réutilisées, celles-ci peuvent être libérées.

Si vous ne souhaitez pas réutiliser les éléments ou si le système « 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 tournant. Lorsqu’il est mis en pool, l’animation est temporairement mise en pause :

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

Hauteurs des lignes et largeurs des colonnes

Lorsqu’une nouvelle colonne est affichée d’un geste rapide, TableView détermine sa largeur en appelant la méthode columnWidthProvider. Si elle est définie, cette fonction détermine à elle seule la largeur de la colonne. Sinon, elle vérifie si une largeur explicite a été définie via setColumnWidth(). Si ce n’est pas le cas, la méthode implicitColumnWidth() est utilisée. La largeur implicite d’une colonne correspond à la plus grande valeur de ` implicit width ` parmi les éléments délégués actuellement chargés dans cette colonne. Tenter de définir une largeur explicite ` width ` directement sur un délégué n’a aucun effet ; cette valeur sera ignorée et écrasée. La même logique s’applique également aux hauteurs de ligne.

Une implémentation d’une méthode 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 la largeur de la colonne déterminée, tous les autres éléments de la même colonne sont redimensionnés à cette largeur, y compris ceux qui sont fait apparaître dans la vue ultérieurement.

Si vous modifiez les valeurs renvoyées par ` rowHeightProvider ` ou ` columnWidthProvider ` pour les lignes et les colonnes situées dans la zone d’affichage, vous devez appeler ` forceLayout`. Cela indique à `TableView` qu’il doit à nouveau utiliser les fonctions du fournisseur pour recalculer et mettre à jour la mise en page.

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 du délégué.

L’exemple suivant montre comment définir une « columnWidthProvider » simple associée à un minuteur qui modifie les valeurs renvoyées par la fonction. Lorsque le tableau est modifié, la méthode ` forceLayout ` est appelée pour que les modifications prennent effet :

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

Modification des cellules

Vous pouvez permettre à l’utilisateur de modifier les cellules du tableau en fournissant un délégué d’édition. Le délégué d’édition sera instancié selon l’ editTriggers, qui, par défaut, se produit lorsque l’utilisateur appuie deux fois sur une cellule ou appuie, par exemple, sur Qt::Key_Enter ou Qt::Key_Return. Le délégué d’édition est défini à l’aide de TableView::editDelegate, une propriété attachée que vous définissez sur l’ delegate. L’extrait de code 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é d’édition est actif, TableView émettra le signal TableView::commit vers le délégué d’édition, afin que celui-ci 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 méthode TableView delegate dispose d’une propriété required property bool editing définie, celle-ci sera définie sur true pour le délégué en cours d’édition. Consultez la documentation relative à editDelegate pour obtenir un exemple d’utilisation.

Superpositions et sous-couches

Tous les nouveaux éléments instanciés à partir du délégué sont rattachés à l’ contentItem avec la valeur z définie sur 1. Vous pouvez ajouter vos propres éléments à l’intérieur de la Tableview, en tant qu’éléments enfants du Flickable. En contrôlant leur valeur z, vous pouvez les faire apparaître au-dessus ou en dessous des éléments du tableau.

Voici un exemple qui montre comment ajouter du texte au-dessus du tableau, qui se déplace avec celui-ci lorsque vous le faites défiler :

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 de superposition qui reste au-dessus d’une cellule particulière. Cela nécessite un peu plus de code, car l’emplacement d’une cellule peut « change » si l’utilisateur, par exemple, redimensionne une colonne située devant celle-ci.

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 associer l’élément superposé directement à la cellule plutôt qu’à l’ contentItem. Mais cette approche s’avère fragile, car la cellule est déchargée ou réutilisée dès qu’elle est déplacée hors de la zone d’affichage.

Sélection d'éléments

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

Pour déterminer si un délégué est sélectionné ou actif, déclarez les propriétés suivantes (à moins que le délégué ne soit un TableViewDelegate, auquel cas ces propriétés ont déjà été ajoutées) :

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

L'extrait de code suivant montre comment une application peut afficher 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 s'avérer utiles si vous souhaitez afficher un délégué différemment selon qu'il se trouve ou non 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 un ` ItemSelectionModel ` à la propriété ` selectionModel `. TableView utilisera alors ce modèle pour manipuler les ` currentIndex` du modèle.

Il incombe au délégué de s’afficher lui-même en tant qu’ current. Pour ce faire, vous pouvez lui ajouter une propriété required property bool current et faire en sorte que son apparence dépende de son état. La valeur de la propriété current est définie par la TableView. Vous pouvez également désactiver complètement la navigation au clavier (si vous souhaitez implémenter vos propres gestionnaires de touches) en définissant keyNavigationEnabled sur false.

L'exemple suivant montre comment 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-coller

La mise en œuvre des opérations de copier-coller pour une TableView implique généralement l’utilisation d’un QUndoStack (ou d’un autre framework de fonction de retour en arrière/rétablir). L’ QUndoStack peut être utilisé pour stocker les différentes opérations effectuées sur le modèle, telles que l’ajout ou la suppression de lignes, ou le collage de données depuis le presse-papiers, avec la possibilité de les annuler ultérieurement. Cependant, une QUndoStack associée décrivant les opérations possibles et la manière de les annuler doit être conçue en fonction des besoins du modèle et de l’application. À ce titre, TableView ne propose pas d’API intégrée pour la gestion du copier-coller.

L'extrait de code suivant peut servir de 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 disponible à l'adresse QAbstractItemModel, ainsi que QClipboard. Cet extrait de code fonctionne tel quel, mais peut également être étendu pour utiliser une 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);
}

Ces deux fonctions peuvent, par exemple, être utilisées depuis 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 également 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 alterner. 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é permet de déterminer si TableView doit animer l'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 elle est définie sur false, toute animation en cours s’arrête 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 également 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`, dont l’ TableView e doit connaître la largeur.

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

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

columns : int [read-only]

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

Si le modèle est une liste, le nombre de colonnes correspondra à 1.

Cette propriété est en lecture seule.

contentHeight : real

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

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é contient la largeur de la table nécessaire pour accueillir le nombre de colonnes du modèle. Elle ne correspond généralement pas à l'width de la view, ce qui signifie que la largeur de la table peut être supérieure ou inférieure à celle de la fenêtre d'affichage. Comme un « TableView » ne peut pas toujours connaître la largeur exacte de la table sans charger toutes les colonnes du modèle, la propriété « contentWidth » correspond généralement à une estimation basée sur la table initialement chargée.

Si vous connaissez la largeur de la table, 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 renferme l'élément sélectionné ( current. ). Si aucun élément n'est sélectionné, elle prend la valeur « -1 ».

Voir également currentRow, selectionModel et Selecting items.

currentRow : int [read-only]

Cette propriété en lecture seule contient la ligne de la vue qui renferme l'élément sélectionné ( current. ). Si aucun élément n'est sélectionné, elle prend la valeur « -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 mis en forme conformément au 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 accessible via la propriété index. 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 à l’aide de ` implicitWidth ` et ` implicitHeight`. La propriété ` TableView ` organise les éléments en fonction de ces informations. Les paramètres explicites de largeur ou de hauteur sont ignorés et remplacés.

À l’intérieur du délégué, vous pouvez, si vous le souhaitez, 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 indiquer au délégué dans quel état il se trouve. Le délégué peut s’en servir pour s’afficher différemment en fonction de son propre état.

• propriété obligatoire bool current - true si le délégué est current.
• propriété obligatoire bool selected - true si le délégué est selected.
• propriété obligatoire bool editing — true si le délégué est en cours de edited.
• propriété obligatoire bool containsDrag - true si une colonne ou une ligne est en cours de glissement 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 obligatoires », « TableViewDelegate » et « Personnalisation de TableViewDelegate ».

delegateModelAccess : enumeration [since 6.10]

Cette propriété détermine la manière dont 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 également Modèles et vues dans Qt Quick#Modification des données du modèle.

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

Cette propriété définit les différentes façons dont l'utilisateur peut commencer à modifier une cellule. Elle peut être une combinaison des valeurs suivantes :

Pour que les événements « TableView.SelectedTapped », « TableView.EditKeyPressed » et « TableView.AnyKeyPressed » aient un effet, « TableView » doit se voir attribuer un « selection model », car ils dépendent de la définition d’un « current index ». Pour pouvoir recevoir des événements de touche, « TableView » doit également disposer d’un « 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 définissant 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 également TableView::editDelegate, TableView::commit et Editing cells.

keyNavigationEnabled : bool [since 6.4]

Cette propriété permet de déterminer si l'utilisateur doit pouvoir modifier 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 également Keyboard navigation, selectionModel, selectionBehavior, pointerNavigationEnabled et interactive.

leftColumn : int

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

Voir également rightColumn, topRow et bottomRow.

model : model

Cette propriété contient le modèle qui fournit les données du tableau.

Le modèle fournit l'ensemble de données utilisé 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 également Modèles de données.

pointerNavigationEnabled : bool [since 6.4]

Cette propriété permet de déterminer si l'utilisateur peut modifier l'the current index ation à l'aide de la souris ou d'un écran tactile. 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 faisant glisser le curseur 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 faisant glisser le curseur 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é détermine si les éléments instanciés à partir de l'delegate doivent être réutilisés ou non. Si elle est définie sur « false », tous les éléments actuellement mis en pool sont détruits.

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

rightColumn : int

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

Voir également 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, dont l’ TableView e doit connaître la hauteur.

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

Voir également 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 de la table.

Cette propriété est en lecture seule.

selectionBehavior : enumeration [since 6.4]

Cette propriété s'applique que l'utilisateur puisse sélectionner des cellules, des lignes ou des colonnes.

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

Voir également Selecting items, selectionMode, selectionModel et keyNavigationEnabled.

selectionMode : enumeration [since 6.6]

Si la propriété selectionBehavior est définie sur TableView.SelectCells, cette propriété détermine si l'utilisateur peut sélectionner une cellule à la fois ou plusieurs cellules. Si la propriété selectionBehavior est définie sur TableView.SelectRows, cette propriété détermine si l'utilisateur peut sélectionner une ligne à la fois ou plusieurs lignes. Si la propriété selectionBehavior est définie sur TableView.SelectColumns, cette propriété détermine 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 également Selecting items, selectionBehavior, selectionModel et keyNavigationEnabled.

selectionModel : ItemSelectionModel [since 6.2]

Cette propriété permet de déterminer quels éléments du délégué doivent être affichés comme sélectionnés, et quel élément doit être affiché comme actif. Si le délégué dispose d’une propriété « required property bool selected » définie, « TableView » la synchronisera avec l’état de sélection de l’élément correspondant dans le modèle de sélection. Si le délégué dispose d’une propriété « required property bool current » définie, « TableView » la synchronisera avec « selectionModel.currentIndex ».

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

Voir également Selecting items, SelectionRectangle, keyNavigationEnabled et pointerNavigationEnabled.

syncDirection : Qt::Orientations

Si l'syncView est définie sur « TableView », cette propriété contrôle la synchronisation du sens (ou des sens) de défilement rapide pour les deux tables. La valeur par défaut est « Qt.Horizontal | Qt.Vertical », ce qui signifie que si vous faites défiler rapidement l'une des tables dans n'importe quelle direction, l'autre table est déplacée de la même distance dans la même direction.

Cette propriété et la propriété « syncView » peuvent être utilisées pour synchroniser de manière fluide le défilement de deux TableViews, indépendamment des différences en matière de dépassement/sous-dépassement, de vitesse, d’accélération/décélération ou d’animation de rebond, etc.

Un cas d’utilisation typique consiste à faire défiler plusieurs en-têtes en même temps que la table.

Voir également syncView.

syncView : TableView

Si cette propriété d'un ` TableView ` est définie sur un autre ` TableView`, les deux tableaux se synchroniseront en matière de défilement, de largeurs de colonnes/hauteurs de lignes et d'espacement, conformément à syncDirection.

Si syncDirection contient Qt.Horizontal, les largeurs de colonnes, l'espacement entre les colonnes et le défilement horizontal de la tableView actuelle se synchronisent avec ceux de syncView.

Si syncDirection contient Qt.Vertical, les hauteurs de ligne, l'espacement entre les lignes et le déplacement par balayage vertical de la tableView actuelle se synchronisent avec ceux de la syncView.

Voir également syncDirection.

topRow : int

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

Voir également leftColumn, rightColumn et bottomRow.

Documentation sur les propriétés associées

TableView.editDelegate : Component [attached]

Cette propriété associée contient le délégué d’édition. Elle est instanciée au début de l’édition et est rattachée au délégué qu’elle modifie. Elle prend en charge les mêmes propriétés obligatoires que l’ TableView delegate, notamment index, row et column. Les propriétés du modèle, telles que display et edit, sont également disponibles (en fonction de l’ role names exposée par le modèle).

La modification commence lorsque les conditions spécifiées par editTriggers sont remplies et que la cellule actuelle est modifiable.

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

L’édition prend fin lorsque l’utilisateur appuie sur Qt::Key_Enter ou Qt::Key_Return (ainsi que sur Qt::Key_Tab ou Qt::Key_Backtab, si TableView a QQuickItem::activeFocusOnTab défini). Dans ce cas, le signal « TableView::commit » sera émis, afin que le délégué d’édition puisse réagir en réécrivant les données modifiées dans le modèle. Si l’édition prend fin pour d’autres raisons (par exemple si l’utilisateur appuie sur Qt::Key_Escape), le signal ne sera pas émis. Dans tous les cas, le signal « destruction() » sera émis à la fin.

Tant que le délégué d’édition est affiché, la cellule sous-jacente reste visible et transparaîtra donc si le délégué d’édition est translucide ou s’il ne recouvre pas entièrement la cellule. Si vous ne le souhaitez pas, vous pouvez soit définir l’élément racine du délégué d’édition comme opaque ( Rectangle), soit masquer certains des éléments à l’intérieur du délégué d’édition ( TableView delegate.). Cette dernière option peut être mise en œuvre en définissant une propriété required property bool editing à l’intérieur du délégué, que vous liez à la propriété visible de certains des éléments enfants. L’extrait de code 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() sur celui-ci. Si vous souhaitez plutôt que le focus actif soit placé sur un enfant du délégué d’édition, faites en sorte que ce délégué 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 [attached]

Cette propriété associée contient la vue qui gère l'instance du délégué. Elle est associée à chaque instance du 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 le nouvel 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 l'loaded a potentiellement changé. C'est notamment le cas lorsque la méthode forceLayout() est appelée, mais aussi, par exemple, lors du redimensionnement d'une ligne ou d'une colonne, ou lorsqu'une ligne ou une colonne est entrée ou sortie de la zone d'affichage.

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 également ` 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'index logique de la ligne est spécifié par logicalIndex, l'ancien index par oldVisualIndex et le nouvel index par newVisualIndex.

Ce signal a été introduit dans Qt 6.8.

Documentation du signal ci-joint

[attached] commit()

Ce signal est émis par le edit delegate

Ce signal est émis lorsque l'option « edit delegate » est active et que l'utilisateur appuie sur « Qt::Key_Enter » ou « Qt::Key_Return ». Il est également émis si l'option « TableView » a la valeur « QQuickItem::activeFocusOnTab » et que l'utilisateur appuie sur « Qt::Key_Tab » ou « Qt::Key_Backtab ».

Ce signal ne sera pas émis si la modification prend fin 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 de modification est supprimée, ou si l'application appelle closeEditor().

À la réception du signal, le délégué d’édition doit réécrire toutes les données modifiées dans le modèle.

Voir également TableView::editDelegate, editTriggers et Editing cells.

[attached] pooled()

Ce signal est émis lorsqu'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 au sein 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 définie sur ` true`.

Voir également Reusing items, reuseItems et reused.

[attached] 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 au sein d'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 création initiale.

Ce signal n’est émis que si la propriété ` reuseItems ` est définie sur ` true`.

Voir également Reusing items, reuseItems et pooled.

Documentation des méthodes

[since 6.4] point cellAtIndex(QModelIndex modelIndex)

Renvoie la cellule de la vue qui correspond à l'modelIndex e du modèle. Fonction pratique permettant d'effectuer l'opération suivante :

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

Une cellule est simplement un « point » qui combine une ligne et une 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'position indiquée dans le tableau. L'position doit être relative à l'contentItem. Si aucune cellule de l'loaded ne recoupe l'position, la valeur renvoyée sera point(-1, -1).

Si includeSpacing est défini sur true, le cadre de délimitation d’une cellule sera considéré comme incluant la moitié des zones adjacentes rowSpacing et columnSpacing de chaque côté. La valeur par défaut est false.

Voir également columnSpacing et rowSpacing.

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

Pour faciliter les appels vers cellAtPosition(Qt.point(x, y), includeSpacing).

[since 6.8] void clearColumnReordering()

Réinitialise tout réordonnancement des colonnes appliqué précédemment.

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

void clearColumnWidths()

Efface toutes les largeurs de colonne définies à l'aide de la fonction ` setColumnWidth()`.

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

void clearRowHeights()

Efface toutes les hauteurs de ligne définies à l'aide de la fonction ` setRowHeight()`.

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

[since 6.8] void clearRowReordering()

Réinitialise tout réordonnancement des lignes précédemment appliqué.

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

[since 6.5] void closeEditor()

Si l'utilisateur est en train de modifier une cellule, l'appel de cette fonction mettra fin à la modification et détruira l'instance du délégué d'édition.

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

Voir également 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 également ` rowAtIndex()` et ` index()`.

[since 6.2] real columnWidth(int column)

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

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

Voir également 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 correspondant à modelIndex. Si l'utilisateur est déjà en train de modifier une autre cellule, cette session prend fin.

Normalement, vous pouvez spécifier les différentes façons de lancer 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 également closeEditor(), editTriggers, TableView::editDelegate et Editing cells.

real explicitColumnWidth(int column)

Renvoie la largeur de l'column définie avec la fonction setColumnWidth(). Cette largeur peut différer de la largeur réelle de la colonne si une columnWidthProvider est utilisée. Pour obtenir la largeur réelle d'une colonne, utilisez la fonction columnWidth().

Une valeur de retour égale à 0 signifie que la colonne a reçu l’instruction de se masquer. 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 l'row définie avec la fonction setRowHeight(). Cette hauteur peut différer de la hauteur réelle de la colonne si un rowHeightProvider est utilisé. Pour obtenir la hauteur réelle d'une ligne, utilisez la fonction rowHeight().

Une valeur de retour égale à 0 signifie que la ligne a reçu l’instruction de se masquer. 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 apportées au modèle sont regroupées par lots, de sorte qu’elles ne sont traitées qu’une seule fois par image. Cela signifie que l’ TableView retarde l’affichage de toute modification 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 force l’ TableView à mettre immédiatement à jour la mise en page afin que les modifications récentes prennent effet.

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

[since 6.2] real implicitColumnWidth(int column)

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

Si l'column n'est pas chargée (et n'est donc pas visible), la valeur renvoyée est -1.

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

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

[since 6.2] real implicitRowHeight(int row)

Renvoie la hauteur implicite de l'row donné. Il s'agit de la plus grande valeur implicitHeight trouvée parmi les éléments délégués loaded actuellement présents dans cette ligne.

Si l'row n'est pas chargée (et n'est donc pas visible), la valeur renvoyée est -1.

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

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

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

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

row column doit correspondre à la ligne et à la colonne de la vue (ligne et colonne du tableau), et non à une ligne et une colonne du modèle. Pour un simple ` `, cela revient à appeler ` `. Mais pour une sous-classe de ` `, comme ` `, où le modèle de données est encapsulé dans un modèle proxy interne qui aplatit la structure arborescente en un tableau, vous devez utiliser cette fonction pour résoudre l’index du modèle. TableView model.index(row, column). TableView TreeView

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

Voir également rowAtIndex() et columnAtIndex().

[since 6.2] bool isColumnLoaded(int column)

Renvoie « true » si l'column on fournie est chargée.

Une colonne est chargée lorsque TableView a chargé les éléments de délégué nécessaires à l’affichage de 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 avez besoin de parcourir les éléments délégués d’une colonne, par exemple à partir d’un ` columnWidthProvider`, afin de vous assurer que ces éléments 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 l'row on fournie est chargée.

Une ligne est chargée lorsque TableView a chargé les éléments délégués nécessaires à l’affichage de la ligne dans la vue. Cela signifie généralement que la ligne est visible pour l’utilisateur, mais ce n’est pas toujours le cas.

Cette fonction peut être utilisée chaque fois que vous avez besoin de parcourir les éléments délégués d’une ligne, par exemple à partir d’un ` rowHeightProvider`, afin de vous assurer que ces éléments sont disponibles pour le parcours.

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

Item itemAtCell(point cell)

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

[since 6.5] Item itemAtIndex(QModelIndex index)

Renvoie l'élément délégué instancié pour la cellule représentant 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 pratique pour effectuer :

index(cell.y, cell.x)

Un « cell » est simplement un « point » qui combine une ligne et une colonne en un seul type.

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

Voir également index().

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

Déplace une colonne de la position « source » vers 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 » vers la position « destination ».

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

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

Positions contentX et contentY telles que cell se trouve à la position indiquée par mode. mode peut être une combinaison (via l'opérateur « ou ») 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.

Vous pouvez éventuellement spécifier ` offset ` pour déplacer `contentX ` et `contentY` 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 trouve dans le coin supérieur gauche avec une marge de 5 px, vous pouvez procéder ainsi :

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

À partir de Qt 6.4, vous pouvez spécifier une valeur « subRect » pour positionner la vue sur un rectangle situé à l’intérieur de la cellule ( cell), plutôt que sur le rectangle englobant de la cellule entière. Cela peut s’avérer utile si, par exemple, la cellule est plus grande que la vue et que vous souhaitez vous assurer qu’une partie spécifique de celle-ci soit visible. L’ subRect doit être définie sur « valid » pour être prise en compte.

Les méthodes ne doivent être appelées qu’une fois que le composant est initialisé. 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)

contentX e les positions de telle sorte que column se trouve à la position indiqué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 manière à ce que index se trouve à l'emplacement spécifié par mode, offset et subRect.

Méthode de commodité pour appeler

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)

contentY e les positions de manière à ce que row se trouve à 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 également columnAtIndex() et index().

[since 6.2] real rowHeight(int row)

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

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

Voir également 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 » sur « size ».

Si vous souhaitez récupérer les valeurs définies à l’aide de cette fonction, vous devez utiliser explicitColumnWidth(). La fonction columnWidth() renvoie la taille réelle de la colonne, qui peut être différente si une valeur columnWidthProvider est définie.

Lorsque TableView doit déterminer la largeur de column, il essaie d'abord d'appeler le columnWidthProvider. Ce n’est que si aucun fournisseur n’est défini que les largeurs définies à l’aide de cette fonction seront utilisées par défaut. Vous pouvez toutefois appeler ` explicitColumnWidth()` depuis le fournisseur et, si nécessaire, ajuster les valeurs afin qu’elles restent, par exemple, toujours dans un certain intervalle. L’extrait de code 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 masquée. Si size est égal à -1, la colonne sera réinitialisée pour utiliser implicitColumnWidth(). Vous pouvez spécifier des tailles de colonnes qui dépassent les dimensions du modèle.

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

void setRowHeight(int row, real size)

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

Si vous souhaitez récupérer les valeurs que vous avez définies à l’aide de cette fonction, vous devez utiliser explicitRowHeight(). La fonction rowHeight() renverra la hauteur réelle de la ligne, qui peut être différente si une rowHeightProvider est définie.

Lorsque TableView doit déterminer la hauteur de row, elle essaiera d’abord d’appeler le rowHeightProvider. Ce n’est que si aucun fournisseur n’est défini que les hauteurs définies à l’aide de cette fonction seront utilisées par défaut. Vous pouvez toutefois appeler ` explicitRowHeight()` depuis le fournisseur et, si nécessaire, moduler les valeurs afin qu’elles restent, par exemple, toujours dans un certain intervalle. L’extrait de code 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 masquée. Si size est égal à -1, la ligne sera réinitialisée pour utiliser implicitRowHeight(). Vous pouvez spécifier des tailles de ligne pour les lignes qui dépassent les dimensions du modèle.

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