TapHandler QML Type

Handler für Taps und Clicks. Mehr...

• Liste aller Mitglieder, einschließlich geerbter Mitglieder

Eigenschaften

• acceptedButtons : flags
• acceptedDevices : flags
• acceptedModifiers : flags
• acceptedPointerTypes : flags
• active : bool
• cursorShape : Qt::CursorShape
• dragThreshold : int
• enabled : bool
• exclusiveSignals : enumeration (since 6.5)
• gesturePolicy : enumeration
• grabPermissions : flags
• longPressThreshold : real
• margin : real
• parent : Item
• point : handlerPoint
• pressed : bool
• tapCount : int
• target : Item
• timeHeld : real

Signale

• canceled(eventPoint point)
• doubleTapped(eventPoint eventPoint, Qt::MouseButton button)
• grabChanged(PointerDevice::GrabTransition transition, eventPoint point)
• longPressed()
• singleTapped(eventPoint eventPoint, Qt::MouseButton button)
• tapCountChanged()
• tapped(eventPoint eventPoint, Qt::MouseButton button)

Detaillierte Beschreibung

TapHandler ist ein Handler für Tippen auf einem Touchscreen oder Klicken auf einer Maus.

Die Erkennung einer gültigen Tap-Geste hängt von gesturePolicy ab. Der Standardwert ist DragThreshold, was voraussetzt, dass das Drücken und Loslassen räumlich und zeitlich nahe beieinander liegen. In diesem Fall ist der TapHandler in der Lage, nur mit einem passiven Greifen zu arbeiten und beeinträchtigt daher nicht die Ereignisübermittlung an andere Elemente oder Eingabe-Handler. Die Standardeinstellung gesturePolicy ist also nützlich, wenn Sie das Verhalten eines vorhandenen Steuerelements oder Elements durch Hinzufügen eines TapHandlers mit Bindungen und/oder JavaScript-Callbacks ändern möchten.

Beachten Sie, dass Schaltflächen (wie z. B. QPushButton) oft so implementiert sind, dass es keine Rolle spielt, ob Drücken und Loslassen nahe beieinander liegen: Wenn Sie die Schaltfläche drücken und es sich dann anders überlegen, müssen Sie den Rand der Schaltfläche ganz wegziehen, um den Klick abzubrechen. Setzen Sie für diesen Anwendungsfall gesturePolicy auf TapHandler.ReleaseWithinBounds.

import QtQuick

Rectangle {
    id: button
    signal clicked
    property alias text: buttonLabel.text

    height: Math.max(Screen.pixelDensity * 7, buttonLabel.implicitHeight * 1.2)
    width: Math.max(Screen.pixelDensity * 11, buttonLabel.implicitWidth * 1.3)
    radius: 3
    property color dark: Qt.darker(palette.button, 1.3)
    gradient: Gradient {
        GradientStop { position: 0.0; color: tapHandler.pressed ? dark : palette.button }
        GradientStop { position: 1.0; color: dark }
    }

    TapHandler {
        id: tapHandler
        gesturePolicy: TapHandler.ReleaseWithinBounds
        onTapped: button.clicked()
    }

    Text {
        id: buttonLabel
        text: "Click Me"
        color: palette.buttonText
        anchors.centerIn: parent
    }
}

Bei Gesten mit mehrfachem Antippen (doppeltes Antippen, dreifaches Antippen usw.) darf die zurückgelegte Entfernung QStyleHints::mouseDoubleClickDistance() bei der Maus und QStyleHints::touchDoubleTapDistance() bei der Berührung nicht überschreiten, und die Zeit zwischen den Antippen darf QStyleHints::mouseDoubleClickInterval() nicht überschreiten.

Siehe auch MouseArea und Qt Quick Beispiele - Pointer Handlers.

Dokumentation der Eigenschaft

acceptedButtons : flags

Die Maustasten, die diesen Pointer-Handler aktivieren können.

Standardmäßig ist diese Eigenschaft auf Qt.LeftButton gesetzt. Sie kann auf eine ODER-Kombination von Maustasten gesetzt werden und ignoriert Ereignisse von anderen Tasten.

Zum Beispiel könnte ein Steuerelement so eingestellt werden, dass es auf Links- und Rechtsklicks auf unterschiedliche Weise reagiert, mit zwei Handlern:

Item {
    TapHandler {
        onTapped: console.log("left clicked")
    }
    TapHandler {
        acceptedButtons: Qt.RightButton
        onTapped: console.log("right clicked")
    }
}

acceptedDevices : flags

Die Typen von Zeigegeräten, die diesen Pointer-Handler aktivieren können.

Standardmäßig ist diese Eigenschaft auf PointerDevice.AllDevices gesetzt. Wenn Sie sie auf eine ODER-Kombination von Gerätetypen setzen, werden Ereignisse von nicht passenden Geräten ignoriert.

So kann ein Steuerelement beispielsweise mit zwei Handlern auf Maus- und Stiftklicks und auf Berührungen des Touchscreens reagieren:

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

acceptedModifiers : flags

Wenn diese Eigenschaft gesetzt ist, müssen die angegebenen Tastaturmodifikatoren gedrückt werden, um auf Zeigerereignisse zu reagieren, andernfalls werden sie ignoriert.

Wenn diese Eigenschaft auf Qt.KeyboardModifierMask (den Standardwert) gesetzt ist, ignoriert PointerHandler die Modifizierungstasten.

Ein Item könnte zum Beispiel zwei Handler desselben Typs haben, von denen einer nur aktiviert wird, wenn die erforderlichen Tastaturmodifikatoren gedrückt werden:

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

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

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

Die verfügbaren Modifikatoren sind wie folgt:

Wenn Sie ein noch komplexeres Verhalten benötigen, als es mit Kombinationen mehrerer Handler mit mehreren Modifier-Flags erreicht werden kann, können Sie die Modifier in JavaScript-Code überprüfen:

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

Siehe auch Qt::KeyboardModifier.

acceptedPointerTypes : flags

Die Typen von Zeigeinstrumenten (Finger, Stift, Radiergummi usw.), die diesen Pointer-Handler aktivieren können.

Standardmäßig ist diese Eigenschaft auf PointerDevice.AllPointerTypes eingestellt. Wenn Sie sie auf eine ODER-Kombination von Gerätetypen einstellen, werden Ereignisse von nicht übereinstimmenden devices ignoriert.

Beispielsweise könnte ein Steuerelement so eingerichtet werden, dass es auf Maus-, Touch- und Stiftklicks reagiert, sich aber selbst löscht, wenn es mit einem Radiergummi auf einem Grafiktablett angetippt wird, und zwar mit zwei Handlern:

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]

Dies gilt true immer dann, wenn dieser Input Handler die alleinige Verantwortung für die Übergabe eines oder mehrerer eventPoints übernommen hat, indem er erfolgreich einen exklusiven Zugriff auf diese Punkte genommen hat. Das bedeutet, dass er seine Eigenschaften entsprechend den Bewegungen dieser EventPoints auf dem neuesten Stand hält und seine target (falls vorhanden) aktiv manipuliert.

cursorShape : Qt::CursorShape

Diese Eigenschaft enthält die Cursorform, die immer dann erscheint, wenn der Mauszeiger über dem Element parent schwebt, während active true ist.

Die verfügbaren Cursorformen sind:

• 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

Der Standardwert ist nicht gesetzt, so dass das Element cursor von parent erscheinen kann. Diese Eigenschaft kann auf den gleichen Ausgangszustand zurückgesetzt werden, indem sie auf undefiniert gesetzt wird.

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

dragThreshold : int

Die Entfernung in Pixeln, die der Benutzer eine eventPoint ziehen muss, damit sie als Ziehgeste behandelt wird.

Der Standardwert hängt von der Plattform und der Bildschirmauflösung ab. Er kann auf den Standardwert zurückgesetzt werden, indem er auf undefiniert gesetzt wird. Das Verhalten, wenn eine Ziehgeste beginnt, variiert in verschiedenen Handlern.

enabled : bool

Wenn ein PointerHandler deaktiviert ist, werden alle Ereignisse zurückgewiesen und es werden keine Signale ausgesendet.

Wenn die parent von PointerHandler disabled ist, wird der Handler ebenfalls deaktiviert, auch wenn die enabled Eigenschaft true bleibt.

exclusiveSignals : enumeration [since 6.5]

Bestimmt die Ausschließlichkeit der Signale singleTapped() und doubleTapped().

Diese Eigenschaft wurde in Qt 6.5 eingeführt.

gesturePolicy : enumeration

Die räumliche Bedingung für die Erkennung eines Tippens oder langen Drückens, zusätzlich zu der Bedingung, dass das Loslassen vor dem Ablauf von longPressThreshold erfolgen muss. Wenn diese Bedingungen nicht erfüllt sind, wird das Signal tapped nicht ausgegeben und tapCount nicht erhöht. Wenn die räumliche Einschränkung verletzt wird, geht pressed sofort von true zu false über, unabhängig von der gehaltenen Zeit.

gesturePolicy beeinflusst auch das Greifverhalten wie unten beschrieben.

Item {
    width: 120; height: 80

    component Button : Rectangle {
        TapHandler {
            id: tapHandler
            gesturePolicy: TapHandler.DragThreshold // the default
            onTapped: tapFlash.start()
        }
    }

    Button { x: 10; y: 10 }
    Button { x: 30; y: 30 }
}

TapHandler {
    id: tapHandler
    gesturePolicy: TapHandler.WithinBounds
    onTapped: tapFlash.start()
}

TapHandler {
    id: tapHandler
    gesturePolicy: TapHandler.ReleaseWithinBounds
    onTapped: tapFlash.start()
}

TapHandler {
    id: menuPopupHandler
    gesturePolicy: TapHandler.DragWithinBounds
    onPressedChanged:
        if (pressed) {
            menu.x = point.position.x - menu.width / 2
            menu.y = point.position.y - menu.height / 2
        } else {
            feedback.text = menu.highlightedMenuItem
            selectFlash.start()
        }
    onCanceled: feedback.text = "canceled"
}

Die Qt Quick Examples - Pointer Handlers demonstriert einige Anwendungsfälle für diese.

grabPermissions : flags

Diese Eigenschaft gibt die Berechtigungen an, wenn die Logik dieses Handlers beschließt, den exklusiven Greifer zu übernehmen, oder wenn er von einem anderen Handler aufgefordert wird, die Übernahme oder den Abbruch des Greifers zu genehmigen.

Die Voreinstellung ist PointerHandler.CanTakeOverFromItems | PointerHandler.CanTakeOverFromHandlersOfDifferentType | PointerHandler.ApprovesTakeOverByAnything, was die meisten Übernahmeszenarien erlaubt, aber z.B. verhindert, dass zwei PinchHandler um dieselben Touchpoints kämpfen.

longPressThreshold : real

Die Zeit in Sekunden, die ein eventPoint gedrückt werden muss, um eine Geste des langen Drückens auszulösen und das Signal longPressed() auszusenden, wenn der Wert größer als 0 ist. Wird der Punkt vor dieser Zeitgrenze losgelassen, kann ein Tippen erkannt werden, wenn die Bedingung gesturePolicy erfüllt ist. Wenn longPressThreshold auf 0 steht, ist der Timer deaktiviert und das Signal wird nicht ausgegeben. Wenn longPressThreshold auf undefined gesetzt ist, wird stattdessen der Standardwert verwendet, der aus dieser Eigenschaft zurückgelesen werden kann.

Der Standardwert ist QStyleHints::mousePressAndHoldInterval(), umgerechnet in Sekunden.

margin : real

Der Rand außerhalb der Grenzen des parent Elements, innerhalb dessen ein eventPoint diesen Handler aktivieren kann. Bei einem PinchHandler, bei dem das target auch das parent ist, ist es beispielsweise sinnvoll, diesen Wert auf einen Abstand von mindestens der halben Breite des Fingers eines typischen Benutzers festzulegen, damit die Pinch-Geste auch dann noch möglich ist, wenn das parent auf eine sehr kleine Größe verkleinert wurde. Wenn eine TapHandler-basierte Schaltfläche in der Nähe des Bildschirmrands platziert ist, kann sie verwendet werden, um das Fitts'sche Gesetz zu erfüllen: Sie reagiert auf Mausklicks am Bildschirmrand, obwohl die Schaltfläche visuell einige Pixel vom Rand entfernt ist.

Der Standardwert ist 0.

parent : Item

Die Item, die der Anwendungsbereich des Handlers ist; das Item, in dem er deklariert wurde. Der Handler behandelt Ereignisse im Namen dieses Items, was bedeutet, dass ein Zeigerereignis relevant ist, wenn mindestens eines seiner eventPoints im Inneren des Items auftritt. Ursprünglich ist target() derselbe, aber er kann neu zugewiesen werden.

Siehe auch target und QObject::parent().

point : handlerPoint [read-only]

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

pressed : bool [read-only]

Hält true, wenn die Maus oder der Berührungspunkt gedrückt wird, und jede Bewegung seit dem Drücken ist mit der aktuellen gesturePolicy konform. Wenn die eventPoint losgelassen wird oder die Richtlinie verletzt wird, ändert sich "gedrückt" in "falsch".

tapCount : int [read-only]

Die Anzahl der Berührungen, die innerhalb der zeitlichen und räumlichen Beschränkungen als eine einzige Geste gelten. Der Zähler wird auf 1 zurückgesetzt, wenn die Taste gewechselt wird. Um zum Beispiel einen Dreifach-Tipp zu erkennen, können Sie schreiben:

Rectangle {
    width: 100; height: 30
    signal tripleTap
    TapHandler {
        acceptedButtons: Qt.AllButtons
        onTapped: if (tapCount == 3) tripleTap()
    }
}

target : Item

Das Element, das von diesem Handler bearbeitet wird.

Standardmäßig ist es dasselbe wie das parent, das Element, in dem der Handler deklariert ist. Manchmal kann es jedoch nützlich sein, das Ziel auf ein anderes Element zu setzen, um Ereignisse innerhalb eines Elements zu behandeln, aber ein anderes zu manipulieren; oder auf null, um das Standardverhalten zu deaktivieren und stattdessen etwas anderes zu tun.

timeHeld : real [read-only]

Die Zeitspanne in Sekunden, die ein gedrückter Punkt gehalten wurde, ohne den Schwellenwert für das Ziehen zu überschreiten. Sie wird mindestens einmal pro gerendertem Bild aktualisiert, so dass eine Animation gerendert werden kann, die den Fortschritt in Richtung einer Aktion zeigt, die durch einen langen Druck ausgelöst wird. Es ist auch möglich, eine Reihe von Aktionen auszulösen, je nachdem, wie lange die Taste gedrückt gehalten wird.

Ein Wert von weniger als Null bedeutet, dass kein Punkt innerhalb dieses Handlers Item gehalten wird.

Signal-Dokumentation

canceled(eventPoint point)

Wenn dieser Handler das angegebene point bereits gegrabbt hat, wird dieses Signal ausgegeben, wenn das Grab von einem anderen Pointer Handler oder Item gestohlen wird.

doubleTapped(eventPoint eventPoint, Qt::MouseButton button)

Dieses Signal wird ausgegeben, wenn das Element parent zweimal innerhalb einer kurzen Zeitspanne (QStyleHints::mouseDoubleClickInterval()) und Entfernung (QStyleHints::mouseDoubleClickDistance() oder QStyleHints::touchDoubleTapDistance()) angetippt wird. Dieses Signal tritt immer nach singleTapped, tapped und tapCountChanged auf. Der Signalparameter eventPoint enthält Informationen aus dem Release-Ereignis über den Punkt, der angetippt wurde, und button ist der mouse button, der angeklickt wurde, oder NoButton auf einem Touchscreen.

grabChanged(PointerDevice::GrabTransition transition, eventPoint point)

Dieses Signal wird ausgegeben, wenn sich der Greifer in irgendeiner Weise verändert hat, die für diesen Handler relevant ist.

Das transition (Verb) sagt, was passiert ist. Das point (Objekt) ist der Punkt, der gegriffen oder nicht gegriffen wurde.

Gültige Werte für transition sind:

longPressed()

Dieses Signal wird ausgegeben, wenn das Element parent gedrückt und für einen Zeitraum gehalten wird, der größer ist als longPressThreshold. Das heißt, wenn Sie einen Touchpoint oder eine Schaltfläche drücken und halten, während eine Bewegung den Schwellenwert für das Ziehen nicht überschreitet, dann wird das Signal longPressed zu dem Zeitpunkt ausgegeben, an dem timeHeld den Wert longPressThreshold überschreitet.

singleTapped(eventPoint eventPoint, Qt::MouseButton button)

Dieses Signal wird ausgesendet, wenn das Element parent einmal angetippt wird. Nach einer Zeitspanne, die größer als QStyleHints::mouseDoubleClickInterval ist, kann es erneut angetippt werden; wenn die Zeit bis zum nächsten Antippen jedoch kürzer ist, wird tapCount erhöht. Der Signalparameter eventPoint enthält Informationen aus dem Release-Ereignis über den Punkt, der angetippt wurde, und button ist der mouse button, der angeklickt wurde, oder NoButton auf einem Touchscreen.

tapCountChanged()

Dieses Signal wird ausgegeben, wenn das Element parent einmal oder mehrmals (innerhalb einer bestimmten Zeit- und Entfernungsspanne) angetippt wird und wenn sich das aktuelle tapCount vom vorherigen tapCount unterscheidet.

tapped(eventPoint eventPoint, Qt::MouseButton button)

Dieses Signal wird jedes Mal ausgegeben, wenn das parent Element angetippt wird.

Das heißt, wenn Sie einen Berührungspunkt oder eine Schaltfläche innerhalb eines Zeitraums, der kleiner als longPressThreshold ist, drücken und loslassen, während eine Bewegung den Schwellenwert für das Ziehen nicht überschreitet, wird das Signal tapped zum Zeitpunkt des Loslassens ausgegeben. Der Signalparameter eventPoint enthält Informationen aus dem Freigabeereignis über den Punkt, der angetippt wurde, und button ist der mouse button, der angeklickt wurde, oder NoButton auf einem Touchscreen.

import QtQuick

Rectangle {
    width: 100
    height: 100

    TapHandler {
        acceptedButtons: Qt.LeftButton | Qt.RightButton
        onTapped: (eventPoint, button)=> console.log("tapped", eventPoint.device.name,
                                             "button", button,
                                             "@", eventPoint.scenePosition)
    }
}