TapHandler QML Type

Handler for taps and clicks. More...

Properties

Signals

Detailed Description

\inheritsSinglePointHandler \inqmlmodule QtQuick \ingroup qtquick-input-handlers

TapHandler is a handler for taps on a touchscreen or clicks on a mouse.

Detection of a valid tap gesture depends on gesturePolicy. The default value is DragThreshold, which requires the press and release to be close together in both space and time. In this case, DragHandler is able to function using only a passive grab, and therefore does not interfere with event delivery to any other Items or Input Handlers. So the default gesturePolicy is useful when you want to modify behavior of an existing control or Item by adding a TapHandler with bindings and/or JavaScript callbacks.

Note that buttons (such as QPushButton) are often implemented not to care whether the press and release occur close together: if you press the button and then change your mind, you need to drag all the way off the edge of the button in order to cancel the click. For this use case, set the gesturePolicy to 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
     }
 }

For multi-tap gestures (double-tap, triple-tap etc.), the distance moved must not exceed QStyleHints::mouseDoubleClickDistance() with mouse and QStyleHints::touchDoubleTapDistance() with touch, and the time between taps must not exceed QStyleHints::mouseDoubleClickInterval().

See also MouseArea and Qt Quick Examples - Pointer Handlers.

Property Documentation

exclusiveSignals : enumeration

\since6.5

Determines the exclusivity of the singleTapped() and doubleTapped() signals.

ConstantDescription
NotExclusive(the default) singleTapped() and doubleTapped() are emitted immediately when the user taps once or twice, respectively.
SingleTapsingleTapped() is emitted immediately when the user taps once, and doubleTapped() is never emitted.
DoubleTapdoubleTapped() is emitted immediately when the user taps twice, and singleTapped() is never emitted.
(SingleTap | DoubleTap)Both signals are delayed until QStyleHints::mouseDoubleClickInterval(), such that either singleTapped() or doubleTapped() can be emitted, but not both. But if 3 or more taps occur within mouseDoubleClickInterval, neither signal is emitted.

Note: The remaining signals such as tapped() and tapCountChanged() are always emitted immediately, regardless of this property.


gesturePolicy : enumeration

The spatial constraint for a tap or long press gesture to be recognized, in addition to the constraint that the release must occur before longPressThreshold has elapsed. If these constraints are not satisfied, the tapped signal is not emitted, and tapCount is not incremented. If the spatial constraint is violated, pressed transitions immediately from true to false, regardless of the time held.

The gesturePolicy also affects grab behavior as described below.

ConstantDescription
TapHandler.DragThreshold

Grab on press: passive

(the default value) The eventPoint must not move significantly. If the mouse, finger or stylus moves past the system-wide drag threshold (QStyleHints::startDragDistance), the tap gesture is canceled, even if the device or finger is still pressed. This policy can be useful whenever TapHandler needs to cooperate with other input handlers (for example DragHandler) or event-handling Items (for example Qt Quick Controls), because in this case TapHandler will not take the exclusive grab, but merely a passive grab. That is, DragThreshold is especially useful to augment existing behavior: it reacts to tap/click/long-press even when another item or handler is already reacting, perhaps even in a different layer of the UI. The following snippet shows one TapHandler as used in one component; but if we stack up two instances of the component, you will see the handlers in both of them react simultaneously when a press occurs over both of them, because the passive grab does not stop event propagation:
 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.WithinBounds

Grab on press: exclusive

If the eventPoint leaves the bounds of the parent Item, the tap gesture is canceled. The TapHandler will take the exclusive grab on press, but will release the grab as soon as the boundary constraint is no longer satisfied.
 TapHandler {
     id: tapHandler
     gesturePolicy: TapHandler.WithinBounds
     onTapped: tapFlash.start()
 }
TapHandler.ReleaseWithinBounds

Grab on press: exclusive

At the time of release (the mouse button is released or the finger is lifted), if the eventPoint is outside the bounds of the parent Item, a tap gesture is not recognized. This corresponds to typical behavior for button widgets: you can cancel a click by dragging outside the button, and you can also change your mind by dragging back inside the button before release. Note that it's necessary for TapHandler to take the exclusive grab on press and retain it until release in order to detect this gesture.
 TapHandler {
     id: tapHandler
     gesturePolicy: TapHandler.ReleaseWithinBounds
     onTapped: tapFlash.start()
 }
TapHandler.DragWithinBounds

Grab on press: exclusive

On press, TapHandler takes the exclusive grab; after that, the eventPoint can be dragged within the bounds of the parent item, while the timeHeld property keeps counting, and the longPressed() signal will be emitted regardless of drag distance. However, like WithinBounds, if the point leaves the bounds, the tap gesture is canceled(), active() becomes false, and timeHeld stops counting. This is suitable for implementing press-drag-release components, such as menus, in which a single TapHandler detects press, timeHeld drives an "opening" animation, and then the user can drag to a menu item and release, while never leaving the bounds of the parent scene containing the menu. This value was added in Qt 6.3.
 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"
 }

The Qt Quick Examples - Pointer Handlers demonstrates some use cases for these.

Note: If you find that TapHandler is reacting in cases that conflict with some other behavior, the first thing you should try is to think about which gesturePolicy is appropriate. If you cannot fix it by changing gesturePolicy, some cases are better served by adjusting grabPermissions, either in this handler, or in another handler that should prevent TapHandler from reacting.


longPressThreshold : real

The time in seconds that an eventPoint must be pressed in order to trigger a long press gesture and emit the longPressed() signal. If the point is released before this time limit, a tap can be detected if the gesturePolicy constraint is satisfied. The default value is QStyleHints::mousePressAndHoldInterval() converted to seconds.


[read-only] pressed : bool

\readonly

Holds true whenever the mouse or touch point is pressed, and any movement since the press is compliant with the current gesturePolicy. When the eventPoint is released or the policy is violated, pressed will change to false.


[read-only] tapCount : int

\readonly

The number of taps which have occurred within the time and space constraints to be considered a single gesture. The counter is reset to 1 if the button changed. For example, to detect a triple-tap, you can write:

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

[read-only] timeHeld : real

\readonly

The amount of time in seconds that a pressed point has been held, without moving beyond the drag threshold. It will be updated at least once per frame rendered, which enables rendering an animation showing the progress towards an action which will be triggered by a long-press. It is also possible to trigger one of a series of actions depending on how long the press is held.

A value of less than zero means no point is being held within this handler's Item.

Note: If gesturePolicy is set to TapHandler.DragWithinBounds, timeHeld does not stop counting even when the pressed point is moved beyond the drag threshold, but only when the point leaves the parent item's bounds.


Signal Documentation

doubleTapped(eventPoint eventPoint, Qt::MouseButton button)

\since5.11

This signal is emitted when the parent Item is tapped twice within a short span of time (QStyleHints::mouseDoubleClickInterval()) and distance (QStyleHints::mouseDoubleClickDistance() or QStyleHints::touchDoubleTapDistance()). This signal always occurs after singleTapped, tapped, and tapCountChanged. The eventPoint signal parameter contains information from the release event about the point that was tapped, and button is the mouse button that was clicked, or NoButton on a touchscreen.

Note: The corresponding handler is onDoubleTapped.


longPressed()

This signal is emitted when the parent Item is pressed and held for a time period greater than longPressThreshold. That is, if you press and hold a touchpoint or button, while any movement does not exceed the drag threshold, then the longPressed signal will be emitted at the time that timeHeld exceeds longPressThreshold.

Note: The corresponding handler is onLongPressed.


singleTapped(eventPoint eventPoint, Qt::MouseButton button)

\since5.11

This signal is emitted when the parent Item is tapped once. After an amount of time greater than QStyleHints::mouseDoubleClickInterval, it can be tapped again; but if the time until the next tap is less, tapCount will increase. The eventPoint signal parameter contains information from the release event about the point that was tapped, and button is the mouse button that was clicked, or NoButton on a touchscreen.

Note: The corresponding handler is onSingleTapped.


tapCountChanged()

This signal is emitted when the parent Item is tapped once or more (within a specified time and distance span) and when the present tapCount differs from the previous tapCount.

Note: The corresponding handler is onTapCountChanged.


tapped(eventPoint eventPoint, Qt::MouseButton button)

This signal is emitted each time the parent Item is tapped.

That is, if you press and release a touchpoint or button within a time period less than longPressThreshold, while any movement does not exceed the drag threshold, then the tapped signal will be emitted at the time of release. The eventPoint signal parameter contains information from the release event about the point that was tapped, and button is the mouse button that was clicked, or NoButton on a 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)
     }
 }

Note: The corresponding handler is onTapped.