QTouchEvent Class

詳細な説明

タッチ イベントの有効化

タッチイベントは、タッチデバイス（タッチスクリーンやトラックパッドなど）上で 1 つ以上のタッチポイントを押したり、指を離したり、移動したりしたときに発生します。タッチイベントを受信するには、ウィジェットに `Qt::WA_AcceptTouchEvents ` 属性を設定し、グラフィックアイテムに `acceptTouchEvents ` 属性を `true` に設定する必要があります。

QAbstractScrollArea ベースのウィジェットを使用する場合は、スクロール領域の `viewport` で `Qt::WA_AcceptTouchEvents ` 属性を有効にする必要があります。

QMouseEvent と同様に、Qt はウィジェット内での最初のタップ時に各タッチポイントを自動的に取得し、そのタッチポイントが離されるまで、ウィジェットはそのタッチポイントに関するすべての更新情報を受け取ります。ウィジェットが多数のタッチポイントに関するイベントを受け取る可能性があり、複数のウィジェットが同時にタッチイベントを受け取っている場合があることに注意してください。

イベント処理

すべてのタッチイベントは、QEvent::TouchBegin 、QEvent::TouchUpdate 、QEvent::TouchEnd 、またはQEvent::TouchCancel のいずれかの型です。タッチイベントを受信するには、ウィジェットの場合はQWidget::event()またはQAbstractScrollArea::viewportEvent()を、グラフィックスビュー内のアイテムの場合はQGraphicsItem::sceneEvent()を再実装してください。

ウィジェットとは異なり、QWindowsは常にタッチイベントを受信するため、明示的に有効にする必要はありません。QWindow を直接扱う場合は、QWindow::touchEvent()を再実装するだけで十分です。

QEvent::TouchUpdate およびQEvent::TouchEnd イベントは、QEvent::TouchBegin イベントを受け入れたウィジェットまたはアイテムに送信されます。QEvent::TouchBegin イベントが受け入れられず、かつイベントフィルタによってフィルタリングされていない場合、次のQEvent::TouchBegin が発生するまで、それ以降のタッチイベントは送信されません。

一部のシステムでは、QEvent::TouchCancel 型のイベントを送信する場合があります。このイベントを受信すると、アプリケーションはアクティブなタッチシーケンス全体を無視するよう求められます。たとえば、コンポジットシステムでは、コンポジターが特定のジェスチャーをシステム全体のジェスチャーとして扱うことを決定する場合があります。 そのような決定（ジェスチャーの認識）が行われるたびに、クライアントには `QEvent::TouchCancel ` イベントが通知され、それに応じて状態を更新できるようになります。

pointCount() およびpoint() 関数を使用することで、個々のタッチポイントにアクセスし、それらを反復処理することができます。

points() 関数は、イベントに含まれるすべてのタッチポイントのリストを返します。なお、このリストは、たとえばQEvent::TouchCancel イベントの場合など、空になることがある点に注意してください。各ポイントは、QEventPoint クラスのインスタンスです。QEventPoint::State 列挙型は、タッチポイントが取り得るさまざまな状態を表します。

イベントの配信と伝播

デフォルトでは、QGuiApplication は QTouchEvent 内の最初のタッチポイントをQMouseEvent に変換します。これにより、通常は QTouchEvent を処理しない既存のウィジェットでもタッチイベントを有効にすることが可能になります。これを行う際に必要な特別な考慮事項については、以下を参照してください。

QEvent::TouchBegin は、ウィジェットに送信される最初のタッチイベントです。QEvent::TouchBegin イベントには、受信側がそのイベントを受け入れるかどうかを示す特別な受入フラグが含まれています。デフォルトでは、イベントは受け入れられます。タッチイベントが自身のウィジェットによって処理されない場合は、ignore()を呼び出す必要があります。QEvent::TouchBegin イベントは、ウィジェットがaccept()でイベントを受け入れるか、イベントフィルタがイベントを消費するまで、親ウィジェットチェーンを順に上へ伝播されます。QGraphicsItemの場合、QEvent::TouchBegin イベントはマウスの下にあるアイテムへ伝播されます（QGraphicsItemのマウスイベントの伝播と同様です）。

タッチポイントのグループ化

前述のように、複数のウィジェットが同時に QTouchEvent を受信する可能性があります。ただし、Qt では、同じウィジェットに対して重複したQEvent::TouchBegin イベントが送信されることが決してないようにしています。これは、例えばユーザーがQGroupBox 内の 2 つの別々のウィジェットに触れ、両方のウィジェットがQEvent::TouchBegin イベントを無視した場合など、伝播中に理論的には発生し得る事態です。

これを回避するため、Qtは以下のルールに従って新しいタッチポイントをグループ化します。

• 最初のタッチポイントが検出されると、対象ウィジェットは、まず画面上の位置によって、次に伝播ルールによって決定されます。
• 追加のタッチポイントが検出されると、Qtはまず、新しいタッチポイントの下にあるウィジェットの祖先または子孫のいずれかにアクティブなタッチポイントが存在するかどうかを確認します。存在する場合、新しいタッチポイントは最初のタッチポイントとグループ化され、新しいタッチポイントは単一のQTouchEventとして、最初のタッチポイントを処理したウィジェットに送信されます。 （新しいタッチポイントの下にあるウィジェットはイベントを受け取りません）。

これにより、QTouchEvent の順序が常に正しいことを保証しつつ、兄弟ウィジェットがタッチイベントを個別に処理することが可能になります。

マウスイベントとタッチイベントの合成

QTouchEventの配信は、QMouseEvent の配信とは独立しています。アプリケーションフラグQt::AA_SynthesizeTouchForUnhandledMouseEvents およびQt::AA_SynthesizeMouseForUnhandledTouchEvents を使用すると、タッチイベントからマウスイベントへの、およびマウスイベントからタッチイベントへの自動合成を有効または無効にすることができます。

注意点

• 前述の通り、タッチイベントを有効にすると、複数のウィジェットが同時にタッチイベントを受信できるようになります。これと、QTouchEvent に対するデフォルトのQWidget::event() 処理を組み合わせることで、タッチユーザーインターフェースの設計において非常に高い柔軟性が得られます。その影響について留意してください。例えば、ユーザーが片方の指でQSlider を移動させながら、もう片方の指でQPushButton を押しているといった状況が考えられます。 これらのウィジェットから発せられるシグナルは、互いに交錯することになります。
• QTouchEvent イベントハンドラ内で、exec() メソッド（例：QDialog::exec() やQMenu::exec()）のいずれかを使用してイベントループに再帰することはサポートされていません。イベントの受信者が複数存在するため、再帰によってイベントの損失や予期しない無限再帰など、問題が発生する可能性があります。
• QTouchEvent は、mouse grab やactive pop-up widget の影響を受けません。アクティブなタッチポイントが複数ある状態でポップアップを開いたり、マウスをグラブしたりした場合、QTouchEvent の挙動は未定義となります。