# 機能設計書 49-InputElement

## 概要

本ドキュメントは、Avalonia UIフレームワークにおけるInputElement（入力要素基底クラス）機能の設計仕様を定義する。InputElementはユーザー入力（キーボード、マウス、タッチ）を受け付けるすべてのコントロールの基底クラスである。

### 本機能の処理概要

InputElementクラスは、フォーカス管理、キーボード入力、ポインター（マウス/タッチ）入力、ジェスチャー認識など、ユーザー入力に関連するすべての機能を提供する基底クラスである。Controlクラスの直接の基底クラスとして、すべてのUIコントロールに入力機能を提供する。

**業務上の目的・背景**：UIアプリケーションではユーザーからの入力を受け付けることが必須である。InputElementはキーボード、マウス、タッチなど様々な入力デバイスからの入力を統一的に処理し、イベントとして派生クラスに通知する。

**機能の利用シーン**：Button、TextBox、ListBoxなどすべてのインタラクティブコントロールの基底として使用される。フォーカス制御、キー入力処理、クリック検出、ジェスチャー認識などで利用される。

**主要な処理内容**：
1. フォーカス状態の管理（IsFocused、Focusable、IsKeyboardFocusWithin）
2. 有効/無効状態の管理（IsEnabled、IsEffectivelyEnabled）
3. ヒットテストの制御（IsHitTestVisible）
4. キーボードイベント処理（KeyDown、KeyUp、TextInput）
5. ポインターイベント処理（PointerEntered、PointerMoved、PointerPressed等）
6. ジェスチャー認識（Tapped、DoubleTapped、RightTapped、Holding）
7. タブナビゲーション（TabIndex、IsTabStop）

**関連システム・外部連携**：FocusManager、InputManager、GestureRecognizerCollectionと連携する。

**権限による制御**：本機能に権限による制御はない。すべてのアプリケーションで使用可能である。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| すべて | すべての画面 | 継承 | すべてのControlがInputElementを継承 |

## 機能種別

基底クラス / 入力処理 / イベント管理 / フォーカス管理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| Focusable | bool | No | フォーカス可能か | デフォルト: false |
| IsEnabled | bool | No | 有効か | デフォルト: true |
| IsHitTestVisible | bool | No | ヒットテスト対象か | デフォルト: true |
| IsTabStop | bool | No | タブストップか | デフォルト: true |
| TabIndex | int | No | タブ順序 | int値 |
| Cursor | Cursor | No | マウスカーソル | - |

### 入力データソース

- InputManager: キーボード・ポインターイベント
- FocusManager: フォーカス変更通知

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| IsFocused | bool | 現在フォーカスを持っているか |
| IsKeyboardFocusWithin | bool | 子孫にフォーカスがあるか |
| IsEffectivelyEnabled | bool | 実効的に有効か（親の状態も考慮） |
| IsPointerOver | bool | ポインターが上にあるか |
| KeyBindings | List<KeyBinding> | キーバインディングリスト |
| GestureRecognizers | GestureRecognizerCollection | ジェスチャー認識器 |

### 出力先

- イベント: 多数のルーテッドイベント（後述）

## 処理フロー

### 処理シーケンス

```
1. InputElement 構築
   └─ 擬似クラス初期化（:disabled, :focus等）

2. ビジュアルツリーへの接続
   └─ IsEffectivelyEnabled更新

3. フォーカス取得
   └─ Focus() → FocusManager.Focus()
   └─ GotFocusイベント発火

4. キーボード入力
   └─ KeyDownイベント発火
   └─ TextInputイベント発火
   └─ KeyUpイベント発火

5. ポインター入力
   └─ PointerEntered/Moved/Pressed/Released
   └─ ジェスチャー認識（Tapped等）

6. フォーカス喪失
   └─ LostFocusイベント発火
```

### フローチャート

```mermaid
flowchart TD
    A[InputElement] --> B{ユーザー操作}
    B -->|クリック| C[PointerPressed]
    B -->|キー入力| D[KeyDown]
    B -->|フォーカス| E[Focus()]
    C --> F[GestureRecognizers処理]
    F --> G{Tapped?}
    G -->|Yes| H[Tappedイベント]
    G -->|No| I{DoubleTapped?}
    I -->|Yes| J[DoubleTappedイベント]
    D --> K[OnKeyDown]
    E --> L[FocusManager.Focus]
    L --> M[GotFocusイベント]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | 有効性継承 | IsEffectivelyEnabledは親の状態を継承 | 常時適用 |
| BR-002 | フォーカス条件 | Focusable && IsEffectivelyEnabled && IsVisible | Focus時 |
| BR-003 | 無効化時フォーカス解除 | IsEffectivelyEnabled=falseでフォーカス解除 | 無効化時 |
| BR-004 | 擬似クラス連動 | :disabled, :focus, :focus-visible, :pointerover | 状態変更時 |

### 計算ロジック

**IsEffectivelyEnabledの計算**：
```
IsEffectivelyEnabled = IsEnabledCore && (Parent?.IsEffectivelyEnabled ?? true)
```

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

本機能はデータベース操作を行わない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | - | - | 入力処理でのエラーは発生しない設計 |

### リトライ仕様

リトライは適用されない。

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

トランザクション管理は不要。

## パフォーマンス要件

- 入力イベント処理は1ms以内
- フォーカス遷移は即座に完了
- IsEffectivelyEnabled更新は子孫全体を効率的に更新

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

特になし。

## 備考

- すべてのControlはInputElementを継承
- カスタムジェスチャーはGestureRecognizersに追加

---

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

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

### 推奨読解順序

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

InputElementクラスのプロパティ定義を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | プロパティ定義 | `src/Avalonia.Base/Input/InputElement.cs` | 24-123行目。StyledProperty/DirectProperty各種 |
| 1-2 | フィールド | `src/Avalonia.Base/Input/InputElement.cs` | 225-230行目。状態管理フィールド |
| 1-3 | 擬似クラス属性 | `src/Avalonia.Base/Input/InputElement.cs` | 18行目。:disabled, :focus等の定義 |

**読解のコツ**: StyledPropertyとDirectPropertyの使い分け。DirectPropertyは高頻度更新やバインディング不要な状態に使用。

#### Step 2: ルーテッドイベントを理解する

入力関連のルーテッドイベント定義。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | フォーカスイベント | `src/Avalonia.Base/Input/InputElement.cs` | 82-101行目。GotFocus、LostFocus等 |
| 2-2 | キーイベント | `src/Avalonia.Base/Input/InputElement.cs` | 106-131行目。KeyDown、KeyUp、TextInput |
| 2-3 | ポインターイベント | `src/Avalonia.Base/Input/InputElement.cs` | 144-203行目。PointerXxx系イベント |
| 2-4 | ジェスチャーイベント | `src/Avalonia.Base/Input/InputElement.cs` | 206-223行目。Tapped、DoubleTapped等 |

**読解のコツ**: RoutingStrategies（Tunnel/Bubble/Direct）がイベントの伝播方向を決定。

#### Step 3: 静的コンストラクタを理解する

イベントハンドラの登録。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | 静的コンストラクタ | `src/Avalonia.Base/Input/InputElement.cs` | 235-269行目。ClassHandler登録 |

**主要処理フロー**:
- **237行目**: IsEnabledProperty.Changed購読
- **239-258行目**: 各イベントのAddClassHandler
- **261-264行目**: ジェスチャー用ハンドラ（handledEventsToo: true）
- **268行目**: アクセスキーハンドラ

#### Step 4: フォーカス処理を理解する

フォーカス取得・喪失の処理。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Focus メソッド | `src/Avalonia.Base/Input/InputElement.cs` | 574-577行目。FocusManagerへの委譲 |
| 4-2 | OnGotFocusCore | `src/Avalonia.Base/Input/InputElement.cs` | 612-618行目。フォーカス取得処理 |
| 4-3 | OnLostFocusCore | `src/Avalonia.Base/Input/InputElement.cs` | 640-645行目。フォーカス喪失処理 |

**主要処理フロー**:
- **574-577行目**: FocusManager.GetFocusManager().Focus()呼び出し
- **614行目**: フォーカス取得時のフォーカス可視フラグ設定
- **615-616行目**: IsFocused設定とイベントハンドラ呼び出し

#### Step 5: IsEffectivelyEnabled処理を理解する

有効状態の伝播処理。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | UpdateIsEffectivelyEnabled | `src/Avalonia.Base/Input/InputElement.cs` | 1024-1027行目。更新トリガー |
| 5-2 | UpdateIsEffectivelyEnabled(parent) | `src/Avalonia.Base/Input/InputElement.cs` | 1059-1075行目。再帰的更新 |
| 5-3 | IsEffectivelyEnabled setter | `src/Avalonia.Base/Input/InputElement.cs` | 531-545行目。状態設定と副作用 |

**主要処理フロー**:
- **1061行目**: IsEnabledCore && 親のIsEffectivelyEnabled
- **1069-1074行目**: 子孫への再帰的伝播
- **537行目**: :disabled擬似クラス設定
- **539-543行目**: 無効化時のフォーカス解除

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

```
InputElement 静的コンストラクタ
    │
    └─ AddClassHandler各種
           ├─ GotFocusEvent → OnGotFocusCore
           ├─ LostFocusEvent → OnLostFocusCore
           ├─ KeyDownEvent → OnKeyDown
           ├─ KeyUpEvent → OnKeyUp
           ├─ TextInputEvent → OnTextInput
           ├─ PointerXxxEvent → OnPointerXxx
           └─ GestureEvents → OnTapped等

Focus()
    │
    └─ FocusManager.GetFocusManager(this)?.Focus(this, ...)

OnGotFocusCore
    │
    ├─ _isFocusVisible設定
    ├─ IsFocused = true
    └─ OnGotFocus (仮想メソッド)

UpdateIsEffectivelyEnabled
    │
    └─ UpdateIsEffectivelyEnabled(parent)
           │
           ├─ IsEffectivelyEnabled = IsEnabledCore && parent?.IsEffectivelyEnabled
           │      ├─ PseudoClasses.Set(":disabled", ...)
           │      └─ フォーカス解除（必要時）
           │
           └─ 子孫への再帰呼び出し
```

### データフロー図

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

マウスクリック ─────────▶ PointerPressedEvent ──────────▶ OnPointerPressed
                              │
                              ▼
                    GestureRecognizers処理
                              │
                              ▼
                         TappedEvent
                              │
                              ▼
                    [アプリケーション処理]

キーボード入力 ─────────▶ KeyDownEvent ────────────────▶ OnKeyDown
                              │
                              ▼
                    [キー処理/KeyBindings]

フォーカス要求 ─────────▶ Focus() ─────────────────────▶ FocusManager
                              │
                              ▼
                         GotFocusEvent
                              │
                              ▼
                    [IsFocused = true]
                    [:focus擬似クラス]
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| InputElement.cs | `src/Avalonia.Base/Input/InputElement.cs` | ソース | InputElementクラスの実装 |
| IInputElement.cs | `src/Avalonia.Base/Input/IInputElement.cs` | ソース | インターフェース定義 |
| FocusManager.cs | `src/Avalonia.Base/Input/FocusManager.cs` | ソース | フォーカスマネージャー |
| KeyboardNavigation.cs | `src/Avalonia.Base/Input/KeyboardNavigation.cs` | ソース | キーボードナビゲーション |
| GestureRecognizerCollection.cs | `src/Avalonia.Base/Input/GestureRecognizers/GestureRecognizerCollection.cs` | ソース | ジェスチャー認識 |
| Interactive.cs | `src/Avalonia.Base/Interactivity/Interactive.cs` | ソース | 基底クラス |
