QGestureRecognizer Class
QGestureRecognizer 类为手势识别提供了基础架构。更多
Header: | #include <QGestureRecognizer> |
CMake: | find_package(Qt6 REQUIRED COMPONENTS Widgets) target_link_libraries(mytarget PRIVATE Qt6::Widgets) |
qmake: | QT += widgets |
公共类型
flags | Result |
enum | 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
flags 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值的OR组合。
另请参阅 QGestureRecognizer::recognize().
成员函数文档
QGestureRecognizer::QGestureRecognizer()
构建一个新的手势识别器对象。
[virtual noexcept]
QGestureRecognizer::~QGestureRecognizer()
销毁手势识别器。
[virtual]
QGesture *QGestureRecognizer::create(QObject *target)
Qt XML 调用此函数为给定的target (QWidget 或QGraphicsObject) 创建一个新的QGesture 对象。
如有必要,可重新实现该函数,以创建自定义的QGesture 衍生手势对象。
应用程序拥有所创建手势对象的所有权。
[pure virtual]
QGestureRecognizer::Result QGestureRecognizer::recognize(QGesture *gesture, QObject *watched, QEvent *event)
为watched 对象处理给定的event ,根据需要更新gesture 对象的状态,并为当前识别步骤返回合适的结果。
该函数由框架调用,允许识别器过滤发送到其监控的QWidget 或QGraphicsObject 实例的输入事件。
结果反映了手势被识别的程度。gesture 对象的状态将根据结果进行设置。
另请参阅 QGestureRecognizer::Result 。
[static]
Qt::GestureType QGestureRecognizer::registerRecognizer(QGestureRecognizer *recognizer)
在手势框架中注册给定的recognizer ,并返回其手势 ID。
应用程序获得recognizer 的所有权,并返回与其相关的手势类型 ID。对于处理自定义QGesture 对象(即在QGesture::gestureType() 函数中返回Qt::CustomGesture 的对象)的手势识别器,返回值是一个生成的手势 ID,并设置了Qt::CustomGesture 标志。
另请参阅 unregisterRecognizer(),QGestureRecognizer::create() 和QGesture 。
[virtual]
void QGestureRecognizer::reset(QGesture *gesture)
框架调用该函数重置给定的gesture 。
重新实现此函数可满足自定义QGesture 对象的其他要求。如果您实现的自定义QGesture 在重置手势时需要对其属性进行特殊处理,则有必要重新实现该函数。
[static]
void QGestureRecognizer::unregisterRecognizer(Qt::GestureType type)
取消注册指定type 的所有手势识别器。
另请参阅 registerRecognizer() 。
© 2025 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.