QGestureRecognizer Class
QGestureRecognizer 클래스는 제스처 인식을 위한 인프라를 제공합니다. 더 보기...
| 헤더: | #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에서의 제스처 처리 개요 및 애플리케이션에서 제스처를 사용하는 방법에 대한 정보는 ‘위젯 및 그래픽 뷰의 제스처(Gestures in Widgets and Graphics View )’ 문서를 참조하십시오.
제스처 인식
제스처를 인식하는 과정에는 특정 객체로 전송된 입력 이벤트를 필터링하고, 관련 QGesture 객체를 수정하여 사용자 입력에 대한 관련 정보를 포함시키는 작업이 포함됩니다.
제스처는 프레임워크가 ` create()`를 호출하여 ` QWidget ` 또는 ` QGraphicsObject ` 하위 클래스의 특정 인스턴스에 대한 사용자 입력을 처리할 때 생성됩니다. 제스처를 사용하도록 구성된 각 위젯이나 항목에 대해 ` QGesture ` 객체가 생성됩니다.
대상 객체에 대해 QGesture 가 생성되면, 제스처 인식기는 recognize() 핸들러 함수를 통해 해당 객체에 대한 이벤트를 수신하게 됩니다.
제스처가 취소되면 reset() 함수가 호출되어, 인식기가 해당 QGesture 객체의 적절한 속성을 업데이트할 수 있게 됩니다.
새로운 제스처 지원
새로운 제스처를 지원하려면, QGestureRecognizer를 상속받아 사용자 정의 인식기 클래스를 생성하고, 이 클래스의 인스턴스를 생성한 다음, QGestureRecognizer::registerRecognizer()를 호출하여 애플리케이션에 등록해야 합니다. 또한 QGesture 를 상속받아 사용자 정의 제스처 클래스를 만들거나, 동적 속성을 활용하여 처리하려는 제스처의 구체적인 세부 사항을 표현할 수도 있습니다.
사용자 정의 QGestureRecognizer 서브클래스는 QWidget 및 QGraphicsObject 서브클래스에 대한 입력 이벤트를 처리하고 필터링하기 위해 recognize() 함수를 재구현해야 합니다. 제스처 인식 로직은 이 함수에서 구현되지만, 인식 프로세스의 상태에 대한 영구적인 정보는 제공된 QGesture 객체에 저장할 수 있습니다. recognize() 함수는 주어진 제스처와 대상 객체에 대한 인식 상태를 나타내는 QGestureRecognizer::Result 값을 반환해야 합니다. 이 값에 따라 제스처 이벤트가 대상 객체에 전달될지 여부가 결정됩니다.
사용자 정의 ` QGesture ` 하위 클래스를 사용하여 제스처를 표현하기로 선택한 경우, 제스처 클래스의 인스턴스를 생성하기 위해 ` create()` 함수를 재구현해야 합니다. 마찬가지로, 제스처가 취소될 때 사용자 정의 제스처 객체를 특별히 처리해야 하는 경우 ` reset()` 함수를 재구현해야 할 수도 있습니다.
QGesture도 참조하십시오 .
멤버 유형 문서
enum 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 | 이 힌트는 제스처 프레임워크가 필터링된 이벤트를 직접 처리하고 수신자에게 전달하지 않아야 함을 지정합니다. |
Result 유형은 QFlags<ResultFlag>에 대한 typedef입니다. 이 유형은 ResultFlag 값들의 OR 조합을 저장합니다.
QGestureRecognizer::recognize()도 참조하십시오 .
멤버 함수 문서
QGestureRecognizer::QGestureRecognizer()
새로운 제스처 인식기 객체를 생성합니다.
[virtual noexcept] QGestureRecognizer::~QGestureRecognizer()
제스처 인식기를 제거합니다.
[virtual] QGesture *QGestureRecognizer::create(QObject *target)
이 함수는 Qt에 의해 호출되어, 지정된 target (QWidget 또는 QGraphicsObject)에 대한 새로운 QGesture 객체를 생성합니다.
필요한 경우 이 함수를 재구현하여 사용자 정의 QGesture 파생 제스처 객체를 생성하십시오.
QApplication 생성된 제스처 객체의 소유권을 인수합니다.
[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를 반환합니다.
QApplication recognizer 의 소유권을 인수하며, 이 함수는 해당 객체와 연관된 제스처 유형 ID를 반환합니다. 사용자 정의 객체를 처리하는 제스처 인식기( () 함수에서 를 반환하는 경우)의 경우, 반환 값은 플래그가 설정된 생성된 제스처 ID입니다. QGesture QGesture::gestureType Qt::CustomGesture Qt::CustomGesture
unregisterRecognizer(), QGestureRecognizer::create() 및 QGesture도 참조하십시오 .
[virtual] void QGestureRecognizer::reset(QGesture *gesture)
이 함수는 Qt XML에서 지정된 gesture 객체를 초기화하기 위해 호출됩니다.
사용자 정의 QGesture 객체에 대한 추가 요구 사항을 구현하려면 이 함수를 재구현하십시오. 제스처가 재설정될 때 속성을 특별히 처리해야 하는 사용자 정의 QGesture 를 구현하는 경우, 이 작업이 필요할 수 있습니다.
[static] void QGestureRecognizer::unregisterRecognizer(Qt::GestureType type)
지정된 ` type`의 모든 제스처 인식기를 등록 해제합니다.
registerRecognizer()도 참조하십시오 .
© 2026 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.
