class QTouchEvent#

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

Inheritance diagram of PySide6.QtGui.QTouchEvent

4.6版本新增。

概要#

方法#

注意

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

详细描述#

启用触摸事件#

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

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

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

事件处理#

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

与小部件不同，QWindows始终接收触摸事件，无需进行选择。当直接与QWindow操作时，只需要重写touchEvent()方法。

当接收到QEvent::TouchBegin事件的小部件或项目确定要处理该事件时，会发送QEvent::TouchUpdate和QEvent::TouchEnd事件。如果未接受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的发送是独立的。可以使用application flags Qt::AA_SynthesizeTouchForUnhandledMouseEvents和Qt::AA_SynthesizeMouseForUnhandledTouchEvents来启用或禁用将触摸事件自动合成到鼠标事件和将鼠标事件合成到触摸事件。

注意事项#

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

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

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

另请参阅

QEventPoint State acceptTouchEvents()

__init__(eventType[, device=None[, modifiers=Qt.NoModifier[, touchPoints={}]]])#
参数：

使用另一个构造函数。

根据给定的 eventType、device、touchPoints 和事件的当前键盘 modifiers 创建一个 QTouchEvent。

__init__(arg__1)
参数：

arg__1 – QTouchEvent

__repr__()#
返回类型：

对象

target()#
返回类型：

QObject

返回在事件发生的窗口中目标对象。通常是 QWidget 或 QQuickItem。如果没有特定的目标，可能为 0。

touchPoints()#
返回类型：

+.列表QEventPoint

注意

此函数已废弃。

请使用 points() 代替。

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

另请参阅

point() pointCount()