The QTouchEvent class contains parameters that describe a touch event. More...
Header: | #include <QTouchEvent> |
CMake: | find_package(Qt6 COMPONENTS Gui REQUIRED) target_link_libraries(mytarget PRIVATE Qt6::Gui) |
qmake: | QT += gui |
Inherits: | QPointerEvent |
virtual | ~QTouchEvent() |
QObject * | target() const |
QEventPoint::States | touchPointStates() const |
virtual bool | isBeginEvent() const override |
virtual bool | isEndEvent() const override |
virtual bool | isUpdateEvent() const override |
Touch events occur when pressing, releasing, or moving one or more touch points on a touch device (such as a touch-screen or track-pad). To receive touch events, widgets have to have the Qt::WA_AcceptTouchEvents attribute set and graphics items need to have the acceptTouchEvents attribute set to true.
When using QAbstractScrollArea based widgets, you should enable the Qt::WA_AcceptTouchEvents attribute on the scroll area's viewport.
Similarly to QMouseEvent, Qt automatically grabs each touch point on the first press inside a widget, and the widget will receive all updates for the touch point until it is released. Note that it is possible for a widget to receive events for numerous touch points, and that multiple widgets may be receiving touch events at the same time.
All touch events are of type QEvent::TouchBegin, QEvent::TouchUpdate, QEvent::TouchEnd or QEvent::TouchCancel. Reimplement QWidget::event() or QAbstractScrollArea::viewportEvent() for widgets and QGraphicsItem::sceneEvent() for items in a graphics view to receive touch events.
Unlike widgets, QWindows receive touch events always, there is no need to opt in. When working directly with a QWindow, it is enough to reimplement QWindow::touchEvent().
The QEvent::TouchUpdate and QEvent::TouchEnd events are sent to the widget or item that accepted the QEvent::TouchBegin event. If the QEvent::TouchBegin event is not accepted and not filtered by an event filter, then no further touch events are sent until the next QEvent::TouchBegin.
Some systems may send an event of type QEvent::TouchCancel. Upon receiving this event applications are requested to ignore the entire active touch sequence. For example in a composited system the compositor may decide to treat certain gestures as system-wide gestures. Whenever such a decision is made (the gesture is recognized), the clients will be notified with a QEvent::TouchCancel event so they can update their state accordingly.
The pointCount() and point() functions can be used to access and iterate individual touch points.
The points() function returns a list of all touch points contained in the event. Note that this list may be empty, for example in case of a QEvent::TouchCancel event. Each point is an instance of the QEventPoint class. The QEventPoint::State enum describes the different states that a touch point may have.
Note: The list of points() will never be partial: A touch event will always contain a touch point for each existing physical touch contacts targeting the window or widget to which the event is sent. For instance, assuming that all touches target the same window or widget, an event with a condition of points().count()==2 is guaranteed to imply that the number of fingers touching the touchscreen or touchpad is exactly two.
By default, QGuiApplication translates the first touch point in a QTouchEvent into a QMouseEvent. This makes it possible to enable touch events on existing widgets that do not normally handle QTouchEvent. See below for information on some special considerations needed when doing this.
QEvent::TouchBegin is the first touch event sent to a widget. The QEvent::TouchBegin event contains a special accept flag that indicates whether the receiver wants the event. By default, the event is accepted. You should call ignore() if the touch event is not handled by your widget. The QEvent::TouchBegin event is propagated up the parent widget chain until a widget accepts it with accept(), or an event filter consumes it. For QGraphicsItems, the QEvent::TouchBegin event is propagated to items under the mouse (similar to mouse event propagation for QGraphicsItems).
As mentioned above, it is possible that several widgets can be receiving QTouchEvents at the same time. However, Qt makes sure to never send duplicate QEvent::TouchBegin events to the same widget, which could theoretically happen during propagation if, for example, the user touched 2 separate widgets in a QGroupBox and both widgets ignored the QEvent::TouchBegin event.
To avoid this, Qt will group new touch points together using the following rules:
This makes it possible for sibling widgets to handle touch events independently while making sure that the sequence of QTouchEvents is always correct.
QTouchEvent delivery is independent from that of QMouseEvent. The application flags Qt::AA_SynthesizeTouchForUnhandledMouseEvents and Qt::AA_SynthesizeMouseForUnhandledTouchEvents can be used to enable or disable automatic synthesizing of touch events to mouse events and mouse events to touch events.
See also QEventPoint, QEventPoint::State, Qt::WA_AcceptTouchEvents, and QGraphicsItem::acceptTouchEvents().
[virtual]
QTouchEvent::~QTouchEvent()
Destroys the QTouchEvent.
[override virtual]
bool QTouchEvent::isBeginEvent() const
Returns true if this event includes at least one newly-pressed touchpoint.
[override virtual]
bool QTouchEvent::isEndEvent() const
Returns true if this event includes at least one newly-released touchpoint.
[override virtual]
bool QTouchEvent::isUpdateEvent() const
Returns true if this event does not include newly-pressed or newly-released touchpoints.
Returns the target object within the window on which the event occurred. This is typically a QWidget or a QQuickItem. May be 0 when no specific target is available.
Returns a bitwise OR of all the touch point states for this event.
© The Qt Company Ltd
Licensed under the GNU Free Documentation License, Version 1.3.
https://doc.qt.io/qt-6.2/qtouchevent.html