# 画面設計書 34-Gestures

## 概要

本ドキュメントは、ControlCatalogサンプルアプリケーションのGesturesページに関する画面設計書です。タッチジェスチャー認識機能のデモンストレーションを行うページです。

### 本画面の処理概要

Gesturesページは、Avaloniaフレームワークにおけるタッチ・ペン入力によるジェスチャー認識機能を確認するためのデモ画面です。プルジェスチャー、ピンチ/ズームジェスチャー、ピンチ/回転ジェスチャーの3種類のジェスチャーを学習・検証できます。

**業務上の目的・背景**：タッチデバイスやペンタブレットに対応したアプリケーションでは、直感的なジェスチャー操作が重要です。プルダウンリフレッシュ、ピンチズーム、回転操作などは、モバイルアプリケーションやタッチ対応デスクトップアプリケーションで広く使用されています。本画面は開発者がAvaloniaのジェスチャー認識機能を理解し、適切に実装する方法を学ぶために提供されています。

**画面へのアクセス方法**：ControlCatalogアプリケーションのMainViewから、HamburgerMenuナビゲーションを使用して「Gestures」を選択することでアクセスできます。

**主要な操作・処理内容**：
1. プルジェスチャー：4方向（上から下、下から上、左から右、右から左）のプル操作
2. ピンチ/ズームジェスチャー：マルチタッチによる画像の拡大縮小
3. スクロールジェスチャー：ズーム中の画像のパン操作
4. ピンチ/回転ジェスチャー：マルチタッチによる回転角度の制御
5. Resetボタン：ピンチ/ズーム状態のリセット

**画面遷移**：
- 遷移元：MainView（HamburgerMenuによるナビゲーション）
- 遷移先：なし（デモページのため他画面への遷移機能はなし）

**権限による表示制御**：特になし。すべてのユーザーが全機能を利用可能。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 55 | Gestures | 主機能 | ジェスチャー認識のデモ。タップ・ダブルタップ・長押し等 |
| 53 | TouchDevice | 補助機能 | タッチ入力とマルチタッチジェスチャー処理 |

## 画面種別

デモ/サンプル画面

## URL/ルーティング

HamburgerMenuナビゲーション経由でアクセス（Avalonia UIフレームワークのページベースナビゲーション）

## 入出力項目

| 項目名 | 入力/出力 | 型 | 説明 |
|--------|----------|------|------|
| プルジェスチャー | 入力 | PullGestureEventArgs | プル方向とデルタ値 |
| ピンチジェスチャー | 入力 | PinchGestureEventArgs | スケール値と回転角度 |
| スクロールジェスチャー | 入力 | ScrollGestureEventArgs | スクロールデルタ値 |
| AngleSlider | 入出力 | double | 回転角度（0-360度） |

## 表示項目

| 項目名 | 型 | 説明 |
|--------|------|------|
| Pull Gesture (Touch / Pen) タブ | TabItem | プルジェスチャーのデモ |
| TopPullZone | Border | 上から下へのプルエリア（赤枠） |
| BottomPullZone | Border | 下から上へのプルエリア（緑枠） |
| LeftPullZone | Border | 左から右へのプルエリア（オレンジ枠） |
| RightPullZone | Border | 右から左へのプルエリア（青枠） |
| Pinch/Zoom Gesture タブ | TabItem | ピンチズームジェスチャーのデモ |
| PinchImage | Image | ピンチズーム対象の画像 |
| ResetButton | Button | ズーム状態をリセットするボタン |
| Pinch/Rotation Gesture タブ | TabItem | ピンチ回転ジェスチャーのデモ |
| AngleSlider | Slider | 回転角度を表示・制御するスライダー |
| RotationGesture | Panel | 回転操作対象のパネル |

## イベント仕様

### 1-プルジェスチャー処理

各プルゾーンにPullGestureRecognizerが設定されており、タッチ/ペンでドラッグすると以下の処理が行われます：
- PullGestureEvent: ドラッグ中にボール（緑色の円）の位置がデルタ値に応じて移動
- PullGestureEndedEvent: ドラッグ終了時にボールが元の位置にアニメーションで戻る

### 2-ピンチズームジェスチャー処理

画像にPinchGestureRecognizerとScrollGestureRecognizerが設定されており：
- PinchEvent: マルチタッチによるピンチ操作でCompositionVisualのScaleが変更され、画像が拡大縮小
- PinchEndedEvent: ピンチ終了時に現在のスケール値を保存
- ScrollGestureEvent: ズーム中にスクロールジェスチャーで画像をパン（移動）

### 3-ピンチ回転ジェスチャー処理

RotationGestureパネルにPinchGestureRecognizerが設定されており、PinchEventでe.Angleの値をAngleSliderに設定し、RotateTransformによる回転が行われます。

### 4-Resetボタン処理

Resetボタンがクリックされると、画像のスケールが1に、オフセットが0にリセットされます。

## データベース更新仕様

本画面はデモ画面のため、データベース操作は行いません。

## メッセージ仕様

本画面には固有のメッセージ表示はありません。

## 例外処理

本画面はデモ画面のため、特別な例外処理は実装されていません。

## 備考

- PullGestureRecognizer: 一方向のプル（ドラッグ）を認識。PullDirectionで方向を指定
- PinchGestureRecognizer: 2本指によるピンチ操作を認識。Scale（拡大率）とAngle（回転角度）を取得可能
- ScrollGestureRecognizer: スクロール操作を認識。CanHorizontallyScroll/CanVerticallyScrollで方向を制御
- ElementComposition.GetElementVisual: 要素のCompositionVisualを取得し、高性能なアニメーション処理を実現
- ImplicitAnimations: プロパティ変更時に自動的にアニメーションを適用

---

## コードリーディングガイド

本画面を理解するために参照すべきファイルと、推奨する読み解き順序を以下に示す。

### 推奨読解順序

#### Step 1: UI定義を理解する

XAMLでジェスチャー認識器の設定とUI構造を定義しています。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | GesturePage.xaml | `samples/ControlCatalog/Pages/GesturePage.xaml` | GestureRecognizerの設定、タブ構造を理解 |

**読解のコツ**: 各コントロールのGestureRecognizersプロパティ内に設定されたPullGestureRecognizer、PinchGestureRecognizer、ScrollGestureRecognizerの設定を確認してください。

#### Step 2: コードビハインドを理解する

ジェスチャーイベントハンドラとCompositionVisualを使用したアニメーション処理を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | GesturePage.cs | `samples/ControlCatalog/Pages/GesturePage.cs` | イベントハンドラ設定、CompositionVisual操作を理解 |

**主要処理フロー**:
1. **行21-28**: OnAttachedToVisualTreeで初期化処理
2. **行32-35**: SetPullHandlersで各プルゾーンにイベントハンドラを設定
3. **行37-38**: SetPinchHandlersでピンチズーム対象にハンドラを設定
4. **行42-52**: Resetボタンのクリックハンドラでスケール・オフセットをリセット
5. **行55-58**: RotationGestureパネルのPinchEventでAngleSliderを更新
6. **行61-146**: SetPinchHandlersでピンチ・スクロールイベント処理
7. **行148-212**: SetPullHandlersでプルイベント処理とImplicitAnimations設定

### プログラム呼び出し階層図

```
GesturePage (UserControl)
    |
    +-- OnAttachedToVisualTree()
            |
            +-- SetPullHandlers(TopPullZone, false)
            +-- SetPullHandlers(BottomPullZone, true)
            +-- SetPullHandlers(RightPullZone, true)
            +-- SetPullHandlers(LeftPullZone, false)
            |       |
            |       +-- PullGestureEvent -> ボール位置更新
            |       +-- PullGestureEndedEvent -> ボール位置リセット
            |       +-- InitComposition() -> ImplicitAnimations設定
            |
            +-- SetPinchHandlers(PinchImage)
            |       |
            |       +-- PinchEvent -> Scale更新
            |       +-- PinchEndedEvent -> Scale保存
            |       +-- ScrollGestureEvent -> Offset更新
            |       +-- InitComposition() -> CompositionVisual取得
            |
            +-- ResetButton.Click -> Scale=1, Offset=0
            |
            +-- RotationGesture.PinchEvent -> AngleSlider.Value更新
```

### データフロー図

```
[入力]                    [処理]                         [出力]

プルジェスチャー ──────> PullGestureEvent ──────────────> ボール位置移動
                              |                          (Offset変更)
                              v
                        Delta * 0.4 * direction

ピンチジェスチャー ────> PinchEvent ────────────────────> 画像スケール変更
                              |                          (Scale変更)
                              v
                        _currentScale * e.Scale

スクロールジェスチャー ─> ScrollGestureEvent ───────────> 画像オフセット変更
                              |                          (Offset変更)
                              v
                        currentOffset += Delta

ピンチ回転 ────────────> PinchEvent.Angle ──────────────> 四角形回転
                              |                          (RotateTransform)
                              v
                        AngleSlider.Value = e.Angle
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| GesturePage.xaml | `samples/ControlCatalog/Pages/GesturePage.xaml` | XAML | UI定義、ジェスチャー認識器設定 |
| GesturePage.cs | `samples/ControlCatalog/Pages/GesturePage.cs` | ソース | コードビハインド、イベントハンドラ |
| delicate-arch-896885_640.jpg | `samples/ControlCatalog/Assets/delicate-arch-896885_640.jpg` | 画像 | ピンチズーム対象の画像 |
