QTouchEvent 类

详细说明

启用触摸事件

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

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

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

事件处理

所有触摸事件都是类型 QEvent::TouchBegin、QEvent::TouchUpdate、QEvent::TouchEnd 或 QEvent::TouchCancel。要对小部件接收触摸事件，请重写 QWidget::event() 或对图形视图中的项重写 QAbstractScrollArea::viewportEvent() 或 QGraphicsItem::sceneEvent()。

与小部件不同，QWindows 总是接收触摸事件，无需注册。当直接与一个 QWindow 交互时，只需重新实现 QWindow::touchEvent() 即可。

当接收到 QEvent::TouchBegin 事件的小部件或项目之后，会发送 QEvent::TouchUpdate 和 QEvent::TouchEnd 事件。如果 QEvent::TouchBegin 事件未被接收也没被事件过滤器过滤，那么在下一个 QEvent::TouchBegin 事件之前，不会发送更多的触摸事件。

一些系统可能会发送类型为 QEvent::TouchCancel 的事件。接收到此事件后，应用程序应忽略当前 active 的触摸序列。例如，在一个合成的系统中，合成器可能决定将某些手势视为全局手势。每次做出此类决定（手势被识别）时，客户端会收到一个 QEvent::TouchCancel 事件，以便他们相应地更新状态。

可以使用 pointCount() 和 point() 函数来访问和遍历单个触摸点。

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

事件投递和传播

默认情况下，QGuiApplication 将 QTouchEvent 中的第一个触摸点转换为 QMouseEvent。这使得可以启用现有小部件上的触摸事件，而无需通常是处理 QTouchEvent 的。有关详细信息，请参阅下文有关执行此操作时需要考虑的一些特殊情况。

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

触摸点分组

如前所述，可能有多个 Widgets 同时接收 QTouchEvents。但是，Qt 确保不会向同一个 Widgets 重复发送 QEvent::TouchBegin 事件，这种事件在实际传播过程中可能发生，例如，如果用户在一个 QGroupBox 中触摸了 2 个不同的 Widgets，且两个 Widgets 都忽略了 QEvent::TouchBegin 事件。

为了防止这种情况，Qt 将使用以下规则来将新的触摸点组合在一起。

• 当检测到第一次触摸点时，首先通过屏幕位置确定目标小部件，其次通过传播规则。
• 当检测到额外的触摸点时，Qt 首先查看新触摸点下是否存在任何父或子小部件上活跃的触摸点。如果有，新的触摸点将与第一个触摸点分组，并且新的触摸点将以单个 QTouchEvent发送到处理第一个触摸点的小部件。（新触摸点下的小部件将不会收到事件）。

这使得同级别小部件能够独立处理触摸事件，同时确保 QTouchEvents 的序列始终正确。

鼠标事件和触摸事件合成

QTouchEvent 的交付独立于 QMouseEvent。可以使用应用程序标志 Qt::AA_SynthesizeTouchForUnhandledMouseEvents 和 Qt::AA_SynthesizeMouseForUnhandledTouchEvents 来启用或禁用将触摸事件自动合成到鼠标事件，以及将鼠标事件合成到触摸事件的自动合成。

注意事项

• 如上所述，启用触摸事件意味着多个小部件可以同时接收触摸事件。结合对 QTouchEvents 的默认 QWidget::event() 处理，这对设计触摸用户界面提供了极大的灵活性。请注意其后果。例如，用户可能用一只手指移动一个 QSlider，而用另一只手指按下一个 QPushButton。这些小部件发出的信号将交织在一起。
• 在 QTouchEvent 事件处理程序中使用 exec() 方法之一（例如，QDialog::exec() 或 QMenu::exec()）来递归到事件循环中是不支持的。由于有多个事件接收者，递归可能引起问题，包括但不限于丢失事件和意外无限递归。
• 当有多个活跃的触摸点时，QTouchEvents 不会被 mouse grab 或 active pop-up widget 影响。当打开弹出窗口或鼠标被捕获时，QTouchEvents 的行为是未定义的。