TapHandler QML Type

Handler für Tippen und Klicken. 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)

Ausführliche Beschreibung

TapHandler ist ein Handler für Berührungen auf einem Touchscreen oder Klicks mit der Maus.

Die Erkennung einer gültigen Tippgeste hängt von „ gesturePolicy “ ab. Der Standardwert ist „DragThreshold“, was erfordert, dass das Drücken und Loslassen sowohl räumlich als auch zeitlich nahe beieinander liegen. In diesem Fall kann TapHandler ausschließlich mit einem passiven „Grab“ arbeiten und beeinträchtigt daher nicht die Ereignisübermittlung an andere Items oder Input-Handler. Daher ist der Standard gesturePolicy n nützlich, wenn Sie das Verhalten eines bestehenden Steuerelements oder Items 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 das Drücken und Loslassen zeitlich nahe beieinander liegen: Wenn Sie die Schaltfläche drücken und es sich dann anders überlegen, müssen Sie den Finger ganz bis zum Rand der Schaltfläche ziehen, um den Klick abzubrechen. Für diesen Anwendungsfall setzen Sie den „ 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 mehreren Antippvorgängen (Doppeltippen, Dreifachtippen usw.) darf die zurückgelegte Strecke bei Mausbedienung QStyleHints::mouseDoubleClickDistance() und bei Touch-Bedienung QStyleHints::touchDoubleTapDistance() nicht überschreiten, und der Zeitabstand zwischen den Antippvorgängen darf QStyleHints::mouseDoubleClickInterval() nicht überschreiten.

Siehe auch MouseArea und Qt Quick Beispiele – Zeiger-Handler.

Dokumentation zu den Eigenschaften

acceptedButtons : flags

Die Maustasten, mit denen dieser Zeiger-Handler aktiviert werden kann.

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

Beispielsweise könnte ein Steuerelement so gestaltet werden, dass es auf Links- und Rechtsklicks unterschiedlich reagiert, und zwar mithilfe von zwei Handlern:

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

acceptedDevices : flags

Die Arten 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 übereinstimmenden Geräten ignoriert.

Beispielsweise könnte ein Steuerelement so konfiguriert werden, dass es auf Maus- und Stiftklicks auf eine bestimmte Weise und auf Touchscreen-Tippen auf eine andere Weise reagiert, wobei zwei Handler verwendet werden:

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, damit auf Zeigerereignisse reagiert wird; andernfalls werden diese ignoriert.

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

Beispielsweise könnte ein „ Item “ zwei Handler desselben Typs haben, von denen einer nur aktiviert wird, wenn die erforderlichen Tastaturmodifikatoren gedrückt sind:

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 Modifikatortasten gedrückt sein 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 aus mehreren Handlern und mehreren Modifikator-Flags erreicht werden kann, können Sie die Modifikatoren im 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 Arten von Zeigeinstrumenten (Finger, Stift, Radiergummi usw.), die diesen Pointer-Handler aktivieren können.

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.

Beispielsweise könnte ein Steuerelement so gestaltet werden, dass es auf Maus-, Touch- und Stiftklicks in gewisser Weise reagiert, sich jedoch löscht, wenn es mit einem Radiergummi-Werkzeug auf einem Grafiktablett angetippt wird – 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 für true, sobald dieser Eingabe-Handler die alleinige Verantwortung für die Verarbeitung eines oder mehrerer eventPoints übernommen hat, indem er diese Punkte erfolgreich exklusiv erfasst hat. Das bedeutet, dass er seine Eigenschaften entsprechend den Bewegungen dieser eventPoints auf dem neuesten Stand hält und seine target (sofern vorhanden) aktiv bearbeitet.

cursorShape : Qt::CursorShape

Diese Eigenschaft legt die Cursorform fest, die angezeigt wird, wenn 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.Zieh-und-Kopiere-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 “.

dragThreshold : int

Die Entfernung in Pixeln, um die der Benutzer ein „ eventPoint “ ziehen muss, damit dies als Ziehgeste gewertet wird.

Der Standardwert hängt von der Plattform und der Bildschirmauflösung ab. Er kann auf den Standardwert zurückgesetzt werden, indem man ihn auf „undefined“ setzt. Das Verhalten beim Beginn einer Ziehgeste variiert je nach Handler.

enabled : bool

Wenn ein „ PointerHandler “ deaktiviert ist, werden alle Ereignisse abgelehnt und es werden keine Signale ausgegeben.

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

exclusiveSignals : enumeration [since 6.5]

Legt die Exklusivität der Signale „ singleTapped “ () und „ doubleTapped “ () fest.

Diese Eigenschaft wurde in Qt 6.5 eingeführt.

gesturePolicy : enumeration

Die räumliche Bedingung für die Erkennung einer Tipp- oder Langdruckgeste gilt zusätzlich zu der Bedingung, dass das Loslassen vor Ablauf von longPressThreshold erfolgen muss. Sind diese Bedingungen nicht erfüllt, wird das Signal „ tapped “ nicht ausgegeben und „ tapCount “ nicht erhöht. Wird die räumliche Bedingung verletzt, wechselt „ pressed “ sofort von „true“ auf „false“, unabhängig von der Haltezeit.

Die „ gesturePolicy “ beeinflusst zudem das Greifverhalten, wie im Folgenden 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 Beispiele unter „Qt Quick – Pointer Handlers“ veranschaulichen einige Anwendungsfälle hierfür.

grabPermissions : flags

Diese Eigenschaft legt die Berechtigungen fest, wenn die Logik dieses Handlers beschließt, die exklusive Grab-Kontrolle zu übernehmen, oder wenn sie 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.

longPressThreshold : real

Die Zeit in Sekunden, die ein „ eventPoint “ gedrückt gehalten werden muss, um eine Langdruckgeste auszulösen und das Signal „ longPressed()“ auszusenden, sofern der Wert größer als „ 0 “ ist. Wird der Punkt vor Ablauf dieser Zeitgrenze losgelassen, kann ein „Tap“ erkannt werden, sofern die Einschränkung „ gesturePolicy “ erfüllt ist. Wenn „ longPressThreshold “ auf „ 0 “ gesetzt ist, ist der Timer deaktiviert und das Signal wird nicht ausgelöst. Wenn „ longPressThreshold “ auf „ undefined “ gesetzt ist, wird stattdessen der Standardwert verwendet, der über diese Eigenschaft ausgelesen werden kann.

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

margin : real

Der Randbereich außerhalb der Grenzen des „ parent “-Elements, innerhalb dessen ein „ eventPoint “ diesen Handler aktivieren kann. Bei einer „ PinchHandler “, bei der die „ target “ gleichzeitig die „ parent “ ist, empfiehlt es sich beispielsweise, diesen Wert auf mindestens die Hälfte der Breite eines typischen Benutzerfingers festzulegen, damit die Pinch-Geste auch dann noch möglich ist, wenn die „ parent “ auf eine sehr kleine Größe verkleinert wurde. Oder wenn eine auf „ TapHandler “ basierende Schaltfläche nahe am Bildschirmrand platziert wird, kann dies zur Einhaltung des Fitts’schen Gesetzes genutzt werden: Mausklicks am Bildschirmrand werden auch dann registriert, wenn die Schaltfläche optisch um einige Pixel vom Rand entfernt ist.

Der Standardwert ist 0.

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 eines seiner „ eventPoints “ innerhalb des „Item“ auftritt. Anfänglich 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).

pressed : bool [read-only]

Gilt immer dann, wenn die Maus oder der Berührungspunkt gedrückt wird und jede Bewegung seit dem Drücken den aktuellen „ gesturePolicy “ entspricht. Wenn der „ eventPoint “ losgelassen wird oder die Richtlinie verletzt wird, wechselt „pressed“ zu „false“.

tapCount : int [read-only]

Die Anzahl der Tippen, die innerhalb der zeitlichen und räumlichen Grenzen stattgefunden haben, um als eine einzige Geste gewertet zu werden. Der Zähler wird auf 1 zurückgesetzt, wenn sich der Button geändert hat. Um beispielsweise ein dreifaches Tippen zu erkennen, kannst du Folgendes schreiben:

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

target : Item

Das Element, auf das dieser Handler einwirkt.

Standardmäßig entspricht es dem „ parent “, also dem Element, in dem der Handler deklariert ist. Manchmal kann es jedoch sinnvoll sein, das Ziel auf ein anderes Element festzulegen, um Ereignisse in einem Element zu verarbeiten, aber ein anderes Element zu bearbeiten; oder auf „ null “, um das Standardverhalten zu deaktivieren und stattdessen etwas anderes auszuführen.

timeHeld : real [read-only]

Die Zeit in Sekunden, die ein gedrückter Punkt gehalten wurde, ohne den Ziehschwellenwert zu überschreiten. Dieser Wert wird mindestens einmal pro gerendertem Frame aktualisiert, wodurch eine Animation gerendert werden kann, die den Fortschritt hin zu einer Aktion anzeigt, die durch einen langen Druck ausgelöst wird. Es ist auch möglich, je nach Dauer des Drucks eine von mehreren Aktionen auszulösen.

Ein Wert kleiner als Null bedeutet, dass kein Punkt innerhalb des „ Item “ dieses Handlers gehalten wird.

Signal-Dokumentation

canceled(eventPoint point)

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

doubleTapped(eventPoint eventPoint, Qt::MouseButton button)

Dieses Signal wird ausgelöst, wenn das Element „ parent “ innerhalb eines kurzen Zeitraums (QStyleHints::mouseDoubleClickInterval()) und einer kurzen Entfernung (QStyleHints::mouseDoubleClickDistance() oder QStyleHints::touchDoubleTapDistance()) zweimal 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 “, auf den geklickt wurde, bzw. „ NoButton “ auf einem Touchscreen.

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 geschehen ist. Das Objekt „ point “ ist der Punkt, der ergriffen oder freigegeben wurde.

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

longPressed()

Dieses Signal wird ausgelöst, wenn das Element „ parent “ länger als „ longPressThreshold “ gedrückt und gehalten wird. Das heißt: Wenn Sie einen Berührungspunkt oder eine Schaltfläche gedrückt halten und dabei die Bewegung den Schwellenwert für das Ziehen nicht überschreitet, wird das Signal „ longPressed “ in dem Moment ausgelöst, in dem „ timeHeld “ den Wert „ longPressThreshold “ überschreitet.

singleTapped(eventPoint eventPoint, Qt::MouseButton button)

Dieses Signal wird ausgelöst, wenn einmal auf das Element „ parent “ getippt wird. Nach Ablauf einer Zeit, die größer ist als „ QStyleHints::mouseDoubleClickInterval “, kann erneut darauf getippt werden; ist die Zeit bis zum nächsten Tippen jedoch kürzer, erhöht sich „ tapCount “. Der Signalparameter „ eventPoint “ enthält Informationen aus dem Release-Ereignis über den Punkt, auf den getippt wurde, und „ button “ ist das „ mouse button “, auf das geklickt wurde, bzw. „ NoButton “ auf einem Touchscreen.

tapCountChanged()

Dieses Signal wird ausgelöst, wenn das Element „ parent “ einmal oder mehrmals (innerhalb eines festgelegten Zeit- und Abstandsbereichs) angetippt wird und wenn sich der aktuelle Wert „ tapCount “ vom vorherigen Wert „ tapCount “ unterscheidet.

tapped(eventPoint eventPoint, Qt::MouseButton button)

Dieses Signal wird jedes Mal ausgelöst, wenn auf das Element „ parent “ getippt wird.

Das heißt: Wenn Sie einen Berührungspunkt oder eine Schaltfläche innerhalb eines Zeitraums drücken und loslassen, der kürzer ist als „ longPressThreshold “, und dabei keine Bewegung den Ziehschwellenwert überschreitet, wird das Signal „ tapped “ zum Zeitpunkt des Loslassens ausgelöst. Der Signalparameter „ eventPoint “ enthält Informationen aus dem Loslassereignis über den Punkt, der angetippt wurde, und „ button “ ist der „ mouse button “, der angeklickt wurde, bzw. „ 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)
    }
}