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 オブジェクトの作成と管理、およびQWidgetQGraphicsObject サブクラスに送られる入力イベントの監視を担当します。QGestureRecognizer は、カスタム・ジェスチャーを実装するための基本クラスです。

標準的なジェスチャのジェスチャ認識のみを提供する必要がある開発者は、このクラスを直接使用する必要はありません。インスタンスは、フレームワークによって舞台裏で作成されます。

Qt におけるジェスチャ処理の概要と、アプリケーションでジェスチャを使用するための情報については、「ウィジェットとグラフィックスビューにおけるジェスチャ」を参照してください。

ジェスチャの認識

ジェスチャーを認識するプロセスでは、特定のオブジェクトに送られた入力イベントをフィルタリングし、関連するQGesture オブジェクトを修正して、ユーザーの入力に関する関連情報を含めることになります。

ジェスチャーは、フレームワークがQWidget またはQGraphicsObject サブクラスの特定のインスタンスのユーザー入力を処理するためにcreate() を呼び出すときに作成されます。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::Ignore0x0001イベントはレコグナイザの状態を変更しません。
QGestureRecognizer::MayBeGesture0x0002イベントはレコグナイザの内部状態を変更したが、それがジェスチャーかどうかはまだ明確ではない。レコグナイザは決定するために、より多くのイベントをフィルターする必要があります。MayBeGesture状態のジェスチャ認識器は、ジェスチャの認識に時間がかかりすぎる場合、自動的にリセットされることがあります。
QGestureRecognizer::TriggerGesture0x0004ジェスチャーがトリガーされ、適切なQGesture オブジェクトがQGestureEvent の一部としてターゲットに配信されます。
QGestureRecognizer::FinishGesture0x0008ジェスチャーが正常に終了し、適切なQGesture オブジェクトがQGestureEvent の一部としてターゲットに配信されます。
QGestureRecognizer::CancelGesture0x0010イベントにより、ジェスチャーではないことが明確になりました。ジェスチャレコグナイザが以前に GestureTriggered 状態であった場合、ジェスチャはキャンセルされ、適切なQGesture オブジェクトがQGestureEvent の一部としてターゲットに配信されます。
QGestureRecognizer::ConsumeEventHint0x0100このヒントは、ジェスチャーフレームワークがフィルタリングされたイベントを消費し、レシーバーに配信しないことを指定します。

Result 型は、QFlags<ResultFlag> の typedef です。これは、ResultFlag 値の OR の組み合わせを格納します。

QGestureRecognizer::recognize()も参照してください

メンバ関数のドキュメント

QGestureRecognizer::QGestureRecognizer()

新しいジェスチャー認識オブジェクトを構築します。

[virtual noexcept] QGestureRecognizer::~QGestureRecognizer()

ジェスチャー認識機能を破棄します。

[virtual] QGesture *QGestureRecognizer::create(QObject *target)

この関数は、与えられたtarget (QWidget またはQGraphicsObject) に対して新しいQGesture オブジェクトを作成するために Qt によって呼び出されます。

必要に応じてこの関数を再実装して、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 を返すもの)の場合、返り値はQt::CustomGesture フラグが設定された生成ジェスチャ ID になります。

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.