# 機能設計書 126-InputInt2/3/4

## 概要

本ドキュメントは、Dear ImGuiライブラリにおける複数要素整数入力機能「InputInt2」「InputInt3」「InputInt4」の設計仕様を定義する。

### 本機能の処理概要

InputInt2/3/4は、2〜4個の整数（int）を水平に並べて一度に入力・編集するためのウィジェット関数群である。ピクセル座標、矩形、複数のインデックス値など、複数の関連する整数を効率的に編集できる。

**業務上の目的・背景**：GUIアプリケーションにおいて、2D/3Dピクセル座標（X,Y,Z）、矩形（Left,Top,Right,Bottom）、タイルインデックスなど、複数の関連する整数をまとめて編集する場面は頻繁に発生する。InputInt2/3/4は、これらの値を単一のウィジェットとしてまとめて表示・編集することで、UIのコンパクト化とユーザー操作の効率化を実現する。

**機能の利用シーン**：
- 2Dピクセル座標の入力（InputInt2: X, Y）
- 3Dピクセル座標の入力（InputInt3: X, Y, Z）
- 矩形の入力（InputInt4: Left, Top, Right, Bottom）
- 配列インデックスの複数指定
- ベクトル要素（整数）の編集

**主要な処理内容**：
1. 指定された数の整数入力フィールドを水平に配置する
2. 各フィールドの幅を自動的に均等に分配する
3. "%d"フォーマットで各数値を表示する
4. 複数フィールドをグループとして管理し、統一されたIDを提供する

**関連システム・外部連携**：内部でInputScalarNを呼び出しており、データ型としてImGuiDataType_S32を使用する。

**権限による制御**：ImGuiInputTextFlags_ReadOnlyフラグにより読み取り専用モードを指定可能。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | Demo Window | 参照画面 | InputInt2/3/4のデモ表示 |
| 23 | Widgets | 参照画面 | ウィジェットデモでの表示 |

## 機能種別

数値入力ウィジェット / 複数要素対応

## 入力仕様

### 入力パラメータ（InputInt2）

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| label | const char* | Yes | ウィジェットの識別ラベル | NULL不可 |
| v | int[2] | Yes | 編集対象の2要素int配列 | NULL不可 |
| flags | ImGuiInputTextFlags | No | 入力動作を制御するフラグ | - |

### 入力パラメータ（InputInt3）

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| label | const char* | Yes | ウィジェットの識別ラベル | NULL不可 |
| v | int[3] | Yes | 編集対象の3要素int配列 | NULL不可 |
| flags | ImGuiInputTextFlags | No | 入力動作を制御するフラグ | - |

### 入力パラメータ（InputInt4）

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| label | const char* | Yes | ウィジェットの識別ラベル | NULL不可 |
| v | int[4] | Yes | 編集対象の4要素int配列 | NULL不可 |
| flags | ImGuiInputTextFlags | No | 入力動作を制御するフラグ | - |

### 入力データソース

ユーザーが提供するint型配列へのポインタ（v）を直接編集する。

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 戻り値 | bool | いずれかの値が変更された場合にtrue |
| v[] | int[] | 編集された整数値の配列 |

### 出力先

提供されたint配列（v[]）に編集結果が直接書き込まれる。

## 処理フロー

### 処理シーケンス

```
1. InputInt2/3/4呼び出し
   └─ 要素数（2, 3, 4）を決定
2. InputScalarNを呼び出し
   └─ ImGuiDataType_S32、要素数、"%d"を渡す
3. グループ開始
   └─ BeginGroup()でウィジェットをグループ化
4. 各要素のフィールド描画
   └─ PushMultiItemsWidths()で幅を均等分配
   └─ 各要素に対してInputScalar()を呼び出し
5. ラベル描画
   └─ 末尾にテキストラベルを表示
6. グループ終了
   └─ EndGroup()でグループ終了
7. 値変更の検出と戻り値の決定
   └─ いずれかの値が変更された場合はtrueを返す
```

### フローチャート

```mermaid
flowchart TD
    A[InputInt2/3/4開始] --> B[InputScalarN呼び出し]
    B --> C[BeginGroup]
    C --> D[PushMultiItemsWidths]
    D --> E[要素ループ開始]
    E --> F[InputScalar呼び出し]
    F --> G{最後の要素?}
    G -->|No| H[SameLine]
    H --> F
    G -->|Yes| I[ラベル描画]
    I --> J[EndGroup]
    J --> K{いずれか変更?}
    K -->|Yes| L[true返却]
    K -->|No| M[false返却]
    L --> N[終了]
    M --> N
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | 幅の均等分配 | 各入力フィールドの幅は利用可能なスペースを均等に分配 | 常に適用 |
| BR-02 | ステップボタンなし | InputInt2/3/4では+/-ボタンは表示されない | 常に適用 |
| BR-03 | 統合戻り値 | いずれかの要素が変更された場合にtrueを返す | 常に適用 |
| BR-04 | フォーマット固定 | フォーマットは"%d"固定（カスタマイズ不可） | 常に適用 |

### 計算ロジック

フィールド幅の計算: `(総幅 - 間隔 * (要素数-1)) / 要素数`

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | パースエラー | 無効な数値文字列入力 | 該当要素の値は変更されない |

### リトライ仕様

リトライ機能は提供されない。

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

本機能はトランザクション処理を行わない。

## パフォーマンス要件

軽量なウィジェットであり、特別なパフォーマンス考慮は不要。

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

特別なセキュリティ考慮事項はない。

## 備考

- +/-ボタンが必要な場合は、個別のInputIntを複数配置するか、カスタム実装が必要
- InputFloat2/3/4とは異なり、formatパラメータはない（常に"%d"）
- 連続的な調整が必要な場合は、DragInt2/3/4やSliderInt2/3/4の使用を検討

---

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

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

### 推奨読解順序

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

データ型の定義を確認。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | imgui.h | `imgui.h` | ImGuiDataType_S32（データ型定義）を確認 |

**読解のコツ**: InputInt2/3/4はInputScalarNの薄いラッパーであり、要素数を指定して呼び出す。formatは"%d"固定。

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

処理の起点となるInputInt2/3/4関数を確認。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | imgui.h | `imgui.h` | 関数宣言（行722-724）。3つの関数が同じパターン、formatパラメータなし |
| 2-2 | imgui_widgets.cpp | `imgui_widgets.cpp` | InputInt2実装（行3915-3918） |
| 2-3 | imgui_widgets.cpp | `imgui_widgets.cpp` | InputInt3実装（行3920-3923） |
| 2-4 | imgui_widgets.cpp | `imgui_widgets.cpp` | InputInt4実装（行3925-3928） |

**主要処理フロー**:
1. **行3917**: InputInt2はInputScalarN(label, S32, v, 2, NULL, NULL, "%d", ...)を呼び出し
2. **行3922**: InputInt3はInputScalarN(label, S32, v, 3, NULL, NULL, "%d", ...)を呼び出し
3. **行3927**: InputInt4はInputScalarN(label, S32, v, 4, NULL, NULL, "%d", ...)を呼び出し

#### Step 3: コア実装を理解する

InputScalarNの実装を確認。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | imgui_widgets.cpp | `imgui_widgets.cpp` | InputScalarN実装（行3853-3886）。複数要素のループ処理 |

**主要処理フロー**:
- **行3861**: BeginGroup()でグループ化開始
- **行3863**: PushMultiItemsWidths()で各フィールドの幅を計算
- **行3865-3874**: 各要素に対してInputScalar()をループ呼び出し
- **行3877-3882**: ラベル描画
- **行3884**: EndGroup()でグループ終了

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

```
ImGui::InputInt2/3/4()
    │
    └─ ImGui::InputScalarN()
           │
           ├─ BeginGroup()
           │
           ├─ PushMultiItemsWidths()
           │
           ├─ [要素数分ループ]
           │      │
           │      ├─ PushID(i)
           │      ├─ SameLine() [i > 0の場合]
           │      ├─ InputScalar()
           │      └─ PopID()
           │
           ├─ TextEx() [ラベル表示]
           │
           └─ EndGroup()
```

### データフロー図

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

int v[N]       ───▶  InputInt2/3/4()
(N要素配列)            │
                       ▼
               InputScalarN()
                       │
                       ├─ v[0] ─▶ InputScalar() ─▶ v[0]更新
                       ├─ v[1] ─▶ InputScalar() ─▶ v[1]更新
                       ├─ v[2] ─▶ InputScalar() ─▶ v[2]更新 (3/4のみ)
                       └─ v[3] ─▶ InputScalar() ─▶ v[3]更新 (4のみ)
                       │
                       ▼
               bool (変更有無) ───▶ 戻り値
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| imgui.h | `imgui.h` | ヘッダー | 関数宣言（行722-724） |
| imgui_widgets.cpp | `imgui_widgets.cpp` | ソース | InputInt2/3/4、InputScalarNの実装 |
| imgui_demo.cpp | `imgui_demo.cpp` | ソース | デモ実装（行1943, 1951, 1959等） |
