ListView QML Type

Fournit une vue en liste des éléments fournis par un modèle. Plus...

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

Propriétés

• add : Transition
• addDisplaced : Transition
• cacheBuffer : int
• count : int
• currentIndex : int
• currentItem : Item
• currentSection : string
• delegate : Component
• delegateModelAccess : enumeration (since 6.10)
• displaced : Transition
• displayMarginBeginning : int (since QtQuick 2.3)
• displayMarginEnd : int (since QtQuick 2.3)
• effectiveLayoutDirection : enumeration
• footer : Component
• footerItem : Item
• footerPositioning : enumeration (since Qt 5.4)
• header : Component
• headerItem : Item
• headerPositioning : enumeration (since Qt 5.4)
• highlight : Component
• highlightFollowsCurrentItem : bool
• highlightItem : Item
• highlightMoveDuration : int
• highlightMoveVelocity : real
• highlightRangeMode : enumeration
• highlightResizeDuration : int
• highlightResizeVelocity : real
• keyNavigationEnabled : bool
• keyNavigationWraps : bool
• layoutDirection : enumeration
• model : model
• move : Transition
• moveDisplaced : Transition
• orientation : enumeration
• populate : Transition
• preferredHighlightBegin : real
• preferredHighlightEnd : real
• remove : Transition
• removeDisplaced : Transition
• reuseItems : bool
• section
  • section.criteria : enumeration
  • section.delegate : Component
  • section.labelPositioning : enumeration
  • section.property : string
• snapMode : enumeration
• spacing : real
• verticalLayoutDirection : enumeration

Propriétés rattachées

• delayRemove : bool
• isCurrentItem : bool
• nextSection : string
• previousSection : string
• section : string
• view : ListView

Signaux attachés

• add()
• pooled()
• remove()
• reused()

Méthodes

• void decrementCurrentIndex()
• void forceLayout()
• void incrementCurrentIndex()
• int indexAt(real x, real y)
• Item itemAt(real x, real y)
• Item itemAtIndex(int index)
• void positionViewAtBeginning()
• void positionViewAtEnd()
• void positionViewAtIndex(int index, PositionMode mode)

Description détaillée

Une ListView affiche des données provenant de modèles créés à partir de types QML intégrés tels que ListModel et XmlListModel, ou de classes de modèles personnalisées définies en C++ qui héritent de QAbstractItemModel ou QAbstractListModel.

Une ListView 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. Les éléments d'une ListView sont disposés horizontalement ou verticalement. Les vues de liste sont intrinsèquement modifiables, car ListView hérite de Flickable.

Exemple d'utilisation

L'exemple suivant montre la définition d'un modèle de liste simple défini dans un fichier appelé ContactModel.qml:

import QtQuick

ListModel {
    ListElement {
        name: "Bill Smith"
        number: "555 3264"
    }
    ListElement {
        name: "John Brown"
        number: "555 8426"
    }
    ListElement {
        name: "Sam Wise"
        number: "555 0473"
    }
}

Un autre composant peut afficher les données de ce modèle dans une ListView, comme ceci :

import QtQuick

ListView {
    width: 180; height: 200

    model: ContactModel {}
    delegate: Text {
        required property string name
        required property string number
        text: name + ": " + number
    }
}

Ici, le ListView crée un composant ContactModel pour son modèle et un élément Text pour son délégué. La vue créera un nouveau composant Text pour chaque élément du modèle. Remarquez que le délégué peut accéder directement aux données name et number du modèle.

Une vue de liste améliorée est présentée ci-dessous. Le délégué est visuellement amélioré et est déplacé dans un composant contactDelegate séparé.

Rectangle {
    width: 180; height: 200

    Component {
        id: contactDelegate
        Item {
            id: myItem
            required property string name
            required property string number
            width: 180; height: 40
            Column {
                Text { text: '<b>Name:</b> ' + myItem.name }
                Text { text: '<b>Number:</b> ' + myItem.number }
            }
        }
    }

    ListView {
        anchors.fill: parent
        model: ContactModel {}
        delegate: contactDelegate
        highlight: Rectangle { color: "lightsteelblue"; radius: 5 }
        focus: true
    }
}

L'élément actuellement sélectionné est mis en évidence par un Rectangle bleu à l'aide de la propriété highlight, et focus est défini sur true pour permettre la navigation au clavier dans la vue de la liste. La vue de la liste elle-même est une portée de focus (voir Focus clavier dans Qt Quick pour plus de détails).

Les délégués sont instanciés en fonction des besoins et peuvent être détruits à tout moment. En tant que tels, state should never be stored in a delegate. Les délégués sont généralement rattachés au parent de ListView contentItem, mais en général, selon qu'il est visible ou non dans la vue, le parent peut changer, et parfois être null. Pour cette raison, il n' est pas recommandé de lier les propriétés du parent à partir du délégué. Si vous souhaitez que le délégué remplisse la largeur du ListView, envisagez plutôt d'utiliser l'une des approches suivantes :

ListView {
    id: listView
    // ...

    delegate: Item {
        // Incorrect.
        width: parent.width

        // Correct.
        width: listView.width
        width: ListView.view.width
        // ...
    }
}

ListView attache un certain nombre de propriétés à l'élément racine du délégué, par exemple ListView.isCurrentItem. Dans l'exemple suivant, l'élément racine du délégué peut accéder directement à cette propriété attachée en tant que ListView.isCurrentItem, tandis que l'objet enfant contactInfo doit se référer à cette propriété en tant que wrapper.ListView.isCurrentItem.

ListView {
    width: 180; height: 200

    Component {
        id: contactsDelegate
        Rectangle {
            id: wrapper
            width: 180
            height: contactInfo.height
            color: ListView.isCurrentItem ? "black" : "red"
            Text {
                id: contactInfo
                text: name + ": " + number
                color: wrapper.ListView.isCurrentItem ? "red" : "black"
            }
        }
    }

    model: ContactModel {}
    delegate: contactsDelegate
    focus: true
}

Disposition des listes

La disposition des éléments d'une ListView peut être contrôlée par ces propriétés :

• orientation - contrôle le flux horizontal ou vertical des éléments. Cette valeur peut être Qt.Horizontal ou Qt.Vertical.
• layoutDirection - contrôle la direction de la disposition horizontale pour une vue orientée horizontalement : c'est-à-dire si les éléments sont disposés du côté gauche de la vue vers la droite, ou vice-versa. Cette valeur peut être Qt.LeftToRight ou Qt.RightToLeft.
• verticalLayoutDirection - contrôle la direction de la disposition verticale pour une vue orientée verticalement, c'est-à-dire si les éléments sont disposés du haut de la vue vers le bas de la vue, ou vice-versa. Cette valeur peut être ListView.TopToBottom ou ListView.BottomToTop.

Par défaut, un ListView a une orientation verticale et les éléments sont disposés de haut en bas. Le tableau ci-dessous montre les différentes dispositions qu'un ListView peut avoir, en fonction des valeurs des propriétés énumérées ci-dessus.

Direction de la pichenette

Par défaut, un ListView vertical définit flickableDirection sur Flickable.Vertical, et un ListView horizontal le définit sur Flickable.Horizontal. En outre, un ListView vertical ne calcule (estime) que le contentHeight, et un ListView horizontal ne calcule que le contentWidth. L'autre dimension est fixée à -1.

Depuis Qt 5.9 (Qt Quick 2.9), il est possible de créer une ListView qui peut être cliquée dans les deux sens. Pour ce faire, l'adresse flickableDirection peut être réglée sur Flickable.AutoFlickDirection ou Flickable.AutoFlickIfNeeded, et la largeur ou la hauteur du contenu doivent être indiquées.

ListView {
    width: 180; height: 200

    contentWidth: 320
    flickableDirection: Flickable.AutoFlickDirection

    model: ContactModel {}
    delegate: Row {
        Text { text: '<b>Name:</b> ' + name; width: 160 }
        Text { text: '<b>Number:</b> ' + number; width: 160 }
    }
}

Ordre d'empilement dans une liste

L'adresse Z value des éléments détermine s'ils sont affichés au-dessus ou au-dessous d'autres éléments. ListView utilise plusieurs valeurs Z par défaut, en fonction du type d'élément créé :

Ces valeurs par défaut sont définies si la valeur Z de l'élément est 0, de sorte que la définition de la valeur Z de ces éléments sur 0 n'a aucun effet. Notez que la valeur Z est de type real, il est donc possible de définir des valeurs fractionnaires comme 0.1.

Réutilisation des éléments

Depuis la version 5.15, ListView peut être configuré pour recycler les éléments au lieu de les instancier à partir de delegate chaque fois que de nouvelles lignes sont affichées. Cette approche améliore les performances, en fonction de la complexité du délégué. La réutilisation des éléments est désactivée par défaut (pour des raisons de rétrocompatibilité), mais peut être activée en définissant la propriété reuseItems sur true.

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 ListView::pooled est émis pour en informer l'élément. De même, lorsque l'élément est retiré de la réserve, le signal ListView::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 et row, 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 ListView::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.

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

Component {
    id: listViewDelegate
    Rectangle {
        width: 100
        height: 50

        ListView.onPooled: rotationAnimation.pause()
        ListView.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
            }
        }
    }
}

Taille variable des délégués et étiquettes de section

Des tailles de délégués variables peuvent entraîner le redimensionnement et le saut de tout élément attaché ScrollBar. En effet, ListView estime la taille de son contenu à partir des éléments alloués (généralement uniquement les éléments visibles, les autres étant supposés avoir une taille similaire), et les tailles variables des délégués empêchent une estimation précise. Pour réduire cet effet, cacheBuffer peut être réglé sur des valeurs plus élevées, créant ainsi plus d'éléments et améliorant l'estimation de la taille des éléments non alloués, au prix d'une utilisation supplémentaire de la mémoire. Sections a le même effet parce qu'il attache et allonge l'étiquette de la section au premier élément de la section.

Éviter de stocker l'état dans les délégués

Les délégués de ListView sont instanciés en fonction des besoins et peuvent être détruits lorsqu'ils sont hors de vue. Pour illustrer ce point, exécutez l'exemple suivant :

ListView {
    anchors.fill: parent
    model: 3
    delegate: CheckDelegate {
        text: qsTr("Channel %1").arg(index + 1)

        required property int index
        property bool channelActivated

        onClicked: channelActivated = checked
    }
}

Lorsqu'un élément est cliqué, channelActivated est défini sur true. Cependant, comme les délégués peuvent être reused et détruits, tout l'état est perdu lorsque la vue est déplacée suffisamment loin. Lorsque le délégué redevient visible, il conserve son état par défaut, non modifié (ou, dans le cas d'un élément réutilisé, l'ancien état d'un élément précédent).

Pour éviter cela, l'état doit être stocké dans le modèle :

ListView {
    anchors.fill: parent
    model: ListModel {
        ListElement {
            channelActivated: true
        }
        // ...
    }
    delegate: CheckDelegate {
        text: qsTr("Channel %1").arg(index + 1)
        checked: model.channelActivated

        required property int index
        required property var model

        onClicked: model.channelActivated = checked
    }
}

Masquage des délégués

En définissant la propriété visible d'un délégué sur false, vous masquerez cet élément, mais l'espace qu'il occupait dans la vue sera conservé. Il est possible de définir la propriété height de l'élément sur 0 (pour une ListView vertical ) :

ListView {
    anchors.fill: parent
    model: ListModel {
        ListElement { hidden: false }
        ListElement { hidden: false }
        ListElement { hidden: false }
        // ...
    }
    delegate: ItemDelegate {
        text: qsTr("Item %1").arg(index)
        visible: !model.hidden
        height: visible ? implicitHeight : 0

        required property int index
        required property var model

        onClicked: model.hidden = true
    }
}

Notez que l'état caché est stocké dans le modèle, conformément aux conseils de la section Avoid Storing State in Delegates.

Cependant, si spacing est différent de zéro, il y aura des écarts inégaux entre les délégués.

Une meilleure option consiste à filtrer votre modèle de manière à ce que les éléments qui ne doivent pas être visibles ne soient pas chargés par la vue. Cela peut être réalisé à l'aide de QSortFilterProxyModel.

Une autre option consiste à disable le délégué au lieu de le cacher.

Voir également les modèles de données QML, GridView, PathView, et Qt Quick Exemples - Vues.

Documentation sur les propriétés

add : Transition

Cette propriété contient la transition à appliquer aux éléments qui sont ajoutés à la vue.

Par exemple, voici une vue qui spécifie une telle transition :

ListView {
    ...
    add: Transition {
        NumberAnimation { properties: "x,y"; from: 100; duration: 1000 }
    }
}

Chaque fois qu'un élément est ajouté à la vue ci-dessus, l'élément sera animé depuis la position (100,100) jusqu'à sa position x,y finale dans la vue, en une seconde. La transition ne s'applique qu'aux nouveaux éléments ajoutés à la vue ; elle ne s'applique pas aux éléments situés en dessous qui sont déplacés par l'ajout des nouveaux éléments. Pour animer les éléments déplacés, définissez les propriétés displaced ou addDisplaced.

Pour plus de détails et d'exemples sur l'utilisation des transitions de vue, voir la documentation ViewTransition.

Voir également addDisplaced, populate, et ViewTransition.

addDisplaced : Transition

Cette propriété définit la transition à appliquer aux éléments de la vue qui sont déplacés par l'ajout d'autres éléments à la vue.

Par exemple, voici une vue qui spécifie une telle transition :

ListView {
    ...
    addDisplaced: Transition {
        NumberAnimation { properties: "x,y"; duration: 1000 }
    }
}

Chaque fois qu'un élément est ajouté à la vue ci-dessus, tous les éléments situés sous le nouvel élément sont déplacés, ce qui les fait descendre (ou se déplacer latéralement, s'ils sont orientés horizontalement) à l'intérieur de la vue. Au fur et à mesure que ce déplacement se produit, le mouvement des éléments vers leurs nouvelles positions x,y à l'intérieur de la vue est animé par une page NumberAnimation pendant une seconde, comme spécifié. Cette transition n'est pas appliquée au nouvel élément qui a été ajouté à la vue ; pour animer les éléments ajoutés, définissez la propriété add.

Si un élément est déplacé par plusieurs types d'opérations en même temps, il n'est pas défini si la transition addDisplaced, moveDisplaced ou removeDisplaced sera appliquée. En outre, s'il n'est pas nécessaire de spécifier des transitions différentes selon qu'un élément est déplacé par une opération d'ajout, de déplacement ou de suppression, il est préférable de définir la propriété displaced.

Pour plus de détails et d'exemples sur l'utilisation des transitions d'affichage, voir la documentation ViewTransition.

Voir également displaced, add, populate, et ViewTransition.

cacheBuffer : int

Cette propriété détermine si les délégués sont conservés en dehors de la zone visible de la vue.

Si cette valeur est supérieure à zéro, la vue peut conserver autant de délégués instanciés qu'elle peut en contenir dans la mémoire tampon spécifiée. Par exemple, si, dans une vue verticale, le délégué a une hauteur de 20 pixels et que la valeur de cacheBuffer est fixée à 40, il est possible de créer ou de conserver jusqu'à deux délégués au-dessus et deux délégués au-dessous de la zone visible. Les délégués mis en mémoire tampon sont créés de manière asynchrone, ce qui permet de les créer sur plusieurs images et de réduire la probabilité de sauter des images. Afin d'améliorer les performances de peinture, les délégués situés en dehors de la zone visible ne sont pas peints.

La valeur par défaut de cette propriété dépend de la plateforme, mais elle est généralement supérieure à zéro. Les valeurs négatives sont ignorées.

Notez que cacheBuffer n'est pas un tampon de pixels - il ne conserve que les délégués instanciés supplémentaires.

Le cacheBuffer fonctionne en dehors des marges d'affichage spécifiées par displayMarginBeginning ou displayMarginEnd.

count : int [read-only]

Cette propriété reflète le nombre d'éléments dans le modèle de ListView, qu'ils soient visibles ou instanciés en tant que Item d'un composant délégué.

La propriété currentIndex contient l'index de l'élément en cours, et currentItem contient l'élément en cours. La définition de la propriété currentIndex à -1 effacera la mise en évidence et définira la propriété currentItem à null.

Si highlightFollowsCurrentItem est true, la définition de l'une ou l'autre de ces propriétés fera défiler en douceur ListView de manière à ce que l'élément en cours devienne visible.

Notez que la position de l'élément courant peut n'être qu'approximative jusqu'à ce qu'il devienne visible dans la vue.

Comme currentItem doit fonctionner avec n'importe quel délégué, son type est Item. Souvent, un ListView est cependant utilisé avec un seul type de délégué. Dans ce cas, le casting de currentItem vers le type du délégué peut aider l'outillage et conduire à un code plus efficace :

component Message : Item {
    required property string sender
    required property string text
}
ListView {
    id: messageView
    delegate: Message {}
    model: messageModel
}
Button {
    text: "Reply to %1".arg((messageView.currentItem) as Message).sender
}

currentSection : string [read-only]

Cette propriété contient la section qui se trouve actuellement au début de la vue.

delegate : Component

Le délégué fournit un modèle définissant chaque élément instancié par la vue. L'index est exposé en tant que propriété index accessible. Les propriétés du modèle sont également disponibles en fonction du type de modèle de données.

Le nombre d'objets et de liaisons dans le délégué a un effet direct sur les performances de visualisation de la vue. Dans la mesure du possible, placez les fonctionnalités qui ne sont pas nécessaires à l'affichage normal du délégué dans un site Loader qui peut charger des composants supplémentaires en cas de besoin.

Le site ListView disposera les éléments en fonction de la taille de l'élément racine du délégué.

Il est recommandé que la taille du délégué soit un nombre entier afin d'éviter l'alignement des éléments en dessous du pixel.

La valeur par défaut de stacking order pour les instances de délégués est 1.

Voir également Stacking Order in ListView.

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.

displaced : Transition

Cette propriété contient la transition générique à appliquer aux éléments qui ont été déplacés par une opération de modélisation affectant la vue.

Elle permet de spécifier la transition générique à appliquer à tout élément déplacé par une opération d'ajout, de déplacement ou de suppression, sans avoir à spécifier les propriétés individuelles addDisplaced, moveDisplaced et removeDisplaced. Par exemple, voici une vue qui spécifie une transition déplacée :

ListView {
    ...
    displaced: Transition {
        NumberAnimation { properties: "x,y"; duration: 1000 }
    }
}

Lorsqu'un élément est ajouté, déplacé ou supprimé dans la vue ci-dessus, les éléments situés en dessous sont déplacés, ce qui les fait descendre (ou se déplacer latéralement, s'ils sont orientés horizontalement) dans la vue. Au fur et à mesure que ce déplacement se produit, le mouvement des éléments vers leurs nouvelles positions x,y à l'intérieur de la vue est animé par une page NumberAnimation pendant une seconde, comme spécifié.

Si une vue spécifie cette transition générique déplacée ainsi qu'une transition spécifique addDisplaced, moveDisplaced ou removeDisplaced, la transition la plus spécifique sera utilisée à la place de la transition générique déplacée lorsque l'opération concernée se produira, à condition que la transition la plus spécifique n'ait pas été désactivée (en attribuant la valeur false à enabled ). Si elle a été désactivée, la transition générique déplacée est appliquée à la place.

Pour plus de détails et d'exemples sur l'utilisation des transitions de vue, voir la documentation ViewTransition.

Voir également addDisplaced, moveDisplaced, removeDisplaced, et ViewTransition.

Cette propriété permet d'afficher les délégués en dehors de la géométrie de la vue.

Si cette valeur est différente de zéro, la vue créera des délégués supplémentaires avant le début de la vue ou après la fin. La vue créera autant de délégués qu'elle peut en contenir dans la taille de pixel spécifiée.

Par exemple, si, dans une vue verticale, le délégué a une hauteur de 20 pixels et que displayMarginBeginning et displayMarginEnd sont tous deux définis à 40, 2 délégués au-dessus et 2 délégués au-dessous seront créés et affichés.

La valeur par défaut est 0.

Cette propriété est destinée à permettre certaines configurations de l'interface utilisateur, et non à optimiser les performances. Si vous souhaitez créer des délégués en dehors de la géométrie de la vue pour des raisons de performances, vous devriez probablement utiliser la propriété cacheBuffer à la place.

Ces propriétés ont été introduites dans QtQuick 2.3.

effectiveLayoutDirection : enumeration [read-only]

Cette propriété définit le sens de présentation effectif d'une liste orientée horizontalement.

Lors de l'utilisation de la propriété jointe LayoutMirroring::enabled pour les mises en page locales, la direction de la mise en page visuelle de la liste horizontale sera inversée. Cependant, la propriété layoutDirection restera inchangée.

Voir également ListView::layoutDirection et LayoutMirroring.

footer : Component

Cette propriété contient le composant à utiliser comme pied de page.

Une instance du composant de pied de page est créée pour chaque vue. Le pied de page est placé à la fin de la vue, après tous les éléments. La valeur par défaut de stacking order pour le pied de page est 1.

Voir également header, footerItem, et Stacking Order in ListView.

footerItem : Item [read-only]

Il contient l'élément de pied de page créé à partir du composant footer.

Une instance du composant footer est créée pour chaque vue. Le pied de page est placé à la fin de la vue, après tous les éléments. La valeur par défaut de stacking order pour le pied de page est 1.

Voir également footer, headerItem, et Stacking Order in ListView.

footerPositioning : enumeration [since Qt 5.4]

Cette propriété détermine le positionnement du site footer item.

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

header : Component

Cette propriété contient le composant à utiliser comme en-tête.

Une instance du composant d'en-tête est créée pour chaque vue. L'en-tête est placé au début de la vue, avant tout élément. La valeur par défaut de stacking order pour l'en-tête est 1.

Voir également footer, headerItem, et Stacking Order in ListView.

headerItem : Item [read-only]

Il contient l'élément d'en-tête créé à partir du composant header.

Une instance du composant d'en-tête est créée pour chaque vue. L'en-tête est placé au début de la vue, avant tout autre élément. stacking order La valeur par défaut de l'en-tête est 1.

Voir également header, footerItem, et Stacking Order in ListView.

headerPositioning : enumeration [since Qt 5.4]

Cette propriété détermine le positionnement du site header item.

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

highlight : Component

Cette propriété contient le composant à utiliser pour la mise en évidence.

Une instance du composant de mise en évidence est créée pour chaque liste. La géométrie de l'instance du composant résultant est gérée par la liste de manière à rester avec l'élément courant, sauf si la propriété highlightFollowsCurrentItem est fausse. La valeur par défaut de stacking order pour l'élément de mise en évidence est 0.

Voir également highlightItem, highlightFollowsCurrentItem, ListView Highlight Example, et Stacking Order in ListView.

highlightFollowsCurrentItem : bool

Cette propriété indique si la mise en évidence est gérée par la vue.

Si cette propriété vaut true (valeur par défaut), la surbrillance est déplacée en douceur pour suivre l'élément en cours. Dans le cas contraire, le surlignage n'est pas déplacé par la vue et tout mouvement doit être réalisé par le surlignage.

Voici une mise en évidence dont le mouvement est défini par un élément SpringAnimation:

Component {
    id: highlight
    Rectangle {
        width: 180; height: 40
        color: "lightsteelblue"; radius: 5
        y: list.currentItem.y
        Behavior on y {
            SpringAnimation {
                spring: 3
                damping: 0.2
            }
        }
    }
}

ListView {
    id: list
    width: 180; height: 200
    model: ContactModel {}
    delegate: Text { text: name }

    highlight: highlight
    highlightFollowsCurrentItem: false
    focus: true
}

Notez que l'animation de la surbrillance affecte également la manière dont la vue est déroulée. En effet, la vue se déplace pour maintenir la mise en évidence dans la plage de mise en évidence préférée (ou la zone de visualisation visible).

Voir également highlight et highlightMoveVelocity.

highlightItem : Item [read-only]

Il contient l'élément de mise en évidence créé à partir du composant highlight.

L'élément highlightItem est géré par la vue, sauf si highlightFollowsCurrentItem est défini comme faux. La valeur par défaut de stacking order pour l'élément de mise en évidence est 0.

Voir également highlight, highlightFollowsCurrentItem, et Stacking Order in ListView.

Ces propriétés contrôlent la vitesse des animations de déplacement et de redimensionnement du délégué de mise en évidence.

highlightFollowsCurrentItem doit être vrai pour que ces propriétés aient un effet.

La valeur par défaut des propriétés velocity est de 400 pixels/seconde. La valeur par défaut des propriétés de durée est -1, ce qui signifie que la mise en évidence prendra le temps nécessaire pour se déplacer à la vitesse définie.

Ces propriétés ont les mêmes caractéristiques qu'une SmoothedAnimation: si la vitesse et la durée sont toutes deux définies, l'animation utilisera celle qui a la durée la plus courte.

Les propriétés move velocity et duration sont utilisées pour contrôler les mouvements dus aux changements d'index ; par exemple, lorsque incrementCurrentIndex() est appelé. Lorsque l'utilisateur donne une pichenette à ListView, la vitesse de la pichenette est utilisée pour contrôler le mouvement.

Pour définir une seule propriété, l'autre peut être définie sur -1. Par exemple, si vous souhaitez animer uniquement la durée et non la vitesse, utilisez le code suivant :

highlightMoveDuration: 1000
highlightMoveVelocity: -1

Voir aussi highlightFollowsCurrentItem.

Ces propriétés définissent l'étendue préférée de la mise en évidence (pour l'élément en cours) dans la vue. La valeur preferredHighlightBegin doit être inférieure à la valeur preferredHighlightEnd.

Ces propriétés affectent la position de l'élément en cours lors du défilement de la liste. Par exemple, si l'élément sélectionné doit rester au milieu de la liste lors du défilement de la vue, définissez les valeurs preferredHighlightBegin et preferredHighlightEnd comme étant les coordonnées supérieures et inférieures de l'emplacement de l'élément central. Si la valeur currentItem est modifiée par programme, la liste défilera automatiquement de manière à ce que l'élément actuel se trouve au milieu de la vue. En outre, le comportement de l'index de l'élément courant se produira qu'il y ait ou non une mise en évidence.

Les valeurs valides pour highlightRangeMode sont les suivantes

keyNavigationEnabled : bool

Cette propriété indique si la navigation au clavier de la liste est activée.

Si cette propriété vaut true, l'utilisateur peut naviguer dans la vue à l'aide du clavier. Cette propriété est utile pour les applications qui doivent activer ou désactiver sélectivement l'interaction avec la souris et le clavier.

Par défaut, la valeur de cette propriété est liée à interactive afin d'assurer la compatibilité du comportement des applications existantes. Lorsqu'elle est définie explicitement, elle cesse d'être liée à la propriété interactive.

Voir également interactive.

keyNavigationWraps : bool

Cette propriété indique si la navigation par touche de la liste est enveloppante.

Si c'est le cas, la navigation par touche qui déplacerait la sélection de l'élément en cours au-delà de la fin de la liste s'enroule et déplace la sélection au début de la liste, et vice-versa.

Par défaut, la navigation par touche n'est pas enveloppée.

layoutDirection : enumeration

Cette propriété indique la direction de la mise en page d'une liste orientée horizontalement.

Valeurs possibles :

La définition de cette propriété n'a aucun effet si le site orientation est Qt.Vertical.

Voir également ListView::effectiveLayoutDirection et ListView::verticalLayoutDirection.

model : model

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

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 ListModel, ObjectModel, ou fournis par des classes de modèles C++. Si une classe de modèle C++ est utilisée, il doit s'agir d'une sous-classe de QAbstractItemModel ou d'une simple liste.

Voir aussi Modèles de données.

move : Transition

Cette propriété définit la transition à appliquer aux éléments de la vue qui sont déplacés à la suite d'une opération de déplacement dans la vue model.

Par exemple, voici une vue qui spécifie une telle transition :

ListView {
    ...
    move: Transition {
        NumberAnimation { properties: "x,y"; duration: 1000 }
    }
}

Chaque fois que model effectue une opération de déplacement d'un ensemble particulier d'index, les éléments respectifs de la vue seront animés jusqu'à leur nouvelle position dans la vue en l'espace d'une seconde. La transition ne s'applique qu'aux éléments qui font l'objet de l'opération de déplacement dans le modèle ; elle ne s'applique pas aux éléments situés en dessous qui sont déplacés par l'opération de déplacement. Pour animer les éléments déplacés, définissez les propriétés displaced ou moveDisplaced.

Pour plus de détails et d'exemples sur l'utilisation des transitions de vue, voir la documentation ViewTransition.

Voir également moveDisplaced et ViewTransition.

moveDisplaced : Transition

Cette propriété définit la transition à appliquer aux éléments déplacés par une opération de déplacement dans la vue model.

Par exemple, voici une vue qui spécifie une telle transition :

ListView {
    ...
    moveDisplaced: Transition {
        NumberAnimation { properties: "x,y"; duration: 1000 }
    }
}

Chaque fois que model effectue une opération de déplacement d'un ensemble particulier d'index, les éléments situés entre les index source et destination de l'opération de déplacement sont déplacés, ce qui entraîne leur déplacement vers le haut ou vers le bas (ou latéralement, s'ils sont orientés horizontalement) à l'intérieur de la vue. Au fur et à mesure que ce déplacement se produit, le mouvement des éléments vers leurs nouvelles positions x,y à l'intérieur de la vue est animé par une page NumberAnimation pendant une seconde, comme spécifié. Cette transition n'est pas appliquée aux éléments qui sont les sujets réels de l'opération de déplacement ; pour animer les éléments déplacés, définissez la propriété move.

Si un élément est déplacé par plusieurs types d'opérations en même temps, il n'est pas défini si la transition addDisplaced, moveDisplaced ou removeDisplaced sera appliquée. En outre, s'il n'est pas nécessaire de spécifier des transitions différentes selon qu'un élément est déplacé par une opération d'ajout, de déplacement ou de suppression, envisagez plutôt de définir la propriété displaced.

Pour plus de détails et d'exemples sur l'utilisation des transitions d'affichage, voir la documentation ViewTransition.

Voir également displaced, move, et ViewTransition.

orientation : enumeration

Cette propriété définit l'orientation de la liste.

Valeurs possibles :

Constante	Description de la propriété
ListView.Horizontal	Les éléments sont disposés horizontalement
ListView.Vertical	(par défaut) Les éléments sont présentés verticalement

Voir aussi Flickable Direction.

populate : Transition

Cette propriété contient la transition à appliquer aux éléments créés initialement pour une vue.

Elle s'applique à tous les éléments créés lorsque :

• la vue est créée pour la première fois
• Le site model de la vue change de manière à ce que les délégués visibles soient complètement remplacés.
• La vue model est reset, si le modèle est une sous-classe de QAbstractItemModel.

Par exemple, voici une vue qui spécifie une telle transition :

ListView {
    ...
    populate: Transition {
        NumberAnimation { properties: "x,y"; duration: 1000 }
    }
}

Lorsque la vue est initialisée, elle crée tous les éléments nécessaires à la vue, puis les anime à leur position correcte dans la vue pendant une seconde.

Cependant, lors du défilement ultérieur de la vue, la transition de remplissage ne s'exécute pas, même si les délégués sont instanciés au fur et à mesure qu'ils deviennent visibles. Lorsque le modèle change de manière à ce que de nouveaux délégués deviennent visibles, c'est la transition add qui s'exécute. Vous ne devez donc pas dépendre de la transition populate pour initialiser les propriétés du délégué, car elle ne s'applique pas à tous les délégués. Si votre animation définit la valeur to d'une propriété, la propriété doit initialement avoir la valeur to, et l'animation doit définir la valeur from au cas où elle serait animée :

ListView {
    ...
    delegate: Rectangle {
        opacity: 1 // not necessary because it's the default
    }
    populate: Transition {
        NumberAnimation { property: "opacity"; from: 0; to: 1; duration: 1000 }
    }
}

Pour plus de détails et d'exemples sur l'utilisation des transitions de vue, voir la documentation ViewTransition.

Voir également add et ViewTransition.

remove : Transition

Cette propriété contient la transition à appliquer aux éléments qui sont retirés de la vue.

Par exemple, voici une vue qui spécifie une telle transition :

ListView {
    ...
    remove: Transition {
        ParallelAnimation {
            NumberAnimation { property: "opacity"; to: 0; duration: 1000 }
            NumberAnimation { properties: "x,y"; to: 100; duration: 1000 }
        }
    }
}

Chaque fois qu'un élément est retiré de la vue ci-dessus, l'élément sera animé jusqu'à la position (100,100) pendant une seconde et, parallèlement, son opacité passera à 0. La transition ne s'applique qu'aux éléments qui sont retirés de la vue ; elle ne s'applique pas aux éléments situés en dessous d'eux qui sont déplacés par le retrait des éléments. Pour animer les éléments déplacés, définissez les propriétés displaced ou removeDisplaced.

Notez qu'au moment où la transition est appliquée, l'élément a déjà été supprimé du modèle ; toute référence aux données du modèle pour l'index supprimé ne sera pas valide.

En outre, si la propriété delayRemove attached a été définie pour un élément délégué, la transition de suppression ne sera pas appliquée tant que delayRemove ne sera pas redevenu faux.

Pour plus de détails et d'exemples sur l'utilisation des transitions de vue, voir la documentation ViewTransition.

Voir également removeDisplaced et ViewTransition.

removeDisplaced : Transition

Cette propriété définit la transition à appliquer aux éléments de la vue qui sont déplacés par la suppression d'autres éléments de la vue.

Par exemple, voici une vue qui spécifie une telle transition :

ListView {
    ...
    removeDisplaced: Transition {
        NumberAnimation { properties: "x,y"; duration: 1000 }
    }
}

Chaque fois qu'un élément est retiré de la vue ci-dessus, tous les éléments situés en dessous sont déplacés, ce qui entraîne leur déplacement vers le haut (ou vers les côtés, s'ils sont orientés horizontalement) à l'intérieur de la vue. Au fur et à mesure que ce déplacement se produit, le mouvement des éléments vers leurs nouvelles positions x,y à l'intérieur de la vue sera animé par une animation NumberAnimation sur une seconde, comme spécifié. Cette transition n'est pas appliquée à l'élément qui a été retiré de la vue ; pour animer les éléments retirés, définissez la propriété remove.

Si un élément est déplacé par plusieurs types d'opérations en même temps, il n'est pas défini si la transition addDisplaced, moveDisplaced ou removeDisplaced sera appliquée. En outre, s'il n'est pas nécessaire de spécifier des transitions différentes selon qu'un élément est déplacé par une opération d'ajout, de déplacement ou de suppression, envisagez plutôt de définir la propriété displaced.

Pour plus de détails et d'exemples sur l'utilisation des transitions d'affichage, voir la documentation ViewTransition.

Voir également displaced, remove, et ViewTransition.

reuseItems : bool

Cette propriété vous permet de réutiliser les éléments qui sont instanciés à partir de delegate. Si elle est définie à false, tous les éléments actuellement mis en commun sont détruits.

Cette propriété vaut false par défaut.

Voir également Reusing items, pooled() et reused().

section group

Ces propriétés déterminent l'expression à évaluer et l'apparence des étiquettes de section.

section.property contient le nom de la propriété qui est à la base de chaque section.

section.criteria contient le critère de formation de chaque section sur la base de section.property. Cette valeur peut être l'une des suivantes

Une comparaison insensible à la casse est utilisée pour déterminer les limites des sections.

section.delegate contient le composant délégué pour chaque section. Le site stacking order par défaut des instances de délégué de section est 2. Si vous y déclarez une propriété required nommée "section", cette propriété contiendra le titre de la section.

section.labelPositioning détermine si les étiquettes de la section actuelle et/ou suivante sont collées au début/à la fin de la vue, et si les étiquettes sont affichées en ligne. Cette valeur peut être une combinaison de :

Chaque élément de la liste possède des propriétés attachées nommées ListView.section, ListView.previousSection et ListView.nextSection.

Par exemple, voici une page ListView qui affiche une liste d'animaux, séparés en sections. Chaque élément du site ListView est placé dans une section différente en fonction de la propriété "size" de l'élément du modèle. Le composant délégué sectionHeading fournit la barre bleu clair qui marque le début de chaque section.

    // The delegate for each section header
    Component {
        id: sectionHeading
        Rectangle {
            width: ListView.view.width
            height: childrenRect.height
            color: "lightsteelblue"

            required property string section

            Text {
                text: parent.section
                font.bold: true
                font.pixelSize: 20
            }
        }
    }

    ListView {
        id: view
        anchors.top: parent.top
        anchors.bottom: buttonBar.top
        width: parent.width
        model: animalsModel
        delegate: Text {
            required property string name

            text: name
            font.pixelSize: 18
        }

        section.property: "size"
        section.criteria: ViewSection.FullString
        section.delegate: sectionHeading
    }

Voir également les exemples de ListView et Stacking Order in ListView.

snapMode : enumeration

Cette propriété détermine la manière dont le défilement de la vue se stabilisera après un glissement ou une pichenette. Les valeurs possibles sont les suivantes

snapMode n'affecte pas currentIndex. Pour mettre à jour currentIndex au fur et à mesure que la liste est déplacée, définissez highlightRangeMode sur ListView.StrictlyEnforceRange.

Voir également highlightRangeMode.

spacing : real

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

La valeur par défaut est 0.

verticalLayoutDirection : enumeration

Cette propriété indique la direction de la mise en page d'une liste orientée verticalement.

Valeurs possibles :

La définition de cette propriété n'a aucun effet si le site orientation est Qt.Horizontal.

Voir également ListView::layoutDirection.

Documentation sur la propriété Attached

ListView.delayRemove : bool

Cette propriété jointe indique si le délégué peut être détruit. Elle est attachée à chaque instance du délégué. La valeur par défaut est false.

Il est parfois nécessaire de retarder la destruction d'un élément jusqu'à la fin d'une animation. L'exemple de délégué ci-dessous garantit que l'animation se termine avant que l'élément ne soit supprimé de la liste.

Component {
    id: delegate
    Item {
        SequentialAnimation {
            id: removeAnimation
            PropertyAction { target: wrapper; property: "ListView.delayRemove"; value: true }
            NumberAnimation { target: wrapper; property: "scale"; to: 0; duration: 250; easing.type: Easing.InOutQuad }
            PropertyAction { target: wrapper; property: "ListView.delayRemove"; value: false }
        }
        ListView.onRemove: removeAnimation.start()
    }
}

Si une transition remove a été spécifiée, elle ne sera pas appliquée tant que delayRemove n'aura pas été ramené à false.

ListView.isCurrentItem : bool [read-only]

Cette propriété attachée est vraie si ce délégué est l'élément courant, sinon elle est fausse.

Elle est attachée à chaque instance du délégué.

Cette propriété peut être utilisée pour ajuster l'apparence de l'élément courant, par exemple :

ListView {
    width: 180; height: 200

    Component {
        id: contactsDelegate
        Rectangle {
            id: wrapper
            width: 180
            height: contactInfo.height
            color: ListView.isCurrentItem ? "black" : "red"
            Text {
                id: contactInfo
                text: name + ": " + number
                color: wrapper.ListView.isCurrentItem ? "red" : "black"
            }
        }
    }

    model: ContactModel {}
    delegate: contactsDelegate
    focus: true
}

ListView.nextSection : string [read-only]

Cette propriété jointe contient la section de l'élément suivant.

Elle est attachée à chaque instance du délégué.

La section est évaluée à l'aide des propriétés section.

ListView.previousSection : string [read-only]

Cette propriété jointe contient la section de l'élément précédent.

Elle est attachée à chaque instance du délégué.

La section est évaluée à l'aide des propriétés section.

ListView.section : string [read-only]

Cette propriété jointe contient la section de cet élément.

Elle est attachée à chaque instance du délégué.

La section est évaluée à l'aide des propriétés section.

ListView.view : ListView [read-only]

Cette propriété attachée contient la vue qui gère cette instance de délégué.

Elle est attachée à chaque instance du délégué ainsi qu'à l'en-tête, au pied de page, à la section et aux délégués de mise en évidence.

Documentation sur le signal attaché

add()

Ce signal attaché est émis immédiatement après l'ajout d'un élément à la vue.

Si une transition d'ajout est spécifiée, elle est appliquée immédiatement après la gestion de ce signal.

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().

remove()

Ce signal attaché est émis immédiatement avant qu'un élément ne soit retiré de la vue.

Si une transition de suppression a été spécifiée, elle est appliquée après le traitement de ce signal, à condition que delayRemove soit faux.

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 index et row 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 aussi Reusing items, reuseItems, et pooled().

Documentation de la méthode

void decrementCurrentIndex()

Diminue l'index actuel. L'index actuel sera repris si keyNavigationWraps est vrai et s'il se trouve au début. Cette méthode n'a aucun effet si l'adresse count est zéro.

Remarque: les méthodes ne doivent être appelées qu'une fois le composant terminé.

void forceLayout()

La réponse aux modifications du modèle est généralement mise en lot pour ne se produire qu'une fois par image. Cela signifie qu'à l'intérieur des blocs de script, il est possible que le modèle sous-jacent ait changé, mais que l'adresse ListView ne l'ait pas encore rattrapé.

Cette méthode oblige le site ListView à répondre immédiatement à tout changement en cours dans le modèle.

Remarque: les méthodes ne doivent être appelées qu'une fois le composant terminé.

void incrementCurrentIndex()

Incrémente l'index courant. L'index actuel sera complété si keyNavigationWraps est vrai et que l'on se trouve à la fin. Cette méthode n'a aucun effet si l'adresse count est zéro.

Remarque: les méthodes ne doivent être appelées qu'une fois le composant terminé.

int indexAt(real x, real y)

Renvoie l'indice de l'élément visible contenant le point x, y en coordonnées de contenu. S'il n'y a pas d'élément au point spécifié, ou si l'élément n'est pas visible, la valeur -1 est renvoyée.

Si l'élément se trouve en dehors de la zone visible, -1 est renvoyé, qu'il y ait ou non un élément à cet endroit lorsqu'il est affiché par défilement.

Remarque: les méthodes ne doivent être appelées qu'une fois le composant terminé.

Item itemAt(real x, real y)

Renvoie l'élément visible contenant le point x, y en coordonnées de contenu. S'il n'y a pas d'élément au point spécifié, ou si l'élément n'est pas visible, la valeur null est renvoyée.

Si l'élément se trouve en dehors de la zone visible, null est renvoyé, même si un élément existe à cet endroit lorsqu'on le fait défiler.

Remarque: les méthodes ne doivent être appelées qu'une fois le composant terminé.

Item itemAtIndex(int index)

Renvoie l'élément correspondant à index. S'il n'y a pas d'élément pour cet index, par exemple parce qu'il n'a pas encore été créé ou parce qu'il a été déplacé hors de la zone visible et supprimé du cache, null est renvoyé.

Remarque: cette méthode ne doit être appelée qu'une fois le composant terminé. La valeur renvoyée ne doit pas non plus être stockée, car elle peut devenir nulle dès que le contrôle sort de la portée de l'appel, si la vue libère l'élément.

Positionne la vue au début ou à la fin, en tenant compte de l'en-tête ou du pied de page.

Il n'est pas recommandé d'utiliser contentX ou contentY pour positionner la vue à un index particulier. Cette méthode n'est pas fiable, car la suppression d'éléments au début de la liste n'entraîne pas le repositionnement de tous les autres éléments, et parce que le début réel de la vue peut varier en fonction de la taille des délégués.

Remarque: 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 au démarrage :

Component.onCompleted: positionViewAtEnd()

void positionViewAtIndex(int index, PositionMode mode)

Positionne la vue de manière à ce que le site index soit à la position spécifiée par mode:

Si le positionnement de la vue à index entraîne l'affichage d'un espace vide au début ou à la fin de la vue, celle-ci sera positionnée à la limite.

Il n'est pas recommandé d'utiliser contentX ou contentY pour positionner la vue à un index particulier. Cette méthode n'est pas fiable, car la suppression d'éléments au début de la liste n'entraîne pas le repositionnement de tous les autres éléments, et parce que le début réel de la vue peut varier en fonction de la taille des délégués. La bonne façon d'afficher un élément est de le faire à l'aide de positionViewAtIndex.

Remarque: 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: positionViewAtIndex(count - 1, ListView.Beginning)