Flickable QML Type

Fournit une surface qui peut être "touchée". Plus d'informations...

Import Statement: import QtQuick
Inherits:

Item

Inherited By:

GridView, ListView, and TableView

Propriétés

Signaux

Méthodes

Description détaillée

L'élément Flickable place ses enfants sur une surface que l'on peut faire glisser et sur laquelle on peut cliquer, ce qui fait défiler la vue sur les éléments enfants. Ce comportement est à la base des éléments conçus pour afficher un grand nombre d'éléments enfants, tels que ListView et GridView.

Dans les interfaces utilisateur traditionnelles, il est possible de faire défiler les vues à l'aide de commandes standard, telles que les barres de défilement et les boutons fléchés. Dans certaines situations, il est également possible de faire glisser la vue directement en appuyant sur un bouton de la souris et en le maintenant enfoncé tout en déplaçant le curseur. Dans les interfaces utilisateur tactiles, cette action de glissement est souvent complétée par une action de pichenette, où le défilement se poursuit après que l'utilisateur a cessé de toucher la vue.

Flickable ne coupe pas automatiquement son contenu. S'il n'est pas utilisé en tant qu'élément plein écran, vous devriez envisager de définir la propriété clip sur true.

Exemple d'utilisation

L'exemple suivant montre une petite vue sur une grande image dans laquelle l'utilisateur peut faire glisser ou basculer l'image afin d'en visualiser différentes parties.

import QtQuick

Flickable {
    width: 200; height: 200
    contentWidth: image.width; contentHeight: image.height

    Image { id: image; source: "bigImage.png" }
}

Les éléments déclarés comme enfants d'un Flickable sont automatiquement rattachés à la propriété contentItem du Flickable. Il convient d'en tenir compte lors des opérations sur les enfants du Flickable ; ce sont généralement les enfants de contentItem qui sont pertinents. Par exemple, la limite des éléments ajoutés au Flickable sera disponible par contentItem.childrenRect

Exemples de contentX et contentY

Les images suivantes montrent un flickable que l'on fait bouger dans différentes directions et les valeurs contentX et contentY qui en résultent. Le carré bleu représente le contenu de la flickable et la bordure noire représente les limites de la flickable.

Les adresses contentX et contentY sont toutes deux 0.

Le contentX et le contentY sont tous deux 50.

Le site contentX est -50 et le site contentY est 50.

Le contentX et le contentY sont tous deux -50.

Le site contentX est 50 et le site contentY est -50.

Limites

Note : En raison d'un détail d'implémentation, les éléments placés à l'intérieur d'un Flickable ne peuvent pas s'ancrer dans le Flickable. Il convient donc d'utiliser parent, qui renvoie à la page contentItem du Flickable. La taille de l'élément de contenu est déterminée par contentWidth et contentHeight.

Documentation sur les propriétés

contentX : real

contentY : real

Ces propriétés contiennent la coordonnée de la surface qui se trouve actuellement dans le coin supérieur gauche du Flickable. Par exemple, si vous déplacez une image de 100 pixels vers le haut, contentY augmentera de 100.

Remarque : si vous revenez à l'origine (le coin supérieur gauche), après l'animation de rebond, contentX reprendra la même valeur que originX, et contentY que originY. Ces valeurs sont généralement (0,0), mais ListView et GridView peuvent avoir une origine arbitraire en raison d'une variation de la taille du délégué ou de l'insertion/suppression d'un élément en dehors de la région visible. Par conséquent, si vous souhaitez mettre en œuvre quelque chose comme une barre de défilement verticale, vous pouvez utiliser y: (contentY - originY) * (height / contentHeight) pour la position, ou les valeurs normalisées de visibleArea.

Voir également Examples of contentX and contentY, originX, et originY.


horizontalVelocity : real [read-only]

verticalVelocity : real [read-only]

Vitesse instantanée du mouvement le long des axes x et y, en pixels/seconde.

La vitesse rapportée est lissée pour éviter des résultats erratiques.

Il convient de noter que pour les vues dont le contenu est volumineux (plus de 10 fois la taille de la vue), la vitesse de la pichenette peut dépasser la vitesse du toucher dans le cas de plusieurs pichenettes rapides et consécutives. Cela permet à l'utilisateur de parcourir plus rapidement un contenu volumineux.


atXBeginning : bool [read-only]

atXEnd : bool [read-only]

atYBeginning : bool [read-only]

atYEnd : bool [read-only]

Ces propriétés sont vraies si la vue flickable est positionnée au début ou à la fin respectivement.


contentHeight : real

contentWidth : real

Les dimensions du contenu (la surface contrôlée par Flickable). En règle générale, ces dimensions doivent correspondre à la taille combinée des éléments placés dans le Flickable.

L'extrait suivant montre comment ces propriétés sont utilisées pour afficher une image plus grande que l'élément Flickable lui-même :

import QtQuick

Flickable {
    width: 200; height: 200
    contentWidth: image.width; contentHeight: image.height

    Image { id: image; source: "bigImage.png" }
}

Dans certains cas, les dimensions du contenu peuvent être automatiquement définies en fonction des propriétés childrenRect.width et childrenRect.height de l'élément contentItem. Par exemple, l'extrait précédent pourrait être réécrit avec :

contentWidth: contentItem.childrenRect.width; contentHeight: contentItem.childrenRect.height

Bien que cela suppose que l'origine du childrenRect est 0,0.


bottomMargin : real

leftMargin : real

rightMargin : real

topMargin : real

Ces propriétés contiennent les marges autour du contenu. Cet espace est réservé en plus des propriétés contentWidth et contentHeight.


originX : real [read-only]

originY : real [read-only]

Ces propriétés définissent l'origine du contenu. Cette valeur fait toujours référence à la position en haut à gauche du contenu, quelle que soit la direction de la mise en page.

Il s'agit généralement de (0,0), mais ListView et GridView peuvent avoir une origine arbitraire en raison de la variation de la taille des délégués ou de l'insertion/suppression d'éléments en dehors de la région visible.

Voir également contentX et contentY.


flicking : bool [read-only]

flickingHorizontally : bool [read-only]

flickingVertically : bool [read-only]

Ces propriétés décrivent si la vue se déplace actuellement horizontalement, verticalement ou dans les deux sens, en raison du mouvement de l'utilisateur.


dragging : bool [read-only]

draggingHorizontally : bool [read-only]

draggingVertically : bool [read-only]

Ces propriétés décrivent si la vue se déplace actuellement horizontalement, verticalement ou dans les deux directions, en raison du déplacement de la vue par l'utilisateur.


moving : bool [read-only]

movingHorizontally : bool [read-only]

movingVertically : bool [read-only]

Ces propriétés décrivent si la vue se déplace actuellement horizontalement, verticalement ou dans l'une ou l'autre direction, en raison d'un glissement ou d'une pichenette de la part de l'utilisateur.


acceptedButtons : flags [since 6.9]

Les boutons de la souris qui peuvent être utilisés pour faire défiler ce Flickable en le faisant glisser.

Par défaut, cette propriété est définie sur Qt.LeftButton, ce qui permet d'obtenir le même comportement que dans les versions précédentes de Qt XML ; mais dans la plupart des interfaces utilisateur, ce comportement est inattendu. Les utilisateurs s'attendent à ne faire glisser que sur un écran tactile, et à utiliser la molette de la souris, les gestes du pavé tactile ou une barre de défilement avec la souris ou le pavé tactile. Définissez-le à Qt.NoButton pour désactiver le glissement.

Elle peut être définie sur une combinaison OU de boutons de la souris, et ignorera les événements provenant d'autres boutons.

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


boundsBehavior : enumeration

Cette propriété indique si la surface peut être déplacée au-delà des limites du Flickable, ou si elle peut dépasser les limites du Flickable lorsqu'elle est cliquée.

Lorsque la valeur de boundsMovement est Flickable.FollowBoundsBehavior, une valeur différente de Flickable.StopAtBounds donnera l'impression que les bords de la vue sont souples, plutôt qu'une limite physique dure.

La valeur boundsBehavior peut être l'une des suivantes

  • Flickable.StopAtBounds - le contenu ne peut pas être déplacé au-delà des limites du flickable, et les flicks ne dépasseront pas les limites.
  • Flickable.DragOverBounds - le contenu peut être déplacé au-delà des limites du flickable, mais les pichenettes ne dépasseront pas les limites.
  • Flickable.OvershootBounds - le contenu peut dépasser la limite lorsqu'il est cliqué, mais le contenu ne peut pas être déplacé au-delà de la limite du flickable. (depuis QtQuick 2.5)
  • Flickable.DragAndOvershootBounds (par défaut) - le contenu peut être déplacé au-delà de la limite du flickable, et peut dépasser la limite lorsqu'il est cliqué.

Voir également horizontalOvershoot, verticalOvershoot, et boundsMovement.


boundsMovement : enumeration

Cette propriété indique si le flickable donnera l'impression que les bords de la vue sont souples, plutôt qu'une limite physique dure.

L'adresse boundsMovement peut être l'une des suivantes

  • Flickable.StopAtBounds - cela permet de mettre en œuvre des effets de bord personnalisés dans lesquels le contenu ne suit pas les déplacements ou les pichenettes au-delà des limites du flickable. Les valeurs de horizontalOvershoot et verticalOvershoot peuvent être utilisées pour mettre en œuvre des effets de bord personnalisés.
  • Flickable.FollowBoundsBehavior (par défaut) - le fait que le contenu suive les déplacements ou les mouvements au-delà des limites du flickable est déterminé par boundsBehavior.

L'exemple suivant maintient le contenu à l'intérieur des limites et applique à la place un effet de retournement lorsque la pichenette dépasse les limites horizontales :

Flickable {
    id: flickable
    boundsMovement: Flickable.StopAtBounds
    boundsBehavior: Flickable.DragAndOvershootBounds
    transform: Rotation {
        axis { x: 0; y: 1; z: 0 }
        origin.x: flickable.width / 2
        origin.y: flickable.height / 2
        angle: Math.min(30, Math.max(-30, flickable.horizontalOvershoot))
    }
}

L'exemple suivant maintient le contenu à l'intérieur des limites et applique à la place un effet d'opacité lorsqu'il est déplacé au-dessus des limites verticales :

Flickable {
    boundsMovement: Flickable.StopAtBounds
    boundsBehavior: Flickable.DragOverBounds
    opacity: Math.max(0.5, 1.0 - Math.abs(verticalOvershoot) / height)
}

Voir également boundsBehavior, verticalOvershoot, et horizontalOvershoot.


contentItem : Item [read-only]

L'élément interne qui contient les éléments à déplacer dans le Flickable.

Les éléments déclarés comme enfants d'un Flickable sont automatiquement rattachés à l'élément de contenu du Flickable.

Les éléments créés dynamiquement doivent être explicitement rattachés à l'élément de contenu:

Flickable {
    id: myFlickable
    function addItem(file) {
        var component = Qt.createComponent(file)
        component.createObject(myFlickable.contentItem);
    }
}

flickDeceleration : real

Cette propriété indique la vitesse de décélération d'un flick : plus le chiffre est élevé, plus le flick ralentit lorsque l'utilisateur arrête de le faire au toucher. Par exemple, 0,0001 est presque "sans friction", et 10000 est plutôt "collant".

La valeur par défaut dépend de la plateforme. Les valeurs égales ou inférieures à zéro ne sont pas autorisées.


flickableDirection : enumeration

Cette propriété détermine les directions dans lesquelles la vue peut être cliquée.

  • Flickable.AutoFlickDirection (par défaut) - permet de cliquer verticalement si le contentHeight n'est pas égal à la hauteur du Flickable. Permet de cliquer horizontalement si la largeur du contenu n'est pas égale à la largeur du Flickable.
  • Flickable.AutoFlickIfNeed - permet de cliquer verticalement si le contentHeight est supérieur à la hauteur du Flickable. Permet de cliquer horizontalement si la largeur du contenu est supérieure à la largeur du Flickable. (depuis QtQuick 2.7)
  • Flickable.HorizontalFlick - permet de cliquer horizontalement.
  • Flickable.VerticalFlick - permet de cliquer verticalement.
  • Flickable.HorizontalAndVerticalFlick - permet de cliquer dans les deux sens.

horizontalOvershoot : real [read-only]

Cette propriété indique le dépassement horizontal, c'est-à-dire la distance horizontale sur laquelle le contenu a été déplacé ou cliqué au-delà des limites du flickable. La valeur est négative lorsque le contenu est déplacé ou cliqué au-delà du début, et positive lorsqu'il dépasse la fin ; 0.0 dans le cas contraire.

Le fait que les valeurs soient signalées pour le glissement et/ou le claquement est déterminé par boundsBehavior. La distance de dépassement est indiquée même si boundsMovement est Flickable.StopAtBounds.

Voir également verticalOvershoot, boundsBehavior, et boundsMovement.


interactive : bool

Cette propriété décrit si l'utilisateur peut interagir avec le Flickable. Un utilisateur ne peut pas faire glisser ou feuilleter un Flickable qui n'est pas interactif.

Par défaut, cette propriété vaut true (vrai).

Cette propriété est utile pour désactiver temporairement le flicking. Cela permet une interaction spéciale avec les enfants du Flickable ; par exemple, vous pourriez vouloir geler une carte cliquable tout en faisant défiler une boîte de dialogue contextuelle qui est un enfant du Flickable.


maximumFlickVelocity : real

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

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


pixelAligned : bool

Cette propriété définit l'alignement de contentX et contentY en pixels (true) ou en sous-pixels (false).

Activez pixelAligned pour optimiser le contenu fixe ou le contenu en mouvement avec des bords très contrastés, tels que des lignes d'un pixel de large, du texte ou des graphiques vectoriels. Désactivez pixelAligned pour optimiser la qualité des animations.

La valeur par défaut est false.


pressDelay : int

Cette propriété indique le délai (ms) nécessaire pour envoyer une pression aux enfants du Flickable. Cela peut s'avérer utile lorsque le fait de réagir à une pression avant une action de pichenette a des effets indésirables.

Si le flickable est déplacé ou cliqué avant l'expiration du délai, l'événement "press" ne sera pas délivré. Si le bouton est relâché dans le délai imparti, la pression et le relâchement seront tous deux pris en compte.

Notez que pour les flickables imbriquées avec un délai de pression défini, le délai de pression des flickables externes est remplacé par le flickable le plus proche. Si la traînée dépasse le seuil de traînée de la plate-forme, l'événement de pression sera délivré indépendamment de cette propriété.

Voir également QStyleHints.


rebound : Transition

Cette propriété contient la transition à appliquer à la vue du contenu lorsqu'elle revient dans les limites du flickable. La transition est déclenchée lorsque la vue est cliquée ou glissée au-delà du bord de la zone de contenu, ou lorsque returnToBounds() est appelé.

import QtQuick 2.0

Flickable {
    width: 150; height: 150
    contentWidth: 300; contentHeight: 300

    rebound: Transition {
        NumberAnimation {
            properties: "x,y"
            duration: 1000
            easing.type: Easing.OutBounce
        }
    }

    Rectangle {
        width: 300; height: 300
        gradient: Gradient {
            GradientStop { position: 0.0; color: "lightsteelblue" }
            GradientStop { position: 1.0; color: "blue" }
        }
    }
}

Lorsque la vue ci-dessus est déplacée au-delà de ses limites, elle revient dans ses limites à l'aide de la transition spécifiée :

Si cette propriété n'est pas définie, une animation par défaut est appliquée.


synchronousDrag : bool

Si cette propriété vaut true, lorsque la souris ou le point de contact se déplace suffisamment pour commencer à faire glisser le contenu, celui-ci saute, de sorte que le pixel de contenu qui se trouvait sous le curseur ou le point de contact au moment de la pression reste sous ce point.

La valeur par défaut est false, ce qui permet d'obtenir une expérience plus fluide (pas de saut) au prix d'une certaine "perte" de la distance de glissement au début.


verticalOvershoot : real [read-only]

Cette propriété indique le dépassement vertical, c'est-à-dire la distance verticale sur laquelle le contenu a été déplacé ou cliqué au-delà des limites du flickable. La valeur est négative lorsque le contenu est déplacé ou cliqué au-delà du début, et positive lorsqu'il dépasse la fin ; 0.0 dans le cas contraire.

Le fait que les valeurs soient signalées pour le glissement et/ou le claquement est déterminé par boundsBehavior. La distance de dépassement est indiquée même si boundsMovement est Flickable.StopAtBounds.

Voir également horizontalOvershoot, boundsBehavior, et boundsMovement.


visibleArea group

visibleArea.heightRatio : real [read-only]

visibleArea.widthRatio : real [read-only]

visibleArea.xPosition : real [read-only]

visibleArea.yPosition : real [read-only]

Ces propriétés décrivent la position et la taille de la zone actuellement visualisée. La taille est définie comme le pourcentage de la vue complète actuellement visible, avec une échelle de 0,0 à 1,0. La position de la page est généralement comprise entre 0,0 (début) et 1,0 moins le rapport de taille (fin), c'est-à-dire que yPosition est compris entre 0,0 et 1,0-heightRatio. Toutefois, il est possible que le contenu soit déplacé en dehors de la plage normale, ce qui fait que les positions de la page sont également en dehors de la plage normale.

Ces propriétés sont généralement utilisées pour dessiner une barre de défilement. Ces propriétés sont généralement utilisées pour dessiner une barre de défilement :

Rectangle {
    width: 200; height: 200

    Flickable {
        id: flickable
        ...
    }

    Rectangle {
        id: scrollbar
        anchors.right: flickable.right
        y: flickable.visibleArea.yPosition * flickable.height
        width: 10
        height: flickable.visibleArea.heightRatio * flickable.height
        color: "black"
    }
}

Signal Documentation

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 se déclenche.

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 après une pichenette ou une série de pichenettes.

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 s'arrête de bouger en raison d'une interaction de l'utilisateur ou d'une action générée par flick(). Si une pichenette était active, ce signal est émis lorsque la pichenette s'arrête. Si la pichenette n'était pas active, ce signal sera émis lorsque l'utilisateur cessera de faire glisser la vue, c'est-à-dire lorsqu'il relâchera sa souris ou son doigt.

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 ou d'une action générée par flick().

Remarque : le gestionnaire correspondant est onMovementStarted.


Documentation de la méthode

cancelFlick()

Annule l'animation de la pichenette en cours.


flick(qreal xVelocity, qreal yVelocity)

Fait bouger le contenu avec xVelocity horizontalement et yVelocity verticalement en pixels/seconde.

L'appel de cette méthode met à jour les propriétés et les signaux de déplacement et de pichenette correspondants, comme s'il s'agissait d'une véritable pichenette sur un écran tactile.


resizeContent(real width, real height, QPointF center)

Redimensionne le contenu à width x height environ center.

Cette méthode ne met pas à l'échelle le contenu du Flickable - elle ne redimensionne que les pages contentWidth et contentHeight.

Le redimensionnement du contenu peut avoir pour effet de positionner le contenu en dehors des limites du Flickable. L'appel à returnToBounds() ramènera le contenu dans les limites légales.


returnToBounds()

Assure que le contenu est dans les limites légales.

Cette fonction peut être appelée pour s'assurer que le contenu est dans les limites légales après avoir positionné manuellement le contenu.


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