TreeView QML Type

Propose une arborescence permettant d'afficher les données d'une QAbstractItemModel. En savoir 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 dispose d'un modèle ( model ) qui définit les données à afficher, et d'un présentoir ( delegate ) qui définit la manière dont ces données doivent être affichées.

TreeView hérite de TableView. Cela signifie que, bien que le modèle présente une structure arborescente parent-enfant, TreeView utilise en interne un modèle proxy qui convertit cette structure en un modèle de table plat pouvant être rendu par TableView. Chaque nœud de l'arborescence occupe finalement une ligne dans la table, dont la première colonne affiche l'arborescence elle-même. En indentant chaque élément délégué dans cette colonne en fonction de sa profondeur parent-enfant dans le modèle, on obtient finalement l’apparence d’une arborescence, même si, techniquement, il ne s’agit toujours que d’une simple liste plate d’éléments.

Déclarer un TreeView

TreeView est un contrôle lié à des données ; il ne peut donc rien afficher sans modèle de données. Il n’est pas possible de déclarer des nœuds d’arborescence 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 dérivés de ` QAbstractItemModel`.
• Un délégué. Un délégué est un modèle qui spécifie la manière dont les nœuds de l’arborescence 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 héritant de ` QAbstractItemModel`.

Pour plus d'informations sur la création et l'utilisation d'un modèle d'arborescence personnalisé, consultez l'exemple : Qt Quick Controls - Table des matières.

Personnalisation des nœuds de l'arborescence

Pour plus de 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 ControlsTreeViewDelegate propose un modèle prêt à l’emploi pouvant être utilisé à cette fin, ce qui présente l’avantage de fonctionner immédiatement et d’afficher une arborescence respectant le style de la plateforme sur laquelle l’application s’exécute.

Même si l’ TreeViewDelegate est personnalisable, il peut arriver que vous souhaitiez afficher l’arborescence différemment, ou veiller à ce que le délégué soit aussi minimaliste que possible, peut-être pour des raisons de performances. Créer votre propre délégué à partir de zéro est facile, car TreeView propose un ensemble de propriétés permettant de positionner et d’afficher correctement chaque nœud de l’arborescence.

Vous trouverez ci-dessous un exemple de délégué personnalisé avec un indicateur animé :

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 renseignées par TreeView et s’apparentent à des propriétés attachées. En les marquant comme obligatoires, le délégué indique indirectement à TreeView qu’il doit se charger 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 contenant l’élément du délégué.
• required property bool isTreeNode - Est « true » si l’élément délégué représente un nœud de l’arborescence. Une seule colonne de la vue sera utilisée pour dessiner l’arborescence ; par conséquent, seuls les éléments délégués de cette colonne verront cette propriété définie sur « true ». Un nœud de l’arborescence doit généralement être indenté en fonction de son « depth » et afficher un indicateur si « hasChildren » est défini sur « true ». Les éléments délégués des 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 défini sur « true » si l'élément du modèle représenté par le délégué est développé dans la vue.
• required property bool hasChildren - Vaut true si l’élément du modèle dessiné par le délégué possède 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 correspond au nombre de ses ancêtres dans le modèle.

Voir également Propriétés obligatoires.

Interaction avec l’utilisateur final

Par défaut, TreeView toggles l'état développé d'une ligne lorsque vous appuyez deux fois dessus. Comme cela entre en conflit avec le double-appui permettant de modifier une cellule, TreeView définit editTriggers sur TableView.EditKeyPressed par défaut (ce qui diffère de TableView, qui utilise TableView.EditKeyPressed | TableView.DoubleTapped. Si vous modifiez editTriggers pour qu’il contienne également TableView.DoubleTapped, la bascule de l’état développé par un double-appui sera désactivée.

Documentation sur les propriétés

rootIndex : QModelIndex [since 6.6]

Cette propriété contient l'index du modèle correspondant à l'élément racine de l'arborescence. Par défaut, il s'agit de l'index de la racine dans le modèle, mais vous pouvez le définir comme étant l'index d'un enfant afin de n'afficher qu'une branche de l'arborescence. Définissez-le sur « undefined » pour afficher l'intégralité du modèle.

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

Documentation sur les signaux

collapsed(row, recursively)

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

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

expanded(row, depth)

Ce signal est émis lorsqu’un élément de type « row » est développé dans la vue. Les signaux « row » et « depth » seront égaux aux arguments passés à l’appel ayant provoqué le développement (expand() ou expandRecursively()). Dans le cas de expand(), le signal « depth » sera toujours 1. Dans le cas de expandToIndex(), le signal « depth » correspondra à 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'arborescence situé à l'row indiquée dans la vue.

row Il doit s'agir d'une ligne de la vue (ligne du tableau), et non d'une ligne du modèle.

Voir également expand() et isExpanded().

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

Réduit récursivement le nœud de l'arborescence situé à l'row indiquée dans la vue, jusqu'à toutes les feuilles.

Si un modèle comporte plusieurs racines, vous pouvez également appeler cette fonction en définissant l'row sur -1. Cela repliera toutes les racines. Par conséquent, l'appel de collapseRecursively(-1), ou simplement collapseRecursively(), repliera tous les nœuds du modèle.

row Il doit s’agir d’une ligne de la vue (ligne du tableau), et non d’une ligne du modèle.

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

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

int depth(row)

Renvoie la profondeur (le nombre de parents jusqu’à la racine) de l’ row donné.

row Il doit s’agir d’une ligne de la vue (ligne de table), et non d’une ligne du modèle. Si ` row ` ne se trouve pas entre ` 0 ` et ` rows`, la valeur renvoyée sera ` -1`.

Voir également modelIndex().

void expand(row)

Développe le nœud de l'arborescence situé à l'row indiquée dans la vue.

row Il doit s'agir d'une ligne de la vue (ligne du tableau), et non d'une ligne du modèle.

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

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

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

Pour un modèle comportant plusieurs racines, vous pouvez également appeler cette fonction en définissant row sur -1. Cela développera toutes les racines. Par conséquent, l'appel de expandRecursively(-1, -1), ou simplement expandRecursively(), développera tous les nœuds du modèle.

row Il doit s’agir de la ligne de la vue (ligne du tableau), et non d’une ligne du modèle.

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

Voir également collapseRecursively(), expand(), collapse(), isExpanded() et depth().

[since 6.4] void expandToIndex(QModelIndex index)

Développe l'arborescence à partir du modèle donné index, et ce de manière récursive jusqu'à la racine. Le résultat sera que l'élément délégué représentant index deviendra visible dans la vue (à moins qu'il ne se retrouve en dehors de la zone d'affichage). Pour vous assurer que la ligne soit bien visible dans la zone d'affichage, vous pouvez procéder comme suit :

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)

Renvoie si l'row on donnée dans la vue est affichée comme développée.

row row doit correspondre à une ligne de la vue (ligne du tableau), et non à une ligne du modèle. Si ne se trouve pas entre et , la valeur renvoyée sera . 0 rows false

void toggleExpanded(row)

Permet de choisir si le nœud de l'arborescence situé à l'row indiquée doit être développé. Cette option est pratique pour effectuer l'opération suivante :

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

row Il doit s'agir d'une ligne de la vue (ligne du tableau), et non d'une ligne du modèle.