直感的な理解
Composeにおけるすべてのタッチジェスチャーは同じ形で始まる。Modifier.pointerInput
ブロックと、そこに渡すsuspend関数だ。変わるのはどの関数を使うかであり、それぞれが同じ生のポインターイベントストリームに対する、1種類のジェスチャーに特化した専用のループになっているからだ。
間違った関数を選ぶと、APIと戦うことになる(タップを検出するために自分でオフセットの生データをパースする)か、求めてもいないデータを渡される(ドラッグだけのジェスチャーに対して回転の値が渡される)ことになる。
detectTapGestures:動かない単一のポイント向け。タップ、ダブルタップ、長押し。detectDragGestures(とその水平/垂直版の兄弟):一度に1方向だけ動く単一のポイント向け。detectTransformGestures:同時に2本以上の指向け。ピンチ、パン、回転。
タップ、ダブルタップ、長押し:detectTapGestures
Modifier.pointerInput(Unit) {
detectTapGestures(
onTap = { /* 単一タップ */ },
onDoubleTap = { /* ダブルタップ判定ウィンドウ内の2回目のタップ */ },
onLongPress = { /* 長押しのしきい値を超えて保持された */ },
onPress = { /* 押下ごとに発火する。Composeがこのジェスチャーが
最終的に何として解決されるかを知る前に呼ばれる */ }
)
}onPressはPressGestureScopeのラムダなので、awaitRelease()と
tryAwaitRelease()を使える。これにより他のコールバックをブロックせずに
リリースを検出できるので、押し続ける系のフィードバックに便利だ。
渡したコールバックだけが組み込まれる。onTapだけを渡すと、Composeは
ダブルタップ判定ウィンドウを待つことをしなくなるので、単発のタップは
2回目のタップが続くかどうかを待たずに即座に解決される。
Modifier.clickableが提供していないものが必要なときは、こちらを使おう。
ダブルタップでいいね、長押しでコンテキストメニュー、自分で制御する
押下状態のスケールや色の変化などだ。
clickableに重ねて使わないこと
すでにModifier.clickable/combinedClickableが設定されているノードに
detectTapGesturesを追加すると、同じポインターストリームに対して
競合する2つのジェスチャー検出器が設置されることになり、clickableが
無料で提供してくれるリップルやアクセシビリティのセマンティクスを
失ってしまう。どちらか一方にしよう。
単一軸のドラッグ:detectDragGesturesとその水平/垂直版のペア
Modifier.pointerInput(Unit) {
detectDragGestures(
onDragStart = { offset -> /* 指がタッチスロップを超えて動いた */ },
onDrag = { change, dragAmount -> change.consume() /* dragAmount: Offset、両軸分 */ },
onDragEnd = { /* 指が離れた */ },
onDragCancel = { /* ジェスチャーが中断された。例:別のポインターが引き継いだ */ }
)
}onDragはPointerInputChangeに加えてdragAmount: Offsetも渡してくる。
これは前回のイベントからの差分であって、ドラッグの総移動距離ではない。
change.consume()は自分で呼ぶ必要があり、detectDragGesturesが
勝手にジェスチャーを確保してくれるわけではない。
consumeされないドラッグは親にリークする
change.consume()を省略すると、ジェスチャーがもたついて感じられる
だけでは済まない。ツリーの上位にある親のscrollable/verticalScrollは
ポインターがすでに確保済みであることを知らないままになり、ドラッグと
同時にスクロールしてしまう。
detectHorizontalDragGesturesとdetectVerticalDragGesturesは同じ形を
しているが、次元が1つ少ない。onHorizontalDrag/onVerticalDragは
OffsetではなくFloatの差分を渡してくるし、ジェスチャーを開始するには
その軸の
だけを超えればよい。ジェスチャーが本当に一方向だけのものである場合
(スワイプ可能な行、縦方向のスライダーなど)は、2軸版よりもこちらを
使おう。そうすれば斜め方向の指の動きが間違った軸でジェスチャーを
確定させることもなく、その上にある縦方向のリストも通常どおり
スクロールできる。
ピンチ、パン、回転:detectTransformGestures
Modifier.pointerInput(Unit) {
detectTransformGestures(
panZoomLock = false
) { centroid, pan, zoom, rotation ->
/* centroid: Offset、アクティブなポインター間の中点
pan: Offset、前回のイベントからの移動量
zoom: Float、前回のイベントからの拡大率(1fは変化なし)
rotation: Float、前回のイベントからの回転角度 */
}
}
があるからこそ、detectTransformGesturesは4つではなく1つの
コールバックを受け取る。パン、ズーム、回転は別々のジェスチャーではなく、
Composeが毎フレーム同じマルチポインターイベントから導き出す3つの数値
にすぎないので、タップと長押しの間にあるような「どちらに解決するか」を
決める必要がないのだ。
panZoomLock = trueは名前が示唆するものと正反対のことをする。
回転のほうをロックして締め出すのであって、パンやズームではない。
ジェスチャーがどのしきい値を最初に超えるかで、以後そのジェスチャー全体の
形状が決まる。パン/ズームが先なら、その後は回転は0fのままになる。
これはピンチズーム式の画像ビューアーや地図で有用だ。パンとズームは
欲しいが、2本指でのピンチが意図しない回転としても読み取られてほしく
ない場合だ。パン、ズーム、回転の3つを1つのジェスチャーで組み合わせる
クロップツールは、falseのままにしておくべきケースだ。
zoomとrotationは総量ではなく差分
zoomとrotationは前回のイベントからの変化量であって、ジェスチャーの
累積総量ではない。自分のアキュムレーターには乗算して加えよう
(scale *= zoom)。代入(scale = zoom)してはいけない。そうしないと
変換が毎フレームリセットされてしまい、積み上がっていかない。
どれを選ぶか
| 関数 | ポインター数 | コールバック | 差分の形 |
|---|---|---|---|
detectTapGestures | 1、動かない | onTap、onDoubleTap、onLongPress、onPress | なし、位置のみ |
detectDragGestures | 1、動く | onDragStart、onDrag、onDragEnd、onDragCancel | イベントごとにOffset |
detectHorizontalDragGestures / detectVerticalDragGestures | 1、単一軸で動く | 同じ形、onHorizontalDrag/onVerticalDrag | イベントごとにFloat |
detectTransformGestures | 2以上 | onGestureコールバック1つ | centroid、pan:Offset;zoom、rotation:Float |
検出器を組み合わせる、そしてその下にあるプリミティブ
1つのModifier.pointerInputブロックは、1つのdetect*Gestures呼び出し
しか実行できない。なぜならそれぞれが(awaitEachGestureの上に構築
された)無限ループであり、ブロックが生きている間は決して戻らないからだ。
同じブロックの中でdetectTapGestures(...)の後にdetectDragGestures(...)
を書いても、両者が競合することはなく、2つ目の呼び出しは単に到達不能な
コードになるだけだ。同じノードでタップとドラッグの両方が必要な場合は、
それぞれに独自のpointerInputモディファイアを与える必要がある。
Composeは両方を並行して実行し、それぞれが同じ生のストリームを独立に
監視する。
どちらのポインターが2つ目の検出器に対して使える状態のままかは、
タッチスロップと、どちらのPointerInputChangeが先にconsumeされるかに
よって決まる。これはこのブログが単独で取り上げている仕組みだ。
これらの関数はすべて、PointerInputScopeが実際に公開している
より低レベルのプリミティブであるawaitPointerEventScope/
awaitEachGestureを使って書かれたループだ。上記の4つのいずれも
当てはまらない場合、例えばストリームの途中で何を待ち受けているかを
切り替える必要があるカスタムの多段階ジェスチャーなどの場合にだけ、
直接そこまで降りていく。
ラムダが実際に読んでいるものでpointerInputをキーする
これら4つはすべてModifier.pointerInput(key)を通じてインストール
される。ラムダが変化する状態をクロージャーで捉えているときに
Unitをキーにすると、ブロックは再インストールされず、最初の
コンポジション時点でのその状態をずっと読み続けてしまう。コールバックが
読む状態をキーにするか、代わりにrememberUpdatedStateを通じてその
状態を読もう。



