# 機能設計書 52-MouseDevice

## 概要

本ドキュメントは、Avaloniaフレームワークにおけるマウスデバイス（MouseDevice）機能の設計仕様を定義する。MouseDeviceは、マウス入力イベントの処理、ポインター位置の管理、およびマウスボタン状態の追跡を担当するコア入力処理コンポーネントである。

### 本機能の処理概要

MouseDeviceは、Avaloniaアプリケーションにおけるマウス入力のハンドリングを一元的に管理するクラスである。プラットフォームから受信した生のマウスイベントを処理し、適切なUI要素にルーティングされたイベントとして配信する。ダブルクリック検出、ホイールスクロール、ジェスチャー認識などの高度な機能も提供する。

**業務上の目的・背景**：マウスはデスクトップアプリケーションにおける最も基本的なポインティングデバイスである。MouseDeviceは、クロスプラットフォームで一貫したマウス入力処理を提供し、開発者がプラットフォーム固有の実装を意識することなくマウスイベントを処理できるようにする。クリック、ドラッグ、ホバー、スクロールなどの操作を統一的に実装できる。

**機能の利用シーン**：
- ボタンクリックやメニュー選択
- ドラッグ＆ドロップ操作
- コントロールへのホバー効果
- スクロールビューでのホイールスクロール
- タッチパッドジェスチャー（ピンチ、回転、スワイプ）

**主要な処理内容**：
1. プラットフォームからの生マウスイベント（RawPointerEventArgs）の受信と解析
2. マウスボタンの押下・解放イベント処理（MouseDown/MouseUp）
3. マウス移動イベント処理（MouseMove）
4. ホイールスクロールイベント処理（MouseWheel）
5. ダブルクリック検出（クリック回数カウント）
6. タッチパッドジェスチャー処理（Magnify、Rotate、Swipe）
7. ポインターキャプチャ管理

**関連システム・外部連携**：InputManager、GestureRecognizer、Pointerクラスと連携し、入力処理パイプラインを構成する。プラットフォーム層から生イベントを受信する。

**権限による制御**：特になし。すべてのUIコンポーネントがマウス入力を受信可能。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 23 | Cursor | 主機能 | カーソル設定のデモ。マウスカーソルスタイル変更 |
| 45 | Pointers | 主機能 | ポインター入力のデモ。マウス入力とポインター位置管理 |
| 95 | Pointer | 主機能 | ポインターのテスト |

## 機能種別

入力デバイス管理 / イベント処理 / ポインター管理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| RawPointerEventArgs | RawPointerEventArgs | Yes | 生ポインターイベントデータ | nullチェック |

### 入力データソース

- プラットフォーム固有のマウスドライバ（Win32、X11、Cocoa等）
- InputManager経由で配信される生入力イベント

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| PointerPressedEventArgs | PointerPressedEventArgs | マウスボタン押下イベント |
| PointerReleasedEventArgs | PointerReleasedEventArgs | マウスボタン解放イベント |
| PointerEventArgs | PointerEventArgs | マウス移動イベント |
| PointerWheelEventArgs | PointerWheelEventArgs | ホイールスクロールイベント |
| PointerDeltaEventArgs | PointerDeltaEventArgs | ジェスチャーイベント（Magnify/Rotate/Swipe） |

### 出力先

- ヒットテストで特定されたInputElement（イベント配信先）
- キャプチャされたInputElement（キャプチャ時）

## 処理フロー

### 処理シーケンス

```
1. ProcessRawEvent受信
   └─ RawPointerEventArgsをMouseDeviceが受信
2. デバイス状態チェック
   └─ Disposedチェック
3. イベント種別判定
   └─ ボタン押下/解放/移動/ホイール/ジェスチャーを判定
4. ターゲット要素決定
   └─ Captured ?? HitTest結果
5. ルーテッドイベント生成・発火
   └─ 各種PointerEventArgsを生成してRaiseEvent
6. ハンドル状態反映
   └─ イベントのHandledプロパティを生イベントに反映
```

### フローチャート

```mermaid
flowchart TD
    A[ProcessRawEvent開始] --> B{Handled or Disposed?}
    B -->|Yes| Z[処理終了]
    B -->|No| C{イベント種別判定}
    C -->|LeaveWindow| D[LeaveWindow処理]
    C -->|ButtonDown| E[MouseDown処理]
    C -->|ButtonUp| F[MouseUp処理]
    C -->|Move| G[MouseMove処理]
    C -->|Wheel| H[MouseWheel処理]
    C -->|Magnify/Rotate/Swipe| I[ジェスチャー処理]
    E --> J[キャプチャ設定]
    J --> K[ClickCount計算]
    K --> L[PointerPressedEvent発火]
    F --> M[PointerReleasedEvent発火]
    M --> N[キャプチャ解除]
    G --> O[PointerMovedEvent発火]
    H --> P[PointerWheelEvent発火]
    I --> Q[PointerDeltaEvent発火]
    D --> Z
    L --> Z
    N --> Z
    O --> Z
    P --> Z
    Q --> Z
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-52-01 | キャプチャ優先 | マウスイベントはCaptured要素に優先的に配信 | Capturedがnullでない場合 |
| BR-52-02 | ヒットテストフォールバック | Capturedがnullの場合はヒットテスト結果に配信 | Captured == null |
| BR-52-03 | 暗黙キャプチャ | MouseDown時に自動的にキャプチャを設定 | ボタン押下時 |
| BR-52-04 | キャプチャ解除 | MouseUp時（ボタンカウント0）にキャプチャを解除 | 最後のボタン解放時 |
| BR-52-05 | ダブルクリック判定 | 時間とエリア内での連続クリックをカウント | PlatformSettings設定に基づく |

### 計算ロジック

**ダブルクリック判定**：
- 前回クリック位置からdoubleClickSize範囲内
- 前回クリックからdoubleClickTime以内
- 上記条件を満たさない場合clickCount = 0にリセット

## データベース操作仕様

### 操作別データベース影響一覧

該当なし（UIフレームワークのためデータベース操作は行わない）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | ArgumentNullException | 必須パラメータがnull | 呼び出し元でのnullチェック |

### リトライ仕様

該当なし

## トランザクション仕様

該当なし

## パフォーマンス要件

- マウスイベント処理は16ms以内（60fps維持のため）
- ヒットテスト処理はビジュアルツリー深度に依存

## セキュリティ考慮事項

- マウス位置情報のログ出力は最小限に抑える
- スクリーン座標からウィンドウ座標への変換時にオーバーフローを防止

## 備考

- MouseDeviceはPrivateApiとしてマークされており、直接のインスタンス化は非推奨
- Primary静的プロパティでシングルトンインスタンスを取得可能
- IDisposable実装により、リソースの適切な解放をサポート

---

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

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

### 推奨読解順序

#### Step 1: データ構造を理解する

マウスイベント処理で使用される型定義を先に把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Pointer.cs | `src/Avalonia.Base/Input/Pointer.cs` | Pointerクラスの定義、キャプチャ管理 |
| 1-2 | PointerPoint.cs | `src/Avalonia.Base/Input/PointerPoint.cs` | ポインター位置とプロパティ |
| 1-3 | PointerEventArgs.cs | `src/Avalonia.Base/Input/PointerEventArgs.cs` | 各種ポインターイベント引数 |

**読解のコツ**: PointerはID、Type（Mouse/Touch/Pen）、キャプチャ状態を管理する。Captured/CapturedGestureRecognizerでイベントルーティング先を制御。

#### Step 2: エントリーポイントを理解する

マウス入力処理の開始点を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | MouseDevice.cs | `src/Avalonia.Base/Input/MouseDevice.cs` | ProcessRawEventメソッドがエントリーポイント |

**主要処理フロー**:
1. **49-53行目**: ProcessRawEvent(RawInputEventArgs)の入口
2. **71-126行目**: ProcessRawEvent(RawPointerEventArgs)でイベント種別に応じた処理分岐
3. **81-126行目**: switch文でRawPointerEventTypeを判定

#### Step 3: マウスボタン処理を理解する

ボタン押下・解放の処理ロジックを把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | MouseDevice.cs | `src/Avalonia.Base/Input/MouseDevice.cs` | MouseDown/MouseUpメソッド |

**主要処理フロー**:
- **138-175行目**: MouseDownメソッド
  - **145行目**: InputHitTestでターゲット決定
  - **149行目**: 暗黙キャプチャ設定
  - **157-165行目**: ダブルクリック判定
  - **169行目**: PointerPressedEventArgs生成・発火
- **202-233行目**: MouseUpメソッド
  - **212行目**: PointerReleasedEventArgs生成
  - **224行目**: キャプチャ解除

#### Step 4: ジェスチャー処理を理解する

タッチパッドジェスチャーの処理を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | MouseDevice.cs | `src/Avalonia.Base/Input/MouseDevice.cs` | GestureMagnify/Rotate/Swipeメソッド |

**主要処理フロー**:
- **256-274行目**: GestureMagnify - 拡大縮小ジェスチャー
- **276-294行目**: GestureRotate - 回転ジェスチャー
- **296-314行目**: GestureSwipe - スワイプジェスチャー

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

```
InputManager.ProcessRawEvent
    │
    └─ MouseDevice.ProcessRawEvent(RawInputEventArgs)
           │
           └─ ProcessRawEvent(RawPointerEventArgs)
                  │
                  ├─ MouseDown
                  │      ├─ Pointer.Capture
                  │      └─ target.RaiseEvent(PointerPressedEventArgs)
                  │
                  ├─ MouseUp
                  │      ├─ GestureRecognizer.PointerReleasedInternal
                  │      ├─ target.RaiseEvent(PointerReleasedEventArgs)
                  │      └─ Pointer.Capture(null)
                  │
                  ├─ MouseMove
                  │      ├─ GestureRecognizer.PointerMovedInternal
                  │      └─ target.RaiseEvent(PointerMovedEvent)
                  │
                  ├─ MouseWheel
                  │      └─ target.RaiseEvent(PointerWheelEventArgs)
                  │
                  └─ GestureMagnify/Rotate/Swipe
                         └─ target.RaiseEvent(PointerDeltaEventArgs)
```

### データフロー図

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

RawPointerEventArgs ───▶ MouseDevice ───▶ PointerPressedEventArgs
  ├─ Position              ├─ HitTest                    ├─▶ target.RaiseEvent
  ├─ Type                  ├─ ClickCount計算
  └─ InputModifiers        └─ Capture管理
                                                    PointerReleasedEventArgs
                                                         └─▶ target.RaiseEvent

                                                    PointerEventArgs (Move)
                                                         └─▶ target.RaiseEvent

                                                    PointerWheelEventArgs
                                                         └─▶ target.RaiseEvent
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| MouseDevice.cs | `src/Avalonia.Base/Input/MouseDevice.cs` | ソース | メインクラス、マウス入力処理 |
| IMouseDevice.cs | `src/Avalonia.Base/Input/IMouseDevice.cs` | ソース | インターフェース定義 |
| Pointer.cs | `src/Avalonia.Base/Input/Pointer.cs` | ソース | ポインター管理、キャプチャ |
| PointerPoint.cs | `src/Avalonia.Base/Input/PointerPoint.cs` | ソース | ポインター位置・プロパティ |
| PointerEventArgs.cs | `src/Avalonia.Base/Input/PointerEventArgs.cs` | ソース | ポインターイベント引数基底 |
| PointerPressedEventArgs.cs | `src/Avalonia.Base/Input/PointerPressedEventArgs.cs` | ソース | ボタン押下イベント |
| PointerReleasedEventArgs.cs | `src/Avalonia.Base/Input/PointerReleasedEventArgs.cs` | ソース | ボタン解放イベント |
| PointerWheelEventArgs.cs | `src/Avalonia.Base/Input/PointerWheelEventArgs.cs` | ソース | ホイールイベント |
| PointerDeltaEventArgs.cs | `src/Avalonia.Base/Input/PointerDeltaEventArgs.cs` | ソース | ジェスチャーイベント |
| InputElement.cs | `src/Avalonia.Base/Input/InputElement.cs` | ソース | ポインターイベント定義 |
