Skip to content

PythonQt.Qt.QTouchEvent

QTouchEvent

PythonQtInstanceWrapper object

Native bases: PythonQtInstanceWrapper

Supplemental documentation: Qt 5 reference:

Detailed Description

Enabling Touch Events

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.

Event Handling

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 touchPoints() 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. Information about each touch point can be retrieved using the QTouchEvent::TouchPoint class. The Qt::TouchPointState enum describes the different states that a touch point may have.

Note: The list of touchPoints() will never be partial: A touch event will always contain a touch point for each existing physical touch contacts targetting 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 touchPoints().count()\=\=2 is guaranteed to imply that the number of fingers touching the touchscreen or touchpad is exactly two.

Event Delivery and Propagation

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).

Touch Point Grouping

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:

  • When the first touch point is detected, the destination widget is determined firstly by the location on screen and secondly by the propagation rules.
  • When additional touch points are detected, Qt first looks to see if there are any active touch points on any ancestor or descendent of the widget under the new touch point. If there are, the new touch point is grouped with the first, and the new touch point will be sent in a single QTouchEvent to the widget that handled the first touch point. (The widget under the new touch point will not receive an event).

This makes it possible for sibling widgets to handle touch events independently while making sure that the sequence of QTouchEvents is always correct.

Mouse Events and Touch Event Synthesizing

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.

Caveats

  • As mentioned above, enabling touch events means multiple widgets can be receiving touch events simultaneously. Combined with the default QWidget::event() handling for QTouchEvents, this gives you great flexibility in designing touch user interfaces. Be aware of the implications. For example, it is possible that the user is moving a QSlider with one finger and pressing a QPushButton with another. The signals emitted by these widgets will be interleaved.
  • Recursion into the event loop using one of the exec() methods (e.g., QDialog::exec() or QMenu::exec()) in a QTouchEvent event handler is not supported. Since there are multiple event recipients, recursion may cause problems, including but not limited to lost events and unexpected infinite recursion.
  • QTouchEvents are not affected by a mouse grab or an active pop-up widget. The behavior of QTouchEvents is undefined when opening a pop-up or grabbing the mouse while there are more than one active touch points.

Source: https://doc.qt.io/archives/qt-5.15/qtouchevent.html

Complete member index

Every captured member retains its own identity. Identical captured declaration text is linked once; this does not establish native inheritance or interchangeable objects.

Member Kind Signature Summary
AcceptDropsChange attribute Any (shared captured text)
ActionAdded attribute Any (shared captured text)
ActionChanged attribute Any (shared captured text)
ActionRemoved attribute Any (shared captured text)
ActivateControl attribute Any (shared captured text)
ActivationChange attribute Any (shared captured text)
ApplicationActivate attribute Any (shared captured text)
ApplicationActivated attribute Any (shared captured text)
ApplicationDeactivate attribute Any (shared captured text)
ApplicationDeactivated attribute Any (shared captured text)
ApplicationFontChange attribute Any (shared captured text)
ApplicationLayoutDirectionChange attribute Any (shared captured text)
ApplicationPaletteChange attribute Any (shared captured text)
ApplicationStateChange attribute Any (shared captured text)
ApplicationWindowIconChange attribute Any (shared captured text)
ChildAdded attribute Any (shared captured text)
ChildPolished attribute Any (shared captured text)
ChildRemoved attribute Any (shared captured text)
Clipboard attribute Any (shared captured text)
Close attribute Any (shared captured text)
CloseSoftwareInputPanel attribute Any (shared captured text)
ContentsRectChange attribute Any (shared captured text)
ContextMenu attribute Any (shared captured text)
Create attribute Any (shared captured text)
CursorChange attribute Any (shared captured text)
DeactivateControl attribute Any (shared captured text)
DeferredDelete attribute Any (shared captured text)
Destroy attribute Any (shared captured text)
DragEnter attribute Any (shared captured text)
DragLeave attribute Any (shared captured text)
DragMove attribute Any (shared captured text)
DragResponse attribute Any (shared captured text)
Drop attribute Any (shared captured text)
DynamicPropertyChange attribute Any (shared captured text)
EmbeddingControl attribute Any (shared captured text)
EnabledChange attribute Any (shared captured text)
Enter attribute Any (shared captured text)
EnterWhatsThisMode attribute Any (shared captured text)
Expose attribute Any (shared captured text)
FileOpen attribute Any (shared captured text)
FocusAboutToChange attribute Any (shared captured text)
FocusIn attribute Any (shared captured text)
FocusOut attribute Any (shared captured text)
FontChange attribute Any (shared captured text)
FutureCallOut attribute Any (shared captured text)
Gesture attribute Any (shared captured text)
GestureOverride attribute Any (shared captured text)
GrabKeyboard attribute Any (shared captured text)
GrabMouse attribute Any (shared captured text)
GraphicsSceneContextMenu attribute Any (shared captured text)
GraphicsSceneDragEnter attribute Any (shared captured text)
GraphicsSceneDragLeave attribute Any (shared captured text)
GraphicsSceneDragMove attribute Any (shared captured text)
GraphicsSceneDrop attribute Any (shared captured text)
GraphicsSceneHelp attribute Any (shared captured text)
GraphicsSceneHoverEnter attribute Any (shared captured text)
GraphicsSceneHoverLeave attribute Any (shared captured text)
GraphicsSceneHoverMove attribute Any (shared captured text)
GraphicsSceneMouseDoubleClick attribute Any (shared captured text)
GraphicsSceneMouseMove attribute Any (shared captured text)
GraphicsSceneMousePress attribute Any (shared captured text)
GraphicsSceneMouseRelease attribute Any (shared captured text)
GraphicsSceneMove attribute Any (shared captured text)
GraphicsSceneResize attribute Any (shared captured text)
GraphicsSceneWheel attribute Any (shared captured text)
HelpRequest attribute Any (shared captured text)
Hide attribute Any (shared captured text)
HideToParent attribute Any (shared captured text)
HoverEnter attribute Any (shared captured text)
HoverLeave attribute Any (shared captured text)
HoverMove attribute Any (shared captured text)
IconDrag attribute Any (shared captured text)
IconTextChange attribute Any (shared captured text)
InputMethod attribute Any (shared captured text)
InputMethodQuery attribute Any (shared captured text)
KeyPress attribute Any (shared captured text)
KeyRelease attribute Any (shared captured text)
KeyboardLayoutChange attribute Any (shared captured text)
LanguageChange attribute Any (shared captured text)
LayoutDirectionChange attribute Any (shared captured text)
LayoutRequest attribute Any (shared captured text)
Leave attribute Any (shared captured text)
LeaveWhatsThisMode attribute Any (shared captured text)
LocaleChange attribute Any (shared captured text)
MacGLClearDrawable attribute Any (shared captured text)
MacGLWindowChange attribute Any (shared captured text)
MacSizeChange attribute Any (shared captured text)
MaxUser attribute Any (shared captured text)
MetaCall attribute Any (shared captured text)
ModifiedChange attribute Any (shared captured text)
MouseButtonDblClick attribute Any (shared captured text)
MouseButtonPress attribute Any (shared captured text)
MouseButtonRelease attribute Any (shared captured text)
MouseMove attribute Any (shared captured text)
MouseTrackingChange attribute Any (shared captured text)
Move attribute Any (shared captured text)
NativeGesture attribute Any (shared captured text)
NetworkReplyUpdated attribute Any (shared captured text)
NonClientAreaMouseButtonDblClick attribute Any (shared captured text)
NonClientAreaMouseButtonPress attribute Any (shared captured text)
NonClientAreaMouseButtonRelease attribute Any (shared captured text)
NonClientAreaMouseMove attribute Any (shared captured text)
None_ attribute Any (shared captured text)
OkRequest attribute Any (shared captured text)
OrientationChange attribute Any (shared captured text)
Paint attribute Any (shared captured text)
PaletteChange attribute Any (shared captured text)
ParentAboutToChange attribute Any (shared captured text)
ParentChange attribute Any (shared captured text)
PlatformPanel attribute Any (shared captured text)
PlatformSurface attribute Any (shared captured text)
Polish attribute Any (shared captured text)
PolishRequest attribute Any (shared captured text)
QueryWhatsThis attribute Any (shared captured text)
Quit attribute Any (shared captured text)
ReadOnlyChange attribute Any (shared captured text)
RequestSoftwareInputPanel attribute Any (shared captured text)
Resize attribute Any (shared captured text)
ScreenChangeInternal attribute Any (shared captured text)
Scroll attribute Any (shared captured text)
ScrollPrepare attribute Any (shared captured text)
Shortcut attribute Any (shared captured text)
ShortcutOverride attribute Any (shared captured text)
Show attribute Any (shared captured text)
ShowToParent attribute Any (shared captured text)
ShowWindowRequest attribute Any (shared captured text)
SockAct attribute Any (shared captured text)
SockClose attribute Any (shared captured text)
Speech attribute Any (shared captured text)
StateMachineSignal attribute Any (shared captured text)
StateMachineWrapped attribute Any (shared captured text)
StatusTip attribute Any (shared captured text)
Style attribute Any (shared captured text)
StyleAnimationUpdate attribute Any (shared captured text)
StyleChange attribute Any (shared captured text)
TabletEnterProximity attribute Any (shared captured text)
TabletLeaveProximity attribute Any (shared captured text)
TabletMove attribute Any (shared captured text)
TabletPress attribute Any (shared captured text)
TabletRelease attribute Any (shared captured text)
ThemeChange attribute Any (shared captured text)
ThreadChange attribute Any (shared captured text)
Timer attribute Any (shared captured text)
ToolBarChange attribute Any (shared captured text)
ToolTip attribute Any (shared captured text)
ToolTipChange attribute Any (shared captured text)
TouchBegin attribute Any (shared captured text)
TouchCancel attribute Any (shared captured text)
TouchEnd attribute Any (shared captured text)
TouchPoint attribute type (shared captured text)
TouchUpdate attribute Any (shared captured text)
Type attribute type Convert a number or string to an integer, or return 0 if no arguments are given. (shared captured text)
UngrabKeyboard attribute Any (shared captured text)
UngrabMouse attribute Any (shared captured text)
UpdateLater attribute Any (shared captured text)
UpdateRequest attribute Any (shared captured text)
User attribute Any (shared captured text)
WhatsThis attribute Any (shared captured text)
WhatsThisClicked attribute Any (shared captured text)
Wheel attribute Any (shared captured text)
WinEventAct attribute Any (shared captured text)
WinIdChange attribute Any (shared captured text)
WindowActivate attribute Any (shared captured text)
WindowBlocked attribute Any (shared captured text)
WindowChangeInternal attribute Any (shared captured text)
WindowDeactivate attribute Any (shared captured text)
WindowIconChange attribute Any (shared captured text)
WindowStateChange attribute Any (shared captured text)
WindowTitleChange attribute Any (shared captured text)
WindowUnblocked attribute Any (shared captured text)
ZOrderChange attribute Any (shared captured text)
ZeroTimerEvent attribute Any (shared captured text)
__init__ function (self, *args: Any, **kwargs: Any) -> None Native constructor; consult class documentation for supported overloads. (shared captured text)
accept function (self) -> Any (shared captured text)
className function (self, *args: Any, **kwargs: Any) -> Any Return the classname of the object (shared captured text)
delete function (self, *args: Any, **kwargs: Any) -> Any Deletes the C++ object (at your own risk, my friend!) (shared captured text)
device function (self) -> Any X.device() -> PythonQt.QtGui.QTouchDevice (shared captured text)
help function (self, *args: Any, **kwargs: Any) -> Any Shows the help of available methods for this class (shared captured text)
ignore function (self) -> Any (shared captured text)
inherits function (self, *args: Any, **kwargs: Any) -> Any Returns if the class inherits or is of given type name (shared captured text)
isAccepted function (self) -> bool X.isAccepted() -> bool (shared captured text)
modifiers function (self) -> Any (shared captured text)
operator_assign function (self, other: Any) -> Any X.operator_assign(other) -> PythonQt.QtCore.QEvent (shared captured text)
registerEventType function (self, hint: Any) -> int X.registerEventType(hint) -> int (shared captured text)
setAccepted function (self, accepted: Any) -> Any (shared captured text)
setDevice function (self, adevice: Any) -> None (shared captured text)
setModifiers function (self, amodifiers: Any) -> Any (shared captured text)
setTarget function (self, atarget: Any) -> None (shared captured text)
setTimestamp function (self, atimestamp: Any) -> Any (shared captured text)
setTouchPointStates function (self, aTouchPointStates: Any) -> None (shared captured text)
setTouchPoints function (self, atouchPoints: Any) -> None (shared captured text)
setWindow function (self, awindow: Any) -> None (shared captured text)
spontaneous function (self) -> bool X.spontaneous() -> bool (shared captured text)
target function (self) -> Any X.target() -> PythonQt.private.QObject (shared captured text)
timestamp function (self) -> int X.timestamp() -> int (shared captured text)
touchPointStates function (self) -> Any Returns a bitwise OR of all the touch point states for this event. (shared captured text)
touchPoints function (self) -> tuple X.touchPoints() -> tuple (shared captured text)
type function (self) -> Any (shared captured text)
window function (self) -> Any X.window() -> PythonQt.QtGui.QWindow (shared captured text)