QTouchEvent Class

详细说明

启用触摸事件

当在触摸设备（如触摸屏或触控板）上按下、松开或移动一个或多个触点时，会触发触摸事件。要接收触摸事件，小部件必须设置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::TouchUpdate 和QEvent::TouchEnd 事件会被发送到已接受QEvent::TouchBegin 事件的控件或项目。如果QEvent::TouchBegin 事件未被接受，且未被事件过滤器过滤，则直到下一次QEvent::TouchBegin 发生前，都不会发送任何后续触摸事件。

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

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

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

事件传递与传播

默认情况下，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 发送给处理了第一个触摸点的小部件。 （新触摸点下方的控件不会收到事件）。

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

鼠标事件与触摸事件的合成

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

注意事项

• 如上所述，启用触摸事件意味着多个控件可以同时接收触摸事件。结合QWidget::event()对QTouchEvent的默认处理机制，这为设计触摸用户界面提供了极大的灵活性。请注意其潜在影响。例如，用户可能用一只手指拖动QSlider ，同时用另一只手指点击QPushButton 。 这些控件发出的信号将会交错出现。
• 在 QTouchEvent 事件处理程序中，不支持使用 exec() 方法（例如QDialog::exec() 或QMenu::exec()）递归进入事件循环。由于存在多个事件接收者，递归可能会导致问题，包括但不限于事件丢失和意外的无限递归。
• QTouchEvent 不受mouse grab 或active pop-up widget 的影响。当存在多个活动触点时，若在此期间打开弹出窗口或抓取鼠标，QTouchEvent 的行为将未定义。