Flickable QML Type

Offre une surface sur laquelle on peut « faire glisser du doigt ». En savoir plus…

• 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 éléments enfants sur une surface pouvant être déplacée et balayée d'un geste rapide, ce qui provoque le défilement de la vue sur les éléments enfants. Ce comportement constitue 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, le défilement des vues s'effectue à l'aide de commandes standard, telles que les barres de défilement et les boutons fléchés. Dans certains cas, il est également possible de faire glisser directement la vue en maintenant un bouton de souris enfoncé tout en déplaçant le curseur. Dans les interfaces utilisateur tactiles, cette action de glissement est souvent complétée par un geste de balayage, où le défilement se poursuit après que l’utilisateur a cessé de toucher la vue.

Flickable ne découpe pas automatiquement son contenu. S’il n’est pas utilisé en mode plein écran, il est recommandé de définir la propriété ` clip ` sur `true`.

Exemple d’utilisation

L’exemple suivant montre une petite vue d’une grande image dans laquelle l’utilisateur peut faire glisser ou donner une petite tape à 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 à l’élément contentItem du Flickable. Il convient d’en tenir compte lors de l’exploitation des enfants du Flickable ; ce sont généralement les enfants de contentItem qui sont pertinents. Par exemple, les limites des éléments ajoutés au Flickable seront disponibles via contentItem.childrenRect

Exemples de contentX et contentY

Les images suivantes montrent un Flickable soumis à des mouvements de balayage dans différentes directions, ainsi que les valeurs correspondantes de ` contentX ` et ` contentY `. Le carré bleu représente le contenu du Flickable, tandis que la bordure noire représente ses limites.

Limitations

Documentation sur les propriétés

acceptedButtons : flags [since 6.9]

Les boutons de la souris permettant de faire défiler ce « Flickable » par glissement.

Par défaut, cette propriété est définie sur « Qt.LeftButton », ce qui offre le même comportement que dans les versions précédentes de Qt ; mais dans la plupart des interfaces utilisateur, ce comportement est inattendu. Les utilisateurs s'attendent à ne faire glisser du doigt 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-la sur « Qt.NoButton » pour désactiver le glissement.

Elle peut être définie sur une combinaison « OU » de boutons de 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 défilable est positionnée respectivement au début ou à la fin.

Ces propriétés définissent les marges autour du contenu. Cet espace est réservé en plus de ceux définis par les propriétés ` contentWidth ` et ` contentHeight`.

boundsBehavior : enumeration

Cette propriété détermine si la surface peut être déplacée au-delà des limites du Flickable ou si elle peut dépasser ces limites lorsqu'on la fait glisser d'un geste rapide.

Lorsque la propriété « boundsMovement » est définie sur « Flickable.FollowBoundsBehavior », une valeur autre que « Flickable.StopAtBounds » donnera l’impression que les bords de la vue sont flous, plutôt que de constituer une limite physique nette.

L’ boundsBehavior peut prendre l’une des valeurs suivantes :

• Flickable.StopAtBounds : le contenu ne peut pas être déplacé au-delà des limites du Flickable, et les glissements ne dépasseront pas ces limites.
• Flickable.DragOverBounds : le contenu peut être déplacé au-delà des limites du Flickable, mais les glissements ne dépasseront pas ces limites.
• Flickable.OvershootBounds : le contenu peut dépasser les limites lors d’un glissement, mais il ne peut pas être déplacé au-delà des limites du Flickable. (depuis QtQuick 2.5)
• Flickable.DragAndOvershootBounds (par défaut) : le contenu peut être déplacé au-delà des limites du Flickable et peut dépasser ces limites lors d’un glissement.

Voir également horizontalOvershoot, verticalOvershoot et boundsMovement.

boundsMovement : enumeration

Cette propriété détermine si l'effet « flickable » donne l'impression que les bords de la vue sont flous, plutôt que de constituer une limite physique nette.

L'boundsMovement e peut prendre l'une des valeurs suivantes :

• Flickable.StopAtBounds : cette option permet de mettre en œuvre des effets de bord personnalisés, dans lesquels le contenu ne suit pas les glissements ou les balayages 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 ou non les glissements ou les balayages au-delà des limites de l’élément « flickable » est déterminé par boundsBehavior.

L’exemple suivant maintient le contenu dans les limites et applique à la place un effet de retournement lorsque l’on effectue un balayage au-delà des 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é lorsque l'on fait glisser le doigt au-delà 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 gérée par Flickable). Cette valeur doit généralement correspondre à la taille totale des éléments placés dans le Flickable.

L'extrait de code 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 définies automatiquement en fonction des propriétés ` childrenRect.width ` et ` childrenRect.height ` de l'contentItem. Par exemple, l'extrait de code précédent pourrait être réécrit comme suit :

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

Cela suppose toutefois que l’origine du childrenRect soit 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 au contentItem de ce Flickable.

Les éléments créés dynamiquement doivent être explicitement rattachés au ` contentItem` :

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

Ces propriétés contiennent les coordonnées de la surface correspondant actuellement au coin supérieur gauche du Flickable. Par exemple, si vous faites glisser une image de 100 pixels vers le haut, la valeur de ` contentY ` augmentera de 100.

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

Ces propriétés indiquent si la vue se déplace actuellement horizontalement, verticalement ou dans les deux sens, lorsque l'utilisateur la fait glisser.

flickDeceleration : real

Cette propriété définit la vitesse à laquelle un mouvement rapide va ralentir : plus la valeur est élevée, plus le mouvement ralentit rapidement lorsque l'utilisateur cesse de le faire par effleurement. Par exemple, une valeur de 0,0001 correspond à un mouvement pratiquement « sans frottement », tandis qu'une valeur de 10 000 donne une sensation assez « collante ».

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 dans quelles directions la vue peut être déplacée d'un geste rapide.

• Flickable.AutoFlickDirection (par défaut) : permet le défilement vertical si la hauteur du contenu (contentHeight) n'est pas égale à la hauteur du Flickable. Permet le défilement horizontal si la largeur du contenu (contentWidth) n'est pas égale à la largeur du Flickable.
• Flickable.AutoFlickIfNeeded : permet le défilement vertical si la hauteur du contenu (contentHeight) est supérieure à la hauteur du Flickable. Permet le défilement horizontal si la largeur du contenu (contentWidth) est supérieure à la largeur du Flickable. (depuis QtQuick 2.7)
• Flickable.HorizontalFlick - autorise le défilement horizontal.
• Flickable.VerticalFlick : permet le défilement vertical.
• Flickable.HorizontalAndVerticalFlick - permet de faire défiler dans les deux sens.

Ces propriétés indiquent si la vue se déplace actuellement horizontalement, verticalement ou dans les deux sens, suite à un geste de balayage effectué par 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é glissé ou déplacé d'un geste rapide au-delà des limites de l'élément « flickable ». La valeur est négative lorsque le contenu est glissé ou déplacé au-delà du début, et positive lorsqu'il dépasse la fin ; 0.0 dans les autres cas.

C’est la propriété ` boundsBehavior` qui détermine si les valeurs sont signalées pour le glissement et/ou le balayage. La distance de dépassement est signalée même lorsque ` boundsMovement ` vaut ` Flickable.StopAtBounds`.

Voir également verticalOvershoot, boundsBehavior et boundsMovement.

La vitesse instantanée de déplacement le long des axes x et y, en pixels/sec.

La vitesse indiquée est lissée afin d'éviter des résultats irréguliers.

Notez que pour les pages dont le contenu est volumineux (plus de 10 fois la taille de la page), la vitesse du balayage peut dépasser celle du toucher en cas de multiples balayages rapides et consécutifs. Cela permet à l'utilisateur de parcourir plus rapidement un contenu volumineux.

interactive : bool

Cette propriété indique si l'utilisateur peut interagir avec l'élément « Flickable ». Un utilisateur ne peut ni faire glisser ni faire défiler un élément « Flickable » qui n'est pas interactif.

Par défaut, cette propriété est définie sur « true ».

Cette propriété est utile pour désactiver temporairement le balayage. Cela permet une interaction particulière avec les éléments enfants du Flickable ; par exemple, vous pouvez vouloir figer une carte « Flickable » tout en faisant défiler une boîte de dialogue contextuelle qui est un élément enfant du Flickable.

maximumFlickVelocity : real

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

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

Ces propriétés indiquent si la vue se déplace actuellement horizontalement, verticalement ou dans les deux sens, suite à un glissement ou à un balayage effectué par l'utilisateur.

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.

Elle est généralement (0,0), mais ListView et GridView peuvent avoir une origine arbitraire en raison des variations de taille des délégués ou de l’insertion/suppression d’éléments en dehors de la zone visible.

Voir également contentX et contentY.

pixelAligned : bool

Cette propriété définit l'alignement des éléments ` contentX ` et ` contentY ` sur les pixels (true) ou les sous-pixels (false).

Activez « pixelAligned » pour optimiser le contenu statique ou le contenu animé présentant des contours à fort contraste, tels que des lignes d’un pixel de large, du texte ou des graphiques vectoriels. Désactivez « pixelAligned » lorsque vous optimisez la qualité des animations.

La valeur par défaut est « false ».

pressDelay : int

Cette propriété définit le délai (en ms) avant la transmission d’un événement de pression aux éléments enfants du Flickable. Cela peut s’avérer utile lorsque le fait de réagir à une pression avant une action de balayage entraîne des effets indésirables.

Si le Flickable est glissé ou balayé avant l'expiration du délai, l'événement de pression ne sera pas déclenché. Si le bouton est relâché avant l'expiration du délai, les événements de pression et de relâchement seront tous deux déclenchés.

Notez que pour les Flickables imbriqués dont la propriété pressDelay est définie, la valeur de pressDelay des Flickables extérieurs est remplacée par celle du Flickable le plus intérieur. Si le glissement dépasse le seuil de glissement de la plateforme, l'événement de pression sera déclenché quelle que soit la valeur de cette propriété.

Voir également QStyleHints.

rebound : Transition

Ce paramètre définit la transition à appliquer à la vue de contenu lorsqu’elle revient dans les limites de l’élément « flickable ». La transition est déclenchée lorsque la vue est déplacée d’un geste rapide ou glissée au-delà du bord de la zone de contenu, ou lorsque la méthode ` returnToBounds()` est appelée.

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 d’un geste rapide au-delà de ses limites, elle revient à l’intérieur de celles-ci en utilisant 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, celui-ci effectuera un saut, de sorte que le pixel du 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 offre une expérience plus fluide (pas de saut) au prix d’une « perte » d’une partie de la distance de glissement au début.

verticalOvershoot : real [read-only]

Cette propriété contient le dépassement vertical, c'est-à-dire la distance verticale dont le contenu a été glissé ou déplacé d'un geste rapide au-delà des limites de l'élément « flickable ». La valeur est négative lorsque le contenu est glissé ou déplacé d'un geste rapide au-delà du début, et positive lorsqu'il dépasse la fin ; 0.0 dans les autres cas.

C’est la propriété ` boundsBehavior` qui détermine si les valeurs sont signalées pour le glissement et/ou le balayage. La distance de dépassement est signalée même lorsque ` boundsMovement ` est défini sur ` 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 affichée. La taille est définie comme le pourcentage de la vue complète actuellement visible, mise à l'échelle entre 0,0 et 1,0. La position de la page se situe généralement dans l'intervalle compris entre 0,0 (début) et 1,0 moins le rapport de taille (fin), c'est-à-dire que yPosition se situe dans l'intervalle compris entre 0,0 et 1,0 -heightRatio. Cependant, il est possible que le contenu soit déplacé hors de cette plage normale, ce qui entraîne des positions de page également hors de cette plage.

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

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"
    }
}

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ù l'utilisateur relâche le doigt ou le bouton de la souris, 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 après un mouvement rapide ou une série de mouvements rapides.

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 encore en cours.

movementEnded()

Ce signal est émis lorsque la vue cesse de se déplacer à la suite d'une interaction de l'utilisateur ou d'un appel à la fonction ` flick()`. Si un « flick » était actif, ce signal sera émis dès que le « flick » s'arrête. Si aucun « flick » n'était actif, 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 ou d'un appel à la fonction flick().

Documentation de la méthode

void cancelFlick()

Annule l'animation de balayage en cours.

void flick(qreal xVelocity, qreal yVelocity)

Déplace le contenu à une vitesse de xVelocity horizontalement et de yVelocity verticalement, en pixels par seconde.

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

[since 6.11] void flickTo(point position)

Fait défiler le contenu défilable vers position.

Si le fait de faire défiler l'élément « flickable » entraînait l'affichage d'un espace vide au début ou à la fin de celui-ci, le défilement s'arrêterait à la limite.

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

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

Déplace l'élément déplaçable de telle sorte qu’un élément de child (s’il s’agit d’un enfant) se trouve à la position spécifiée par mode. mode peut être une combinaison (avec l’opérateur « ou ») des éléments suivants :

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

Vous pouvez éventuellement spécifier ` offset ` pour faire défiler un nombre supplémentaire de pixels au-delà de l’alignement cible.

Si le déplacement de l’élément déplaçable au niveau de l’élément enfant entraîne l’affichage d’un espace vide au début ou à la fin de l’élément déplaçable, celui-ci s’arrêtera à 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)

Positions contentX et contentY telles 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 (avec l'opérateur « ou ») 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.

Vous pouvez éventuellement 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 de l’élément « flickable » au niveau de l’élément enfant entraîne l’affichage d’un espace vide au début ou à la fin de l’élément « flickable », celui-ci 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, soit environ center.

Cela ne modifie pas l'échelle du contenu du Flickable : cela redimensionne uniquement les valeurs contentWidth et contentHeight.

Le redimensionnement du contenu peut entraîner son positionnement en dehors des limites du Flickable. L'appel de returnToBounds() replacera le contenu dans les limites autorisées.

void returnToBounds()

Vérifie que le contenu respecte les dispositions légales.

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