PinchHandler QML Type

Gestionnaire des gestes de pincement. En savoir plus...

• Liste de tous les membres, y compris les membres hérités
• Membres obsolètes

Propriétés

• acceptedDevices : flags
• acceptedModifiers : flags
• acceptedPointerTypes : flags
• active : bool
• activeRotation : real
• activeScale : real
• activeTranslation : point
• centroid : QtQuick::handlerPoint
• cursorShape : Qt::CursorShape
• dragThreshold : int
• enabled : bool
• grabPermissions : flags
• margin : real
• parent : Item
• persistentRotation : real
• persistentScale : real
• persistentTranslation : point
• rotationAxis
  • rotationAxis.activeValue : real
  • rotationAxis.enabled : bool
  • rotationAxis.maximum : real
  • rotationAxis.minimum : real
• scaleAxis
  • scaleAxis.activeValue : real
  • scaleAxis.enabled : bool
  • scaleAxis.maximum : real
  • scaleAxis.minimum : real
• target : Item
• xAxis
  • xAxis.activeValue : real
  • xAxis.enabled : bool
  • xAxis.maximum : real
  • xAxis.minimum : real
• yAxis
  • yAxis.activeValue : real
  • yAxis.enabled : bool
  • yAxis.maximum : real
  • yAxis.minimum : real

Signaux

• canceled(eventPoint point)
• grabChanged(PointerDevice::GrabTransition transition, eventPoint point)
• rotationChanged(qreal delta)
• scaleChanged(qreal delta)
• translationChanged(QVector2D delta)

Description détaillée

PinchHandler est un gestionnaire qui interprète un geste à plusieurs doigts pour faire pivoter, zoomer et faire glisser un élément de manière interactive. À l'instar des autres gestionnaires d'entrée, il est, par défaut, entièrement fonctionnel et manipule son target, c'est-à-dire l'élément dans lequel il est déclaré.

import QtQuick

Rectangle {
    width: 400
    height: 300
    color: "lightsteelblue"
    PinchHandler { }
}

Il dispose de propriétés permettant de limiter la plage de glissement, de rotation et de zoom.

S’il est déclaré au sein d’un élément mais qu’on lui attribue un ` target` différent, il gère les événements dans les limites de l’élément externe mais manipule à la place l’élément ` target ` :

import QtQuick

Item {
    width: 640
    height: 480

    Rectangle {
        id: map
        color: "aqua"
        width: 400
        height: 300
    }

    PinchHandler {
        target: map
    }
}

Une troisième façon de l'utiliser consiste à définir ` target ` sur ` null ` et à réagir aux changements de propriété d'une autre manière :

import QtQuick

Window {
    width: 320; height: 240
    visible: true
    title: handler.persistentRotation.toFixed(1) + "° " +
           handler.persistentTranslation.x.toFixed(1) + ", " +
           handler.persistentTranslation.y.toFixed(1) + " " +
           (handler.persistentScale * 100).toFixed(1) + "%"

    PinchHandler {
        id: handler
        target: null
        persistentScale: 0.25
        onTranslationChanged: (delta) => {
            image.x -= delta.x
            image.y -= delta.y
        }
    }

    Image {
        id: image
        source: "images/album-cover.jpg"
        scale: handler.persistentScale
        x: -600; y: -450
    }
}

Voir également PinchArea, QPointerEvent::pointCount(), QNativeGestureEvent::fingerCount() et Qt Quick Exemples - Gestionnaires de pointeur.

Documentation sur les propriétés

acceptedDevices : flags

Les types de périphériques de pointage pouvant activer ce gestionnaire de pointeur.

Par défaut, cette propriété est définie sur « PointerDevice.AllDevices ». Si vous la définissez sur une combinaison de types de périphériques séparés par « OR », elle ignorera les événements provenant des périphériques qui ne correspondent pas.

Par exemple, un contrôle pourrait être configuré pour répondre d’une certaine manière aux clics de souris et de stylet, et d’une autre manière aux tapotements sur un écran tactile, à l’aide de deux gestionnaires :

Item {
   TapHandler {
       acceptedDevices: PointerDevice.Mouse | PointerDevice.TouchPad | PointerDevice.Stylus
       onTapped: console.log("clicked")
   }
   TapHandler {
       acceptedDevices: PointerDevice.TouchScreen
       onTapped: console.log("tapped")
   }
}

acceptedModifiers : flags

Si cette propriété est définie, les événements liés au pointeur ne seront pris en compte que si les touches de modification spécifiées sont enfoncées ; dans le cas contraire, ils seront ignorés.

Si cette propriété est définie sur « Qt.KeyboardModifierMask » (valeur par défaut), l’ PointerHandler ignore les touches de modification.

Par exemple, une ` Item ` peut comporter deux gestionnaires de même type, dont l’un n’est activé que si les touches de modification requises sont enfoncées :

Item {
   TapHandler {
       acceptedModifiers: Qt.ControlModifier
       onTapped: console.log("control-tapped")
   }
   TapHandler {
       acceptedModifiers: Qt.NoModifier
       onTapped: console.log("tapped")
   }
}

Si vous définissez « acceptedModifiers » sur une combinaison « OU » de touches de modification, cela signifie que toutes ces touches doivent être enfoncées pour activer le gestionnaire :

Item {
   TapHandler {
       acceptedModifiers: Qt.ControlModifier | Qt.AltModifier | Qt.ShiftModifier
       onTapped: console.log("control-alt-shift-tapped")
   }
}

Les touches de modification disponibles sont les suivantes :

Si vous avez besoin d'un comportement encore plus complexe que celui pouvant être obtenu avec des combinaisons de plusieurs gestionnaires et de plusieurs indicateurs de modificateurs, vous pouvez vérifier les modificateurs dans le code JavaScript :

Item {
    TapHandler {
        onTapped:
            switch (point.modifiers) {
            case Qt.ControlModifier | Qt.AltModifier:
                console.log("CTRL+ALT");
                break;
            case Qt.ControlModifier | Qt.AltModifier | Qt.MetaModifier:
                console.log("CTRL+META+ALT");
                break;
            default:
                console.log("other modifiers", point.modifiers);
                break;
            }
    }
}

Voir également Qt::KeyboardModifier.

acceptedPointerTypes : flags

Les types d'instruments de pointage (doigt, stylet, gomme, etc.) pouvant activer ce gestionnaire de pointeur.

Par défaut, cette propriété est définie sur « PointerDevice.AllPointerTypes ». Si vous la définissez sur une combinaison « OU » de types de périphériques, elle ignorera les événements provenant d’ devices non correspondants.

Par exemple, un contrôle pourrait être configuré pour répondre d’une certaine manière aux clics de souris, aux touches tactiles et aux clics de stylet, mais s’effacer s’il est touché avec un outil « gomme » sur une tablette graphique, à l’aide de deux gestionnaires :

Rectangle {
   id: rect
   TapHandler {
       acceptedPointerTypes: PointerDevice.Generic | PointerDevice.Finger | PointerDevice.Pen
       onTapped: console.log("clicked")
   }
   TapHandler {
       acceptedPointerTypes: PointerDevice.Eraser
       onTapped: rect.destroy()
   }
}

active : bool [read-only]

Cette propriété est vérifiée ( true ) lorsque toutes les contraintes (notamment minimumPointCount et maximumPointCount) sont respectées et que la target, le cas échéant, est en cours de modification.

activeRotation : real [read-only]

Angle de rotation du geste de pincement en degrés, les valeurs positives correspondant au sens des aiguilles d'une montre. Il s'agit de la valeur « 0 » au moment où le geste commence. Si « target » n'est pas nul, cette valeur sera automatiquement ajoutée à son « rotation ». Sinon, des liaisons peuvent être utilisées pour effectuer des opérations arbitraires avec cette valeur.

Voir également ` QtQuick::PinchHandler::rotationAxis.activeValue`.

activeScale : real [read-only]

Facteur d'échelle pendant l'exécution du geste de pincement. Il est égal à 1,0 au début du geste, augmente à mesure que les points de contact s'écartent, et diminue à mesure qu'ils se rapprochent. Si target n'est pas nul, son scale sera automatiquement multiplié par cette valeur. Sinon, des liaisons peuvent être utilisées pour effectuer des opérations arbitraires avec cette valeur.

Voir également QtQuick::PinchHandler::scaleAxis.activeValue.

activeTranslation : point [read-only]

Translation du groupe de points pendant l'exécution du geste de pincement. Elle est égale à 0, 0 au début du geste, puis augmente à mesure que les « eventPoint(s) » sont déplacés vers le bas et vers la droite. Une fois le geste terminé, elle reste inchangée ; et lorsque le geste de pincement suivant commence, elle est réinitialisée à 0, 0.

centroid : QtQuick::handlerPoint [read-only]

Un point situé exactement au milieu des points tactiles actuellement enfoncés. L'target e pivotera autour de ce point.

cursorShape : Qt::CursorShape

Cette propriété définit la forme du curseur qui s'affichera lorsque la souris survolera l'élément « parent » et que la propriété « active » aura la valeur « true ».

Les formes de curseur disponibles sont les suivantes :

• Qt.ArrowCursor
• Qt.UpArrowCursor
• Qt.CrossCursor
• Qt.WaitCursor
• Qt.IBeamCursor
• Qt.CursorTailleVerticale
• Qt.CursorTailleHoriz
• Qt.SizeBDiagCursor
• Qt.SizeFDiagCursor
• Qt.SizeAllCursor
• Qt.CursorVide
• Qt.CursorDiviséVertical
• Qt.Cursor à division horizontale
• Qt.CursorMainPointante
• Qt.CursorInterdit
• Qt.Cursor« Qu'est-ce que c'est ? »
• Qt.Curseur-occupé
• Qt.CursorMainOuverte
• Qt.CurseurMainFermée
• Qt.CurseurGlisserCopier
• Qt.CurseurGlisserDéplacer
• Qt.DragLinkCursor

La valeur par défaut n'est pas définie, ce qui permet à l'élément « cursor » de l'parent d'apparaître. Cette propriété peut être réinitialisée à son état initial en lui attribuant la valeur « undefined ».

Voir également Qt::CursorShape, QQuickItem::cursor() et HoverHandler::cursorShape.

dragThreshold : int

Distance en pixels sur laquelle l'utilisateur doit faire glisser un élément « eventPoint » pour que ce mouvement soit considéré comme un geste de glissement.

La valeur par défaut dépend de la plateforme et de la résolution de l'écran. Elle peut être réinitialisée à sa valeur par défaut en la définissant sur « undefined ». Le comportement lors du début d’un geste de glissement varie selon les gestionnaires.

enabled : bool

Si un « PointerHandler » est désactivé, il rejettera tous les événements et aucun signal ne sera émis.

Si la propriété « parent » d'une PointerHandler est définie sur « disabled », le gestionnaire sera également désactivé de fait, même si la propriété « enabled » reste définie sur « true ».

grabPermissions : flags

Cette propriété définit les autorisations lorsque la logique de ce gestionnaire décide de prendre le contrôle exclusif, ou lorsqu'il est invité à approuver la prise de contrôle ou l'annulation de celle-ci par un autre gestionnaire.

La valeur par défaut est « PointerHandler.CanTakeOverFromItems | PointerHandler.CanTakeOverFromHandlersOfDifferentType | PointerHandler.ApprovesTakeOverByAnything », ce qui autorise la plupart des scénarios de prise de contrôle tout en évitant, par exemple, que deux PinchHandlers ne se disputent les mêmes points de contact.

margin : real

La marge situant-se au-delà des limites de l’élément « parent », à l’intérieur de laquelle un « eventPoint » peut activer ce gestionnaire. Par exemple, sur une page PinchHandler où l’élément « target » est également l’« parent », il est utile de définir cette marge à une distance correspondant au moins à la moitié de la largeur du doigt d’un utilisateur type, afin que, si l’« parent » a été réduit à une très petite taille, le geste de pincement reste possible. De même, si un bouton basé sur l’ TapHandler est placé près du bord de l’écran, cela permet de respecter la loi de Fitts : réagir aux clics de souris au bord de l’écran même si le bouton est visuellement espacé de quelques pixels par rapport à ce bord.

La valeur par défaut est 0.

parent : Item

L'objet ` Item `, qui correspond à la portée du gestionnaire ; l'`Item` dans lequel il a été déclaré. Le gestionnaire traitera les événements pour le compte de cet `Item`, ce qui signifie qu'un événement de pointeur est pertinent si au moins l'un de ses ` eventPoints ` se produit à l'intérieur de l'`Item`. Au départ, ` target() ` est identique, mais il peut être réaffecté.

Voir également target et QObject::parent().

persistentRotation : real

Rotation à appliquer à l’ target si celle-ci n’est pas nulle. Sinon, les liaisons peuvent être utilisées pour effectuer des opérations arbitraires sur cette valeur. Pendant l’exécution du geste de pincement, la valeur activeRotation est mise à jour en continu ; une fois le geste terminé, elle reste inchangée ; et lorsque le geste de pincement suivant commence, elle recommence à être modifiée par activeRotation.

Il est possible de définir cette propriété afin de synchroniser la rotation de base avec une rotation définie d’une autre manière, par exemple par un autre gestionnaire. Si vous définissez cette propriété directement, ` activeRotation ` ne change pas et ` rotationChanged(0) ` est émis.

persistentScale : real

Le facteur d'échelle qui sera automatiquement appliqué à l'target s'il n'est pas nul. Sinon, des liaisons peuvent être utilisées pour effectuer des opérations arbitraires avec cette valeur. Pendant l'exécution du geste de pincement, cette valeur est multipliée en continu par activeScale; une fois le geste terminé, elle reste inchangée ; et lorsque le geste de pincement suivant commence, elle recommence à être multipliée par activeScale.

Il est possible de définir cette propriété afin de synchroniser l’échelle de base avec une échelle définie d’une autre manière, par exemple par un autre gestionnaire. Si vous définissez cette propriété directement, activeScale ne change pas et scaleChanged(1) est émis.

persistentTranslation : point

Traduction à appliquer à l'target si celle-ci n'est pas null. Sinon, des liaisons peuvent être utilisées pour effectuer des opérations arbitraires avec cette valeur. Pendant l'exécution du geste de pincement, la valeur activeTranslation y est ajoutée en continu ; une fois le geste terminé, elle reste inchangée.

Il est possible de définir cette propriété afin de synchroniser la translation de base avec une translation définie d’une autre manière, par exemple par un autre gestionnaire. Si vous définissez cette propriété directement, activeTranslation ne change pas et translationChanged({0, 0}) est émis.

rotationAxis group

rotationAxis définit les contraintes permettant de régler l'rotation de l'élément « target » en fonction de la rotation du groupe de points de contact.

minimum correspond à la rotation minimale acceptable. maximum correspond à la rotation maximale acceptable. Si enabled est défini sur true, la rotation est autorisée. activeValue est identique à QtQuick::PinchHandler::activeRotation.

Le signal « activeValueChanged » est émis lorsque « activeValue » change, afin de fournir l’incrément correspondant à ce changement. Ceci est destiné à ajuster de manière incrémentielle une propriété via plusieurs gestionnaires.

import QtQuick

Rectangle {
    width: 100; height: 100
    color: "lightsteelblue"; antialiasing: true

    PinchHandler {
        id: handler
        target: null
        xAxis.onActiveValueChanged: (delta) => parent.radius -= delta
        yAxis.onActiveValueChanged: (delta) => parent.border.width += delta
        rotationAxis.onActiveValueChanged: (delta) => parent.rotation += delta // add
        scaleAxis.onActiveValueChanged: (delta) => parent.scale *= delta // multiply
    }

    WheelHandler {
        acceptedModifiers: Qt.NoModifier
        property: "rotation"
    }

    WheelHandler {
        acceptedModifiers: Qt.ControlModifier
        property: "scale"
    }
}

scaleAxis group

scaleAxis définit les contraintes relatives à l'scale de l'élément « target » en fonction de la distance entre les points de contact.

minimum correspond à l’échelle minimale acceptable. maximum correspond à l’échelle maximale acceptable. Si enabled est défini sur true, la mise à l’échelle est autorisée. activeValue est identique à QtQuick::PinchHandler::activeScale.

Le signal « activeValueChanged » est émis lorsque « activeValue » change, afin de fournir le multiplicateur pour la modification incrémentielle. Cela est destiné à ajuster de manière incrémentielle une propriété via plusieurs gestionnaires.

import QtQuick

Rectangle {
    width: 100; height: 100
    color: "lightsteelblue"; antialiasing: true

    PinchHandler {
        id: handler
        target: null
        xAxis.onActiveValueChanged: (delta) => parent.radius -= delta
        yAxis.onActiveValueChanged: (delta) => parent.border.width += delta
        rotationAxis.onActiveValueChanged: (delta) => parent.rotation += delta // add
        scaleAxis.onActiveValueChanged: (delta) => parent.scale *= delta // multiply
    }

    WheelHandler {
        acceptedModifiers: Qt.NoModifier
        property: "rotation"
    }

    WheelHandler {
        acceptedModifiers: Qt.ControlModifier
        property: "scale"
    }
}

target : Item

L'élément que ce gestionnaire va manipuler.

Par défaut, il s'agit de l'parent, c'est-à-dire l'élément dans lequel le gestionnaire est déclaré. Cependant, il peut parfois être utile de définir la cible sur un autre élément, afin de gérer les événements au sein d'un élément tout en manipulant un autre ; ou de l'null, pour désactiver le comportement par défaut et effectuer une autre action à la place.

xAxis group

xAxis définit les contraintes relatives au déplacement horizontal de l'élément target.

minimum est la coordonnée x minimale acceptable de la translation. maximum est la coordonnée x maximale acceptable de la translation. Si enabled est vrai, le glissement horizontal est autorisé.

Le signal ` activeValueChanged ` est émis lorsque ` activeValue ` change, afin de fournir l’incrément correspondant à ce changement. Ceci est destiné à ajuster de manière incrémentielle une propriété via plusieurs gestionnaires.

import QtQuick

Rectangle {
    width: 100; height: 100
    color: "lightsteelblue"; antialiasing: true

    PinchHandler {
        id: handler
        target: null
        xAxis.onActiveValueChanged: (delta) => parent.radius -= delta
        yAxis.onActiveValueChanged: (delta) => parent.border.width += delta
        rotationAxis.onActiveValueChanged: (delta) => parent.rotation += delta // add
        scaleAxis.onActiveValueChanged: (delta) => parent.scale *= delta // multiply
    }

    WheelHandler {
        acceptedModifiers: Qt.NoModifier
        property: "rotation"
    }

    WheelHandler {
        acceptedModifiers: Qt.ControlModifier
        property: "scale"
    }
}

yAxis group

yAxis définit les contraintes relatives au déplacement vertical de l'élément « target ».

minimum correspond à la coordonnée y minimale acceptable de la translation. « maximum » correspond à la coordonnée y maximale acceptable de la translation. Si « enabled » est vrai, le glissement vertical est autorisé.

Le signal « activeValueChanged » est émis lorsque « activeValue » change, afin de fournir l’incrément correspondant à cette modification. Ceci est destiné à ajuster de manière incrémentielle une propriété via plusieurs gestionnaires.

import QtQuick

Rectangle {
    width: 100; height: 100
    color: "lightsteelblue"; antialiasing: true

    PinchHandler {
        id: handler
        target: null
        xAxis.onActiveValueChanged: (delta) => parent.radius -= delta
        yAxis.onActiveValueChanged: (delta) => parent.border.width += delta
        rotationAxis.onActiveValueChanged: (delta) => parent.rotation += delta // add
        scaleAxis.onActiveValueChanged: (delta) => parent.scale *= delta // multiply
    }

    WheelHandler {
        acceptedModifiers: Qt.NoModifier
        property: "rotation"
    }

    WheelHandler {
        acceptedModifiers: Qt.ControlModifier
        property: "scale"
    }
}

Documentation sur les signaux

canceled(eventPoint point)

Si ce gestionnaire a déjà saisi l'point donné, ce signal est émis lorsqu'un autre gestionnaire de pointeur ou un autre élément lui vole la saisie.

grabChanged(PointerDevice::GrabTransition transition, eventPoint point)

Ce signal est émis lorsque le « grab » a subi une modification pertinente pour ce gestionnaire.

Le verbe « transition » indique ce qui s'est passé. L'objet « point » correspond au point qui a été sélectionné ou désélectionné.

Les valeurs valides pour « transition » sont :

rotationChanged(qreal delta)

Le signal « rotationChanged » est émis lorsque la valeur de « activeRotation » (et donc celle de « persistentRotation ») change. La valeur de « delta » correspond à la variation additive de la rotation. Par exemple, si l'utilisateur déplace ses doigts pour modifier la distance de pincement, de sorte que la valeur de « activeRotation » passe de 10 à 30 degrés, le signal « rotationChanged(20) » sera émis. Vous pouvez utiliser ce signal pour modifier progressivement la rotation d'un élément :

import QtQuick

Rectangle {
    width: 100; height: 100
    color: "lightsteelblue"

    PinchHandler {
        id: handler
        target: null
        onRotationChanged: (delta) => parent.rotation += delta // add
        onScaleChanged: (delta) => parent.scale *= delta // multiply
    }
}

scaleChanged(qreal delta)

Le signal « scaleChanged » est émis lorsque la valeur de « activeScale » (et donc « persistentScale ») change. La valeur « delta » indique le facteur de modification de l’échelle. Par exemple, si l’utilisateur déplace ses doigts pour modifier la distance de pincement de sorte que la valeur de « activeScale » passe de 2 à 2,5, le signal « scaleChanged(1.25) » sera émis. Vous pouvez utiliser ce signal pour modifier progressivement l’échelle d’un élément :

import QtQuick

Rectangle {
    width: 100; height: 100
    color: "lightsteelblue"

    PinchHandler {
        id: handler
        target: null
        onRotationChanged: (delta) => parent.rotation += delta // add
        onScaleChanged: (delta) => parent.scale *= delta // multiply
    }
}

translationChanged(QVector2D delta)

Le signal « translationChanged » est émis lorsque la propriété « activeTranslation » (et donc « persistentTranslation ») change. Le vecteur « delta » indique la variation de la translation. Vous pouvez l’utiliser pour modifier progressivement la position d’un élément :

import QtQuick

Window {
    width: 320; height: 240
    visible: true
    title: handler.persistentRotation.toFixed(1) + "° " +
           handler.persistentTranslation.x.toFixed(1) + ", " +
           handler.persistentTranslation.y.toFixed(1) + " " +
           (handler.persistentScale * 100).toFixed(1) + "%"

    PinchHandler {
        id: handler
        target: null
        persistentScale: 0.25
        onTranslationChanged: (delta) => {
            image.x -= delta.x
            image.y -= delta.y
        }
    }

    Image {
        id: image
        source: "images/album-cover.jpg"
        scale: handler.persistentScale
        x: -600; y: -450
    }
}