ListView QML Type

Affiche une liste des éléments fournis par un modèle. En savoir 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 associées

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

Signaux associé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 les 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.

Un ListView dispose d’un model, qui définit les données à afficher, et d’un delegate, qui définit la manière dont ces données doivent être affichées. Les éléments d’un ListView sont disposés horizontalement ou verticalement. Les ListView sont intrinsèquement « feuilletables », 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 nommé ` 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, la 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. Notez 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. L'apparence du délégué a été améliorée et celui-ci a été déplacé dans un composant contactDelegate distinct.

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 à l’aide d’un Rectangle bleu grâce à la propriété highlight, et focus est défini sur true afin de permettre la navigation au clavier dans la vue de liste. La vue de liste elle-même constitue une zone de focus (voir Focus clavier dans Qt Quick pour plus de détails).

Les délégués sont instanciés selon les besoins et peuvent être détruits à tout moment. Ainsi, state should never be stored in a delegate. Les délégués sont généralement rattachés à l’ contentItem de la ListView, mais selon qu’ils sont visibles ou non dans la vue, le parent peut changer et être parfois null. C’est pourquoi il n’ est pas recommandé de lier les propriétés du parent depuis l’intérieur du délégué. Si vous souhaitez que le délégué occupe toute la largeur de la 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 associe 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é associée via ` ListView.isCurrentItem`, tandis que l’objet enfant ` contactInfo ` doit faire référence à cette propriété via ` 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
}

Mises en page de ListView

La disposition des éléments dans une ListView peut être contrôlée à l'aide des propriétés suivantes :

• orientation - détermine si les éléments s'affichent horizontalement ou verticalement. Cette valeur peut être soit Qt.Horizontal, soit Qt.Vertical.
• layoutDirection - contrôle le sens de disposition horizontale pour une vue orientée horizontalement : c’est-à-dire si les éléments sont disposés de la gauche vers la droite de la vue, ou inversement. Cette valeur peut être soit Qt.LeftToRight, soit Qt.RightToLeft.
• verticalLayoutDirection - contrôle le sens de 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, ou inversement. Cette valeur peut être soit ListView.TopToBottom, soit ListView.BottomToTop.

Par défaut, une ListView est orientée verticalement et les éléments sont disposés de haut en bas. Le tableau ci-dessous présente les différentes dispositions possibles d'une ListView, en fonction des valeurs des propriétés énumérées ci-dessus.

Direction de défilement

Par défaut, une ListView verticale définit flickableDirection sur Flickable.Vertical, et une ListView horizontale le définit sur Flickable.Horizontal. De plus, une ListView verticale ne calcule (estime) que l'contentHeight, et une ListView horizontale ne calcule que l'contentWidth. L'autre dimension est définie sur -1.

Depuis Qt 5.9 (Qt Quick 2.9), il est possible de créer une ListView pouvant être parcourue par un mouvement de balayage dans les deux sens. Pour ce faire, la propriété « flickableDirection » peut être définie sur « Flickable.AutoFlickDirection » ou « Flickable.AutoFlickIfNeeded », et les valeurs souhaitées pour « contentWidth » ou « contentHeight » doivent être fournies.

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 ListView

L'Z value e des éléments détermine s'ils s'affichent au-dessus ou en dessous des autres éléments. La 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; par conséquent, définir 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 telles que 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 fait glisser à l’écran. 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 compatibilité ascendante), mais peut être activée en définissant la propriété reuseItems sur true.

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. Dans ce cas, le signal ` ListView::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 ` ListView::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 » 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 à la réception du signal « ListView::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.

L’exemple suivant présente un délégué qui anime un rectangle tournant. Lorsqu’il est placé dans le pool, l’animation est temporairement mise en pause :

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 du délégué et étiquettes de section

Les tailles variables des délégués peuvent entraîner un redimensionnement et le saut de tout élément « ScrollBar » associé. 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 de taille similaire), et les tailles variables des délégués empêchent une estimation précise. Pour atténuer cet effet, on peut définir des valeurs plus élevées pour ` cacheBuffer `, ce qui crée effectivement davantage d’éléments et améliore l’estimation de la taille des éléments non alloués, au prix d’une consommation de mémoire supplémentaire. Les ` Sections ` ont le même effet, car ils associent et allongent l’étiquette de section jusqu’au premier élément de la section.

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

Les délégués de ListView sont instanciés à la demande et peuvent être détruits lorsqu’ils ne sont plus visibles. Pour illustrer ce phénomène, 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’on clique sur un élément, ` 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 retrouve 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
    }
}

Masquer des délégués

Définir la propriété ` visible ` d’un délégué sur ` false ` masquera 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` de type ` 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 « masqué » est stocké dans le modèle, conformément aux recommandations de la section Avoid Storing State in Delegates.

Cependant, si la valeur de ` spacing ` est différente de zéro, des espaces irréguliers apparaîtront entre les délégués.

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

Une autre option consiste à appeler ` disable ` sur le délégué au lieu de le masquer.

Voir également Modèles de données QML, GridView, PathView et Exemples d’Qt Quick s - Vues.

Documentation sur les propriétés

add : Transition

Cette propriété définit la transition à appliquer aux éléments ajoutés à la vue.

Voici, par exemple, 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, celui-ci sera animé depuis la position (100,100) jusqu’à sa position finale en x et y au sein de la vue, en l’espace d’une seconde. La transition s'applique uniquement 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, consultez la documentation relative à la propriété ` 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 suite à l'ajout d'autres éléments dans celle-ci.

Voici, par exemple, 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) au sein de la vue. Lorsque ce déplacement se produit, le mouvement des éléments vers leurs nouvelles positions x, y au sein de la vue sera animé par une transition « NumberAnimation » sur une seconde, comme spécifié. Cette transition ne s’applique pas 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 simultanément, il n’est pas précisé si la transition addDisplaced, moveDisplaced ou removeDisplaced sera appliquée. De plus, 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 de vue, consultez la documentation relative à ` 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 que le tampon spécifié peut en contenir. Par exemple, si dans une vue verticale, le délégué mesure 20 pixels de haut et que l’ cacheBuffer e est défini sur 40, alors jusqu’à 2 délégués au-dessus et 2 délégués en dessous de la zone visible peuvent être créés/conservés. Les délégués mis en mémoire tampon sont créés de manière asynchrone, ce qui permet la création sur plusieurs images et réduit le risque de saut d’images. Afin d’améliorer les performances de dessin, les délégués situés en dehors de la zone visible ne sont pas dessinés.

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 fait que gérer 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 présents dans le modèle de l'ListView, qu'ils soient visibles ou instanciés en tant qu'Item s d'un composant délégué.

La propriété ` currentIndex ` contient l'index de l'élément actuel, et ` currentItem ` contient l'élément actuel. En définissant ` currentIndex ` sur -1, vous effacerez la mise en surbrillance et mettrez ` currentItem ` à null.

Si highlightFollowsCurrentItem est égal à true, la modification de l’une ou l’autre de ces propriétés fera défiler en douceur la ListView afin que l’élément actuel devienne visible.

Notez que la position de l’élément actuel 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 toutefois utilisé avec un seul et même type de délégué. Dans ce cas, le transtypage de ` currentItem ` vers le type du délégué peut faciliter le développement et permettre d’obtenir 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 accessible via la propriété ` index `. 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 impact direct sur les performances de défilement rapide 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 ` Loader ` capable de charger des composants supplémentaires en cas de besoin.

L’ ListView organisera la disposition des é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 un alignement des éléments au niveau des sous-pixels.

L’ stacking order par défaut des instances de délégué est 1.

Voir également Stacking Order in ListView.

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.

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 du modèle affectant la vue.

Cela permet de spécifier facilement la transition générique à appliquer à tous les éléments déplacés par une opération d’ajout, de déplacement ou de suppression, sans avoir à définir individuellement les propriétés addDisplaced, moveDisplaced et removeDisplaced. Voici, par exemple, une vue qui spécifie une transition de déplacement :

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

Lorsqu’un élément est ajouté, déplacé ou supprimé au sein de 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 de ce déplacement, le mouvement des éléments vers leurs nouvelles positions x, y au sein de la vue sera animé par une transition de type « NumberAnimation » sur une durée d’une seconde, comme spécifié.

Si une vue spécifie cette transition de décalage générique ainsi qu’une transition spécifique de type « addDisplaced », « moveDisplaced » ou « removeDisplaced », la transition la plus spécifique sera utilisée à la place de la transition de décalage générique lorsque l’opération concernée se produit, à condition que la transition la plus spécifique n’ait pas été désactivée (en définissant enabled sur false). Si elle a effectivement été désactivée, c’est la transition de décalage générique qui est appliquée à la place.

Pour plus de détails et d’exemples sur l’utilisation des transitions de vue, consultez 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 sa fin. La vue créera autant de délégués que la taille en pixels spécifiée le permet.

Par exemple, si, dans une vue verticale, le délégué mesure 20 pixels de haut et que les paramètres « displayMarginBeginning » et « displayMarginEnd » sont tous deux définis sur 40, alors 2 délégués au-dessus et 2 délégués en 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 plutôt utiliser la propriété ` cacheBuffer `.

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

effectiveLayoutDirection : enumeration [read-only]

Cette propriété définit le sens de mise en page effectif d'une liste orientée horizontalement.

Lorsque vous utilisez la propriété associée « LayoutMirroring::enabled » pour les mises en page locales, le sens visuel de la mise en page de la liste horizontale sera inversé. 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 positionné à la fin de la vue, après tous les éléments. L'stacking order par défaut du pied de page est 1.

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

footerItem : Item [read-only]

Cet élément contient le pied de page généré à partir du composant footer.

Une instance du composant de pied de page est créée pour chaque vue. Le pied de page est positionné à la fin de la vue, après tous les autres éléments. L'stacking order par défaut du 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 de l'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 positionné au début de la vue, avant tout autre élément. L'stacking order par défaut de l'en-tête est 1.

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

headerItem : Item [read-only]

Cet élément 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 positionné au début de la vue, avant tout autre élément. L'stacking order 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 de l'header item.

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

highlight : Component

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

Une instance du composant de mise en évidence est créée pour chaque liste. La géométrie de l'instance de composant résultante est gérée par la liste de manière à rester associée à l'élément actuel, sauf si la propriété ` highlightFollowsCurrentItem ` est définie sur `false`. L'stacking order e par défaut de l'élément de mise en évidence est ` 0`.

Voir également highlightItem, highlightFollowsCurrentItem, Exemple de mise en surbrillance dans ListView et Stacking Order in ListView.

highlightFollowsCurrentItem : bool

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

Si cette propriété est définie sur true (valeur par défaut), la surbrillance se déplace en douceur pour suivre l'élément actuel. Dans le cas contraire, la surbrillance n'est pas déplacée par la vue, et tout déplacement doit être implémenté par la surbrillance elle-même.

Voici un surlignage 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 du surlignage affecte également la manière dont la vue défile. En effet, la vue se déplace pour maintenir le surlignage dans la plage de surlignage préférée (ou la fenêtre d’affichage visible).

Voir également highlight et highlightMoveVelocity.

highlightItem : Item [read-only]

Cet élément contient l'élément mis en évidence créé à partir du composant « highlight ».

La gestion de l'highlightItem est assurée par la vue, sauf si la propriété highlightFollowsCurrentItem est définie sur false. L'stacking order par défaut de l'élément mis 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 pour le délégué de mise en évidence.

highlightFollowsCurrentItem La valeur doit être « true » pour que ces propriétés prennent effet.

La valeur par défaut des propriétés de vitesse est de 400 pixels/seconde. La valeur par défaut des propriétés de durée est -1, c'est-à-dire que la mise en surbrillance prendra autant de temps que nécessaire pour se déplacer à la vitesse définie.

Ces propriétés présentent les mêmes caractéristiques qu’une animation « SmoothedAnimation » : si la vitesse et la durée sont toutes deux définies, l’animation utilisera celle qui donne la durée la plus courte.

Les propriétés de vitesse et de durée de déplacement sont utilisées pour contrôler le mouvement résultant des changements d’index ; par exemple, lorsque la méthode ` incrementCurrentIndex()` est appelée. Lorsque l’utilisateur effectue un balayage sur un ` ListView`, c’est la vitesse issue de ce balayage qui est utilisée pour contrôler le mouvement.

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

highlightMoveDuration: 1000
highlightMoveVelocity: -1

Voir également highlightFollowsCurrentItem.

Ces propriétés définissent la plage souhaitée de mise en surbrillance (pour l'élément actuel) au sein de la vue. La valeur « preferredHighlightBegin » doit être inférieure à la valeur « preferredHighlightEnd ».

Ces propriétés influent sur la position de l’élément actif lors du défilement de la liste. Par exemple, si l’élément actuellement sélectionné doit rester au milieu de la liste lors du défilement de la vue, définissez les valeurs preferredHighlightBegin et preferredHighlightEnd sur les coordonnées supérieure et inférieure de l’emplacement où se trouverait l’élément central. Si l'index de l'élément actif ( currentItem ) est modifié par programmation, la liste se fera automatiquement défiler de manière à ce que l'élément actif se trouve au milieu de la vue. De plus, ce comportement de l'index de l'élément actif s'appliquera qu'il y ait ou non une mise en surbrillance.

Les valeurs valides pour ` highlightRangeMode ` sont :

keyNavigationEnabled : bool

Cette propriété indique si la navigation à l'aide des touches du clavier est activée dans la liste.

Si cette propriété est définie sur « true », l'utilisateur peut naviguer dans la vue à l'aide du clavier. Elle est utile pour les applications qui doivent activer ou désactiver de manière sélective les interactions avec la souris et le clavier.

Par défaut, la valeur de cette propriété est liée à « interactive » afin de garantir la compatibilité du comportement avec les 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 à l'aide des touches de direction effectue un retour en début de liste.

Si cette propriété est définie sur « true », la navigation au clavier qui ferait passer la sélection de l'élément actuel au-delà de la fin de la liste effectue un retour en début de liste et place la sélection au début de celle-ci, et inversement.

Par défaut, la navigation au clavier ne boucle pas.

layoutDirection : enumeration

Cette propriété définit le sens de mise en page d'une liste orientée horizontalement.

Valeurs possibles :

La définition de cette propriété n'a aucun effet si la propriété « orientation » est définie sur «Qt.Vertical».

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

model : model

Cette propriété contient le modèle fournissant 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` et ` ObjectModel`, ou fournis par des classes de modèle C++. Si une classe de modèle C++ est utilisée, elle doit être une sous-classe de ` QAbstractItemModel ` ou une simple liste.

Voir également 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 l'model de la vue.

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

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

Chaque fois que l’ model effectue une opération de déplacement visant à déplacer un ensemble particulier d’index, les éléments correspondants de la vue seront animés vers leurs nouvelles positions dans la vue en l’espace d’une seconde. La transition ne s’applique qu’aux éléments faisant 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 d’eux et déplacés par cette opération. 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, consultez 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 l'model de la vue.

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

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

Chaque fois que l’ model effectue une opération de déplacement pour déplacer un ensemble particulier d’index, les éléments situés entre les index source et de destination de l’opération de déplacement sont déplacés, ce qui les fait se déplacer vers le haut ou vers le bas (ou latéralement, s’ils sont orientés horizontalement) au sein de la vue. Lorsque ce déplacement se produit, le mouvement des éléments vers leurs nouvelles positions x, y au sein de la vue sera animé par une transition « NumberAnimation » sur une seconde, comme spécifié. Cette transition ne s’applique pas aux éléments qui sont les véritables objets 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 simultanément, il n’est pas précisé si la transition « addDisplaced », « moveDisplaced » ou « removeDisplaced » sera appliquée. De plus, 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 de vue, consultez la documentation relative à ` ViewTransition `.

Voir également displaced, move et ViewTransition.

orientation : enumeration

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

Valeurs possibles :

Constante	Description
ListView.Horizontal	Les éléments sont disposés horizontalement
ListView.Vertical	(par défaut) Les éléments sont disposés verticalement

Voir aussi Flickable Direction.

populate : Transition

Cette propriété définit 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
• l'model de la vue change de telle sorte que les délégués visibles sont entièrement remplacés
• L'model de la vue est de type « reset », si le modèle est une sous-classe de ` QAbstractItemModel `

Voici, par exemple, une vue qui spécifie une telle transition :

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

Lors de son initialisation, la vue créera tous les éléments nécessaires, puis les animera pour les placer à leur position correcte au sein de la vue en l’espace d’une seconde.

Cependant, lorsque l’on fait défiler la vue par la suite, la transition « populate » 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 telle sorte que de nouveaux délégués deviennent visibles, c’est la transition « add » qui s’exécute. Vous ne devez donc pas compter sur 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é, celle-ci doit initialement avoir la valeur to, et l’animation doit définir la valeur from au cas où elle ferait l’objet d’une animation :

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, consultez la documentation ViewTransition.

Voir également add et ViewTransition.

remove : Transition

Cette propriété définit la transition à appliquer aux éléments supprimés de la vue.

Voici, par exemple, 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 supprimé de la vue ci-dessus, celui-ci est animé vers la position (100,100) en une seconde, et, parallèlement, son opacité passe à 0. La transition s'applique uniquement aux éléments supprimés de la vue ; elle ne s'applique pas aux éléments situés en dessous qui sont déplacés par la suppression 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 correspondant à l’index supprimé ne sera plus valide.

De plus, si la propriété attachée ` delayRemove ` 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 `false`.

Pour plus de détails et d’exemples sur l’utilisation des transitions de vue, consultez la documentation relative à « 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 à la suite de 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 supprimé de la vue ci-dessus, tous les éléments situés en dessous sont déplacés, ce qui les fait remonter (ou se déplacer latéralement, s’ils sont orientés horizontalement) au sein de la vue. Lorsque ce déplacement se produit, le mouvement des éléments vers leurs nouvelles positions x, y au sein de la vue sera animé par une transition de type « NumberAnimation » sur une durée d’une seconde, comme spécifié. Cette transition ne s’applique pas à l’élément qui a effectivement été supprimé de la vue ; pour animer les éléments supprimés, définissez la propriété « remove ».

Si un élément est déplacé par plusieurs types d’opérations simultanément, il n’est pas précisé si la transition « addDisplaced », « moveDisplaced » ou « removeDisplaced » sera appliquée. De plus, 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 de vue, consultez la documentation relative à ViewTransition.

Voir également displaced, remove et ViewTransition.

reuseItems : bool

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

Par défaut, cette propriété est définie sur ` false `.

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

section group

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

section.property Contient le nom de la propriété qui sert de base à chaque section.

section.criteria contient les critères de formation de chaque section, basés sur 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. L’ stacking order par défaut des instances de délégué de section est 2. Si vous y déclarez une propriété de type required nommée « section », cette propriété contiendra le titre de la section.

section.labelPositioning détermine si les libellés de la section actuelle et/ou suivante sont alignés au début ou à la fin de la vue, et si ces libellés s’affichent en ligne. Cette valeur peut être une combinaison des éléments suivants :

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

Par exemple, voici un « ListView » qui affiche une liste d’animaux, répartis en sections. Chaque élément de la liste « 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 d’ Stacking Order in ListView.

snapMode : enumeration

Cette propriété détermine la manière dont le défilement de la vue se stabilise après un glissement ou un balayage. Les valeurs possibles sont :

snapMode n’affecte pas l’ currentIndex. Pour mettre à jour l’ 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é définit le sens de mise en page d'une liste orientée verticalement.

Valeurs possibles :

La définition de cette propriété n'a aucun effet si la propriété « orientation » est définie sur Qt.Horizontal.

Voir aussi ListView::layoutDirection.

Documentation sur les propriétés associées

ListView.delayRemove : bool [attached]

Cette propriété associée indique si le délégué peut être détruit. Elle est associé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 de type « remove » a été spécifiée, elle ne sera appliquée qu’une fois que la méthode `delayRemove` aura renvoyé la valeur ` false`.

ListView.isCurrentItem : bool [read-only attached]

Cette propriété associée renvoie « true » si ce délégué correspond à l'élément actuel ; sinon, elle renvoie « false ».

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

Cette propriété peut être utilisée pour modifier l'apparence de l'élément actuel, 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 attached]

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

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

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

ListView.previousSection : string [read-only attached]

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

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

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

ListView.section : string [read-only attached]

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

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

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

ListView.view : ListView [read-only attached]

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

Elle est associée à chaque instance du délégué, ainsi qu'aux délégués « header », « footer », « section » et « highlight ».

Documentation sur le signal attaché

[attached] add()

Ce signal associé 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 le traitement de ce signal.

[attached] pooled()

Ce signal est émis lorsqu'un élément a été ajouté au pool de réutilisation. Vous pouvez l'utiliser pour suspendre les minuteurs 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] remove()

Ce signal est émis juste avant qu'un élément ne soit supprimé 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 la valeur de « delayRemove » soit fausse.

[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 ` 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 tout état à l'intérieur 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 première création.

Ce signal n'est émis que si la propriété « reuseItems » est définie sur « true ».

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

Documentation de la méthode

void decrementCurrentIndex()

Décrémente l'index actuel. L'index actuel revient au début si la propriété « keyNavigationWraps » est définie sur « true » et qu'il se trouve actuellement au début. Cette méthode n'a aucun effet si la propriété « count » est égale à zéro.

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

void forceLayout()

La mise à jour en fonction des modifications apportées au modèle est généralement traitée par lots, de sorte qu'elle n'a lieu qu'une seule fois par image. Cela signifie qu'au sein des blocs de script, il est possible que le modèle sous-jacent ait changé, mais que l'ListView n'ait pas encore pris en compte ces modifications.

Cette méthode force l'ListView à réagir immédiatement à tout changement en attente dans le modèle.

Remarque: les méthodes ne doivent être appelées qu’une fois que le composant a terminé son exécution.

void incrementCurrentIndex()

Incrémente l'index actuel. L'index actuel revient au début si la propriété « keyNavigationWraps » est définie sur « true » et qu'il se trouve actuellement à la fin. Cette méthode n'a aucun effet si la propriété « count » est égale à zéro.

Remarque: les méthodes ne doivent être appelées qu’une fois que le composant a terminé son exécution.

int indexAt(real x, real y)

Renvoie l'index de l'élément visible contenant le point x, y en coordonnées de contenu. S'il n'y a pas d'élément à l'emplacement spécifié, ou si l'élément n'est pas visible, la fonction renvoie -1.

Si l’élément se trouve en dehors de la zone visible, la valeur -1 est renvoyée, que cet élément soit ou non présent à cet emplacement une fois affiché à la suite d’un défilement.

Remarque: ces méthodes ne doivent être appelées qu’une fois le composant initialisé.

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 à l’emplacement 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, la valeur null est renvoyée, que cet élément soit ou non présent à cet emplacement une fois affiché à la suite d’un défilement.

Remarque: ces méthodes ne doivent être appelées qu’une fois le composant initialisé.

Item itemAtIndex(int index)

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

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

Positionne la vue au début ou à la fin, en tenant compte d'un éventuel en-tête ou 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 que le composant est 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 l'index e se trouve à la position spécifiée par mode:

Si le positionnement de la vue à l’adresse index entraînait l’affichage d’un espace vide au début ou à la fin de la vue, celle-ci sera alors 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 manière correcte d’afficher un élément est d’utiliser positionViewAtIndex.

Remarque: les méthodes ne doivent être appelées qu'une fois le composant 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: positionViewAtIndex(count - 1, ListView.Beginning)