# 画面設計書 27-Inputs

## 概要

本ドキュメントは、Dear ImGuiのデモセクション「Inputs & Focus」の設計書です。Demo Window内の折りたたみセクションとして、キーボード・マウス入力およびフォーカス制御のデモンストレーションを行います。

### 本画面の処理概要

**業務上の目的・背景**：本セクションは、Dear ImGuiにおける入力処理とフォーカス制御の包括的なリファレンスです。マウス位置、ボタン状態、キーボード入力、修飾キー、ショートカットキー、マウスカーソル、タブ移動、フォーカス制御など、インタラクティブなGUIアプリケーションに必要な入力関連機能を網羅しています。ゲーム、ツール、エディタなど、キーボードショートカットやマウス操作を多用するアプリケーションの開発において参考となります。

**画面へのアクセス方法**：Demo Windowの「Inputs & Focus」CollapsingHeaderをクリックすることでセクションが展開されます。DemoWindowInputs関数がShowDemoWindow()から呼び出されることで表示されます。

**主要な操作・処理内容**：
1. Inputs - 現在の入力状態の表示（マウス位置、ボタン、キー等）
2. Outputs - ImGuiの出力フラグ（WantCaptureMouse等）の表示
3. WantCapture override - WantCapture動作のオーバーライドデモ
4. Shortcuts - ショートカットキーとルーティングポリシー
5. Mouse Cursors - マウスカーソルの種類とプレビュー
6. Tabbing - Tabキーによるフォーカス移動
7. Focus from code - コードからのフォーカス制御
8. Dragging - マウスドラッグの検出
9. Mouse Buttons - マウスボタンの操作

**画面遷移**：Demo Windowの一部として表示されます。CollapsingHeaderで折りたたみ/展開可能です。各サブセクションはTreeNodeで階層化されています。

**権限による表示制御**：本セクションでは権限による表示制御は実装されていません。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 229 | IsKeyDown | 主機能 | キー押下判定のデモ |
| 230 | IsKeyPressed | 主機能 | キープレス判定のデモ |
| 235 | IsMouseDown | 主機能 | マウスボタン判定のデモ |
| 236 | IsMouseClicked | 主機能 | マウスクリック判定のデモ |
| 241 | GetMousePos | 主機能 | マウス位置取得のデモ |
| 240 | IsMouseDragging | 補助機能 | マウスドラッグ判定のデモ |
| 233 | Shortcut | 補助機能 | ショートカットキーのデモ |

## 画面種別

デモセクション（CollapsingHeader）

## URL/ルーティング

N/A（Dear ImGuiはImmediate Mode GUIライブラリのため、URL/ルーティングの概念は適用されません）

## 入出力項目

| 項目名 | 型 | 入力/出力 | 説明 |
|--------|-----|----------|------|
| なし | - | - | 本セクションは引数を受け取らない |

## 表示項目

### Inputs セクション
| 項目名 | 表示形式 | 説明 |
|--------|----------|------|
| Mouse pos | Text | マウス位置座標（x, y） |
| Mouse delta | Text | マウス移動量 |
| Mouse down | Text | 押下中のマウスボタンと時間 |
| Mouse wheel | Text | マウスホイールの回転量 |
| Mouse clicked count | Text | 各ボタンのクリック回数 |
| Keys down | Text | 押下中のキー名とコード |
| Keys mods | Text | 押下中の修飾キー（Ctrl/Shift/Alt/Super） |
| Chars queue | Text | 入力キュー内の文字 |

### Outputs セクション
| 項目名 | 表示形式 | 説明 |
|--------|----------|------|
| io.WantCaptureMouse | Text | ImGuiがマウス入力を要求しているか |
| io.WantCaptureKeyboard | Text | ImGuiがキーボード入力を要求しているか |
| io.WantTextInput | Text | テキスト入力が必要か |
| io.NavActive/Visible | Text | キーボードナビゲーション状態 |

### Shortcuts セクション
| 項目名 | 表示形式 | 説明 |
|--------|----------|------|
| ルーティングオプション | CheckboxFlags/RadioButton | Repeat, RouteActive/Focused/Global/Always |
| SetNextItemShortcutデモ | Button/SliderFloat | Ctrl+S, Alt+Fのショートカット |
| Shortcut()デモ | Text/BeginChild | Ctrl+Aのルーティングテスト |

### Mouse Cursors セクション
| 項目名 | 表示形式 | 説明 |
|--------|----------|------|
| Current cursor | Text | 現在のカーソル種類 |
| カーソルプレビュー | Selectable | 各カーソル種類のホバープレビュー |

## イベント仕様

### 1-入力状態の取得

ImGuiIOから各種入力状態を取得します。io.MousePos、io.MouseDown[]、io.MouseDownDuration[]、io.MouseWheel、io.KeyCtrl/Shift/Alt/Super等。

### 2-キー判定

IsKeyDown(key)でキーが押下中か判定します。IsKeyPressed(key)でキーが押されたフレームか判定します。

### 3-マウスボタン判定

IsMouseDown(button)でボタンが押下中か判定します。IsMouseClicked(button)でクリックされたか判定します。

### 4-ショートカット

Shortcut(key_chord, flags)でショートカットキーを判定します。SetNextItemShortcut()で次のウィジェットにショートカットを関連付けます。

### 5-マウスカーソル変更

SetMouseCursor(cursor)で現在のマウスカーソルを変更します。ImGuiMouseCursor_Arrow、TextInput、ResizeAll等が使用可能です。

### 6-タブ移動

Tabキーでフォーカスを次のウィジェットに移動します。Shift+Tabで前のウィジェットに移動します。ImGuiItemFlags_NoTabStopでタブ移動をスキップできます。

### 7-コードからのフォーカス制御

SetKeyboardFocusHere(offset)で相対位置のウィジェットにフォーカスを設定します。offset=0で次のウィジェット、-1で前のウィジェットです。

### 8-WantCaptureオーバーライド

SetNextFrameWantCaptureMouse/Keyboard(value)でWantCaptureフラグを手動で設定できます。

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

N/A（本デモセクションはデータベースを使用しません。すべてのデータはローカル変数またはstatic変数で管理されます）

## メッセージ仕様

| メッセージID | 種別 | 表示条件 | メッセージ内容 |
|--------------|------|----------|----------------|
| なし | - | - | 本セクションではメッセージ表示なし |

## 例外処理

| 例外状況 | 処理内容 |
|----------|----------|
| CollapsingHeaderが折りたたまれている場合 | 早期リターンで処理をスキップ |
| マウス位置が無効な場合 | IsMousePosValid()でチェックし、"<INVALID>"を表示 |

## 備考

- io.WantCaptureMouse/Keyboardは、アプリケーション側で入力をImGuiに渡すかどうかを判断するために使用
- ショートカットのルーティングは、複数のウィンドウ/ウィジェットが同じキーを使用する場合の優先順位を決定
- ImGuiInputFlags_RouteGlobalはグローバルショートカット、RouteActiveはアクティブアイテム優先、RouteFocusedはフォーカスウィンドウ優先
- マウスカーソルはio.MouseDrawCursorがtrueの場合、ImGuiが描画し、falseの場合はバックエンドが処理
- キーボードナビゲーション（io.NavActive）はゲームパッドやキーボードでのUI操作を可能にする

---

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

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

### 推奨読解順序

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

処理の起点となる関数を特定します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | imgui_demo.cpp | `imgui_demo.cpp` | DemoWindowInputs関数（行7802-8200+）がエントリーポイント |

**主要処理フロー**:
1. **行7804**: CollapsingHeader("Inputs & Focus")で折りたたみセクションを開始
2. **行7806**: ImGuiIO& io = ImGui::GetIO()で入力状態を取得
3. **行7810-7841**: Inputsセクション
4. **行7844-7888**: Outputsセクション
5. **行7900-7989**: Shortcutsセクション
6. **行7992-8018**: Mouse Cursorsセクション
7. **行8021-8035**: Tabbingセクション
8. **行8037以降**: Focus from code等のセクション

#### Step 2: 入力状態の取得を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | imgui_demo.cpp | `imgui_demo.cpp` | Inputsセクション（行7810-7841）を理解する |

**主要処理フロー**:
- **行7819-7822**: マウス位置（IsMousePosValidでチェック）
- **行7823**: マウス移動量（io.MouseDelta）
- **行7825**: 押下中のマウスボタン（IsMouseDown + MouseDownDuration）
- **行7826**: マウスホイール（io.MouseWheel）
- **行7828**: クリック回数（io.MouseClickedCount）
- **行7836**: 押下中のキー（IsKeyDown + GetKeyName）
- **行7837**: 修飾キー（io.KeyCtrl/Shift/Alt/Super）
- **行7838**: 入力キュー（io.InputQueueCharacters）

#### Step 3: ショートカットを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | imgui_demo.cpp | `imgui_demo.cpp` | Shortcutsセクション（行7900-7989）を理解する |

**主要処理フロー**:
- **行7903-7925**: ルーティングオプションの設定UI
- **行7927-7933**: SetNextItemShortcut()の使用例
- **行7937-7985**: Shortcut()のルーティングテスト（WindowA、ChildD、ChildE、PopupF）

#### Step 4: マウスカーソルを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | imgui_demo.cpp | `imgui_demo.cpp` | Mouse Cursorsセクション（行7992-8018）を理解する |

**主要処理フロー**:
- **行7995-7996**: カーソル種類の名前配列
- **行7998-8000**: 現在のカーソル種類を取得・表示
- **行8010-8017**: 各カーソルのホバープレビュー

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

```
ShowDemoWindow()
    |
    +-- DemoWindowInputs()
            |
            +-- ImGui::CollapsingHeader("Inputs & Focus")
            |
            +-- TreeNode("Inputs")
            |       |
            |       +-- ImGui::GetIO() [入力状態取得]
            |       +-- IsMousePosValid() / GetMousePos()
            |       +-- IsMouseDown() / IsKeyDown()
            |       +-- GetKeyName()
            |
            +-- TreeNode("Outputs")
            |       |
            |       +-- io.WantCaptureMouse / WantCaptureKeyboard
            |       +-- io.WantTextInput / WantSetMousePos
            |       +-- io.NavActive / NavVisible
            |       |
            |       +-- TreeNode("WantCapture override")
            |               +-- SetNextFrameWantCaptureMouse/Keyboard()
            |
            +-- TreeNode("Shortcuts")
            |       |
            |       +-- CheckboxFlags() [ルーティングオプション]
            |       +-- RadioButton() [ルーティングタイプ]
            |       +-- SetNextItemShortcut(ImGuiMod_Ctrl | ImGuiKey_S)
            |       +-- Shortcut(ImGuiMod_Ctrl | ImGuiKey_A)
            |       +-- BeginChild() [ショートカットスコープテスト]
            |
            +-- TreeNode("Mouse Cursors")
            |       |
            |       +-- GetMouseCursor()
            |       +-- Selectable() + SetMouseCursor() [ホバー時]
            |
            +-- TreeNode("Tabbing")
            |       |
            |       +-- InputText() [複数]
            |       +-- PushItemFlag(ImGuiItemFlags_NoTabStop)
            |
            +-- TreeNode("Focus from code")
                    |
                    +-- Button("Focus on N") + SetKeyboardFocusHere()
                    +-- InputText() [フォーカス対象]
```

### データフロー図

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

ハードウェア入力 ------> ImGuiIO構造体 -------------------> 入力状態表示
(マウス/キーボード)           |                                |
                              |                                v
                              |                           io.MousePos
                              |                           io.KeysDown
                              |                           io.MouseDown
                              v
キー押下 --------------> IsKeyDown/Pressed() ------------> キー状態
                              |
                              v
ショートカット --------> Shortcut() ----------------------> アクション実行
(Ctrl+A等)                    |
                              |
ルーティング -----------> RouteActive/Focused/Global -----> 優先順位決定
                              |
                              v
                         SetNextItemShortcut() -----------> ウィジェット連動
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| imgui_demo.cpp | `imgui_demo.cpp` | ソース | DemoWindowInputs関数の実装（行7799-8200+） |
| imgui.h | `imgui.h` | ヘッダー | 入力関連API定義（IsKeyDown, GetMousePos等） |
| imgui.h | `imgui.h` | ヘッダー | ImGuiIO構造体の定義 |
| imgui.cpp | `imgui.cpp` | ソース | 入力関連関数の実装 |
