PointHandler QML Type

Gestionnaire permettant de réagir à un seul point de contact. Plus d'informations...

• 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 un retour d'information sur un point de contact ou sur la position de la souris, ou pour réagir d'une autre manière aux é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 PointerHandler::parent, et qu'aucun PointHandler frère dans le même PointerHandler::parent n'a encore acquis une prise passive sur ce point, et si les autres contraintes telles que acceptedButtons, acceptedDevices etc. sont satisfaites, il est éligible, et le PointHandler acquiert alors une prise passive. De cette manière, le site PointerHandler::parent agit comme un groupe exclusif : il peut y avoir plusieurs instances de PointHandler, et l'ensemble des points de contact pressés sera réparti entre elles. Chaque PointHandler qui a choisi un point à suivre a sa propriété active true . Il continue ensuite à suivre le point choisi jusqu'à sa libération : les propriétés de point seront maintenues à jour. N'importe quel élément peut se lier à ces propriétés et suivre ainsi les mouvements du point.

En n'étant qu'un attrapeur passif, il a la capacité de garder un contrôle indépendant sur tous les mouvements. La saisie passive ne peut pas être volée ou remplacée, même lorsque d'autres gestes sont détectés et que des saisies exclusives ont lieu.

Si votre objectif est la surveillance orthogonale des points d'événements, une alternative plus ancienne était QObject::installEventFilter(), mais cela n'a jamais été une fonctionnalité intégrée de QtQuick: il faut du code C++, comme une sous-classe de QQuickItem. PointHandler est plus efficace que cela, parce que seuls les événements de pointeurs lui seront livrés, au cours du processus normal de livraison d'événements dans QQuickWindow; alors qu'un filtre d'événements doit filtrer tous les QEvents de tous les types, et se place donc comme un goulot d'étranglement potentiel pour la livraison d'événements.

Un cas d'utilisation possible est d'ajouter ce gestionnaire à un élément transparent qui est au-dessus du reste de la scène (en ayant une valeur z élevée), de sorte que lorsqu'un point est fraîchement pressé, il sera livré à cet élément et à ses gestionnaires en premier, offrant l'opportunité de prendre la saisie passive le plus tôt possible. Un tel élément (comme une vitre sur l'ensemble de l'interface utilisateur) peut être un parent pratique pour d'autres éléments qui visualisent le type de retour d'information réactif qui doit toujours être en haut ; de même, il peut être le parent pour les popups, les popovers, les boîtes de dialogue, etc. S'il est utilisé de cette manière, il peut être utile que votre main.cpp utilise QQmlContext::setContextProperty() pour rendre la "vitre" accessible par ID à l'ensemble de l'interface utilisateur, de sorte que d'autres éléments et PointHandlers puissent lui être référencé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 possède une propriété target, qui peut être utilisée comme un endroit pratique pour placer un élément de suivi de point ; mais le PointHandler ne manipulera pas automatiquement l'élément target de quelque manière que ce soit. Vous devez utiliser des liaisons pour le faire réagir à l'élément point.

Voir aussi MultiPointTouchArea, HoverHandler, et Qt Quick Exemples - Gestionnaires de pointeurs.

Documentation sur les propriétés

acceptedButtons : flags

Les boutons de la souris qui peuvent 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 dans lesquels d'autres boutons sont pressés ou maintenus. Si elle est définie sur Qt.NoButton, cela signifie qu'elle ne se préoccupe pas du tout des boutons et qu'elle ignore les événements de souris synthétiques provenant d'un périphérique pour lequel elle gère déjà un événement authentique eventPoint.

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

Types de dispositifs de pointage pouvant activer cette propriété 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 dispositifs, elle ignorera les événements provenant de dispositifs ne correspondant pas à 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 du clavier soient enfoncées pour réagir à PointerEvents, sinon il les ignore.

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

Par exemple, un site Item peut avoir deux gestionnaires, dont l'un n'est activé que si le modificateur de clavier requis est enfoncé :

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 attribuez à acceptedModifiers une combinaison OU de touches de modification, cela signifie que tous ces modificateurs doivent être enfoncés pour activer le gestionnaire.

Les modificateurs disponibles sont les suivants :

Voir aussi Qt::KeyboardModifier.

acceptedPointerTypes : flags

Les types d'instruments de pointage (doigt, stylet, gomme, etc.) qui peuvent activer cette propriété 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 de 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"
    }
}

Le site Qt Quick Examples - Pointer Handlers comprend un exemple plus complexe pour dessiner sur un Canvas avec une tablette graphique.

active : bool [read-only]

Cela vaut pour true chaque fois que les contraintes sont satisfaites et que ce PointHandler réagit. Cela signifie qu'il met à jour ses propriétés en fonction des mouvements de eventPoints qui satisfont les contraintes.

cursorShape : Qt::CursorShape

Cette propriété définit la forme du curseur qui apparaîtra lorsque la souris survolera 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.

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

Marge au-delà des limites de l'élément parent dans laquelle 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

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().

point : handlerPoint [read-only]

Le site eventPoint en cours de traitement. Si aucun point n'est en cours de traitement, cet objet est réinitialisé aux valeurs par défaut (toutes les coordonnées sont à 0).

target : real

Une propriété qui peut commodément contenir un élément à manipuler ou pour montrer un retour d'information. Contrairement à d'autres gestionnaires de pointeurs, PointHandler ne fait rien de lui-même avec target: vous devez généralement créer des liaisons réactives avec des propriétés telles que SinglePointHandler::point et PointHandler::active. Si vous déclarez une instance d'élément ici, vous devez explicitement définir son parent, car PointHandler n'est pas un élément.

Par défaut, il est identique à parent, l'élément dans lequel le gestionnaire est déclaré.

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