TapHandler QML Type

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

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

Standardmäßig ist diese Eigenschaft auf PointerDevice.AllDevices eingestellt. Wenn Sie sie auf eine ODER-Kombination von Gerätetypen einstellen, werden Ereignisse von nicht übereinstimmenden 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")
   }
}

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.

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 ODER-Kombination von Gerätetypen setzen, werden Ereignisse von nicht übereinstimmenden devices ignoriert.

Beispielsweise könnte ein Steuerelement so eingerichtet werden, dass es auf Maus-, Touch- und Stylus-Klicks 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()
   }
}

Dies gilt für true, 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.

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.

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.

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

Bestimmt die Exklusivität der Signale singleTapped() und doubleTapped().

Diese Eigenschaft wurde in Qt 6.5 eingeführt.

Die räumliche Einschränkung für die Erkennung einer Tap- oder Longpress-Geste, zusätzlich zu der Einschränkung, 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 wird nicht inkrementiert. 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"
}

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

Diese Eigenschaft gibt die Berechtigungen an, wenn die Logik dieses Handlers entscheidet, den exklusiven Greifer zu übernehmen, oder wenn er von einem anderen Handler aufgefordert wird, die Übernahme oder den Abbruch des Greifens 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.

Die Zeit in Sekunden, die ein eventPoint gedrückt werden muss, um eine Long-Press-Geste auszulösen und das longPressed()-Signal auszusenden, wenn der Wert größer als 0 ist. Wird der Punkt vor diesem Zeitlimit losgelassen, kann ein Tap erkannt werden, wenn die gesturePolicy -Bedingung 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.

Die Spanne außerhalb der Grenzen des parent Elements, innerhalb derer ein eventPoint diesen Handler aktivieren kann. Bei einem PinchHandler, bei dem das target auch das parent ist, ist es zum Beispiel sinnvoll, diesen Wert auf einen Abstand von mindestens der halben Breite des Fingers eines typischen Benutzers zu setzen, 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 wird, 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.

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

Siehe auch target und QObject::parent().

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

Bleibt wahr, wenn die Maus oder der Berührungspunkt gedrückt wird, und jede Bewegung seit dem Drücken ist mit dem aktuellen gesturePolicy konform. Wenn die eventPoint losgelassen wird oder die Richtlinie verletzt wird, ändert sich pressed in false.

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

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

Das Element, das von diesem Handler bearbeitet wird.

Standardmäßig ist dies dasselbe wie parent, das Element, innerhalb dessen 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.

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 Frame aktualisiert, was das Rendern einer Animation ermöglicht, die den Fortschritt 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.

Wenn dieser Handler den angegebenen point bereits gegriffen hat, wird dieses Signal ausgegeben, wenn das Greifen durch einen anderen Pointer-Handler oder ein anderes Item gestohlen wird.

Dieses Signal wird ausgegeben, wenn das parent Item 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.

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:

Dieses Signal wird ausgegeben, wenn das Element parent länger als longPressThreshold gedrückt und gehalten wird. 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, wird das Signal longPressed zu dem Zeitpunkt ausgegeben, an dem timeHeld longPressThreshold überschreitet.

Dieses Signal wird ausgelöst, 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, erhöht sich tapCount. 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.

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

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 einer Zeitspanne von weniger als longPressThreshold 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)
    }
}