ウィジェットおよびグラフィックスビューにおけるジェスチャー

Qtには、使用される入力方式に依存せず、一連のイベントからジェスチャーを形成できるジェスチャープログラミング用のフレームワークが含まれています。ジェスチャーとは、マウスの特定の動き、タッチスクリーンでの操作、あるいはその他のソースからの一連のイベントなどを指します。入力の性質、ジェスチャーの解釈、および実行されるアクションは、開発者が選択します。

概要

QGesture は、Qtのジェスチャーフレームワークの中核となるクラスであり、ユーザーによって実行されたジェスチャーに関する情報を格納するコンテナを提供します。QGesture は、すべてのジェスチャーに共通する一般的な情報を提供するプロパティを公開しており、これらを拡張してジェスチャー固有の追加情報を提供することも可能です。一般的なパン、ピンチ、スワイプのジェスチャーは、QPanGesture 、QPinchGesture 、QSwipeGesture といった特殊化されたクラスによって表現されます。

開発者は、QGestureRecognizer クラスをサブクラス化して拡張することで、新しいジェスチャーを実装することもできます。新しいジェスチャーのサポートを追加するには、入力イベントからそのジェスチャーを認識するコードを実装する必要があります。これについては、「独自のジェスチャー認識器を作成する」セクションで説明しています。

ウィジェットでの標準ジェスチャーの使用

ジェスチャーは、QWidget およびQGraphicsObject のサブクラスのインスタンスに対して有効にできます。ジェスチャー入力を受け付けるオブジェクトは、このドキュメント全体を通じて「ターゲットオブジェクト」と呼ばれます。

ターゲットオブジェクトでジェスチャーを有効にするには、必要なジェスチャータイプを指定する引数を渡して、そのオブジェクトのQWidget::grabGesture()またはQGraphicsObject::grabGesture()関数を呼び出します。標準のタイプはQt::GestureType 列挙型で定義されており、一般的に使用される多くのジェスチャーが含まれています。

for (Qt::GestureType gesture : gestures)
    grabGesture(gesture);

上記のコードでは、ジェスチャーはターゲットオブジェクト自体のコンストラクタ内で設定されています。

イベントの処理

ユーザーがジェスチャーを実行すると、QGestureEvent イベントがターゲットオブジェクトに配信されます。これらは、ウィジェットの場合はQWidget::event()ハンドラ関数を、グラフィックスオブジェクトの場合はQGraphicsItem::sceneEvent()を再実装することで処理できます。

1つのターゲットオブジェクトが複数のジェスチャタイプを購読できるため、QGestureEvent には複数のQGesture が含まれることがあり、これは複数のジェスチャが同時にアクティブになっていることを示しています。その場合、それらの複数のジェスチャをどのように処理するか、また一部のジェスチャを他のジェスチャを優先してキャンセルするかどうかを決定するのは、ウィジェットの責任となります。

QGestureEvent オブジェクト内に含まれる各QGesture は、個別にaccept()またはignore()を行うことも、まとめて処理することも可能です。さらに、いくつかのゲッターを使用して、個々のQGesture データオブジェクト（状態）を照会することもできます。

イベント処理の標準手順

QGesture は、ウィジェットに到達した時点でデフォルトで受け入れられます。ただし、ジェスチャーは常に明示的に受け入れるか拒否することを推奨します。一般的なルールとして、ジェスチャーを受け入れる場合はそれを利用していること、無視する場合は関心がないことを意味します。ジェスチャーを無視すると、別のターゲットオブジェクトに提供されるか、キャンセルされる場合があります。

各QGesture はいくつかの状態を経由します。状態を変更する方法は明確に定義されており、通常はユーザー入力（例えば、インタラクションの開始や停止など）が状態変更の原因となりますが、ウィジェット自体も状態変更を引き起こすことがあります。

特定のQGesture がウィジェットまたはグラフィックアイテムに初めて配信された際、そのジェスチャーはQt::GestureStarted 状態になります。この時点でジェスチャーをどのように処理するかによって、後でそのジェスチャーと対話できるかどうかが決まります。

ジェスチャーを受け入れるとは、ウィジェットがそのジェスチャーに基づいて動作することを意味し、その後、Qt::GestureUpdated状態のジェスチャーが続きます。
ジェスチャーを無視すると、そのジェスチャーは二度と提供されなくなります。また、そのジェスチャーは親ウィジェットや親アイテムにも提供されます。
ジェスチャーが開始状態であり、かつ受け入れられている状態で setGestureCancelPolicy() を呼び出すと、他のジェスチャーがキャンセルされる可能性があります。

QGesture::CancelAllInContext を使用してジェスチャーをキャンセルすると、明示的に受け入れられていない限り、状態を問わずすべてのジェスチャーがキャンセルされます。これは、子ウィジェット上のアクティブなジェスチャーもキャンセルされることを意味します。また、ウィジェットがそれらを無視した場合、同じQGestureEvent で配信されたジェスチャーもキャンセルされることを意味します。これは、関心のあるジェスチャー以外のすべてをフィルタリングするのに役立つ方法です。

イベント処理の例

利便性を高めるため、「Image Gestures Example」では、汎用的なevent()ハンドラ関数を再実装し、ジェスチャイベントを専用のgestureEvent()関数に委譲しています：

bool ImageWidget::event(QEvent *event)
{
    if (event->type() == QEvent::Gesture)
        return gestureEvent(static_cast<QGestureEvent*>(event));
    return QWidget::event(event);
}

ターゲットオブジェクトに配信されたジェスチャーイベントは個別に確認し、適切に処理することができます：

bool ImageWidget::gestureEvent(QGestureEvent *event)
{
    qCDebug(lcExample) << "gestureEvent():" << event;
    if (QGesture *swipe = event->gesture(Qt::SwipeGesture))
        swipeTriggered(static_cast<QSwipeGesture *>(swipe));
    else if (QGesture *pan = event->gesture(Qt::PanGesture))
        panTriggered(static_cast<QPanGesture *>(pan));
    if (QGesture *pinch = event->gesture(Qt::PinchGesture))
        pinchTriggered(static_cast<QPinchGesture *>(pinch));
    return true;
}

ジェスチャーへの対応は、ターゲットオブジェクトに送信されたQGestureEvent に含まれるQGesture オブジェクトを取得し、そこに含まれる情報を確認するだけの簡単な作業です。

void ImageWidget::swipeTriggered(QSwipeGesture *gesture)
{
    if (gesture->state() == Qt::GestureFinished) {
        if (gesture->swipeAngle() < 45 || gesture->swipeAngle() > 225) {
            // swipe direction right or down
            qCDebug(lcExample) << "swipeTriggered(): angle"
                               << gesture->swipeAngle() << "; swipe to next";
            goNextImage();
        } else {
            // swipe direction left or up
            qCDebug(lcExample) << "swipeTriggered(): angle"
                               << gesture->swipeAngle() << "; swipe to previous";
            goPrevImage();
        }
        update();
    }
}

ここでは、ユーザーがウィジェットをスワイプした方向を確認し、それに応じてウィジェットの内容を変更します。

独自のジェスチャー認識器の作成

新しいジェスチャーへの対応を追加するには、新しいジェスチャー認識器を作成して登録する必要があります。ジェスチャーの認識プロセスによっては、新しいジェスチャーオブジェクトの作成も必要になる場合があります。

新しい認識器を作成するには、QGestureRecognizer をサブクラス化して、カスタム認識器クラスを作成する必要があります。再実装が必須の仮想関数が 1 つあり、必要に応じて再実装できる仮想関数が他に 2 つあります。

入力イベントのフィルタリング

recognize() 関数は再実装する必要があります。この関数は、対象オブジェクトに対する入力イベントを処理およびフィルタリングし、それらが認識器が検知しようとしているジェスチャーに対応しているかどうかを判断します。

ジェスチャー認識のロジックは、Qt::GestureState 列挙型に基づくステートマシンを使用してこの関数内で実装されますが、認識プロセスの状態に関する永続的な情報は、渡されるQGesture オブジェクトに格納することができます。

recognize() 関数は、指定されたジェスチャーおよびターゲットオブジェクトに対する認識状態を示すQGestureRecognizer::Result の値を返さなければなりません。これにより、ジェスチャーイベントがターゲットオブジェクトに配信されるかどうかが決まります。

カスタムジェスチャ

ジェスチャーをカスタムQGesture サブクラスで表現する場合は、create()関数を再実装し、標準のQGesture インスタンスの代わりに、独自のジェスチャークラスのインスタンスを生成する必要があります。あるいは、標準のQGesture インスタンスを使用しつつ、処理したいジェスチャーの具体的な詳細を表現するために、それらに動的なプロパティを追加することも可能です。

ジェスチャーのリセット

ジェスチャーがキャンセルされた際にリセットやその他の特別な処理が必要なカスタムジェスチャーオブジェクトを使用する場合、これらの特別な処理を実行するためにreset()関数を再実装する必要があります。

QGesture オブジェクトは、ターゲットオブジェクトとジェスチャタイプの各組み合わせに対して一度だけ作成され、ユーザーがターゲットオブジェクトに対して同じジェスチャタイプを実行しようとするたびに再利用される可能性があることに注意してください。そのため、ジェスチャの認識を試みた各試行の後にクリーンアップを行うために、reset()関数を再実装しておくと便利です。

新しいジェスチャー認識器の使用

ジェスチャー認識器を使用するには、QGestureRecognizer のサブクラスのインスタンスを作成し、QGestureRecognizer::registerRecognizer() を使用してアプリケーションに登録します。特定の種類のジェスチャーに対する認識器は、QGestureRecognizer::unregisterRecognizer() を使用して削除できます。