PathView QML Type

Dispose les éléments fournis par le modèle le long d'un chemin. En savoir plus...

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

Propriétés

• cacheItemCount : int
• count : int
• currentIndex : int
• currentItem : Item
• delegate : Component
• dragMargin : real
• dragging : bool
• flickDeceleration : real
• flicking : bool
• highlight : Component
• highlightItem : Item
• highlightMoveDuration : int
• highlightRangeMode : enumeration
• interactive : bool
• maximumFlickVelocity : real
• model : model
• movementDirection : enumeration
• moving : bool
• offset : real
• path : Path
• pathItemCount : int
• preferredHighlightBegin : real
• preferredHighlightEnd : real
• snapMode : enumeration

Propriétés associées

• isCurrentItem : bool
• onPath : bool
• view : PathView

Signaux

• dragEnded()
• dragStarted()
• flickEnded()
• flickStarted()
• movementEnded()
• movementStarted()

Méthodes

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

Description détaillée

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

La vue 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. Le ` delegate ` est instancié pour chaque élément de l’ path. Les éléments peuvent être déplacés d’un simple geste le long du chemin.

Par exemple, si un modèle de liste simple est défini dans un fichier ContactModel.qml comme suit :

import QtQuick

ListModel {
    ListElement {
        name: "Bill Jones"
        icon: "pics/qtlogo.png"
    }
    ListElement {
        name: "Jane Doe"
        icon: "pics/qtlogo.png"
    }
    ListElement {
        name: "John Smith"
        icon: "pics/qtlogo.png"
    }
}

Ces données peuvent être représentées sous la forme d’un PathView, comme ceci :

import QtQuick

Rectangle {
    width: 240; height: 200

    Component {
        id: delegate
        Column {
            id: wrapper

            required property url icon
            required property string name

            opacity: PathView.isCurrentItem ? 1 : 0.5

            Image {
                anchors.horizontalCenter: nameText.horizontalCenter
                width: 64; height: 64
                source: wrapper.icon
            }
            Text {
                id: nameText
                text: wrapper.name
                font.pointSize: 16
            }
        }
    }

    PathView {
        anchors.fill: parent
        model: ContactModel {}
        delegate: delegate
        path: Path {
            startX: 120; startY: 100
            PathQuad { x: 120; y: 25; controlX: 260; controlY: 75 }
            PathQuad { x: 120; y: 100; controlX: -20; controlY: 75 }
        }
    }
}

(Notez que l’exemple ci-dessus utilise PathAttribute pour mettre à l’échelle et modifier l’opacité des éléments lorsqu’ils pivotent. Ce code supplémentaire est disponible dans la documentation PathAttribute.)

PathView ne gère pas automatiquement la navigation au clavier. En effet, les touches à utiliser pour la navigation dépendent de la forme du chemin. La navigation peut être ajoutée très simplement en définissant focus sur true et en appelant decrementCurrentIndex() ou incrementCurrentIndex(), par exemple pour naviguer à l’aide des touches fléchées gauche et droite :

PathView {
    // ...
    focus: true
    Keys.onLeftPressed: decrementCurrentIndex()
    Keys.onRightPressed: incrementCurrentIndex()
}

La vue du chemin d’accès est elle-même 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é.

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

    Component {
        id: delegate
        Column {
            id: wrapper

            required property url icon
            required property string name

            opacity: PathView.isCurrentItem ? 1 : 0.5

            Image {
                anchors.horizontalCenter: nameText.horizontalCenter
                width: 64; height: 64
                source: wrapper.icon
            }
            Text {
                id: nameText
                text: wrapper.name
                font.pointSize: 16
            }
        }
    }

Notez que les vues n’activent pas automatiquement le découpage. Si la vue n’est pas découpée par un autre élément ou par l’écran, il sera nécessaire de définir clip: true afin que les éléments hors champ soient correctement découpés.

Voir également Path, Modèles de données QML, ListView, GridView et Qt Quick Exemples - Vues.

Documentation sur les propriétés

cacheItemCount : int

Cette propriété définit le nombre maximal d'éléments à mettre en cache hors du chemin d'accès.

Par exemple, un ` PathView ` dont le modèle contient 20 éléments, avec un ` pathItemCount ` égal à 10 et un `cacheItemCount` égal à 4, créera jusqu’à 14 éléments : 10 éléments visibles sur le chemin et 4 éléments mis en cache invisibles.

Les délégués mis en cache sont créés de manière asynchrone, ce qui permet leur création sur plusieurs images et réduit le risque de saut d’images.

Voir également pathItemCount.

count : int [read-only]

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

currentIndex : int

Cette propriété contient l'index de l'élément actuel.

currentItem : Item [read-only]

Cette propriété contient l'élément actuellement affiché 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 lorsque ` pathItemCount ` est spécifié. 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 `, qui peut charger des composants supplémentaires en cas de besoin.

Notez que l’ PathView organisera la disposition des éléments en fonction de la taille de l’élément racine du délégué.

Voici un exemple de délégué :

    Component {
        id: delegate
        Column {
            id: wrapper

            required property url icon
            required property string name

            opacity: PathView.isCurrentItem ? 1 : 0.5

            Image {
                anchors.horizontalCenter: nameText.horizontalCenter
                width: 64; height: 64
                source: wrapper.icon
            }
            Text {
                id: nameText
                text: wrapper.name
                font.pointSize: 16
            }
        }
    }

dragMargin : real

Cette propriété définit la distance maximale par rapport au tracé à partir de laquelle le glissement de la souris est déclenché.

Par défaut, le tracé ne peut être déplacé qu'en cliquant sur un élément. Si la valeur de dragMargin est supérieure à zéro, un glissement peut être déclenché en cliquant à une distance maximale de dragMargin pixels du tracé.

dragging : bool [read-only]

Cette propriété indique si la vue est en train de se déplacer parce que l'utilisateur la fait glisser.

flickDeceleration : real

Cette propriété définit le taux de décélération d'un mouvement rapide.

La valeur par défaut est 100.

flicking : bool [read-only]

Cette propriété indique si la vue est en train de se déplacer parce que l'utilisateur a effectué un geste de balayage.

highlight : Component

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

Une instance du composant de mise en évidence sera 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.

L'exemple ci-dessous montre comment créer une mise en évidence simple. Notez l'utilisation de la propriété attachée ` PathView.onPath ` pour garantir que la mise en évidence soit masquée lorsque l'élément est éloigné du chemin par un mouvement rapide.

Component {
    Rectangle {
        visible: PathView.onPath
        // ...
    }
}

Voir également highlightItem et highlightRangeMode.

highlightItem : Item [read-only]

highlightItem contient l'élément mis en avant, qui a été créé à partir du composant highlight.

Voir également highlight.

highlightMoveDuration : int

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

Si la propriété « highlightRangeMode » est définie sur «StrictlyEnforceRange», cette propriété détermine la vitesse à laquelle les éléments se déplacent le long du chemin.

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

Ces propriétés définissent la plage préférentielle de la sélection (élément actuel) dans la vue. Les valeurs préférentielles doivent se situer dans l'intervalle compris entre 0 et 1.

Les valeurs valides pour highlightRangeMode sont les suivantes :

La valeur par défaut est PathView.StrictlyEnforceRange.

Définir une plage de mise en surbrillance est le moyen approprié d’influencer l’emplacement final de l’élément actif lorsque la vue se déplace. Par exemple, si vous souhaitez que l’élément actuellement sélectionné se trouve au milieu du chemin, définissez la plage de mise en surbrillance sur 0,5,0,5 et la propriété « highlightRangeMode » sur PathView.StrictlyEnforceRange. Ainsi, lorsque le chemin défile, l’élément actuellement sélectionné sera celui situé à cette position. Cela s’applique également lorsque l’élément actuellement sélectionné change : il se déplacera à l’intérieur de la plage de mise en surbrillance souhaitée. De plus, le comportement de l’index de l’élément actuel s’appliquera qu’il y ait ou non une mise en surbrillance.

interactive : bool

Un utilisateur ne peut pas faire glisser ni faire défiler un élément « PathView » qui n'est pas interactif.

Cette propriété est utile pour désactiver temporairement le balayage. Cela permet une interaction particulière avec les éléments enfants de l'PathView.

maximumFlickVelocity : real

Cette propriété indique la vitesse maximale approximative, en pixels par seconde, à laquelle l'utilisateur peut faire défiler la vue d'un geste rapide.

La valeur par défaut dépend de la plateforme.

model : model

Cette propriété contient le modèle fournissant les données à la vue.

Le modèle fournit un ensemble de données utilisées pour créer les éléments de la vue. Pour les ensembles de données volumineux ou dynamiques, le modèle est généralement fourni par un objet modèle C++. Les modèles peuvent également être créés directement en QML, à l'aide du type ` ListModel `.

Voir aussi Modèles de données.

movementDirection : enumeration

Cette propriété détermine la direction dans laquelle les éléments se déplacent lors de la définition de l'index courant. Les valeurs possibles sont les suivantes :

Par exemple, supposons qu’il y ait 5 éléments dans le modèle et que currentIndex soit 0. Si currentIndex est défini sur 2,

• un sens de déplacement « Positive » donnera l’ordre suivant : 0, 1, 2
• une direction de déplacement « Negative » donnera l'ordre suivant : 0, 5, 4, 3, 2
• une direction de déplacement « Shortest » donnera le même ordre qu’avec « Positive ».

moving : bool [read-only]

Cette propriété indique si la vue est actuellement en mouvement, que ce soit parce que l'utilisateur la fait glisser ou parce qu'il effectue un geste de balayage.

offset : real

Le décalage indique la distance qui sépare les éléments de leur position initiale le long du tracé. Il s’agit d’un nombre réel compris entre 0 et le nombre d’éléments du modèle.

path : Path

Cette propriété contient le chemin utilisé pour la mise en page des éléments. Pour plus d'informations, consultez la documentation relative à la balise « Path ».

pathItemCount : int

Cette propriété indique le nombre d'éléments visibles à un moment donné sur le chemin.

Si vous définissez `pathItemCount` sur `undefined`, tous les éléments du chemin seront affichés.

snapMode : enumeration

Cette propriété détermine la manière dont les éléments se positionnent 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 vue est déplacée, définissez « highlightRangeMode » sur « PathView.StrictlyEnforceRange » (valeur par défaut pour « PathView »).

Voir également highlightRangeMode.

Documentation sur les propriétés associées

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

    Component {
        id: delegate
        Column {
            id: wrapper

            required property url icon
            required property string name

            opacity: PathView.isCurrentItem ? 1 : 0.5

            Image {
                anchors.horizontalCenter: nameText.horizontalCenter
                width: 64; height: 64
                source: wrapper.icon
            }
            Text {
                id: nameText
                text: wrapper.name
                font.pointSize: 16
            }
        }
    }

PathView.onPath : bool [read-only attached]

Cette propriété associée indique si l'élément se trouve actuellement sur le chemin.

Si une méthode « pathItemCount » a été définie, il est possible que certains éléments soient instanciés, mais ne soient pas considérés comme se trouvant actuellement sur le chemin. En général, ces éléments sont rendus invisibles, par exemple :

Component {
    Rectangle {
        visible: PathView.onPath
        // ...
    }
}

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

PathView.view : PathView [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é.

Documentation sur les signaux

dragEnded()

Ce signal est émis lorsque l'utilisateur cesse de faire glisser la vue.

Si la vitesse de glissement est suffisante au moment où le doigt ou le bouton de la souris est relâché, un mouvement rapide (flick) est alors déclenché.

dragStarted()

Ce signal est émis lorsque la vue commence à être déplacée à la suite d'une interaction de l'utilisateur.

flickEnded()

Ce signal est émis lorsque la vue cesse de se déplacer à la suite d'un geste de balayage.

flickStarted()

Ce signal est émis lorsqu'un mouvement rapide est effectué sur la vue. Un mouvement rapide commence à partir du moment où la souris ou le doigt est relâché, alors que le mouvement est toujours en cours.

movementEnded()

Ce signal est émis lorsque la vue cesse de se déplacer à la suite d'une interaction de l'utilisateur. Si un « flick » a été généré, ce signal sera émis dès que le « flick » s'arrête. Si aucun « flick » n'a été généré, ce signal sera émis lorsque l'utilisateur cesse de faire glisser l'élément, c'est-à-dire lorsqu'il relâche la souris ou le doigt.

movementStarted()

Ce signal est émis lorsque la vue commence à se déplacer à la suite d'une interaction de l'utilisateur.

Documentation de la méthode

void decrementCurrentIndex()

Diminue l'index actuel.

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.

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 contenant le point x, y dans les coordonnées de contenu. S'il n'y a pas d'élément à l'emplacement spécifié, la valeur -1 est renvoyée.

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

Item itemAt(real x, real y)

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

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

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 de l’appel, si la vue libère cet élément.

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:

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, PathView.End)