PathView QML Type
Dispose les éléments fournis par le modèle sur un chemin. Plus d'informations...
| Import Statement: | import QtQuick |
| Inherits: |
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
Méthodes
- decrementCurrentIndex()
- incrementCurrentIndex()
- int indexAt(real x, real y)
- Item itemAt(real x, real y)
- Item itemAtIndex(int index)
- 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 sur 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
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
| Constante | Description |
|---|---|
PathView.NoHighlightRange | aucune plage n'est appliquée : la surbrillance se déplace librement dans la vue. |
PathView.ApplyRange | la vue tentera de maintenir la surbrillance à l'intérieur de la plage, mais la surbrillance peut sortir de la plage aux extrémités du chemin ou à la suite d'une interaction avec la souris. |
PathView.StrictlyEnforceRange | la surbrillance ne se déplacera jamais en dehors de la plage. Cela signifie que l'élément courant changera si une action du clavier ou de la souris entraîne le déplacement de la surbrillance en dehors de la plage. |
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.
Remarque : pour que la plage soit valide, il faut que preferredHighlightEnd soit supérieur ou égal à preferredHighlightBegin.
cacheItemCount : int |
Cette propriété indique le nombre maximum d'éléments à mettre en cache en dehors du chemin.
Par exemple, un site PathView avec un modèle contenant 20 éléments, un site pathItemCount de 10 et un 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.
Remarque : la définition de cette propriété ne remplace pas la création de délégués efficaces. Elle peut améliorer la fluidité du défilement au prix d'une utilisation supplémentaire de la mémoire. Moins il y a d'objets et de liaisons dans un délégué, plus le défilement de la vue est rapide. Il est important de comprendre que la définition de cacheItemCount ne fera que retarder les problèmes causés par des délégués qui se chargent lentement, ce n'est pas une solution pour ce scénario.
Voir également pathItemCount.
count : int |
Cette propriété contient le nombre d'éléments dans le modèle.
currentIndex : int |
Cette propriété contient l'index de l'élément courant.
currentItem : Item |
Cette propriété contient l'élément courant 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 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 |
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é indique la vitesse de décélération d'une pichenette.
La valeur par défaut est 100.
flicking : bool |
Cette propriété indique si la vue se déplace actuellement lorsque l'utilisateur la fait glisser.
highlight : Component |
Cette propriété définit 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 |
highlightMoveDuration : int |
Cette propriété indique 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.
interactive : bool |
maximumFlickVelocity : real |
Cette propriété indique la vitesse maximale approximative à laquelle l'utilisateur peut faire glisser 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 de 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.
Remarque : le changement de modèle réinitialise le décalage et currentIndex à 0.
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 actuel. Les valeurs possibles sont les suivantes
| Constante | Description |
|---|---|
PathView.Shortest | (par défaut) les éléments se déplacent dans la direction qui nécessite le moins de mouvement, ce qui peut être Negative ou Positive. |
PathView.Negative | les éléments se déplacent en arrière vers leur destination. |
PathView.Positive | les éléments se déplacent en avant vers leur destination. |
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
Positivese traduira par l'ordre suivant : 0, 1, 2 - une direction de mouvement
Negativese traduira par l'ordre suivant : 0, 5, 4, 3, 2 - une direction de mouvement
Shortestse traduira dans le même ordre quePositive.
Remarque : cette propriété n'affecte pas le mouvement de incrementCurrentIndex() et decrementCurrentIndex().
moving : bool |
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 dans le modèle.
path : Path |
Cette propriété contient le chemin utilisé pour disposer les éléments. Pour plus d'informations, voir la documentation 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
| Constante | Description |
|---|---|
PathView.NoSnap | (par défaut) les éléments s'arrêtent n'importe où sur la trajectoire. |
PathView.SnapToItem | les éléments s'installent avec un élément aligné sur le preferredHighlightBegin. |
PathView.SnapOneItem | les éléments s'installent à un maximum d'un élément de l'élément le plus proche de preferredHighlightBegin au moment où l'on relâche la pression. Ce mode est particulièrement utile pour déplacer une page à la fois. |
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 de la propriété attached
PathView.isCurrentItem : bool |
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 |
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 // ... } }
Elle est attachée à chaque instance du délégué.
PathView.view : PathView |
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 du signal
dragEnded() |
Ce signal est émis lorsque l'utilisateur cesse de faire glisser la vue.
Si la vitesse du glissement est suffisante au moment où le bouton tactile/souris est relâché, une pichenette est lancée.
Remarque : le gestionnaire correspondant est onDragEnded.
dragStarted() |
Ce signal est émis lorsque la vue commence à être déplacée en raison de l'interaction de l'utilisateur.
Remarque : le gestionnaire correspondant est onDragStarted.
flickEnded() |
Ce signal est émis lorsque la vue cesse de se déplacer à la suite d'une pichenette.
Remarque : le gestionnaire correspondant est onFlickEnded.
flickStarted() |
Ce signal est émis lorsque la vue est déplacée. Une pichenette commence à partir du moment où la souris ou le toucher est relâché, alors que la vue est toujours en mouvement.
Remarque : le gestionnaire correspondant est onFlickStarted.
movementEnded() |
Ce signal est émis lorsque la vue cesse de se déplacer à la suite 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 toucher.
Remarque : le gestionnaire correspondant est onMovementEnded.
movementStarted() |
Ce signal est émis lorsque la vue commence à se déplacer à la suite d'une interaction avec l'utilisateur.
Remarque : le gestionnaire correspondant est onMovementStarted.
Documentation de la méthode
decrementCurrentIndex() |
Diminue l'index actuel.
Remarque: les méthodes ne doivent être appelées qu'une fois le composant terminé.
incrementCurrentIndex() |
Incrémente l'index courant.
Remarque: les méthodes ne doivent être appelées qu'une fois le composant terminé.
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é.
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é.
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.
positionViewAtIndex(int index, PositionMode mode) |
Positionne la vue de manière à ce que index soit à la position spécifiée par mode:
| Constante | Description |
|---|---|
PathView.Beginning | positionner l'élément au début du chemin. |
PathView.Center | position item in the center of the path. |
PathView.End | positionner l'élément à la fin du chemin. |
PathView.Contain | assure le positionnement de l'élément sur le chemin. |
PathView.SnapPosition | positionner l'élément à l'adresse preferredHighlightBegin. Ce mode n'est valable que si highlightRangeMode est StrictlyEnforceRange ou si l'accrochage est activé via snapMode. |
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)
© 2025 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.