# 機能設計書 123-InputFloat

## 概要

本ドキュメントは、Dear ImGuiライブラリにおける浮動小数点数入力機能「InputFloat」の設計仕様を定義する。

### 本機能の処理概要

InputFloatは、単精度浮動小数点数（float）を入力・編集するためのウィジェット関数である。テキスト入力方式で数値を編集でき、オプションで+/-ボタンによるステップ増減機能を提供する。

**業務上の目的・背景**：GUIアプリケーションにおいて、位置座標、スケール値、アルファ値などの浮動小数点数パラメータをユーザーが直接入力・調整する場面は頻繁に発生する。InputFloatは、キーボードによる直接入力と、ボタンによる微調整の両方をサポートし、効率的な数値編集を実現する。DragFloatやSliderFloatとは異なり、正確な数値入力に適している。

**機能の利用シーン**：
- 座標値の精密な入力（X, Y, Z座標など）
- 物理パラメータの設定（質量、速度、加速度など）
- グラフィックス設定（透明度、明るさ、コントラストなど）
- 科学技術計算のパラメータ入力

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

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

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

## 関連画面

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

## 機能種別

数値入力ウィジェット / 浮動小数点対応

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| label | const char* | Yes | ウィジェットの識別ラベル | NULL不可 |
| v | float* | Yes | 編集対象の浮動小数点数へのポインタ | NULL不可 |
| step | float | No | +/-ボタンによる増減値（デフォルト: 0.0f = ボタンなし） | 0.0以上 |
| step_fast | float | No | Ctrl押下時の高速増減値（デフォルト: 0.0f） | 0.0以上 |
| format | const char* | No | 表示フォーマット文字列（デフォルト: "%.3f"） | printf形式 |
| flags | ImGuiInputTextFlags | No | 入力動作を制御するフラグ | - |

### 入力データソース

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

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 戻り値 | bool | 値が変更された場合にtrue |
| *v | float | 編集された浮動小数点数値 |

### 出力先

提供されたfloat変数（*v）に編集結果が直接書き込まれる。

## 処理フロー

### 処理シーケンス

```
1. InputFloat呼び出し
   └─ stepが0より大きいかを判定
2. InputScalarを呼び出し
   └─ ImGuiDataType_Float、step、step_fast、formatを渡す
3. テキスト入力フィールドの描画
   └─ 現在値をformat文字列で表示
4. step > 0の場合、+/-ボタンを描画
   └─ ボタンクリックで値を増減
5. テキスト入力の処理
   └─ 入力値をパースしてfloatに変換
6. 値変更の検出と戻り値の決定
   └─ 値が変更された場合はtrueを返す
```

### フローチャート

```mermaid
flowchart TD
    A[InputFloat開始] --> B[InputScalar呼び出し]
    B --> C{step > 0?}
    C -->|Yes| D[+/-ボタン描画]
    C -->|No| E[テキストフィールドのみ]
    D --> F[ユーザー入力処理]
    E --> F
    F --> G{値変更?}
    G -->|Yes| H[*v更新]
    G -->|No| I[変更なし]
    H --> J[true返却]
    I --> K[false返却]
    J --> L[終了]
    K --> L
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | ボタン表示条件 | step > 0の場合のみ+/-ボタンが表示される | 常に適用 |
| BR-02 | Ctrl+ボタン | Ctrlを押しながら+/-ボタンを押すとstep_fastで増減 | step_fast > 0の場合 |
| BR-03 | デフォルトフォーマット | formatがNULLの場合、"%.3f"が使用される | 常に適用 |
| BR-04 | EnterReturnsTrue非対応 | ImGuiInputTextFlags_EnterReturnsTrueはサポートされない | 常に適用 |

### 計算ロジック

- ボタン押下時: *v = *v +/- step（または step_fast）
- テキスト入力時: 入力文字列をatof()相当でパース

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

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

## エラー処理

### エラーケース一覧

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

### リトライ仕様

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

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

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

## パフォーマンス要件

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

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

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

## 備考

- 複数のfloat値を一度に編集する場合は、InputFloat2/3/4を使用することを推奨
- より広い範囲や連続的な調整が必要な場合は、DragFloatやSliderFloatの使用を検討
- ImGuiInputTextFlags_ParseEmptyRefValで空文字列を0として解釈可能
- ImGuiInputTextFlags_DisplayEmptyRefValで値が0のとき空表示可能

---

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

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

### 推奨読解順序

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

データ型とフラグの定義を確認。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | imgui.h | `imgui.h` | ImGuiDataType_Float（データ型定義）を確認 |
| 1-2 | imgui.h | `imgui.h` | ImGuiInputTextFlags_の定義（行1268-1269）。ParseEmptyRefVal、DisplayEmptyRefValを確認 |

**読解のコツ**: InputFloatはInputScalarの薄いラッパーであり、ImGuiDataType_Floatを指定して呼び出す。

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | imgui.h | `imgui.h` | 関数宣言（行717）。パラメータと戻り値の仕様を確認 |
| 2-2 | imgui_widgets.cpp | `imgui_widgets.cpp` | InputFloat実装（行3888-3891）。1行のシンプルなラッパー |

**主要処理フロー**:
1. **行3888-3891**: InputScalarをImGuiDataType_Floatで呼び出し
2. **行3890**: step > 0.0f の場合のみstepポインタを渡す

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

InputScalarの実装を確認。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | imgui_widgets.cpp | `imgui_widgets.cpp` | InputScalar実装（行3769-3851）。テキスト入力とボタン処理 |

**主要処理フロー**:
- **行3777**: EnterReturnsTrueフラグ使用時のアサーション
- **行3796-3800**: step==NULLの場合はテキストフィールドのみ
- **行3801-3844**: step指定時のボタン付きレイアウト
- **行3819-3829**: +/-ボタンの処理

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

```
ImGui::InputFloat()
    │
    └─ ImGui::InputScalar()
           │
           ├─ step == NULL の場合
           │      └─ InputText() [テキストフィールドのみ]
           │
           └─ step != NULL の場合
                  │
                  ├─ BeginGroup()
                  ├─ InputText() [テキストフィールド]
                  ├─ ButtonEx("-") [減少ボタン]
                  ├─ ButtonEx("+") [増加ボタン]
                  └─ EndGroup()
```

### データフロー図

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

float* v       ───▶  InputFloat()
(値へのポインタ)          │
                         ▼
float step     ───▶  InputScalar()
(増減値)                  │
                         ├─ テキスト入力
                         │      └─ 文字列→float変換
                         │
                         └─ +/-ボタン
                                └─ v += step
                         │
                         ▼
                    bool (変更有無) ───▶ 戻り値
                         │
                         ▼
                    *v 更新      ───▶ 編集結果
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| imgui.h | `imgui.h` | ヘッダー | 関数宣言、ImGuiDataType定義、ImGuiInputTextFlags定義 |
| imgui_widgets.cpp | `imgui_widgets.cpp` | ソース | InputFloat、InputScalarの実装 |
| imgui_demo.cpp | `imgui_demo.cpp` | ソース | デモ実装（行925, 931等） |
