PySide6.QtGui.QTouchEvent

class QTouchEvent

QTouchEvent 类包含描述触摸事件的参数。更多…

PySide6.QtGui.QTouchEvent 的继承图

在版本4.6中添加。

概要

方法

注意

本文档可能包含从C++自动翻译到Python的代码片段。我们始终欢迎对代码片段翻译的贡献。如果您发现翻译问题，您也可以通过在我们的https:/bugreports.qt.io/projects/PYSIDE上创建工单来告知我们。

详细描述

启用触摸事件

触摸事件发生在触摸设备（如触摸屏或触控板）上按下、释放或移动一个或多个触摸点时。为了接收触摸事件，小部件必须设置Qt::WA_AcceptTouchEvents属性，并且图形项需要将acceptTouchEvents属性设置为true。

在使用基于QAbstractScrollArea的小部件时，您应该在滚动区域的视口上启用Qt::WA_AcceptTouchEvents属性。

类似于QMouseEvent，Qt在部件内首次按下时自动捕获每个触摸点，并且该部件将接收该触摸点的所有更新，直到它被释放。请注意，一个部件可能会接收到多个触摸点的事件，并且多个部件可能同时接收触摸事件。

事件处理

所有触摸事件的类型为QEvent::TouchBegin、QEvent::TouchUpdate、QEvent::TouchEnd或QEvent::TouchCancel。对于小部件，重新实现QWidget::event()或QAbstractScrollArea::viewportEvent()，对于图形视图中的项目，重新实现QGraphicsItem::sceneEvent()以接收触摸事件。

与小部件不同，QWindows总是接收触摸事件，无需选择加入。当直接使用QWindow时，只需重新实现touchEvent()即可。

QEvent::TouchUpdate 和 QEvent::TouchEnd 事件会被发送给接受了 QEvent::TouchBegin 事件的小部件或项目。如果 QEvent::TouchBegin 事件未被接受且未被事件过滤器过滤，那么在下一个 QEvent::TouchBegin 事件之前，不会发送进一步的触摸事件。

某些系统可能会发送类型为QEvent::TouchCancel的事件。接收到此事件后，应用程序需要忽略整个活动的触摸序列。例如，在复合系统中，合成器可能会决定将某些手势视为系统范围的手势。每当做出这样的决定（手势被识别）时，客户端将通过QEvent::TouchCancel事件得到通知，以便他们可以相应地更新其状态。

pointCount() 和 point() 函数可用于访问和迭代单个触摸点。

points() 函数返回事件中包含的所有触摸点的列表。请注意，此列表可能为空，例如在 QEvent::TouchCancel 事件的情况下。每个点都是 QEventPoint 类的一个实例。State 枚举描述了触摸点可能具有的不同状态。

注意

points() 的列表永远不会是部分的：触摸事件将始终包含针对事件发送到的窗口或小部件的每个现有物理触摸接触的触摸点。例如，假设所有触摸都针对同一个窗口或小部件，具有 points() .count()==2 条件的事件保证意味着触摸屏或触摸板上的手指数量正好是两个。

事件传递与传播

默认情况下，QGuiApplication 将 QTouchEvent 中的第一个触摸点转换为 QMouseEvent。这使得可以在通常不处理 QTouchEvent 的现有小部件上启用触摸事件。有关执行此操作时需要注意的一些特殊事项，请参见下文。

QEvent::TouchBegin 是发送给小部件的第一个触摸事件。QEvent::TouchBegin 事件包含一个特殊的接受标志，表示接收者是否希望接受该事件。默认情况下，事件是被接受的。如果触摸事件未被您的小部件处理，您应该调用 ignore()。QEvent::TouchBegin 事件会沿着父小部件链向上传播，直到一个小部件通过 accept() 接受它，或者事件过滤器消耗它。对于 QGraphicsItems，QEvent::TouchBegin 事件会传播到鼠标下的项目（类似于 QGraphicsItems 的鼠标事件传播）。

触点分组

如上所述，多个小部件可能同时接收QTouchEvents。然而，Qt确保不会向同一小部件发送重复的QEvent::TouchBegin事件，这在理论上可能在传播过程中发生，例如，如果用户在QGroupBox中触摸了两个独立的小部件，并且这两个小部件都忽略了QEvent::TouchBegin事件。

为了避免这种情况，Qt 将使用以下规则将新的触摸点分组：

  • 当检测到第一个触摸点时，目标小部件首先由屏幕上的位置确定，其次由传播规则确定。

  • 当检测到额外的触摸点时，Qt首先会查看新触摸点下的窗口小部件的任何祖先或后代是否有任何活动的触摸点。如果有，新的触摸点将与第一个触摸点分组，并且新的触摸点将以单个QTouchEvent发送到处理第一个触摸点的窗口小部件。（新触摸点下的窗口小部件将不会接收到事件）。

这使得兄弟小部件可以独立处理触摸事件，同时确保QTouchEvents的顺序始终正确。

鼠标事件和触摸事件合成

QTouchEvent 的传递与 QMouseEvent 的传递是独立的。应用程序标志 Qt::AA_SynthesizeTouchForUnhandledMouseEvents 和 Qt::AA_SynthesizeMouseForUnhandledTouchEvents 可用于启用或禁用将触摸事件自动合成为鼠标事件以及将鼠标事件自动合成为触摸事件。

注意事项

  • 如上所述，启用触摸事件意味着多个小部件可以同时接收触摸事件。结合默认的QWidget::event()对QTouchEvents的处理，这为设计触摸用户界面提供了极大的灵活性。请注意其影响。例如，用户可能用一个手指移动QSlider，同时用另一个手指按下QPushButton。这些小部件发出的信号将会交错。

  • 在QTouchEvent事件处理程序中使用exec()方法之一（例如，QDialog::exec()或QMenu::exec()）递归进入事件循环是不支持的。由于有多个事件接收者，递归可能会导致问题，包括但不限于丢失事件和意外的无限递归。

  • QTouchEvents 不受鼠标抓取或活动弹出窗口小部件的影响。当打开弹出窗口或抓取鼠标时，如果有多个活动触摸点，QTouchEvents 的行为是未定义的。

另请参阅

QEventPoint State acceptTouchEvents()

__init__(arg__1)
Parameters:

arg__1 – QTouchEvent

__init__(eventType[, device=None[, modifiers=Qt.NoModifier[, touchPoints={}]]])
Parameters:

使用给定的eventType、device、touchPoints以及事件发生时的当前键盘modifiers构造一个QTouchEvent。

__repr__()
Return type:

字符串

target()
Return type:

QObject

返回窗口中发生事件的目标对象。这通常是一个QWidget或QQuickItem。当没有特定目标可用时，可能为0。

touchPoints()
Return type:

QEventPoint的列表

注意

此函数已弃用。

请使用points()代替。

返回对触摸事件中包含的触摸点列表的引用。

另请参阅

point() pointCount()