GridView QML Type

Permet de définir un affichage sous forme de grille 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
• cellHeight : real
• cellWidth : real
• count : int
• currentIndex : int
• currentItem : Item
• delegate : Component
• delegateModelAccess : enumeration (since 6.10)
• displaced : Transition
• displayMarginBeginning : int (since QtQuick 2.3)
• displayMarginEnd : int (since QtQuick 2.3)
• effectiveLayoutDirection : enumeration
• flow : enumeration
• footer : Component
• footerItem : Item
• header : Component
• headerItem : Item
• highlight : Component
• highlightFollowsCurrentItem : bool
• highlightItem : Item
• highlightMoveDuration : int
• highlightRangeMode : enumeration
• keyNavigationEnabled : bool
• keyNavigationWraps : bool
• layoutDirection : enumeration
• model : model
• move : Transition
• moveDisplaced : Transition
• populate : Transition
• preferredHighlightBegin : real
• preferredHighlightEnd : real
• remove : Transition
• removeDisplaced : Transition
• reuseItems : bool
• snapMode : enumeration
• verticalLayoutDirection : enumeration

Propriétés associées

• delayRemove : bool
• isCurrentItem : bool
• view : GridView

Signaux associés

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

Méthodes

• void forceLayout()
• int indexAt(real x, real y)
• Item itemAt(real x, real y)
• Item itemAtIndex(int index)
• void moveCurrentIndexDown()
• void moveCurrentIndexLeft()
• void moveCurrentIndexRight()
• void moveCurrentIndexUp()
• void positionViewAtBeginning()
• void positionViewAtEnd()
• void positionViewAtIndex(int index, PositionMode mode)

Description détaillée

Un GridView affiche les données issues 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 QAbstractListModel.

Un GridView 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 GridView sont disposés horizontalement ou verticalement. Les vues en grille sont intrinsèquement « flickables », car GridView 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: "Jim Williams"
        portrait: "pics/portrait.png"
    }
    ListElement {
        name: "John Brown"
        portrait: "pics/portrait.png"
    }
    ListElement {
        name: "Bill Smyth"
        portrait: "pics/portrait.png"
    }
    ListElement {
        name: "Sam Wise"
        portrait: "pics/portrait.png"
    }
}

Ce modèle peut être référencé sous le nom ContactModel dans d’autres fichiers QML. Consultez la section Modules QML pour plus d’informations sur la création de composants réutilisables de ce type.

Un autre composant peut afficher les données de ce modèle dans une GridView, comme dans l’exemple suivant, qui crée un composant ContactModel pour son modèle, et un Column (contenant les éléments Image et Text ) pour son délégué.

import QtQuick

GridView {
    width: 300; height: 200

    model: ContactModel {}
    delegate: Column {
        Image { source: portrait; anchors.horizontalCenter: parent.horizontalCenter }
        Text { text: name; anchors.horizontalCenter: parent.horizontalCenter }
    }
}

La vue créera un nouveau délégué pour chaque élément du modèle. Notez que le délégué peut accéder directement aux données « name » et « portrait » du modèle.

Une vue en grille 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: 300; height: 200

    Component {
        id: contactDelegate
        Item {
            width: grid.cellWidth; height: grid.cellHeight
            Column {
                anchors.fill: parent
                Image { source: portrait; anchors.horizontalCenter: parent.horizontalCenter }
                Text { text: name; anchors.horizontalCenter: parent.horizontalCenter }
            }
        }
    }

    GridView {
        id: grid
        anchors.fill: parent
        cellWidth: 80; cellHeight: 80

        model: ContactModel {}
        delegate: contactDelegate
        highlight: Rectangle { color: "lightsteelblue"; radius: 5 }
        focus: true
    }
}

L’élément actuellement sélectionné est mis en évidence par une Rectangle bleue grâce à la propriété highlight, et focus est défini sur true afin de permettre la navigation au clavier dans la vue en grille. La vue en grille 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. L’état ne doit jamais être stocké dans un délégué.

GridView associe un certain nombre de propriétés à l’élément racine du délégué, par exemple GridView.isCurrentItem. Dans l’exemple suivant, l’élément racine du délégué peut accéder directement à cette propriété associée via GridView.isCurrentItem, tandis que l’objet enfant contactInfo doit faire référence à cette propriété via wrapper.GridView.isCurrentItem.

GridView {
    width: 300; height: 200
    cellWidth: 80; cellHeight: 80

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

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

Mises en page de GridView

La mise en page des éléments dans un GridView peut être contrôlée par les propriétés suivantes :

• flow - détermine si les éléments s'affichent de gauche à droite (sous forme d'une série de lignes) ou de haut en bas (sous forme d'une série de colonnes). Cette valeur peut être soit GridView.FlowLeftToRight, soit GridView.FlowTopToBottom.
• layoutDirection - contrôle le sens de la disposition horizontale : 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 : 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 GridView.TopToBottom, soit GridView.BottomToTop.

Par défaut, une GridView s'affiche de gauche à droite, et les éléments sont disposés de gauche à droite horizontalement, et de haut en bas verticalement.

Ces propriétés peuvent être combinées pour produire une grande variété de mises en page, comme le montre le tableau ci-dessous. Les GridViews de la première ligne ont toutes une valeur « flow » définie sur « GridView.FlowLeftToRight », mais utilisent différentes combinaisons de directions de mise en page horizontale et verticale (spécifiées respectivement par « layoutDirection » et « verticalLayoutDirection »). De même, les GridViews de la deuxième ligne ci-dessous ont toutes une valeur flow définie sur GridView.FlowTopToBottom, mais utilisent différentes combinaisons de directions de mise en page horizontale et verticale pour agencer leurs éléments de différentes manières.

Voir également Modèles de données QML, ListView, PathView et Qt Quick Exemples - 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 :

GridView {
    ...
    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 (x, y) au sein de la vue, en 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 :

GridView {
    ...
    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, qu’il y a 3 colonnes et que la valeur de ` cacheBuffer ` est définie sur 40, alors jusqu’à 6 délégués au-dessus et 6 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 plate-forme, 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.

Ces propriétés définissent la largeur et la hauteur de chaque cellule de la grille.

La taille par défaut d'une cellule est de 100x100.

count : int [read-only]

Cette propriété contient le nombre d'éléments du modèle.

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, la mise en surbrillance sera désactivée et ` currentItem ` sera défini sur null.

Si highlightFollowsCurrentItem est égal à true, la modification de l’une ou l’autre de ces propriétés provoquera un défilement fluide de la GridView 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.

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 effet 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.

La taille des éléments de l’ GridView est déterminée par cellHeight et cellWidth. Elle ne redimensionne pas les éléments en fonction de la taille de l’élément racine du délégué.

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

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 une transition générique pour les éléments déplacés par des opérations 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 :

GridView {
    ...
    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) au sein de 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 « NumberAnimation » sur une seconde, comme spécifié.

Si une vue spécifie à la fois cette transition générique de déplacement et une transition spécifique de type « addDisplaced », « moveDisplaced » ou « removeDisplaced », c’est la transition la plus spécifique qui sera utilisée à la place de la transition générique de déplacement 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 générique de déplacement 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, qu'il y a 3 colonnes, et que les paramètres « displayMarginBeginning » et « displayMarginEnd » sont tous deux définis sur 40, alors 6 délégués au-dessus et 6 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 de la grille.

Lorsque vous utilisez la propriété associée LayoutMirroring::enabled pour les mises en page locales, la direction visuelle de la mise en page de la grille sera inversée. Cependant, la propriété layoutDirection restera inchangée.

Voir également « GridView::layoutDirection » et « LayoutMirroring ».

flow : enumeration

Cette propriété définit le flux de la grille.

Valeurs possibles :

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 et footerItem.

footerItem : Item [read-only]

Cet élément contient le pied de page créé à 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 et headerItem.

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 et headerItem.

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 et footerItem.

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 vue. La géométrie de l'instance de composant résultante sera gérée par la vue de manière à rester associée à l'élément actuel, sauf si la propriété highlightFollowsCurrentItem est définie sur false. L'stacking order par défaut de l'élément de mise en évidence est 0.

Voir également highlightItem et highlightFollowsCurrentItem.

highlightFollowsCurrentItem : bool

Cette propriété détermine 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 de manière fluide 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: view.cellWidth; height: view.cellHeight
        color: "lightsteelblue"; radius: 5
        x: view.currentItem.x
        y: view.currentItem.y
        Behavior on x { SpringAnimation { spring: 3; damping: 0.2 } }
        Behavior on y { SpringAnimation { spring: 3; damping: 0.2 } }
    }
}

GridView {
    id: view
    width: 300; height: 200
    cellWidth: 80; cellHeight: 80

    model: ContactModel {}
    delegate: Column {
        Image { source: portrait; anchors.horizontalCenter: parent.horizontalCenter }
        Text { text: name; anchors.horizontalCenter: parent.horizontalCenter }
    }

    highlight: highlight
    highlightFollowsCurrentItem: false
    focus: true
}

highlightItem : Item [read-only]

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

L'élément « highlightItem » est géré 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 et highlightFollowsCurrentItem.

highlightMoveDuration : int

Cette propriété contient la durée de l'animation de déplacement du délégué de mise en évidence.

highlightFollowsCurrentItem Cette propriété doit être définie sur « true » pour que l'effet soit appliqué.

La valeur par défaut de la durée est de 150 ms.

Voir également highlightFollowsCurrentItem.

Ces propriétés définissent la plage privilégiée de mise en évidence (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 vue. Par exemple, si l’élément actuellement sélectionné doit rester au centre de la vue lors du défilement, 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 vue se fera automatiquement défiler de manière à ce que l’élément actif se trouve au centre de la vue. De plus, ce comportement s’applique quel que soit l’état de mise en surbrillance de l’élément actif.

Les valeurs valides pour ` highlightRangeMode ` sont les suivantes :

keyNavigationEnabled : bool

Cette propriété indique si la navigation au clavier dans la grille est activée.

Si cette propriété prend la valeur « 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 explicitement définie, elle cesse d’être liée à la propriété `interactive`.

Voir également interactive.

keyNavigationWraps : bool

Cette propriété détermine si la grille effectue un retour à la ligne lors de la navigation à l'aide des touches de direction

Si cette propriété est définie sur « true », la navigation au clavier qui ferait dépasser la sélection de l'élément actuel d'une extrémité de la vue effectue alors un retour à l'autre extrémité de la vue.

Par défaut, la navigation au clavier ne s'enroule pas.

layoutDirection : enumeration

Cette propriété définit le sens de mise en page de la grille.

Valeurs possibles :

Remarque: si GridView::flow est défini sur GridView.FlowLeftToRight, il ne faut pas confondre cette valeur avec le cas où GridView::layoutDirection est défini sur Qt.RightToLeft. La valeur de flux GridView.FlowLeftToRight indique simplement que le flux est horizontal.

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

model : model

Cette propriété contient le modèle fournissant les données pour la grille.

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`, ` DelegateModel` ou ` 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.

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

GridView {
    ...
    move: 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 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 :

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

Chaque fois que l’ model effectue une opération de déplacement sur un ensemble d’index donné, les éléments situés entre les index source et destination de cette opération 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.

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 e 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 :

GridView {
    ...
    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 dès 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 prendre la valeur to, et l’animation doit définir la valeur from au cas où elle ferait l’objet d’une animation :

GridView {
    ...
    delegate: Rectangle {
        opacity: 1 // not necessary because it's the default; but don't set 0
        ...
    }
    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 :

GridView {
    ...
    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, en parallèle, 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.

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

GridView {
    ...
    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 « NumberAnimation » sur 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()`.

snapMode : enumeration

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

verticalLayoutDirection : enumeration

Cette propriété définit le sens de disposition verticale de la grille.

Valeurs possibles :

Voir aussi GridView::layoutDirection.

Documentation sur les propriétés associées

GridView.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’à ce qu’une animation soit terminée. L’exemple de délégué ci-dessous garantit que l’animation s’achève avant que l’élément ne soit supprimé de la liste.

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

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`.

GridView.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é.

GridView {
    width: 300; height: 200
    cellWidth: 80; cellHeight: 80

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

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

GridView.view : GridView [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 d'en-tête, de pied de page et de mise en évidence.

Documentation sur les signaux associés

[attached] add()

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

[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 minuteries ou les animations en cours au sein de l'élément, ou pour libérer les ressources qui ne peuvent pas être réutilisées.

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

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

[attached] 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 delayRemove soit faux.

[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 au sein d’un délégué, mais si vous le faites, réinitialisez manuellement cet état à la réception de ce signal.

Ce signal est émis lorsque l’élément est réutilisé, et non lors de sa première création.

Ce signal n’est émis que si la propriété reuseItems a la valeur true.

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

Documentation de la méthode

void forceLayout()

La mise à jour en fonction des modifications apportées au modèle est généralement effectuée par lots, à raison d'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'GridView n'ait pas encore pris en compte ces modifications.

Cette méthode force l’ GridView à réagir immédiatement à toute modification 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.

int indexAt(real x, real y)

Renvoie l'index de l'élément visible contenant le point x, y dans les coordonnées content item. 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, la valeur -1 est renvoyée, que cet élément soit ou non présent à cet endroit une fois affiché à la suite d’un défilement.

GridView {
    id: view
    MouseArea {
        anchors.fill: parent
        onClicked: (mouse) => {
            let posInGridView = Qt.point(mouse.x, mouse.y)
            let posInContentItem = mapToItem(view.contentItem, posInGridView)
            let index = view.indexAt(posInContentItem.x, posInContentItem.y)
        }
    }
}

Remarque: les méthodes ne doivent être appelées qu’une fois le composant (Component) finalisé.

Voir également itemAt.

Item itemAt(real x, real y)

Renvoie l'élément visible contenant le point x, y dans les coordonnées content item. 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, 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é.

Voir également indexAt.

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 le composant terminé. 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.

void moveCurrentIndexDown()

Déplace l'currentIndex e d'un élément vers le bas dans la vue. L'index actuel effectuera un retour à la fin de la liste si la valeur de ` keyNavigationWraps ` est vraie et qu'il se trouve actuellement à la fin. Cette méthode n'a aucun effet si la valeur de ` 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 moveCurrentIndexLeft()

Déplace l'currentIndex e d'un élément vers la gauche dans la vue. L'index actuel effectuera un retour à la fin de la liste si la valeur de ` keyNavigationWraps ` est vraie et qu'il se trouve actuellement à la fin. Cette méthode n'a aucun effet si la valeur de ` count ` est égale à zéro.

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

void moveCurrentIndexRight()

Déplace l'currentIndex e d'un élément vers la droite dans la vue. L'index actuel effectuera un retour à la fin de la liste si la valeur de ` keyNavigationWraps ` est vraie et qu'il se trouve actuellement à la fin. Cette méthode n'a aucun effet si la valeur de ` count ` est égale à zéro.

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

void moveCurrentIndexUp()

Déplace l'currentIndex e d'un élément vers le haut dans la vue. L'index actuel passe à la ligne suivante si la valeur de keyNavigationWraps est vraie et qu'il se trouve actuellement à la fin. Cette méthode n'a aucun effet si la valeur de count est égale à zéro.

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

Positionne la vue au début ou à la fin, en tenant compte des éventuels en-têtes ou pieds 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’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 vue n’entraîne pas le repositionnement de tous les autres éléments. 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 que le composant (Component) 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 :

Component.onCompleted: positionViewAtIndex(count - 1, GridView.Beginning)