Flickable QML Type

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

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

Propriétés

• acceptedButtons : flags (since 6.9)
• atXBeginning : bool
• atXEnd : bool
• atYBeginning : bool
• atYEnd : bool
• bottomMargin : real
• boundsBehavior : enumeration
• boundsMovement : enumeration
• contentHeight : real
• contentItem : Item
• contentWidth : real
• contentX : real
• contentY : real
• dragging : bool
• draggingHorizontally : bool
• draggingVertically : bool
• flickDeceleration : real
• flickableDirection : enumeration
• flicking : bool
• flickingHorizontally : bool
• flickingVertically : bool
• horizontalOvershoot : real
• horizontalVelocity : real
• interactive : bool
• leftMargin : real
• maximumFlickVelocity : real
• moving : bool
• movingHorizontally : bool
• movingVertically : bool
• originX : real
• originY : real
• pixelAligned : bool
• pressDelay : int
• rebound : Transition
• rightMargin : real
• synchronousDrag : bool
• topMargin : real
• verticalOvershoot : real
• verticalVelocity : real
• visibleArea
  • visibleArea.heightRatio : real
  • visibleArea.widthRatio : real
  • visibleArea.xPosition : real
  • visibleArea.yPosition : real

Signaux

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

Méthodes

• void cancelFlick()
• void flick(qreal xVelocity, qreal yVelocity)
• void flickTo(point position) (since 6.11)
• void flickToChild(QQuickItem *child, PositionMode mode, point offset) (since 6.11)
• void positionViewAtChild(QQuickItem *child, PositionMode mode, point offset) (since 6.11)
• void resizeContent(real width, real height, point center)
• void returnToBounds()

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.

Limites

Documentation sur les propriétés

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

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

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

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'on la touche.

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 aussi horizontalOvershoot, verticalOvershoot, et boundsMovement.

boundsMovement : enumeration

Cette propriété indique si le flickable donnera l'impression que les bords de la vue sont doux, 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.

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.

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);
    }
}

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.

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

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.

flickDeceleration : real

Cette propriété indique la vitesse de décélération d'une pichenette : plus le nombre est élevé, plus la pichenette ralentit lorsque l'utilisateur arrête de la 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.

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.

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.

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.

interactive : bool

Cette propriété indique 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 basculer la vue en pixels/seconde.

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

Ces propriétés indiquent si la vue est en train de se déplacer horizontalement, verticalement ou dans l'une ou l'autre direction, du fait que l'utilisateur a fait glisser la vue ou l'a fait basculer.

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.

pixelAligned : bool

Cette propriété définit l'alignement de contentX et contentY sur des pixels (true) ou des 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 transmettre une pression aux enfants du Flickable. Cela peut s'avérer utile lorsque la réaction à un appui avant une action de flickage a des effets indésirables.

Si le flickable est déplacé ou cliqué avant que le délai ne soit écoulé, 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

Ceci 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é est définie sur true, lorsque la souris ou le point de contact se déplace suffisamment loin pour commencer à faire glisser le contenu, ce dernier saute, de sorte que le pixel du contenu qui se trouvait sous le curseur ou le point de contact au moment de l'appui reste sous ce point.

La valeur par défaut est false, ce qui permet 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

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 l'affichage complet actuellement visible, échelonné entre 0,0 et 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 de faire glisser le contenu en dehors de la plage normale, ce qui a pour conséquence que la position de la page se situe é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 de déplacement est suffisante au moment où le bouton tactile/souris est relâché, une pichenette se déclenche.

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

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 s'arrête de bouger en raison de l'interaction de l'utilisateur ou d'une flick() générée. 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.

movementStarted()

Ce signal est émis lorsque la vue commence à se déplacer à la suite d'une interaction avec l'utilisateur ou d'un message généré par flick().

Documentation de la méthode

void cancelFlick()

Annule l'animation de la pichenette en cours.

void 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 signaux de mouvement et de pichenette correspondants, tout comme une véritable pichenette sur un écran tactile.

[since 6.11] void flickTo(point position)

Fait clignoter le flickable à l'adresse position.

Si l'actionnement du flickable entraîne l'affichage d'un espace vide au début ou à la fin du flickable, le flickable s'arrête à la limite.

Cette méthode a été introduite dans Qt 6.11.

[since 6.11] void flickToChild(QQuickItem *child, PositionMode mode, point offset)

Fait basculer le flickable de telle sorte que l'élément child (s'il s'agit d'un enfant) se trouve à la position spécifiée par mode. mode peut être une combinaison or-ed des éléments suivants :

Si aucun alignement vertical n'est spécifié, les pichenettes verticales seront ignorées. Il en va de même pour l'alignement horizontal.

En option, vous pouvez spécifier offset pour afficher un nombre supplémentaire de pixels au-delà de l'alignement cible.

Si l'actionnement du flickable au niveau de l'élément enfant entraîne l'affichage d'un espace vide au début ou à la fin du flickable, le flickable s'arrêtera au niveau de la limite.

import QtQuick
import QtQuick.Controls
import QtQuick.Window

Flickable {
    id: flickable

    width: 200
    height: 200
    contentWidth: width
    contentHeight: column.height

    // Will flick to the beginning of the activeFocusItem every time it changes
    property Item activeFocusItem: Window.activeFocusItem
    onActiveFocusItemChanged: flickable.flickToChild(activeFocusItem, Flickable.AlignTop)

    Column {
        id: column

        spacing: 10

        Repeater {
            model: 10
            TextArea {}
        }
    }
}

Cette méthode a été introduite dans Qt 6.11.

[since 6.11] void positionViewAtChild(QQuickItem *child, PositionMode mode, point offset)

Positionne contentX et contentY de telle sorte que l'élément child (s'il s'agit d'un enfant) se trouve à la position spécifiée par mode. mode peut être une combinaison or-ed des éléments suivants :

Si aucun alignement vertical n'est spécifié, le positionnement vertical sera ignoré. Il en va de même pour l'alignement horizontal.

En option, vous pouvez spécifier offset pour déplacer contentX et contentY d'un nombre supplémentaire de pixels au-delà de l'alignement cible.

Si le positionnement du flickable au niveau de l'élément enfant entraîne l'affichage d'un espace vide au début ou à la fin du flickable, le flickable sera positionné à la limite.

import QtQuick
import QtQuick.Controls
import QtQuick.Window

Flickable {
    id: flickable

    width: 200
    height: 200
    contentWidth: width
    contentHeight: column.height

    // Will center activeFocusItem in the Flickable every time it changes
    property Item activeFocusItem: Window.activeFocusItem
    onActiveFocusItemChanged: flickable.positionViewAtChild(activeFocusItem, Flickable.AlignCenter)

    Column {
        id: column

        spacing: 10

        Repeater {
            model: 10
            TextArea {}
        }
    }
}

Cette méthode a été introduite dans Qt 6.11.

void resizeContent(real width, real height, point center)

Redimensionne le contenu à width x height environ center.

Cette opération ne met pas à l'échelle le contenu du flickable - elle ne fait que redimensionner 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.

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