TreeView QML Type

Fournit une vue arborescente pour afficher les données d'un site QAbstractItemModel. Plus....

• Liste de tous les membres, y compris les membres hérités

Propriétés

• rootIndex : QModelIndex (since 6.6)

Signaux

• collapsed(row, recursively)
• expanded(row, depth)

Méthodes

• void collapse(row)
• void collapseRecursively(row) (since 6.4)
• int depth(row)
• void expand(row)
• void expandRecursively(row, depth) (since 6.4)
• void expandToIndex(QModelIndex index) (since 6.4)
• bool isExpanded(row)
• void toggleExpanded(row)

Description détaillée

Un TreeView 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.

TreeView hérite de TableView. Cela signifie que, bien que le modèle ait une structure arborescente parent-enfant, TreeView utilise en interne un modèle proxy qui convertit cette structure en un modèle de tableau plat qui peut être rendu par TableView. Chaque nœud de l'arbre occupe une ligne du tableau, dont la première colonne représente l'arbre lui-même. En indentant chaque élément de délégué dans cette colonne en fonction de sa profondeur parent-enfant dans le modèle, celui-ci finira par ressembler à un arbre, même s'il ne s'agit techniquement que d'une liste plate d'éléments.

Déclarer un TreeView

TreeView est un contrôle lié aux données, il ne peut donc rien afficher sans modèle de données. Vous ne pouvez pas déclarer de nœuds d'arbre en QML.

Lorsque vous déclarez un TreeView, vous devez spécifier

• Un modèle de données. TreeView peut fonctionner avec des modèles de données qui dérivent de QAbstractItemModel.
• Un délégué. Un délégué est un modèle qui spécifie comment les nœuds de l'arbre sont affichés dans l'interface utilisateur.

TreeView {
    // The model needs to be a QAbstractItemModel
    model: myTreeModel
    // You can set a custom delegate or use a built-in TreeViewDelegate
    delegate: TreeViewDelegate {}
}

Création d'un modèle de données

Un TreeView n'accepte qu'un modèle qui hérite de QAbstractItemModel.

Pour plus d'informations sur la création et l'utilisation d'un modèle d'arbre personnalisé, voir l'exemple : Qt Quick Contrôles - Table des matières.

Personnaliser les nœuds de l'arbre

Pour une meilleure flexibilité, TreeView ne positionne pas lui-même les éléments du délégué dans une structure arborescente. Cette tâche incombe au délégué. Qt Quick Controls propose un site TreeViewDelegate prêt à l'emploi qui a l'avantage de fonctionner immédiatement et d'afficher un arbre conforme au style de la plate-forme sur laquelle l'application est exécutée.

Même si TreeViewDelegate est personnalisable, il peut arriver que vous souhaitiez rendre l'arbre d'une manière différente ou faire en sorte que le délégué finisse par être aussi minimal que possible, peut-être pour des raisons de performance. Il est facile de créer son propre délégué à partir de zéro, puisque TreeView offre un ensemble de propriétés qui peuvent être utilisées pour positionner et rendre correctement chaque nœud de l'arbre.

Un exemple de délégué personnalisé avec un indicateur animé est présenté ci-dessous :

import QtQuick
import QtQuick.Controls

ApplicationWindow {
    width: 800
    height: 600
    visible: true

    TreeView {
        id: treeView
        anchors.fill: parent
        anchors.margins: 10
        clip: true

        selectionModel: ItemSelectionModel {}

        // The model needs to be a QAbstractItemModel
        // model: yourTreeModel

        delegate: Item {
            implicitWidth: padding + label.x + label.implicitWidth + padding
            implicitHeight: label.implicitHeight * 1.5

            readonly property real indentation: 20
            readonly property real padding: 5

            // Assigned to by TreeView:
            required property TreeView treeView
            required property bool isTreeNode
            required property bool expanded
            required property bool hasChildren
            required property int depth
            required property int row
            required property int column
            required property bool current

            // Rotate indicator when expanded by the user
            // (requires TreeView to have a selectionModel)
            property Animation indicatorAnimation: NumberAnimation {
                target: indicator
                property: "rotation"
                from: expanded ? 0 : 90
                to: expanded ? 90 : 0
                duration: 100
                easing.type: Easing.OutQuart
            }
            TableView.onPooled: indicatorAnimation.complete()
            TableView.onReused: if (current) indicatorAnimation.start()
            onExpandedChanged: indicator.rotation = expanded ? 90 : 0

            Rectangle {
                id: background
                anchors.fill: parent
                color: row === treeView.currentRow ? palette.highlight : "black"
                opacity: (treeView.alternatingRows && row % 2 !== 0) ? 0.3 : 0.1
            }

            Label {
                id: indicator
                x: padding + (depth * indentation)
                anchors.verticalCenter: parent.verticalCenter
                visible: isTreeNode && hasChildren
                text: "▶"

                TapHandler {
                    onSingleTapped: {
                        let index = treeView.index(row, column)
                        treeView.selectionModel.setCurrentIndex(index, ItemSelectionModel.NoUpdate)
                        treeView.toggleExpanded(row)
                    }
                }
            }

            Label {
                id: label
                x: padding + (isTreeNode ? (depth + 1) * indentation : 0)
                anchors.verticalCenter: parent.verticalCenter
                width: parent.width - padding - x
                clip: true
                text: model.display
            }
        }
    }
}

Les propriétés marquées comme required seront remplies par TreeView et sont similaires aux propriétés attachées. En les marquant comme obligatoires, le délégué informe indirectement TreeView qu'il doit prendre la responsabilité de leur attribuer des valeurs. Les propriétés obligatoires suivantes peuvent être ajoutées à un délégué :

• required property TreeView treeView - Pointe vers le TreeView qui contient l'élément délégué.
• required property bool isTreeNode - Est true si l'élément délégué représente un nœud dans l'arbre. Une seule colonne de la vue sera utilisée pour dessiner l'arbre et, par conséquent, seuls les éléments délégués de cette colonne auront cette propriété définie sur true. Un nœud de l'arbre doit généralement être indenté en fonction de son depth, et afficher un indicateur si hasChildren est true. Les éléments délégués dans d'autres colonnes auront cette propriété définie sur false, et afficheront les données des colonnes restantes du modèle (et ne seront généralement pas indentés).
• required property bool expanded - Est true si l'élément de modèle dessiné par le délégué est développé dans la vue.
• required property bool hasChildren - Est true si l'élément de modèle dessiné par le délégué a des enfants dans le modèle.
• required property int depth - Contient la profondeur de l'élément de modèle dessiné par le délégué. La profondeur d'un élément de modèle est la même que le nombre d'ancêtres qu'il a dans le modèle.

Voir aussi Propriétés requises.

Interaction avec l'utilisateur final

Par défaut, TreeView toggles affiche l'état développé d'une ligne lorsque vous double-cliquez dessus. Comme cela entre en conflit avec le fait de double-cliquer pour modifier une cellule, TreeView définit editTriggers comme étant TableView.EditKeyPressed par défaut (ce qui est différent de TableView, qui utilise TableView.EditKeyPressed | TableView.DoubleTapped. Si vous modifiez editTriggers pour qu'il contienne également TableView.DoubleTapped, le basculement de l'état développé avec une double tape sera désactivé.

Documentation sur les propriétés

rootIndex : QModelIndex [since 6.6]

Cette propriété contient l'index du modèle de l'élément racine de l'arbre. Par défaut, il s'agit de l'index de la racine dans le modèle, mais vous pouvez le remplacer par un index enfant pour n'afficher qu'une branche de l'arbre. Définissez-le à undefined pour afficher l'ensemble du modèle.

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

Documentation sur le signal

collapsed(row, recursively)

Ce signal est émis lorsqu'une ligne row est réduite dans la vue. row sera égal à l'argument donné à l'appel qui a provoqué la réduction (collapse() ou collapseRecursively()). Si la ligne a été réduite de manière récursive, recursively sera true.

Voir aussi expanded(), expand(), collapse(), et toggleExpanded().

expanded(row, depth)

Ce signal est émis lorsqu'un row est développé dans la vue. row et depth seront égaux aux arguments donnés à l'appel qui a provoqué le développement (expand() ou expandRecursively()). Dans le cas de expand(), depth sera toujours 1. Dans le cas de expandToIndex(), depth sera la profondeur de l'index cible.

Voir également collapsed(), expand(), collapse() et toggleExpanded().

Documentation de la méthode

void collapse(row)

Réduit le nœud de l'arbre à l'adresse row dans la vue.

row doit être la ligne dans la vue (ligne du tableau), et non une ligne dans le modèle.

Voir également expand() et isExpanded().

[since 6.4] void collapseRecursively(row = -1)

Réduit le nœud de l'arbre à l'adresse row dans la vue de manière récursive jusqu'à toutes les feuilles.

Pour un modèle ayant plus d'une racine, vous pouvez également appeler cette fonction avec row égal à -1, ce qui aura pour effet de réduire toutes les racines. Par conséquent, l'appel à collapseRecursively(-1), ou simplement à collapseRecursively(), réduira tous les nœuds du modèle.

row doit être la ligne de la vue (ligne du tableau), et non une ligne du modèle.

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

Voir aussi expandRecursively(), expand(), collapse(), isExpanded(), et depth().

int depth(row)

Renvoie la profondeur (le nombre de parents jusqu'à la racine) du site row donné.

row doit être la ligne dans la vue (ligne de table), et non une ligne dans le modèle. Si row n'est pas compris entre 0 et rows, la valeur retournée sera -1.

Voir aussi modelIndex().

void expand(row)

Développe le nœud de l'arbre à l'adresse row dans la vue.

row doit être la ligne dans la vue (ligne du tableau), et non une ligne dans le modèle.

Voir également collapse(), isExpanded() et expandRecursively().

[since 6.4] void expandRecursively(row = -1, depth = -1)

Développe le nœud de l'arbre à l'adresse row dans la vue de manière récursive jusqu'à depth. depth doit être relatif à la profondeur de row. Si depth est -1, l'arbre sera développé jusqu'à toutes les feuilles.

Pour un modèle qui a plus d'une racine, vous pouvez également appeler cette fonction avec row égal à -1. Cela développera toutes les racines. Par conséquent, l'appel à expandRecursively(-1, -1), ou simplement expandRecursively(), développera tous les nœuds du modèle.

row doit être la ligne de la vue (ligne du tableau), et non une ligne du modèle.

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

Voir aussi collapseRecursively(), expand(), collapse(), isExpanded() et depth().

[since 6.4] void expandToIndex(QModelIndex index)

Développe l'arbre à partir du modèle donné index, et de manière récursive jusqu'à la racine. Le résultat sera que l'élément délégué qui représente index deviendra visible dans la vue (à moins qu'il ne se retrouve en dehors de la fenêtre de visualisation). Pour s'assurer que la ligne finit par être visible dans la fenêtre, vous pouvez utiliser la méthode suivante :

expandToIndex(index)
forceLayout()
positionViewAtRow(rowAtIndex(index), Qt.AlignVCenter)

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

Voir également expand() et expandRecursively().

bool isExpanded(row)

Retourne si le site row donné dans la vue est affiché comme étant développé.

row doit être la ligne dans la vue (ligne de table), et non une ligne dans le modèle. Si row n'est pas situé entre 0 et rows, la valeur renvoyée sera false.

void toggleExpanded(row)

Indique si le nœud de l'arbre à l'adresse row doit être développé. Il s'agit d'une commodité :

if (isExpanded(row))
    collapse(row)
else
    expand(row)

row doit être la ligne dans la vue (ligne de table), et non une ligne dans le modèle.