QGestureRecognizer 类

QGestureRecognizer 类提供了手势识别的基础结构。更多...

头文件	#include <QGestureRecognizer>
CMake	find_package(Qt6 REQUIRED COMPONENTS Widgets) target_link_libraries(mytarget PRIVATE Qt6::Widgets)
qmake	QT += widgets

所有成员列表，包括继承成员

公共类型

flags	结果
枚举	ResultFlag { Ignore, MayBeGesture, TriggerGesture, FinishGesture, CancelGesture, ConsumeEventHint }

公共函数

	QGestureRecognizer()
virtual	~QGestureRecognizer()
virtual QGesture *	create(QObject *target)
virtual QGestureRecognizer::Result	recognize(QGesture *gesture, QObject *watched, QEvent *event) = 0
virtual void	reset(QGesture *gesture)

静态公共成员

Qt::GestureType	registerRecognizer(QGestureRecognizer *recognizer)
void	unregisterRecognizer(Qt::GestureType type)

详细描述

手势识别器负责创建和管理 QGesture 对象，并监控发送到 QWidget 和 QGraphicsObject 子类的输入事件。QGestureRecognizer 是实现自定义手势的基类。

只需要为标准手势提供识别功能的开发者不需要直接使用此类。实例将通过框架在幕后创建。

有关 Qt 中手势处理概述和使用手势的详细信息，请参阅 Widgets 和 Graphics View 中的手势文档。

识别手势

识别手势的过程涉及过滤发送到特定对象的输入事件，并修改相关的 QGesture 对象以包含有关用户输入的相关信息。

当框架调用 create() 处理特定实例的 QWidget 或 QGraphicsObject 子类的用户输入时创建手势。每个配置为使用手势的小部件或项目都会创建一个 QGesture 对象。

一旦为对象创建了一个QGesture，手势识别器就会在其recognize() 处理函数中接收该手势的事件。

当手势取消时，会调用reset() 函数，使得识别器有机会更新对应的QGesture 对象中的适当属性。

支持新手势

要添加对新手势的支持，需要从 QGestureRecognizer 派生以创建自定义识别器类，构造此类的实例，并通过调用 QGestureRecognizer::registerRecognizer() 在应用中注册它。您还可以通过创建自定义手势类来继承 QGesture，或利用动态属性来表达您想处理的手势的特定细节。

您的自定义 QGestureRecognizer 子类需要重写recognize() 函数来处理和过滤针对 QWidget 和 QGraphicsObject 子类传入的输入事件。尽管手势识别逻辑实现在此函数中，但您可以在提供的QGesture 对象中存储识别过程状态的持久信息。该recognize() 函数必须返回一个值为QGestureRecognizer::Result 的值，该值指示给定手势和目标对象的识别状态。这决定了是否将手势事件传递给目标对象。

如果您选择通过自定义 QGesture 子类来表示手势，则需要重写 create() 函数来构建手势类的实例。类似地，如果您的自定义手势对象需要在手势被取消时进行特殊处理，则可能需要重写 reset() 函数。

另请参阅QGesture。

成员类型文档

枚举 QGestureRecognizer::ResultFlag
标志 QGestureRecognizer::Result

此枚举描述了手势识别器状态机中当前事件过滤步骤的结果。

结果由状态值（Ignore、MayBeGesture、TriggerGesture、FinishGesture、CancelGesture 之一）和可选提示（ConsumeEventHint）组成。

常量	值	描述
`QGestureRecognizer::Ignore`	`0x0001`	该事件不会改变识别器的状态。
`QGestureRecognizer::MayBeGesture`	`0x0002`	事件改变了识别器的内部状态，但还不清楚它是否是手势。识别器需要过滤更多事件来决定。处于 MayBeGesture 状态的手势识别器，如果识别手势花费时间过长，可能会被自动重置。
`QGestureRecognizer::TriggerGesture`	`0x0004`	手势已被触发，适当的 QGesture 对象将作为QGestureEvent 的一部分传送到目标。
`QGestureRecognizer::FinishGesture`	`0x0008`	手势成功完成，适当的 QGesture 对象将作为 QGestureEvent 的一部分传送到目标。
`QGestureRecognizer::CancelGesture`	`0x0010`	事件清楚地表明，它不是一个手势。如果手势识别器在之前的 GestureTriggered 状态之前，则手势被取消，适当的 QGesture 对象将作为 QGestureEvent 的一部分传送到目标。
`QGestureRecognizer::ConsumeEventHint`	`0x0100`	此提示指定手势框架应该消耗过滤事件的筛选事件，并将其不传递给接收者。

结果类型是对 QFlags<ResultFlag> 的类型定义。它存储了 ResultFlag 值的或组合。

另请参阅QGestureRecognizer::recognize()。

成员函数文档

QGestureRecognizer::QGestureRecognizer()

构建一个新的手势识别器对象。

`[虚函数 noexcept]` QGestureRecognizer::~QGestureRecognizer()

销毁手势识别器。

`[虚函数]` QGesture *QGestureRecognizer::create(QObject **target*)

此函数由 Qt 调用，为给定的 target（QWidget 或 QGraphicsObject）创建一个新的 QGesture 对象。

如果需要，实现此函数以创建自定义的派生自 QGesture 的手势对象。

应用程序将拥有创建的手势对象。

`[纯虚函数]` QGestureRecognizer::Result QGestureRecognizer::recognize(QGesture **gesture*, QObject **watched*, QEvent **event*)

处理给定的 event 对象，更新 gesture 对象的状态，并返回当前识别步骤的合适结果。

此函数由框架调用，以允许识别器过滤传递给其监控的 QWidget 或 QGraphicsObject 实例的输入事件。

结果反映了识别的手势程度。根据结果设置 gesture 对象的状态。

另请参阅QGestureRecognizer::Result。

`[静态]` Qt::GestureType QGestureRecognizer::registerRecognizer(QGestureRecognizer **recognizer*)

将给定的 recognizer 在手势框架中注册，并返回相应的手势 ID。

应用程序接受 recognizer 的所有权并返回与之相关联的手势类型 ID。对于处理自定义 QGesture 对象的手势识别器（即，那些在 QGesture::gestureType() 函数中返回 Qt::CustomGesture 的识别器），返回值是随生成的手势 ID，其中设置了 Qt::CustomGesture 标志。

另请参阅unregisterRecognizer，QGestureRecognizer::create，和 QGesture。

`[虚函数]` void QGestureRecognizer::reset(QGesture **gesture*)

框架调用此函数以重置给定的 gesture。

实现此函数以实现自定义 QGesture 对象的额外要求。如果您实现了一个需要特殊处理重置时的属性的自定义 QGesture，则可能需要这么做。

`[静态]` void QGestureRecognizer::unregisterRecognizer(Qt::GestureType type)

注销指定类型的所有动作识别器。

另请参阅 registerRecognizer。