#include <qquicktaphandler_p.h>

Inheritance diagram for QQuickTapHandler:

Collaboration diagram for QQuickTapHandler:

Public Types
enum	GesturePolicy { DragThreshold , WithinBounds , ReleaseWithinBounds , DragWithinBounds }

enum	ExclusiveSignal { NotExclusive = 0 , SingleTap = 1 << 0 , DoubleTap = 1 << 1 }

Public Types inherited from QQuickPointerHandler
enum	GrabPermission { TakeOverForbidden = 0x0 , CanTakeOverFromHandlersOfSameType = 0x01 , CanTakeOverFromHandlersOfDifferentType = 0x02 , CanTakeOverFromItems = 0x04 , CanTakeOverFromAnything = 0x0F , ApprovesTakeOverByHandlersOfSameType = 0x10 , ApprovesTakeOverByHandlersOfDifferentType = 0x20 , ApprovesTakeOverByItems = 0x40 , ApprovesCancellation = 0x80 , ApprovesTakeOverByAnything = 0xF0 }

Signals
void	pressedChanged ()

void	tapCountChanged ()

void	timeHeldChanged ()

void	longPressThresholdChanged ()

void	gesturePolicyChanged ()

	Q_REVISION (6, 5) void exclusiveSignalsChanged()

void	tapped (QEventPoint eventPoint, Qt::MouseButton)

void	singleTapped (QEventPoint eventPoint, Qt::MouseButton)

void	doubleTapped (QEventPoint eventPoint, Qt::MouseButton)

void	longPressed ()

Signals inherited from QQuickSinglePointHandler
void	pointChanged ()

Signals inherited from QQuickPointerDeviceHandler
void	acceptedDevicesChanged ()

void	acceptedPointerTypesChanged ()

void	acceptedButtonsChanged ()

void	acceptedModifiersChanged ()

Signals inherited from QQuickPointerHandler
void	enabledChanged ()

void	activeChanged ()

void	targetChanged ()

void	marginChanged ()

	Q_REVISION (2, 15) void dragThresholdChanged()

void	grabChanged (QPointingDevice::GrabTransition transition, QEventPoint point)

void	grabPermissionChanged ()

void	canceled (QEventPoint point)

	Q_REVISION (6, 3) void parentChanged()

Signals inherited from QObject
void	destroyed (QObject *=nullptr)
	This signal is emitted immediately before the object obj is destroyed, after any instances of QPointer have been notified, and cannot be blocked.

void	objectNameChanged (const QString &objectName, QPrivateSignal)
	This signal is emitted after the object's name has been changed.

Public Member Functions
	QQuickTapHandler (QQuickItem *parent=nullptr)
	\qmltype TapHandler \nativetype QQuickTapHandler \inherits SinglePointHandler \inqmlmodule QtQuick

bool	isPressed () const

int	tapCount () const

qreal	timeHeld () const

qreal	longPressThreshold () const
	\qmlproperty real QtQuick::TapHandler::longPressThreshold

void	setLongPressThreshold (qreal longPressThreshold)

void	resetLongPressThreshold ()

GesturePolicy	gesturePolicy () const

void	setGesturePolicy (GesturePolicy gesturePolicy)
	\qmlproperty enumeration QtQuick::TapHandler::gesturePolicy

QQuickTapHandler::ExclusiveSignals	exclusiveSignals () const

void	setExclusiveSignals (QQuickTapHandler::ExclusiveSignals newexclusiveSignals)
	\qmlproperty enumeration QtQuick::TapHandler::exclusiveSignals

Public Member Functions inherited from QQuickSinglePointHandler
	QQuickSinglePointHandler (QQuickItem *parent=nullptr)
	\qmltype SinglePointHandler \qmlabstract \preliminary \nativetype QQuickSinglePointHandler \inherits PointerDeviceHandler \inqmlmodule QtQuick

QQuickHandlerPoint	point () const

Public Member Functions inherited from QQuickPointerDeviceHandler
	QQuickPointerDeviceHandler (QQuickItem *parent=nullptr)
	\qmltype PointerDeviceHandler \qmlabstract

QInputDevice::DeviceTypes	acceptedDevices () const

QPointingDevice::PointerTypes	acceptedPointerTypes () const

Qt::MouseButtons	acceptedButtons () const
	\qmlproperty flags QtQuick::PointerDeviceHandler::acceptedButtons

Qt::KeyboardModifiers	acceptedModifiers () const

Public Member Functions inherited from QQuickPointerHandler
	QQuickPointerHandler (QQuickItem *parent=nullptr)
	\qmltype PointerHandler \qmlabstract

	~QQuickPointerHandler ()

bool	enabled () const
	\qmlproperty bool QtQuick::PointerHandler::enabled

void	setEnabled (bool enabled)

bool	active () const
	\readonly \qmlproperty bool QtQuick::PointerHandler::active

QQuickItem *	target () const
	\qmlproperty Item QtQuick::PointerHandler::target

void	setTarget (QQuickItem *target)

QQuickItem *	parentItem () const
	\qmlproperty Item QtQuick::PointerHandler::parent

void	setParentItem (QQuickItem *p)

void	handlePointerEvent (QPointerEvent *event)

GrabPermissions	grabPermissions () const
	\qmlproperty flags QtQuick::PointerHandler::grabPermissions

void	setGrabPermissions (GrabPermissions grabPermissions)

qreal	margin () const
	\qmlproperty real PointerHandler::margin

void	setMargin (qreal pointDistanceThreshold)

int	dragThreshold () const
	\qmlproperty int PointerHandler::dragThreshold

void	setDragThreshold (int t)

void	resetDragThreshold ()

Public Member Functions inherited from QObject
Q_INVOKABLE	QObject (QObject *parent=nullptr)
	Constructs an object with parent object parent.

virtual	~QObject ()
	Destroys the object, deleting all its child objects.

virtual bool	eventFilter (QObject watched, QEvent event)
	Filters events if this object has been installed as an event filter for the watched object.

QString	objectName () const

Q_WEAK_OVERLOAD void	setObjectName (const QString &name)
	Sets the object's name to name.

void	setObjectName (QAnyStringView name)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

QBindable< QString >	bindableObjectName ()

bool	isWidgetType () const
	Returns `true` if the object is a widget; otherwise returns `false`.

bool	isWindowType () const
	Returns `true` if the object is a window; otherwise returns `false`.

bool	isQuickItemType () const
	Returns `true` if the object is a QQuickItem; otherwise returns `false`.

bool	signalsBlocked () const noexcept
	Returns `true` if signals are blocked; otherwise returns `false`.

bool	blockSignals (bool b) noexcept
	If block is true, signals emitted by this object are blocked (i.e., emitting a signal will not invoke anything connected to it).

QThread *	thread () const
	Returns the thread in which the object lives.

bool	moveToThread (QThread *thread QT6_DECL_NEW_OVERLOAD_TAIL)
	Changes the thread affinity for this object and its children and returns `true` on success.

int	startTimer (int interval, Qt::TimerType timerType=Qt::CoarseTimer)
	This is an overloaded function that will start a timer of type timerType and a timeout of interval milliseconds.

int	startTimer (std::chrono::nanoseconds time, Qt::TimerType timerType=Qt::CoarseTimer)

void	killTimer (int id)
	Kills the timer with timer identifier, id.

void	killTimer (Qt::TimerId id)

template<typename T >
T	findChild (QAnyStringView aName, Qt::FindChildOptions options=Qt::FindChildrenRecursively) const
	Returns the child of this object that can be cast into type T and that is called name, or \nullptr if there is no such object.

template<typename T >
QList< T >	findChildren (QAnyStringView aName, Qt::FindChildOptions options=Qt::FindChildrenRecursively) const
	Returns all children of this object with the given name that can be cast to type T, or an empty list if there are no such objects.

template<typename T >
T	findChild (Qt::FindChildOptions options=Qt::FindChildrenRecursively) const
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

template<typename T >
QList< T >	findChildren (Qt::FindChildOptions options=Qt::FindChildrenRecursively) const
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

const QObjectList &	children () const
	Returns a list of child objects.

void	setParent (QObject *parent)
	Makes the object a child of parent.

void	installEventFilter (QObject *filterObj)
	Installs an event filter filterObj on this object.

void	removeEventFilter (QObject *obj)
	Removes an event filter object obj from this object.

QMetaObject::Connection	connect (const QObject sender, const char signal, const char *member, Qt::ConnectionType type=Qt::AutoConnection) const

bool	disconnect (const char signal=nullptr, const QObject receiver=nullptr, const char *member=nullptr) const

bool	disconnect (const QObject receiver, const char member=nullptr) const

void	dumpObjectTree () const
	Dumps a tree of children to the debug output.

void	dumpObjectInfo () const
	Dumps information about signal connections, etc.

bool	setProperty (const char *name, const QVariant &value)
	Sets the value of the object's name property to value.

bool	setProperty (const char *name, QVariant &&value)

QVariant	property (const char *name) const
	Returns the value of the object's name property.

QList< QByteArray >	dynamicPropertyNames () const

QBindingStorage *	bindingStorage ()

const QBindingStorage *	bindingStorage () const

QObject *	parent () const
	Returns a pointer to the parent object.

bool	inherits (const char *classname) const
	Returns `true` if this object is an instance of a class that inherits className or a QObject subclass that inherits className; otherwise returns `false`.

Public Member Functions inherited from QQmlParserStatus
	QQmlParserStatus ()

virtual	~QQmlParserStatus ()

Protected Member Functions
void	onGrabChanged (QQuickPointerHandler grabber, QPointingDevice::GrabTransition transition, QPointerEvent ev, QEventPoint &point) override
	Notification that the grab has changed in some way which is relevant to this handler.

void	timerEvent (QTimerEvent *event) override
	This event handler can be reimplemented in a subclass to receive timer events for the object.

bool	wantsEventPoint (const QPointerEvent *event, const QEventPoint &point) override
	Returns `true` if the given point (as part of event) could be relevant at all to this handler, as a preliminary check.

void	handleEventPoint (QPointerEvent *event, QEventPoint &point) override

Protected Member Functions inherited from QQuickSinglePointHandler
	QQuickSinglePointHandler (QQuickSinglePointHandlerPrivate &dd, QQuickItem *parent)

bool	wantsPointerEvent (QPointerEvent *event) override
	It is the responsibility of this function to decide whether the event could be relevant at all to this handler, as a preliminary check.

void	handlePointerEventImpl (QPointerEvent *event) override
	This function can be overridden to implement whatever behavior a specific subclass is intended to have: \list.

QEventPoint &	currentPoint (QPointerEvent *ev)

void	setIgnoreAdditionalPoints (bool v=true)

void	moveTarget (QPointF pos, QEventPoint &point)

void	setPointId (int id)

Protected Member Functions inherited from QQuickPointerDeviceHandler
	QQuickPointerDeviceHandler (QQuickPointerDeviceHandlerPrivate &dd, QQuickItem *parent=nullptr)

Protected Member Functions inherited from QQuickPointerHandler
	QQuickPointerHandler (QQuickPointerHandlerPrivate &dd, QQuickItem *parent)

void	classBegin () override
	Overridden only because QQmlParserStatus requires it.

void	componentComplete () override
	Overridden from QQmlParserStatus to ensure that parentItem() sets its cursor if this handler's \l cursorShape property has been set.

bool	event (QEvent *) override

QPointerEvent *	currentEvent ()

void	setActive (bool active)

virtual void	onTargetChanged (QQuickItem *oldTarget)

virtual void	onActiveChanged ()

virtual bool	canGrab (QPointerEvent *event, const QEventPoint &point)
	Check whether it's OK to take an exclusive grab of the point.

virtual bool	approveGrabTransition (QPointerEvent event, const QEventPoint &point, QObject proposedGrabber)
	Check this handler's rules to see if \l proposedGrabber will be allowed to take the exclusive grab.

void	setPassiveGrab (QPointerEvent *event, const QEventPoint &point, bool grab=true)
	Acquire or give up a passive grab of the given point, according to the grab state.

bool	setExclusiveGrab (QPointerEvent *ev, const QEventPoint &point, bool grab=true)
	Acquire or give up the exclusive grab of the given point, according to the grab state, and subject to the rules: canGrab(), and the rule not to relinquish another handler's grab.

void	cancelAllGrabs (QPointerEvent *event, QEventPoint &point)
	Cancel any existing grab of the given point.

QPointF	eventPos (const QEventPoint &point) const

bool	parentContains (const QEventPoint &point) const
	Returns `true` if margin() > 0 and point is within the margin beyond QQuickItem::boundingRect(), or else returns QQuickItem::contains() QEventPoint::position() effectively (because parentContains(scenePosition) calls QQuickItem::mapFromScene()).

bool	parentContains (const QPointF &scenePosition) const
	Returns `true` if scenePosition is within the margin() beyond QQuickItem::boundingRect() (if margin > 0), or parentItem() contains scenePosition according to QQuickItem::contains().

Protected Member Functions inherited from QObject
QObject *	sender () const
	Returns a pointer to the object that sent the signal, if called in a slot activated by a signal; otherwise it returns \nullptr.

int	senderSignalIndex () const

int	receivers (const char *signal) const
	Returns the number of receivers connected to the signal.

bool	isSignalConnected (const QMetaMethod &signal) const

virtual void	childEvent (QChildEvent *event)
	This event handler can be reimplemented in a subclass to receive child events.

virtual void	customEvent (QEvent *event)
	This event handler can be reimplemented in a subclass to receive custom events.

virtual void	connectNotify (const QMetaMethod &signal)

virtual void	disconnectNotify (const QMetaMethod &signal)

	QObject (QObjectPrivate &dd, QObject *parent=nullptr)

Properties
bool	pressed

int	tapCount

qreal	timeHeld

qreal	longPressThreshold

GesturePolicy	gesturePolicy

QQuickTapHandler::ExclusiveSignals	exclusiveSignals

Properties inherited from QQuickSinglePointHandler
QQuickHandlerPoint	point

Properties inherited from QQuickPointerDeviceHandler
QInputDevice::DeviceTypes	acceptedDevices

QPointingDevice::PointerTypes	acceptedPointerTypes

Qt::MouseButtons	acceptedButtons

Qt::KeyboardModifiers	acceptedModifiers

Properties inherited from QQuickPointerHandler
bool	enabled

bool	active

QQuickItem *	target

QQuickItem *	parent

GrabPermissions	grabPermissions

qreal	margin

int	dragThreshold

Properties inherited from QObject
QString	objectName
	the name of this object

Additional Inherited Members
Public Slots inherited from QQuickPointerDeviceHandler
void	setAcceptedDevices (QInputDevice::DeviceTypes acceptedDevices)
	\qmlproperty flags PointerDeviceHandler::acceptedDevices

void	setAcceptedPointerTypes (QPointingDevice::PointerTypes acceptedPointerTypes)
	\qmlproperty flags PointerDeviceHandler::acceptedPointerTypes

void	setAcceptedButtons (Qt::MouseButtons buttons)

void	setAcceptedModifiers (Qt::KeyboardModifiers acceptedModifiers)
	\qmlproperty flags PointerDeviceHandler::acceptedModifiers

Public Slots inherited from QObject
void	deleteLater ()
	\threadsafe

Static Public Member Functions inherited from QObject
static QMetaObject::Connection	connect (const QObject sender, const char signal, const QObject receiver, const char member, Qt::ConnectionType=Qt::AutoConnection)
	\threadsafe

static QMetaObject::Connection	connect (const QObject sender, const QMetaMethod &signal, const QObject receiver, const QMetaMethod &method, Qt::ConnectionType type=Qt::AutoConnection)

template<typename Func1 , typename Func2 >
static QMetaObject::Connection	connect (const typename QtPrivate::FunctionPointer< Func1 >::Object sender, Func1 signal, const typename QtPrivate::ContextTypeForFunctor< Func2 >::ContextType context, Func2 &&slot, Qt::ConnectionType type=Qt::AutoConnection)

template<typename Func1 , typename Func2 >
static QMetaObject::Connection	connect (const typename QtPrivate::FunctionPointer< Func1 >::Object *sender, Func1 signal, Func2 &&slot)

static bool	disconnect (const QObject sender, const char signal, const QObject receiver, const char member)
	\threadsafe

static bool	disconnect (const QObject sender, const QMetaMethod &signal, const QObject receiver, const QMetaMethod &member)

static bool	disconnect (const QMetaObject::Connection &)
	Disconnect a connection.

template<typename Func1 , typename Func2 >
static bool	disconnect (const typename QtPrivate::FunctionPointer< Func1 >::Object sender, Func1 signal, const typename QtPrivate::FunctionPointer< Func2 >::Object receiver, Func2 slot)

template<typename Func1 >
static bool	disconnect (const typename QtPrivate::FunctionPointer< Func1 >::Object sender, Func1 signal, const QObject receiver, void **zero)

Protected Attributes inherited from QObject
QScopedPointer< QObjectData >	d_ptr

Related Symbols inherited from QObject
template< class T > T	qobject_cast (const QObject *object)
	Returns the given object cast to type T if the object is of type T (or of a subclass); otherwise returns \nullptr.

template< typename T > T	qFindChildqFindChildren (const QObject *obj, const QString &name)()

template< typename T > QList< T >	qFindChildrenqFindChildren (const QObject *obj, const QString &name)()

	QObjectList
	\macro Q_CLASSINFO(Name, Value)

Detailed Description

Definition at line 27 of file qquicktaphandler_p.h.

Member Enumeration Documentation

◆ ExclusiveSignal

enum QQuickTapHandler::ExclusiveSignal

Enumerator
NotExclusive
SingleTap
DoubleTap

Definition at line 49 of file qquicktaphandler_p.h.

◆ GesturePolicy

enum QQuickTapHandler::GesturePolicy

Enumerator
DragThreshold
WithinBounds
ReleaseWithinBounds
DragWithinBounds

Definition at line 41 of file qquicktaphandler_p.h.

Constructor & Destructor Documentation

◆ QQuickTapHandler()

QQuickTapHandler::QQuickTapHandler ( QQuickItem * parent = nullptr )

explicit

\qmltype TapHandler \nativetype QQuickTapHandler \inherits SinglePointHandler \inqmlmodule QtQuick

Handler for taps and clicks.

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

Detection of a valid tap gesture depends on \l 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 \l 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, {Qt Quick Examples - Pointer Handlers}

Definition at line 56 of file qquicktaphandler.cpp.

Member Function Documentation

◆ doubleTapped

void QQuickTapHandler::doubleTapped	(	QEventPoint	eventPoint,
		Qt::MouseButton	)

signal

◆ exclusiveSignals()

QQuickTapHandler::ExclusiveSignals QQuickTapHandler::exclusiveSignals ( ) const

inline

Definition at line 71 of file qquicktaphandler_p.h.

◆ gesturePolicy()

GesturePolicy QQuickTapHandler::gesturePolicy ( ) const

inline

Definition at line 68 of file qquicktaphandler_p.h.

◆ gesturePolicyChanged

void QQuickTapHandler::gesturePolicyChanged ( )

signal

◆ handleEventPoint()

void QQuickTapHandler::handleEventPoint	(	QPointerEvent *	event,
		QEventPoint &	point )

overrideprotectedvirtual

Reimplemented from QQuickSinglePointHandler.

Definition at line 124 of file qquicktaphandler.cpp.

◆ isPressed()

bool QQuickTapHandler::isPressed ( ) const

inline

Definition at line 59 of file qquicktaphandler_p.h.

◆ longPressed

void QQuickTapHandler::longPressed ( )

signal

◆ longPressThreshold()

qreal QQuickTapHandler::longPressThreshold ( ) const

\qmlproperty real QtQuick::TapHandler::longPressThreshold

The time in seconds that an \l eventPoint must be pressed in order to trigger a long press gesture and emit the \l longPressed() signal, if the value is greater than 0. If the point is released before this time limit, a tap can be detected if the \l gesturePolicy constraint is satisfied. If longPressThreshold is 0, the timer is disabled and the signal will not be emitted. If longPressThreshold is set to undefined, the default value is used instead, and can be read back from this property.

The default value is QStyleHints::mousePressAndHoldInterval() converted to seconds.

Definition at line 162 of file qquicktaphandler.cpp.

◆ longPressThresholdChanged

void QQuickTapHandler::longPressThresholdChanged ( )

signal

◆ onGrabChanged()

void QQuickTapHandler::onGrabChanged	(	QQuickPointerHandler *	grabber,
		QPointingDevice::GrabTransition	transition,
		QPointerEvent *	event,
		QEventPoint &	point )

overrideprotectedvirtual

Notification that the grab has changed in some way which is relevant to this handler.

Since: 5.15 \qmlproperty Qt::CursorShape PointerHandler::cursorShape This property holds the cursor shape that will appear whenever the mouse is hovering over the \l parent item while \l active is true.

The available cursor shapes are: \list

The default value is not set, which allows the \l {QQuickItem::cursor()}{cursor} of \l parent item to appear. This property can be reset to the same initial condition by setting it to undefined.

Note: When this property has not been set, or has been set to undefined, if you read the value it will return Qt.ArrowCursor.

See also: Qt::CursorShape, QQuickItem::cursor(), HoverHandler::cursorShape

The grabber (subject) will be the Input Handler whose state is changing, or null if the state change regards an Item. The transition (verb) tells what happened. The point (object) is the \l eventPoint that was grabbed or ungrabbed. QQuickDeliveryAgent calls this function. The Input Handler must react in whatever way is appropriate, and must emit the relevant signals (for the benefit of QML code). A subclass is allowed to override this virtual function, but must always call its parent class's implementation in addition to (usually after) whatever custom behavior it implements.

Reimplemented from QQuickSinglePointHandler.

Definition at line 454 of file qquicktaphandler.cpp.

◆ pressedChanged

void QQuickTapHandler::pressedChanged ( )

signal

◆ Q_REVISION

QQuickTapHandler::Q_REVISION	(	6	,
		5	)

signal

◆ resetLongPressThreshold()

void QQuickTapHandler::resetLongPressThreshold ( )

Definition at line 181 of file qquicktaphandler.cpp.

◆ setExclusiveSignals()

void QQuickTapHandler::setExclusiveSignals ( QQuickTapHandler::ExclusiveSignals exc )

\qmlproperty enumeration QtQuick::TapHandler::exclusiveSignals

Since: 6.5

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

\value NotExclusive (the default) singleTapped() and doubleTapped() are emitted immediately when the user taps once or twice, respectively.

\value SingleTap singleTapped() is emitted immediately when the user taps once, and doubleTapped() is never emitted.

\value DoubleTap doubleTapped() is emitted immediately when the user taps twice, and singleTapped() is never emitted.

\value (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.

Definition at line 344 of file qquicktaphandler.cpp.

◆ setGesturePolicy()

void QQuickTapHandler::setGesturePolicy ( QQuickTapHandler::GesturePolicy gesturePolicy )

\qmlproperty enumeration QtQuick::TapHandler::gesturePolicy

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

The gesturePolicy also affects grab behavior as described below.

\table \header

Constant
Description \row
TapHandler.DragThreshold Grab on press: passive
(the default value) The \l 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 \l DragHandler) or event-handling Items (for example \l {Qt Quick Controls}), because in this case TapHandler will not take the exclusive grab, but merely a \l {QPointerEvent::addPassiveGrabber()}{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: \quotefromfile pointerHandlers/tapHandlerOverlappingButtons.qml \skipto Item \printuntil component Button \skipto TapHandler \printuntil } \skipuntil Text { \skipuntil } \printuntil Button \printuntil Button \printuntil }

\row

TapHandler.WithinBounds Grab on press: exclusive
If the \l eventPoint leaves the bounds of the parent Item, the tap gesture is canceled. The TapHandler will take the \l {QPointerEvent::setExclusiveGrabber}{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()

}

\row

TapHandler.ReleaseWithinBounds Grab on press: exclusive
At the time of release (the mouse button is released or the finger is lifted), if the \l 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 \l {QPointerEvent::setExclusiveGrabber}{exclusive grab} on press and retain it until release in order to detect this gesture.
TapHandler {

id: tapHandler

gesturePolicy: TapHandler.ReleaseWithinBounds

onTapped: tapFlash.start()

}

\row

TapHandler.DragWithinBounds Grab on press: exclusive
On press, TapHandler takes the \l {QPointerEvent::setExclusiveGrabber}{exclusive grab}; after that, the \l eventPoint can be dragged within the bounds of the parent item, while the \l timeHeld property keeps counting, and the \l longPressed() signal will be emitted regardless of drag distance. However, like WithinBounds, if the point leaves the bounds, the tap gesture is \l {PointerHandler::}{canceled()}, \l active() becomes false, and \l 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"

}

\endtable

The \l {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 \l {PointerHandler::}{grabPermissions}, either in this handler, or in another handler that should prevent TapHandler from reacting.

Definition at line 312 of file qquicktaphandler.cpp.

◆ setLongPressThreshold()

void QQuickTapHandler::setLongPressThreshold ( qreal longPressThreshold )

Definition at line 167 of file qquicktaphandler.cpp.

◆ singleTapped

void QQuickTapHandler::singleTapped	(	QEventPoint	eventPoint,
		Qt::MouseButton	)

signal

◆ tapCount()

int QQuickTapHandler::tapCount ( ) const

inline

Definition at line 61 of file qquicktaphandler_p.h.

◆ tapCountChanged

void QQuickTapHandler::tapCountChanged ( )

signal

◆ tapped

void QQuickTapHandler::tapped	(	QEventPoint	eventPoint,
		Qt::MouseButton	)

signal

◆ timeHeld()

qreal QQuickTapHandler::timeHeld ( ) const

inline

Definition at line 62 of file qquicktaphandler_p.h.

◆ timeHeldChanged

void QQuickTapHandler::timeHeldChanged ( )

signal

◆ timerEvent()

void QQuickTapHandler::timerEvent ( QTimerEvent * event )

overrideprotectedvirtual

This event handler can be reimplemented in a subclass to receive timer events for the object.

QChronoTimer provides higher-level interfaces to the timer functionality, and also more general information about timers. The timer event is passed in the event parameter.

See also: startTimer(), killTimer(), event()

Reimplemented from QObject.

Definition at line 191 of file qquicktaphandler.cpp.

◆ wantsEventPoint()

bool QQuickTapHandler::wantsEventPoint	(	const QPointerEvent *	event,
		const QEventPoint &	point )

overrideprotectedvirtual

Returns true if the given point (as part of event) could be relevant at all to this handler, as a preliminary check.

If you override this function, you should call the immediate parent class implementation (and return false if it returns false); that in turn calls its parent class implementation, and so on.

In particular, the bounds checking is done here: the base class QQuickPointerHandler::wantsEventPoint() calls parentContains(point) (which allows the flexibility promised by margin(), QQuickItem::contains() and QQuickItem::containmentMask()). Pointer Handlers can receive QEventPoints that are outside the parent item's bounds: this allows some flexibility for dealing with multi-point gestures in which one or more fingers have strayed outside the bounds, and yet the gesture is still unambiguously intended for the target() item.

You should not generally react to the event or point here, but it's ok to set state to remember what needs to be done in your overridden handlePointerEventImpl() or QQuickSinglePointHandler::handleEventPoint().

Reimplemented from QQuickPointerHandler.

Definition at line 69 of file qquicktaphandler.cpp.

Property Documentation

◆ exclusiveSignals

QQuickTapHandler::ExclusiveSignals QQuickTapHandler::exclusiveSignals

readwrite

Definition at line 35 of file qquicktaphandler_p.h.

◆ gesturePolicy

GesturePolicy QQuickTapHandler::gesturePolicy

readwrite

Definition at line 34 of file qquicktaphandler_p.h.

◆ longPressThreshold

qreal QQuickTapHandler::longPressThreshold

readwrite

Definition at line 33 of file qquicktaphandler_p.h.

◆ pressed

bool QQuickTapHandler::pressed

read

Definition at line 30 of file qquicktaphandler_p.h.

◆ tapCount

int QQuickTapHandler::tapCount

read

Definition at line 31 of file qquicktaphandler_p.h.

◆ timeHeld

qreal QQuickTapHandler::timeHeld

read

Definition at line 32 of file qquicktaphandler_p.h.

The documentation for this class was generated from the following files:

qtdeclarative/src/quick/handlers/qquicktaphandler_p.h (821f8f1f6c74b562bd984a12c959bc137dd2c11f)
qtdeclarative/src/quick/handlers/qquicktaphandler.cpp (a464ff5bfa15201de64d05121dc192dbd4655890)

Public Types

Signals

Public Member Functions

Protected Member Functions

Properties

Additional Inherited Members

Detailed Description

Member Enumeration Documentation

◆ ExclusiveSignal

◆ GesturePolicy

Constructor & Destructor Documentation

◆ QQuickTapHandler()

Member Function Documentation

◆ doubleTapped

◆ exclusiveSignals()

◆ gesturePolicy()

◆ gesturePolicyChanged

◆ handleEventPoint()

◆ isPressed()

◆ longPressed

◆ longPressThreshold()

◆ longPressThresholdChanged

◆ onGrabChanged()

◆ pressedChanged

◆ Q_REVISION

◆ resetLongPressThreshold()

◆ setExclusiveSignals()

◆ setGesturePolicy()

◆ setLongPressThreshold()

◆ singleTapped

◆ tapCount()

◆ tapCountChanged

◆ tapped

◆ timeHeld()

◆ timeHeldChanged

◆ timerEvent()

◆ wantsEventPoint()

Property Documentation

◆ exclusiveSignals

◆ gesturePolicy

◆ longPressThreshold

◆ pressed

◆ tapCount

◆ timeHeld