PointHandler QML Type

Handler zur Reaktion auf einen einzelnen Berührungspunkt. Mehr...

• Liste aller Mitglieder, einschließlich geerbter Mitglieder

Eigenschaften

• 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

Signale

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

Ausführliche Beschreibung

PointHandler kann verwendet werden, um Rückmeldungen zu einem Berührungspunkt oder zur Mausposition anzuzeigen oder anderweitig auf Zeigerereignisse zu reagieren.

Wenn ein Druckereignis auftritt, wählt jede Instanz von PointHandler einen einzelnen Punkt aus, der zu diesem Zeitpunkt noch nicht „belegt“ ist: Wenn der Druck innerhalb der Grenzen des „ PointerHandler::parent “ erfolgt und kein gleichrangiger PointHandler innerhalb desselben „ PointerHandler::parent “ diesen Punkt bereits passiv belegt hat und wenn die anderen Einschränkungen wie „ acceptedButtons “, „ acceptedDevices “ usw. erfüllt sind, ist der Punkt zulässig, und der PointHandler belegt ihn dann passiv. Auf diese Weise verhält sich „ PointerHandler::parent “ wie eine exklusive Gruppe: Es kann mehrere Instanzen von „PointHandler“ geben, und die Menge der gedrückten Berührungspunkte wird unter ihnen verteilt. Jeder „PointHandler“, der einen zu verfolgenden Punkt ausgewählt hat, verfügt über die Eigenschaft „ active “ true. Er verfolgt dann den ausgewählten Punkt bis zum Loslassen weiter: Die Eigenschaften des „ point “ werden auf dem neuesten Stand gehalten. Jedes Item kann sich an diese Eigenschaften binden und so den Bewegungen des Punktes folgen.

Da es sich lediglich um einen passiven „Grabber“ handelt, ist es in der Lage, alle Bewegungen unabhängig voneinander zu überwachen. Der passive „Grab“ kann nicht gestohlen oder überschrieben werden, selbst wenn andere Gesten erkannt werden und exklusive „Grabs“ auftreten.

Wenn Ihr Ziel die orthogonale Überwachung von Ereignispunkten ist, gab es früher als Alternative die Funktion „ QObject::installEventFilter()“, doch diese war nie eine integrierte Funktion von „ QtQuick “: Sie erfordert etwas C++-Code, wie beispielsweise eine Unterklasse von „ QQuickItem “. „PointHandler“ ist effizienter als diese Vorgehensweise, da im Rahmen der normalen Ereignisübermittlung in „ QQuickWindow “ nur Zeigerereignisse an ihn übermittelt werden; ein Ereignisfilter hingegen muss alle QEvents aller Typen filtern und stellt somit einen potenziellen Engpass bei der Ereignisübermittlung dar.

Ein möglicher Anwendungsfall besteht darin, diesen Handler einem transparenten „Item“ hinzuzufügen, das sich über dem Rest der Szene befindet (durch einen hohen „ z “-Wert), sodass bei einem neuen Klick dieses „Item“ und seine Handler zuerst mit dem Ereignis versorgt werden, was die Möglichkeit bietet, das passive Greifen so früh wie möglich zu übernehmen. Ein solches Item (wie beispielsweise eine Glasscheibe über der gesamten Benutzeroberfläche) kann ein praktisches übergeordnetes Element für andere Items sein, die reaktive Rückmeldungen visualisieren, die stets im Vordergrund angezeigt werden müssen; ebenso kann es als übergeordnetes Element für Popups, Popovers, Dialoge und dergleichen dienen. Wenn es auf diese Weise verwendet wird, kann es für Ihre `main.cpp` hilfreich sein, ` QQmlContext::setContextProperty()` zu verwenden, um die „Glasscheibe“ für die gesamte Benutzeroberfläche über ihre ID zugänglich zu machen, sodass andere Elemente und `PointHandler` ihr als übergeordnetes Element zugewiesen werden können.

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

Wie alle Eingabe-Handler verfügt ein „PointHandler“ über eine „ target “-Eigenschaft, die als praktischer Ort zum Platzieren eines „Point-Tracking“-Elements genutzt werden kann; der „PointHandler“ manipuliert das „ target “-Element jedoch nicht automatisch in irgendeiner Weise. Sie müssen Bindungen verwenden, damit er auf die „ point “ reagiert.

Siehe auch MultiPointTouchArea, HoverHandler und Qt Quick Beispiele – Zeiger-Handler.

Dokumentation zu den Eigenschaften

acceptedButtons : flags

Die Maustasten, mit denen diese Funktion aktiviert werden kann: PointHandler.

Standardmäßig ist diese Eigenschaft auf „ Qt.LeftButton “ gesetzt. Sie kann auf eine „OR“-Kombination von Maustasten gesetzt werden und ignoriert dann Ereignisse, bei denen andere Tasten gedrückt oder gehalten werden. Ist sie auf „ Qt.NoButton “ gesetzt, bedeutet dies, dass sie Tasten überhaupt nicht berücksichtigt und synthetische Mausereignisse ignoriert, die von einem Gerät stammen, für das sie bereits ein authentisches „ eventPoint “ verarbeitet.

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

, um dieses Problem zu vermeiden. Siehe auch Qt::AA_SynthesizeMouseForUnhandledTouchEvents und Qt::AA_SynthesizeMouseForUnhandledTabletEvents.

acceptedDevices : flags

Die Arten von Zeigegeräten, die diese Funktion aktivieren können: PointHandler.

Standardmäßig ist diese Eigenschaft auf „ PointerDevice.AllDevices “ gesetzt. Wenn Sie sie auf eine „ODER“-Kombination von Gerätetypen setzen, werden Ereignisse von nicht übereinstimmenden devices ignoriert:

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

Wenn diese Eigenschaft gesetzt ist, verlangt „ PointHandler “, dass die angegebenen Tastaturmodifikatortasten gedrückt werden, damit „ PointerEvents “ darauf reagiert; andernfalls ignoriert es diese.

Ist diese Eigenschaft auf „ Qt.KeyboardModifierMask “ gesetzt (Standardwert), ignoriert „ PointHandler “ die Modifikatortasten.

Beispielsweise könnte ein „ Item “ zwei Handler haben, von denen einer nur aktiviert wird, wenn die erforderliche Tastenkombination gedrückt wird:

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

Wenn Sie „ acceptedModifiers “ auf eine „ODER“-Kombination von Modifikatortasten setzen, bedeutet dies, dass alle diese Modifikatortasten gedrückt werden müssen, um den Handler zu aktivieren.

Die verfügbaren Modifikatoren sind wie folgt:

Siehe auch Qt::KeyboardModifier.

acceptedPointerTypes : flags

Die Arten von Zeigeinstrumenten (Finger, Stift, Radierer usw.), die diese Funktion aktivieren können: PointHandler.

Standardmäßig ist diese Eigenschaft auf „ PointerDevice.AllPointerTypes “ gesetzt. Wenn Sie sie auf eine OR-Kombination von Gerätetypen setzen, werden Ereignisse von nicht übereinstimmenden „ devices “ ignoriert:

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

Die „Qt Quick Examples – Pointer Handlers“ enthalten ein komplexeres Beispiel für das Zeichnen auf einer „Canvas“-Oberfläche mit einem Grafiktablett.

active : bool [read-only]

Dies gilt unter true, wann immer die Nebenbedingungen erfüllt sind und dieses PointHandler reagiert. Das bedeutet, dass es seine Eigenschaften entsprechend den Bewegungen der eventPoints, die die Nebenbedingungen erfüllen, auf dem neuesten Stand hält.

cursorShape : Qt::CursorShape

Diese Eigenschaft legt die Cursorform fest, die angezeigt wird, sobald der Mauszeiger über das Element „ parent “ bewegt wird, während „ active “ auf „ true “ gesetzt ist.

Die verfügbaren Cursorformen sind:

• Qt.ArrowCursor
• Qt.UpArrowCursor
• Qt.CrossCursor
• Qt.WaitCursor
• Qt.IBeamCursor
• Qt.Größe-Vertikal-Cursor
• Qt.SizeHorCursor
• Qt.SizeBDiagCursor
• Qt.SizeFDiagCursor
• Qt.SizeAllCursor
• Qt.LeererCursor
• Qt.SplitVCursor
• Qt.SplitHCursor
• Qt.ZeigenderFinger-Cursor
• Qt.VerbotenerCursor
• Qt.Was-ist-das-Cursor
• Qt.Beschäftigt-Cursor
• Qt.Cursor mit offener Hand
• Qt.Geschlossene-Hand-Cursor
• Qt.Ziehen-Kopieren-Cursor
• Qt.Ziehen-Verschieben-Cursor
• Qt.DragLinkCursor

Der Standardwert ist nicht festgelegt, wodurch das Element „ cursor “ von „ parent “ angezeigt wird. Diese Eigenschaft kann auf den ursprünglichen Zustand zurückgesetzt werden, indem sie auf „undefined“ gesetzt wird.

Siehe auch „ Qt::CursorShape“ , „ QQuickItem::cursor()“ und „ HoverHandler::cursorShape “.

enabled : bool

Wenn ein PointerHandler deaktiviert ist, lehnt er alle Ereignisse ab und es werden keine Signale ausgegeben.

Wenn bei einem „ PointerHandler “ die Eigenschaft „ parent “ auf „ disabled “ gesetzt ist, wird der Handler ebenfalls effektiv deaktiviert, selbst wenn die Eigenschaft „ enabled “ weiterhin auf „ true “ gesetzt ist.

grabPermissions : flags

Diese Eigenschaft legt die Berechtigungen fest, wenn die Logik dieses Handlers beschließt, die exklusive Grab-Kontrolle zu übernehmen, oder wenn er aufgefordert wird, die Übernahme oder Aufhebung der Grab-Kontrolle durch einen anderen Handler zu genehmigen.

Die Standardeinstellung ist „ PointerHandler.CanTakeOverFromItems | PointerHandler.CanTakeOverFromHandlersOfDifferentType | PointerHandler.ApprovesTakeOverByAnything “, was die meisten Übernahme-Szenarien zulässt, aber beispielsweise verhindert, dass sich zwei „PinchHandler“ um dieselben Berührungspunkte streiten.

margin : real

Der Randbereich außerhalb der Grenzen des Elements „ parent “, innerhalb dessen ein „ eventPoint “ diesen Handler aktivieren kann.

Der Standardwert ist „ 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

Die „ Item “, die den Geltungsbereich des Handlers darstellt; das „Item“, in dem er deklariert wurde. Der Handler verarbeitet Ereignisse im Namen dieses „Item“, was bedeutet, dass ein Zeigerereignis relevant ist, wenn mindestens eine seiner „ eventPoints “ innerhalb des „Item“ auftritt. Anfangs ist „ target() “ identisch, kann jedoch neu zugewiesen werden.

Siehe auch „ target “ und „ QObject::parent()“.

point : handlerPoint [read-only]

Das Objekt „ eventPoint “, das derzeit bearbeitet wird. Wenn gerade kein Punkt bearbeitet wird, wird dieses Objekt auf die Standardwerte zurückgesetzt (alle Koordinaten sind 0).

target : real

Eine Eigenschaft, die bequem ein zu bearbeitendes Element aufnehmen oder Feedback anzeigen kann. Im Gegensatz zu anderen Zeiger-Handlern führt „ PointHandler “ von sich aus keine Aktionen mit dem „ target “ durch: In der Regel müssen Sie reaktive Bindungen zu Eigenschaften wie „ SinglePointHandler::point “ und „ PointHandler::active “ erstellen. Wenn Sie hier eine „Item“-Instanz deklarieren, müssen Sie deren „ parent “ explizit festlegen, da „ PointHandler “ kein „Item“ ist.

Standardmäßig entspricht dies dem „ parent “, also dem „Item“, in dem der Handler deklariert ist.

Signal-Dokumentation

canceled(eventPoint point)

Wenn dieser Handler den angegebenen „ point “ bereits ergriffen hat, wird dieses Signal ausgelöst, sobald die Ergreifung von einem anderen Pointer-Handler oder Item übernommen wird.

grabChanged(PointerDevice::GrabTransition transition, eventPoint point)

Dieses Signal wird ausgelöst, wenn sich der „Grab“ in einer Weise verändert hat, die für diesen Handler relevant ist.

Das Verb „ transition “ gibt an, was passiert ist. Das Objekt „ point “ ist der Punkt, der ergriffen oder freigegeben wurde.

Gültige Werte für „ transition “ sind: