PointHandler QML Type

Gestionnaire permettant de réagir à un seul point de contact. En savoir plus…

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

Propriétés

• acceptedButtons : flags
• acceptedDevices : flags
• acceptedModifiers : flags
• acceptedPointerTypes : flags
• active : bool
• cursorShape : Qt::CursorShape
• enabled : bool
• grabPermissions : flags
• margin : real
• parent : Item
• point : handlerPoint
• target : real

Signaux

• canceled(eventPoint point)
• grabChanged(PointerDevice::GrabTransition transition, eventPoint point)

Description détaillée

PointHandler peut être utilisé pour afficher des informations sur un point de contact ou la position de la souris, ou pour réagir de toute autre manière à des événements liés au pointeur.

Lorsqu’un événement de pression se produit, chaque instance de PointHandler choisit un point unique qui n’est pas encore « pris » à ce moment-là : si la pression se produit dans les limites de l’ PointerHandler::parent, si aucun PointHandler « frère » au sein de la même PointerHandler::parent n’a encore acquis de « passive grab » sur ce point, et si les autres contraintes telles que acceptedButtons, acceptedDevices, etc. sont satisfaites, ce point est éligible et le PointHandler acquiert alors un « passive grab ». De cette manière, l’ PointerHandler::parent agit comme un groupe exclusif : il peut y avoir plusieurs instances de PointHandler, et l’ensemble des points de contact enfoncés sera réparti entre elles. Chaque PointHandler qui a choisi un point à suivre dispose d’une propriété « active » true. Il continue alors à suivre le point qu’il a choisi jusqu’à ce que celui-ci soit relâché : les propriétés de l’ point seront mises à jour en temps réel. Tout « Item » peut se lier à ces propriétés et ainsi suivre les mouvements du point.

En n’étant qu’un « grabber » passif, il a la capacité de garder une surveillance indépendante de tous les mouvements. La saisie passive ne peut être ni volée ni remplacée, même lorsque d’autres gestes sont détectés et que des saisies exclusives se produisent.

Si votre objectif est la surveillance orthogonale des points d’événement, une ancienne alternative était ` QObject::installEventFilter()`, mais cela n’a jamais été une fonctionnalité intégrée d’ QtQuick: cela nécessite du code C++, tel qu’une sous-classe de ` QQuickItem `. PointHandler est plus efficace que cela, car seuls les événements de pointeur lui seront transmis, au cours de la transmission normale des événements dans QQuickWindow; alors qu’un filtre d’événements doit filtrer tous les QEvents de tous types, et se positionne ainsi comme un goulot d’étranglement potentiel dans la transmission des événements.

Un cas d’utilisation possible consiste à ajouter ce gestionnaire à un `Item` transparent situé au-dessus du reste de la scène (en lui attribuant une valeur ` z ` élevée), de sorte que lorsqu’un point est fraîchement enfoncé, l’événement soit d’abord transmis à cet `Item` et à ses gestionnaires, ce qui permet d’effectuer la saisie passive le plus tôt possible. Un tel élément (comme une vitre recouvrant l’ensemble de l’interface utilisateur) peut servir de parent pratique à d’autres éléments qui affichent le type de retour réactif devant toujours rester au premier plan ; de même, il peut servir de parent à des fenêtres contextuelles, des popovers, des boîtes de dialogue, etc. S’il est utilisé de cette manière, il peut être utile que votre fichier main.cpp utilise la fonction ` QQmlContext::setContextProperty()` pour rendre la « vitre » accessible par son ID à l’ensemble de l’interface utilisateur, afin que d’autres éléments et gestionnaires de points puissent lui être rattachés.

import QtQuick

Window {
    width: 480
    height: 320
    visible: true

    Item {
        id: glassPane
        z: 10000
        anchors.fill: parent

        PointHandler {
            id: handler
            acceptedDevices: PointerDevice.TouchScreen | PointerDevice.TouchPad
            target: Rectangle {
                parent: glassPane
                color: "red"
                visible: handler.active
                x: handler.point.position.x - width / 2
                y: handler.point.position.y - height / 2
                width: 20; height: width; radius: width / 2
            }
        }
    }
}

Comme tous les gestionnaires d’entrée, un PointHandler dispose d’une propriété ` target `, qui peut servir d’emplacement pratique pour y placer un élément de suivi de point ; toutefois, le PointHandler ne manipulera en aucun cas automatiquement l’élément ` target `. Vous devez utiliser des liaisons pour le faire réagir à l’événement ` point`.

Voir également MultiPointTouchArea, HoverHandler et Qt Quick Exemples - Gestionnaires de pointeur.

Documentation des propriétés

acceptedButtons : flags

Les boutons de la souris pouvant activer cette PointHandler.

Par défaut, cette propriété est définie sur Qt.LeftButton. Elle peut être définie sur une combinaison « OU » de boutons de souris et ignorera les événements au cours desquels d’autres boutons sont enfoncés ou maintenus enfoncés. Si elle est définie sur Qt.NoButton, cela signifie qu’elle ne tient aucun compte des boutons et ignore les événements de souris synthétiques provenant de tout périphérique pour lequel elle gère déjà un eventPoint authentique.

import QtQuick

Item {
    width: 480; height: 320

    Rectangle {
        color: handler.active ? "tomato" : "wheat"
        x: handler.point.position.x - width / 2
        y: handler.point.position.y - height / 2
        width: 20; height: width; radius: width / 2
    }

    PointHandler {
        id: handler
        acceptedButtons: Qt.MiddleButton | Qt.RightButton
    }
}

acceptedButtons: \c Qt.NoButton

pour éviter ce problème. Voir également Qt::AA_SynthesizeMouseForUnhandledTouchEvents et Qt::AA_SynthesizeMouseForUnhandledTabletEvents.

acceptedDevices : flags

Les types de périphériques de pointage pouvant déclencher cette PointHandler.

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 des périphériques non correspondants devices:

PointHandler {
    id: handler
    acceptedDevices: PointerDevice.TouchScreen | PointerDevice.TouchPad
    target: Rectangle {
        parent: glassPane
        color: "red"
        visible: handler.active
        x: handler.point.position.x - width / 2
        y: handler.point.position.y - height / 2
        width: 20; height: width; radius: width / 2
    }
}

acceptedModifiers : flags

Si cette propriété est définie, PointHandler exige que les touches de modification spécifiées soient enfoncées pour que le site PointerEvents réagisse à l'action, et les ignore dans le cas contraire.

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

Par exemple, un « Item » peut comporter deux gestionnaires, dont l’un n’est activé que si la touche de modification requise est enfoncée :

import QtQuick

Item {
    id: feedbackPane
    width: 480; height: 320

    PointHandler {
        id: control
        acceptedModifiers: Qt.ControlModifier
        cursorShape: Qt.PointingHandCursor
        target: Rectangle {
            parent: feedbackPane
            color: control.active ? "indianred" : "khaki"
            x: control.point.position.x - width / 2
            y: control.point.position.y - height / 2
            width: 20; height: width; radius: width / 2
        }
    }

    PointHandler {
        id: shift
        acceptedModifiers: Qt.ShiftModifier | Qt.MetaModifier
        cursorShape: Qt.CrossCursor
        target: Rectangle {
            parent: feedbackPane
            color: shift.active ? "darkslateblue" : "lightseagreen"
            x: shift.point.position.x - width / 2
            y: shift.point.position.y - height / 2
            width: 30; height: width; radius: width / 2
        }
    }
}

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.

Les modificateurs disponibles sont les suivants :

Voir également Qt::KeyboardModifier.

acceptedPointerTypes : flags

Les types de périphériques de pointage (doigt, stylet, gomme, etc.) pouvant activer cette PointHandler.

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 des périphériques non correspondants devices:

import QtQuick

Canvas {
    id: canvas
    width: 800
    height: 600
    antialiasing: true
    renderTarget: Canvas.FramebufferObject
    property var points: []
    onPaint: {
        if (points.length < 2)
            return
        var ctx = canvas.getContext('2d');
        ctx.save()
        ctx.strokeStyle = stylusHandler.active ? "blue" : "white"
        ctx.lineCap = "round"
        ctx.beginPath()
        ctx.moveTo(points[0].x, points[0].y)
        for (var i = 1; i < points.length; i++)
            ctx.lineTo(points[i].x, points[i].y)
        ctx.lineWidth = 3
        ctx.stroke()
        points = points.slice(points.length - 2, 1)
        ctx.restore()
    }

    PointHandler {
        id: stylusHandler
        acceptedPointerTypes: PointerDevice.Pen
        onPointChanged: {
            canvas.points.push(point.position)
            canvas.requestPaint()
        }
    }

    PointHandler {
        id: eraserHandler
        acceptedPointerTypes: PointerDevice.Eraser
        onPointChanged: {
            canvas.points.push(point.position)
            canvas.requestPaint()
        }
    }

    Rectangle {
        width: 10; height: 10
        color: stylusHandler.active ? "green" : eraserHandler.active ? "red" : "beige"
    }
}

La section « Qt Quick Examples - Pointer Handlers » (Exemples de gestionnaires de pointage - Gestionnaires de pointeurs) comprend un exemple plus complexe de dessin sur un Canvas à l’aide d’une tablette graphique.

active : bool [read-only]

Cela signifie qu'true est valable dès lors que les contraintes sont respectées et que PointHandler est en interaction. En d'autres termes, ses propriétés sont mises à jour en fonction des mouvements des eventPoints s qui satisfont aux contraintes.

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.CurseurVide
• 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 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.

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 sollicité pour 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 se disputent les mêmes points de contact.

margin : real

La marge au-delà des limites de l'élément « parent » à l'intérieur de laquelle une « eventPoint » peut activer ce gestionnaire.

La valeur par défaut est « 0 ».

import QtQuick

Item {
    width: 480; height: 320

    Rectangle {
        anchors.fill: handlingContainer
        anchors.margins: -handler.margin
        color: "beige"
    }

    Rectangle {
        id: handlingContainer
        width: 200; height: 200
        anchors.centerIn: parent
        border.color: "green"
        color: handler.active ? "lightsteelblue" : "khaki"

        Text {
            text: "X"
            x: handler.point.position.x - width / 2
            y: handler.point.position.y - height / 2
            visible: handler.active
        }

        PointHandler {
            id: handler
            margin: 30
        }
    }

}

parent : Item

L'objet ` Item `, qui correspond au périmètre d'action 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éattribué.

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

point : handlerPoint [read-only]

L'eventPoint t actuellement sélectionné. Lorsqu'aucun point n'est sélectionné, cet objet est réinitialisé à ses valeurs par défaut (toutes les coordonnées sont égales à 0).

target : real

Une propriété permettant de contenir facilement un `Item` à manipuler ou d’afficher un retour d’information. Contrairement à d’autres gestionnaires de pointeurs, ` PointHandler ` n’effectue aucune opération sur l’` target ` de lui-même : vous devez généralement créer des liaisons réactives vers des propriétés telles que ` SinglePointHandler::point ` et ` PointHandler::active`. Si vous déclarez une instance `Item` ici, vous devez définir explicitement son ` parent`, car ` PointHandler ` n’est pas un `Item`.

Par défaut, elle correspond à l'parent, c'est-à-dire l'Item au sein duquel le gestionnaire est déclaré.

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 :