PinchHandler QML Type

Gestionnaire pour les gestes de pincement. Plus d'informations...

• Liste de tous les membres, y compris les membres hérités
• les 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 glisser un élément de manière interactive. Comme les autres gestionnaires d'entrée, il est entièrement fonctionnel par défaut et manipule son target, qui est l'élément dans lequel il est déclaré.

import QtQuick

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

Il possède des propriétés permettant de restreindre les possibilités de déplacement, de rotation et de zoom.

S'il est déclaré dans un élément mais qu'on lui attribue un autre target, il traite les événements dans les limites de l'élément extérieur mais manipule l'élément target à la place :

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 est de définir target sur null et de 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 aussi PinchArea, QPointerEvent::pointCount(), QNativeGestureEvent::fingerCount(), et Qt Quick Exemples - Pointer Handlers.

Documentation sur les propriétés

acceptedDevices : flags

Types de dispositifs de pointage pouvant activer ce gestionnaire de pointeurs.

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

Par exemple, un contrôle peut répondre aux clics de souris et de stylet d'une certaine manière, et aux pressions sur l'écran tactile d'une autre manière, avec 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, il faudra appuyer sur les modificateurs de clavier donnés pour réagir aux événements de pointeur, et les ignorer dans le cas contraire.

Si la valeur de cette propriété est Qt.KeyboardModifierMask (valeur par défaut), PointerHandler ignore les touches de modification.

Par exemple, un site Item peut avoir deux gestionnaires du même type, dont l'un n'est activé que si les modificateurs de clavier requis sont enfoncés :

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

Si vous attribuez à acceptedModifiers 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 modificateurs disponibles sont les suivants :

Si vous avez besoin d'un comportement encore plus complexe que celui que l'on peut obtenir en combinant plusieurs gestionnaires avec plusieurs indicateurs de modification, 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.) qui peuvent 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 de devices qui ne correspondent pas.

Par exemple, un contrôle pourrait répondre aux clics de la souris, du toucher et du stylet d'une certaine manière, mais s'effacer s'il est tapé avec une gomme sur une tablette graphique, avec 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 true lorsque toutes les contraintes (en particulier minimumPointCount et maximumPointCount) sont satisfaites et que target, le cas échéant, est manipulé.

activeRotation : real [read-only]

La rotation du geste de pincement en degrés, avec des valeurs positives dans le sens des aiguilles d'une montre. Il s'agit de 0 lorsque le geste commence. Si target n'est pas nul, cette valeur sera automatiquement ajoutée à sa valeur rotation. Sinon, les liaisons peuvent être utilisées pour faire des choses 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 vaut 1,0 au début du geste, augmente au fur et à mesure que les points de contact s'écartent et diminue au fur et à mesure que les points de contact se rapprochent. Si target n'est pas nul, son scale sera automatiquement multiplié par cette valeur. Sinon, les liaisons peuvent être utilisées pour faire des choses arbitraires avec cette valeur.

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

activeTranslation : point [read-only]

La translation du groupe de points pendant l'exécution du geste de pincement. Elle est égale à 0, 0 au début du geste et augmente au fur et à mesure que les eventPoint(s) sont tirés vers le bas et vers la droite. À la fin du geste, elle reste inchangée et, au début du prochain geste de pincement, elle est à nouveau réinitialisée à 0, 0.

centroid : QtQuick::handlerPoint [read-only]

Un point situé exactement au milieu des points de contact actuellement pressés. Le site target sera tourné autour de ce point.

cursorShape : Qt::CursorShape

Cette propriété définit la forme du curseur qui apparaîtra lorsque la souris passera au-dessus de l'élément parent alors que active est true.

Les formes de curseur disponibles sont les suivantes :

• Qt.ArrowCursor
• Qt.UpArrowCursor
• Qt.CrossCursor
• Qt.WaitCursor
• Qt.IBeamCursor
• Qt.SizeVerCursor
• Qt.SizeHorCursor
• Qt.SizeBDiagCursor
• Qt.SizeFDiagCursor
• Qt.SizeAllCursor
• Qt.BlankCursor
• Qt.SplitVCursor
• Qt.SplitHCursor
• Qt.PointingHandCursor
• Qt.ForbiddenCursor
• Qt.WhatsThisCursor
• Qt.BusyCursor
• Qt.OpenHandCursor
• Qt.ClosedHandCursor
• Qt.DragCopyCursor
• Qt.DragMoveCursor
• Qt.DragLinkCursor

La valeur par défaut n'est pas définie, ce qui permet à l'élément cursor de parent d'apparaître. Cette propriété peut être ramenée à la même condition initiale en lui attribuant la valeur undefined.

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

dragThreshold : int

La distance en pixels sur laquelle l'utilisateur doit faire glisser une page eventPoint pour que cela soit considéré comme un geste de glissement.

La valeur par défaut dépend de la plate-forme et de la résolution de l'écran. Elle peut être ramenée à la valeur par défaut en lui attribuant la valeur undefined. Le comportement au 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'un PointerHandler est disabled, le gestionnaire sera également désactivé, même si la propriété enabled reste true.

grabPermissions : flags

Cette propriété spécifie les autorisations lorsque la logique de ce gestionnaire décide de prendre en charge la saisie exclusive, ou lorsqu'il lui est demandé d'approuver la prise en charge ou l'annulation de la saisie par un autre gestionnaire.

La valeur par défaut est PointerHandler.CanTakeOverFromItems | PointerHandler.CanTakeOverFromHandlersOfDifferentType | PointerHandler.ApprovesTakeOverByAnything, ce qui permet la plupart des scénarios de prise en charge mais évite, par exemple, que deux PinchHandler ne se disputent les mêmes points de contact.

margin : real

La marge au-delà des limites de l'élément parent dans laquelle un eventPoint peut activer ce gestionnaire. Par exemple, sur un site PinchHandler où le site target est également le site parent, il est utile de fixer cette distance à au moins la moitié de la largeur du doigt d'un utilisateur typique, de sorte que si le site parent a été réduit à une taille très petite, le geste de pincement reste possible. Par ailleurs, si un bouton basé sur TapHandler est placé près du bord de l'écran, il peut être utilisé pour respecter la loi de Fitts : réagir aux clics de souris sur le bord de l'écran même si le bouton est visuellement éloigné du bord de quelques pixels.

La valeur par défaut est 0.

parent : Item

Le Item qui est la portée du gestionnaire ; l'élément dans lequel il a été déclaré. Le gestionnaire traitera les événements au nom de cet élément, 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'élément. Initialement, target() est le même, mais il peut être réaffecté.

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

persistentRotation : real

La rotation à appliquer à l'adresse target si elle n'est pas nulle. Sinon, des liens peuvent être utilisés pour faire des choses arbitraires avec cette valeur. Pendant l'exécution du geste de pincement, activeRotation est continuellement ajouté ; après la fin du geste, il reste le même ; et lorsque le prochain geste de pincement commence, il commence à être modifié par activeRotation à nouveau.

Il est possible de définir cette propriété afin de synchroniser la rotation de la 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 défini sur le site target s'il n'est pas nul. Sinon, des liens peuvent être utilisés pour faire des choses arbitraires avec cette valeur. Pendant que le geste de pincement est effectué, il est continuellement multiplié par activeScale; après la fin du geste, il reste le même ; et lorsque le prochain geste de pincement commence, il commence à être multiplié par activeScale à nouveau.

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

La traduction à appliquer à target s'il ne s'agit pas de null. Sinon, les liaisons peuvent être utilisées pour faire des choses arbitraires avec cette valeur. Pendant l'exécution du geste de pincement, activeTranslation est continuellement ajouté ; après la fin du geste, il reste inchangé.

Il est possible de définir cette propriété afin de synchroniser la traduction de base avec une traduction 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 contrôle les contraintes de réglage de rotation de l'élément target en fonction de la rotation du groupe de points de contact.

minimum est la rotation minimale acceptable. maximum est la rotation maximale acceptable. Si enabled est vrai, 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 par lequel il a changé. Cela permet d'ajuster progressivement une propriété par l'intermédiaire de 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 contrôle les contraintes de réglage de scale de l'élément target en fonction de la distance entre les points de contact.

minimum est l'échelle minimale acceptable. maximum est l'échelle maximale acceptable. Si enabled est vrai, 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 le changement incrémental. Cela permet d'ajuster progressivement une propriété par l'intermédiaire de 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 manipulera.

Par défaut, il est identique à parent, l'élément dans lequel le gestionnaire est déclaré. Cependant, il peut parfois être utile de définir la cible sur un élément différent, afin de gérer des événements dans un élément mais d'en manipuler un autre ; ou de null, pour désactiver le comportement par défaut et faire quelque chose d'autre à la place.

xAxis group

xAxis contrôle les contraintes de translation horizontale 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 déplacement horizontal est autorisé.

Le signal activeValueChanged est émis lorsque activeValue change, afin de fournir l'incrément par lequel il a changé. Cela permet d'ajuster progressivement une propriété par l'intermédiaire de 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 contrôle les contraintes de translation verticale de l'élément target.

minimum est la coordonnée y minimale acceptable de la translation. maximum est la coordonnée y maximale acceptable de la translation. Si enabled est vrai, le déplacement vertical est autorisé.

Le signal activeValueChanged est émis lorsque activeValue change, afin de fournir l'incrément par lequel il a changé. Cela permet d'ajuster progressivement une propriété par l'intermédiaire de 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'objet donné point, ce signal est émis lorsque la saisie est volée par un autre gestionnaire de pointeurs ou un autre objet.

grabChanged(PointerDevice::GrabTransition transition, eventPoint point)

Ce signal est émis lorsque le grab a changé d'une manière ou d'une autre, ce qui est pertinent pour ce gestionnaire.

Le transition (verbe) indique ce qui s'est passé. Le point (objet) est le point qui a été saisi ou désaisi.

Les valeurs valides pour transition sont les suivantes

rotationChanged(qreal delta)

Le signal rotationChanged est émis lorsque activeRotation (et donc persistentRotation) change. La valeur delta indique le changement additif de la rotation. Par exemple, si l'utilisateur déplace ses doigts pour modifier la distance de pincement de sorte que activeRotation passe de 10 à 30 degrés, le signal rotationChanged(20) sera émis. Vous pouvez l'utiliser 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 activeScale (et donc persistentScale) change. La valeur delta indique le changement d'échelle multiplicatif. Par exemple, si l'utilisateur déplace ses doigts pour modifier la distance de pincement de sorte que activeScale passe de 2 à 2,5, le signal scaleChanged(1.25) sera émis. Vous pouvez l'utiliser 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 activeTranslation (et donc persistentTranslation) change. Le vecteur delta donne le changement de 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
    }
}