# 機能設計書 128-InputScalar

## 概要

本ドキュメントは、Dear ImGuiライブラリにおける汎用スカラー入力機能「InputScalar」の設計仕様を定義する。

### 本機能の処理概要

InputScalarは、様々なデータ型のスカラー値を入力・編集するための汎用ウィジェット関数である。int、float、doubleだけでなく、8ビット、16ビット、64ビットの符号付き/符号なし整数など、多様なデータ型に対応する。InputFloat、InputInt、InputDoubleなどの高レベル関数の基盤となる関数である。

**業務上の目的・背景**：異なるデータ型の数値を統一的なインターフェースで編集できることは、汎用的なGUIツールやエディタの開発において重要である。InputScalarは、ImGuiDataType列挙型で指定されたデータ型に応じて適切な入力処理を行い、型安全な数値編集を提供する。これにより、カスタムデータ型や特殊な精度要件を持つアプリケーションにも対応可能となる。

**機能の利用シーン**：
- カスタムデータ型（u8, s8, u16, s16, u32, s32, u64, s64, float, double）の編集
- データエディタやプロパティエディタでの汎用数値入力
- シリアライズ/デシリアライズツールでのバイナリデータ編集
- メモリエディタでの数値編集
- 科学技術計算アプリケーションでの多様な数値型サポート

**主要な処理内容**：
1. 指定されたデータ型に応じたテキストボックスを描画する
2. stepパラメータが指定されている場合、+/-ボタンを表示する
3. テキスト入力を指定されたデータ型にパースして値を更新する
4. フォーマット文字列に従って数値を表示する

**関連システム・外部連携**：InputFloat、InputInt、InputDoubleなどの高レベル関数から呼び出される。また、TempInputScalarはドラッグ/スライダーウィジェットでCtrl+クリック時の直接入力にも使用される。

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | Demo Window | 参照画面 | Data Typesセクションでの各種データ型デモ |

## 機能種別

数値入力ウィジェット / 汎用スカラー対応

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| label | const char* | Yes | ウィジェットの識別ラベル | NULL不可 |
| data_type | ImGuiDataType | Yes | データ型（ImGuiDataType_S8〜ImGuiDataType_Double） | 有効なImGuiDataType値 |
| p_data | void* | Yes | 編集対象データへのポインタ | NULL不可 |
| p_step | const void* | No | +/-ボタンによる増減値へのポインタ（NULL=ボタンなし） | - |
| p_step_fast | const void* | No | Ctrl押下時の高速増減値へのポインタ | - |
| format | const char* | No | 表示フォーマット文字列（NULL=データ型のデフォルト） | printf形式 |
| flags | ImGuiInputTextFlags | No | 入力動作を制御するフラグ | - |

### サポートされるデータ型（ImGuiDataType）

| データ型 | サイズ | 説明 | デフォルトフォーマット |
|---------|-------|------|---------------------|
| ImGuiDataType_S8 | 1バイト | 符号付き8ビット整数 | "%d" |
| ImGuiDataType_U8 | 1バイト | 符号なし8ビット整数 | "%u" |
| ImGuiDataType_S16 | 2バイト | 符号付き16ビット整数 | "%d" |
| ImGuiDataType_U16 | 2バイト | 符号なし16ビット整数 | "%u" |
| ImGuiDataType_S32 | 4バイト | 符号付き32ビット整数 | "%d" |
| ImGuiDataType_U32 | 4バイト | 符号なし32ビット整数 | "%u" |
| ImGuiDataType_S64 | 8バイト | 符号付き64ビット整数 | "%lld" |
| ImGuiDataType_U64 | 8バイト | 符号なし64ビット整数 | "%llu" |
| ImGuiDataType_Float | 4バイト | 単精度浮動小数点数 | "%.3f" |
| ImGuiDataType_Double | 8バイト | 倍精度浮動小数点数 | "%.6f" |

### 入力データソース

ユーザーが提供するデータへのポインタ（p_data）を直接編集する。

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 戻り値 | bool | 値が変更された場合にtrue |
| *p_data | (data_typeに依存) | 編集された数値 |

### 出力先

提供されたデータポインタ（p_data）に編集結果が直接書き込まれる。

## 処理フロー

### 処理シーケンス

```
1. InputScalar呼び出し
   └─ データ型情報を取得（DataTypeGetInfo）
2. フォーマット文字列の決定
   └─ format==NULLの場合はデータ型のデフォルトフォーマットを使用
3. 現在値を文字列にフォーマット
   └─ DataTypeFormatString()で変換
4. p_step==NULLの場合
   └─ テキストフィールドのみを描画
5. p_step!=NULLの場合
   └─ BeginGroup()でグループ化
   └─ テキストフィールドを描画
   └─ +/-ボタンを描画
   └─ EndGroup()
6. テキスト入力の処理
   └─ DataTypeApplyFromText()でパースして値を更新
7. 値変更の検出と戻り値の決定
   └─ 値が変更された場合はtrueを返す
```

### フローチャート

```mermaid
flowchart TD
    A[InputScalar開始] --> B[データ型情報取得]
    B --> C{format指定?}
    C -->|No| D[デフォルトフォーマット使用]
    C -->|Yes| E[指定フォーマット使用]
    D --> F[現在値を文字列変換]
    E --> F
    F --> G{p_step指定?}
    G -->|No| H[テキストフィールドのみ]
    G -->|Yes| I[BeginGroup]
    I --> J[テキストフィールド]
    J --> K[+/-ボタン]
    K --> L[EndGroup]
    H --> M[入力処理]
    L --> M
    M --> N{値変更?}
    N -->|Yes| O[MarkItemEdited]
    N -->|No| P[変更なし]
    O --> Q[true返却]
    P --> R[false返却]
    Q --> S[終了]
    R --> S
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | ボタン表示条件 | p_step!=NULLの場合のみ+/-ボタンが表示される | 常に適用 |
| BR-02 | Ctrl+ボタン | Ctrlを押しながら+/-ボタンを押すとp_step_fastで増減 | p_step_fast!=NULLの場合 |
| BR-03 | フォーマット自動選択 | format==NULLの場合、データ型に応じたデフォルトフォーマットを使用 | 常に適用 |
| BR-04 | EnterReturnsTrue非対応 | ImGuiInputTextFlags_EnterReturnsTrueはサポートされない | 常に適用 |
| BR-05 | 自動選択 | ImGuiInputTextFlags_AutoSelectAllが自動的に適用される | 常に適用 |

### 計算ロジック

- ボタン押下時: DataTypeApplyOp()で*p_data +/- stepを計算
- テキスト入力時: DataTypeApplyFromText()でパース

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | アサーション失敗 | ImGuiInputTextFlags_EnterReturnsTrueフラグ使用時 | IsItemDeactivatedAfterEdit()を代わりに使用 |
| - | パースエラー | 無効な数値文字列入力 | 値は変更されない |

### リトライ仕様

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

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

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

## パフォーマンス要件

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

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

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

## 備考

- 複数要素を編集する場合はInputScalarNを使用
- ImGuiInputTextFlags_ParseEmptyRefValで空文字列を0として解釈可能
- ImGuiInputTextFlags_DisplayEmptyRefValで値が0のとき空表示可能
- フォーマットに%Xを指定すると自動的に16進数入力が許可される
- フォーマットにfloat/double形式を指定すると自動的に科学表記入力が許可される

---

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

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

### 推奨読解順序

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

データ型定義を確認。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | imgui.h | `imgui.h` | ImGuiDataType列挙型の定義。対応するデータ型を確認 |
| 1-2 | imgui_internal.h | `imgui_internal.h` | ImGuiDataTypeInfo構造体。各データ型のサイズ、フォーマット情報 |

**読解のコツ**: GDataTypeInfo配列にデータ型ごとの情報（サイズ、PrintFmt、ScanFmt等）が定義されている。

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

処理の起点となるInputScalar関数を確認。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | imgui.h | `imgui.h` | 関数宣言（行726）。パラメータと戻り値の仕様を確認 |
| 2-2 | imgui_widgets.cpp | `imgui_widgets.cpp` | InputScalar実装（行3769-3851）。コア実装 |

**主要処理フロー**:
1. **行3777**: EnterReturnsTrueフラグ使用時のアサーション
2. **行3779-3780**: format==NULLの場合、DataTypeGetInfo(data_type)->PrintFmtを使用
3. **行3784-3788**: 現在値を文字列にフォーマット
4. **行3796-3800**: p_step==NULLの場合、InputText()のみ呼び出し
5. **行3801-3844**: p_step!=NULLの場合、ボタン付きレイアウト
6. **行3819-3829**: +/-ボタンの処理（DataTypeApplyOp使用）

#### Step 3: ヘルパー関数を理解する

データ型操作のヘルパー関数を確認。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | imgui_widgets.cpp | `imgui_widgets.cpp` | DataTypeGetInfo() - データ型情報の取得 |
| 3-2 | imgui_widgets.cpp | `imgui_widgets.cpp` | DataTypeFormatString() - 値を文字列に変換 |
| 3-3 | imgui_widgets.cpp | `imgui_widgets.cpp` | DataTypeApplyFromText() - 文字列を値に変換 |
| 3-4 | imgui_widgets.cpp | `imgui_widgets.cpp` | DataTypeApplyOp() - 演算適用 |

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

```
ImGui::InputScalar()
    │
    ├─ DataTypeGetInfo() [データ型情報取得]
    │
    ├─ DataTypeFormatString() [値→文字列変換]
    │
    ├─ p_step == NULL の場合
    │      └─ InputText() [テキストフィールドのみ]
    │             └─ DataTypeApplyFromText() [文字列→値変換]
    │
    └─ p_step != NULL の場合
           │
           ├─ BeginGroup()
           ├─ InputText() [テキストフィールド]
           │      └─ DataTypeApplyFromText()
           ├─ ButtonEx("-")
           │      └─ DataTypeApplyOp('-')
           ├─ ButtonEx("+")
           │      └─ DataTypeApplyOp('+')
           └─ EndGroup()
```

### データフロー図

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

void* p_data   ───▶  InputScalar()
(値へのポインタ)          │
                         ▼
ImGuiDataType  ───▶  DataTypeGetInfo()
(データ型)                │
                         ▼
                    DataTypeFormatString() ───▶ 文字列表示
                         │
const char* format ───▶ │
                         │
                    [ユーザー入力]
                         │
                         ▼
                    DataTypeApplyFromText() ───▶ *p_data更新
                         │
                         ▼
                    bool (変更有無) ───▶ 戻り値
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| imgui.h | `imgui.h` | ヘッダー | 関数宣言、ImGuiDataType定義 |
| imgui_widgets.cpp | `imgui_widgets.cpp` | ソース | InputScalar、ヘルパー関数の実装 |
| imgui_internal.h | `imgui_internal.h` | ヘッダー | ImGuiDataTypeInfo構造体、GDataTypeInfo配列 |
| imgui_demo.cpp | `imgui_demo.cpp` | ソース | Data Typesセクションでのデモ（行1397-1517等） |
