PathView QML Type

Dispose les éléments fournis par le modèle sur un chemin. Plus d'informations...

• 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 rattaché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

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

La vue a un model, qui définit les données à afficher, et un delegate, qui définit la manière dont les données doivent être affichées. Le site delegate est instancié pour chaque élément du site path. Il est possible de cliquer sur les éléments pour les déplacer le long du chemin.

Par exemple, s'il existe un modèle de liste simple défini dans un fichier ContactModel.qml comme celui-ci :

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 tournent. Ce code supplémentaire peut être consulté dans la documentation de 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 réglant 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 elle-même est une portée de focalisation (voir la focalisation du clavier dans Qt Quick pour plus de détails).

Les délégués sont instanciés en fonction des besoins et peuvent être détruits à tout moment. L'état ne doit jamais être stocké dans un délégué.

PathView attache 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é attachée en tant que PathView.isCurrentItem, tandis que l'objet enfant nameText doit se référer à cette propriété en tant que 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 la fonction d'écrêtage. Si la vue n'est pas coupée par un autre élément ou par l'écran, il sera nécessaire de définir clip : true pour que les éléments hors vue soient bien coupés.

Voir également Path, QML Data Models, ListView, GridView, et Qt Quick Exemples - Vues.

Documentation sur les propriétés

cacheItemCount : int

Cette propriété indique le nombre maximum d'éléments à mettre en cache hors du chemin.

Par exemple, une page PathView avec un modèle contenant 20 éléments, une page pathItemCount de 10 et une page cacheItemCount de 4 créera jusqu'à 14 éléments, dont 10 visibles sur le chemin et 4 invisibles mis en cache.

Les délégués mis en cache sont créés de manière asynchrone, ce qui permet de répartir la création sur plusieurs images et de réduire la probabilité de sauter des 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 en cours.

currentItem : Item [read-only]

Cette propriété contient l'élément actuel de la vue.

delegate : Component

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

Le nombre d'objets et de liaisons dans le délégué a un effet direct sur les performances de feuilletage 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 site Loader qui peut charger des composants supplémentaires en cas de besoin.

Notez que le site PathView disposera les é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 du chemin qui déclenche le glissement de la souris.

Par défaut, le chemin ne peut être déplacé qu'en cliquant sur un élément. Si dragMargin est supérieur à zéro, un glissement peut être initié en cliquant à l'intérieur des pixels de dragMargin du chemin.

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'une pichenette.

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 en raison du mouvement de l'utilisateur.

highlight : Component

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

Une instance du composant de mise en évidence sera créée pour chaque vue. La géométrie de l'instance du composant résultant sera gérée par la vue de manière à rester avec l'élément en cours.

L'exemple ci-dessous montre comment créer une simple mise en évidence. Notez l'utilisation de la propriété PathView.onPath attached pour s'assurer que la mise en évidence est cachée lorsqu'on l'éloigne du chemin.

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

Voir également highlightItem et highlightRangeMode.

highlightItem : Item [read-only]

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

Voir également highlight.

highlightMoveDuration : int

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

Si le site highlightRangeMode est StrictlyEnforceRange, cette propriété détermine la vitesse à laquelle les éléments se déplacent le long de la trajectoire.

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

Ces propriétés définissent la plage préférée de la mise en évidence (élément actuel) dans la vue. Les valeurs préférées doivent être comprises entre 0 et 1.

Les valeurs valides pour highlightRangeMode sont les suivantes

La valeur par défaut est PathView.StrictlyEnforceRange.

La définition d'une plage de mise en évidence est la bonne façon d'influencer l'endroit où l'élément actuel se retrouve lorsque la vue se déplace. Par exemple, si vous souhaitez que l'élément sélectionné se trouve au milieu du chemin, définissez une plage de mise en évidence de 0,5,0,5 et highlightRangeMode à PathView.StrictlyEnforceRange. Ainsi, lorsque le chemin défile, l'élément actuellement sélectionné sera celui qui se trouve à cette position. Il en va de même lorsque l'élément sélectionné change : il défilera jusqu'à ce qu'il se trouve dans la plage de mise en évidence préférée. En outre, le comportement de l'index de l'élément actuel se produira qu'il y ait ou non une mise en évidence.

interactive : bool

Un utilisateur ne peut pas faire glisser ou feuilleter un site PathView qui n'est pas interactif.

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

maximumFlickVelocity : real

Cette propriété indique la vitesse maximale approximative à laquelle l'utilisateur peut faire basculer la vue en pixels/seconde.

La valeur par défaut dépend de la plate-forme.

model : model

Cette propriété contient le modèle qui fournit les données pour la vue.

Le modèle fournit un ensemble de données qui est utilisé 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

Par exemple, supposons que le modèle comporte 5 éléments et que currentIndex soit 0. Si currentIndex est défini sur 2,

• une direction de mouvement Positive se traduira par l'ordre suivant : 0, 1, 2
• une direction de mouvement Negative se traduira par l'ordre suivant : 0, 5, 4, 3, 2
• une direction de mouvement Shortest se traduira dans le même ordre que Positive.

moving : bool [read-only]

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

offset : real

Le décalage indique à quelle distance de la trajectoire se trouvent les éléments par rapport à leur position initiale. 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 disposer les éléments. Pour plus d'informations, voir la documentation de Path.

pathItemCount : int

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

Si la valeur de pathItemCount est indéfinie, tous les éléments du chemin seront affichés.

snapMode : enumeration

Cette propriété détermine la manière dont les éléments se stabiliseront après un glissement ou une pichenette. Les valeurs possibles sont les suivantes

snapMode n'affecte pas currentIndex. Pour mettre à jour currentIndex au fur et à mesure que la vue est déplacée, réglez highlightRangeMode sur PathView.StrictlyEnforceRange ( PathView par défaut).

Voir également highlightRangeMode.

Documentation sur les propriétés attachées

PathView.isCurrentItem : bool [read-only]

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

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

Cette propriété peut être utilisée pour ajuster l'apparence de l'élément courant.

    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]

Cette propriété jointe indique si l'élément est actuellement sur le chemin.

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

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

Il est attaché à chaque instance du délégué.

PathView.view : PathView [read-only]

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

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

Documentation sur les signaux

dragEnded()

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

Si la vitesse de déplacement est suffisante au moment où le bouton tactile/souris est relâché, une pichenette est lancée.

dragStarted()

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

flickEnded()

Ce signal est émis lorsque la vue s'arrête de bouger à cause d'une pichenette.

flickStarted()

Ce signal est émis lorsque la vue est cliquée. Une pichenette commence à partir du moment où la souris ou le toucher est relâché, alors que la vue est toujours en mouvement.

movementEnded()

Ce signal est émis lorsque la vue cesse de se déplacer en raison d'une interaction avec l'utilisateur. Si une pichenette a été générée, ce signal est émis lorsque la pichenette s'arrête. Si aucune pichenette n'a été générée, ce signal est émis lorsque l'utilisateur cesse de faire glisser la vue, c'est-à-dire lorsqu'il relâche la souris ou le clavier.

movementStarted()

Ce signal est émis lorsque la vue commence à se déplacer à la suite d'une interaction avec 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 le composant terminé.

void incrementCurrentIndex()

Incrémente l'index courant.

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

int indexAt(real x, real y)

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

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

Item itemAt(real x, real y)

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

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

Item itemAtIndex(int index)

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

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

void positionViewAtIndex(int index, PositionMode mode)

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

Remarque: les méthodes ne doivent être appelées qu'une fois le composant terminé. Pour positionner la vue au démarrage, cette méthode doit être appelée par Component.onCompleted. Par exemple, pour positionner la vue à la fin :

Component.onCompleted: positionViewAtIndex(count - 1, PathView.End)