# 機能設計書 275-imgui_stdlib

## 概要

本ドキュメントは、Dear ImGuiのC++標準ライブラリ（STL）ラッパー（imgui_stdlib）の機能設計について記述する。std::stringをImGuiのInputText系関数で直接使用できるようにするヘルパー機能を提供する。

### 本機能の処理概要

C++標準ライブラリのstd::string型をImGuiのテキスト入力ウィジェットで直接使用できるようにするラッパー関数を提供する。ImGuiInputTextFlags_CallbackResize機能を活用して、動的なバッファリサイズを実現している。

**業務上の目的・背景**：ImGuiの標準InputText関数はchar配列を使用するが、現代のC++開発ではstd::stringが広く使用されている。このヘルパーにより、std::stringを直接渡すことができ、バッファサイズ管理の煩雑さを解消する。開発効率の向上とコードの可読性改善に貢献する。

**機能の利用シーン**：std::stringを使用するC++アプリケーションでImGuiのテキスト入力を使用する場合。設定画面、検索ボックス、ログフィルタ、コンソール入力など、テキスト入力が必要なあらゆる場面で使用される。

**主要な処理内容**：
1. std::string*を受け取るInputText関数のオーバーロード提供
2. CallbackResizeを使用した動的バッファリサイズ
3. ユーザーコールバックのチェーン対応
4. InputTextMultiline、InputTextWithHintのサポート

**関連システム・外部連携**：C++標準ライブラリ（std::string）

**権限による制御**：特になし。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 23 | Widgets | 補助機能 | テキスト入力ウィジェットで使用 |
| 10 | Console | 補助機能 | コンソール入力で使用 |
| 13 | Property Editor | 補助機能 | プロパティ編集で使用 |

## 機能種別

ユーティリティ / STLラッパー

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| label | const char* | Yes | ウィジェットのラベル | nullptr不可 |
| str | std::string* | Yes | 編集対象の文字列 | nullptr不可 |
| flags | ImGuiInputTextFlags | No | 入力フラグ | CallbackResize以外を使用可 |
| callback | ImGuiInputTextCallback | No | ユーザーコールバック | チェーン対応 |
| user_data | void* | No | コールバック用ユーザーデータ | |
| hint | const char* | No | プレースホルダーテキスト | InputTextWithHintのみ |
| size | const ImVec2& | No | 入力ボックスサイズ | InputTextMultilineのみ |

### 入力データソース

- ユーザー提供のstd::stringポインタ
- ImGuiInputTextCallbackData経由のテキストイベント

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 戻り値 | bool | 値が変更された場合true |
| str | std::string* | 更新された文字列（入出力） |

### 出力先

渡されたstd::stringインスタンス

## 処理フロー

### 処理シーケンス

```
1. フラグ設定
   └─ ImGuiInputTextFlags_CallbackResizeを追加
2. コールバックユーザーデータ準備
   └─ InputTextCallback_UserData構造体作成
3. 標準InputText呼び出し
   └─ str->c_str()をバッファとして渡す
   └─ str->capacity() + 1をバッファサイズとして渡す
4. コールバック処理（内部）
   a. CallbackResizeイベント時
      └─ str->resize()でサイズ変更
      └─ data->Bufを新しいc_str()に更新
   b. その他のイベント時
      └─ ユーザーコールバックをチェーン呼び出し
```

### フローチャート

```mermaid
flowchart TD
    A[InputText呼び出し] --> B{CallbackResizeフラグ確認}
    B -->|既に設定| C[エラー: アサーション]
    B -->|未設定| D[CallbackResizeフラグ追加]
    D --> E[UserData構造体作成]
    E --> F[標準InputText呼び出し]
    F --> G{コールバック発生?}
    G -->|No| H[結果返却]
    G -->|Yes| I{イベント種別}
    I -->|CallbackResize| J[str->resize]
    I -->|その他| K{ユーザーコールバックあり?}
    J --> L[data->Buf更新]
    L --> G
    K -->|Yes| M[ユーザーコールバック呼び出し]
    K -->|No| G
    M --> G
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-275-01 | フラグ排他制御 | CallbackResizeは内部で使用するため、ユーザーが設定してはいけない | 常に適用 |
| BR-275-02 | コールバックチェーン | ユーザーコールバックはCallbackResize以外のイベントで呼び出される | コールバック指定時 |
| BR-275-03 | バッファ同一性 | data->Bufとstr->c_str()が同一であることを確認 | リサイズ時 |

### 計算ロジック

- バッファサイズ: `str->capacity() + 1`（ヌル終端用に+1）

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

本機能はデータベースを使用しない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | アサーション | CallbackResizeフラグが既に設定されている | フラグを削除してから呼び出す |
| - | アサーション | data->Bufとstr->c_str()が一致しない | 内部エラー |

### リトライ仕様

リトライ処理なし。

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

該当なし

## パフォーマンス要件

- std::string::resize()による効率的なメモリ管理
- コールバックチェーンによるオーバーヘッド最小化

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

- ユーザー入力はstd::stringに直接格納
- バッファオーバーフローはstd::stringが防止

## 備考

- misc/cpp/に配置
- ヘッダーとソースの両方をインクルード可能（インライン実装不要の場合）
- 類似のラッパーを独自の型に対して作成する際の参考例としても機能

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | imgui_stdlib.cpp | `misc/cpp/imgui_stdlib.cpp` | InputTextCallback_UserData構造体（32-37行目） |

**読解のコツ**: この構造体がコールバックチェーンを実現するキー。Strはstd::stringポインタ、ChainCallback/ChainCallbackUserDataはユーザー指定のコールバック情報。

#### Step 2: コールバック処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | imgui_stdlib.cpp | `misc/cpp/imgui_stdlib.cpp` | InputTextCallback関数（39-58行目） |

**主要処理フロー**:
- **42-50行目**: CallbackResizeイベント処理
  - **46行目**: str->c_str()とdata->Bufの同一性確認
  - **47行目**: str->resize()でサイズ変更
  - **48行目**: data->Bufを新しいc_str()に更新
- **51-56行目**: ユーザーコールバックチェーン
  - **53行目**: UserDataを元に戻す
  - **54行目**: ユーザーコールバック呼び出し

#### Step 3: 公開API関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | imgui_stdlib.h | `misc/cpp/imgui_stdlib.h` | 関数宣言（32-34行目） |
| 3-2 | imgui_stdlib.cpp | `misc/cpp/imgui_stdlib.cpp` | InputText実装（60-70行目） |
| 3-3 | imgui_stdlib.cpp | `misc/cpp/imgui_stdlib.cpp` | InputTextMultiline実装（72-82行目） |
| 3-4 | imgui_stdlib.cpp | `misc/cpp/imgui_stdlib.cpp` | InputTextWithHint実装（84-94行目） |

**主要処理フロー（共通）**:
1. **アサーション**: CallbackResizeフラグが設定されていないことを確認
2. **フラグ追加**: CallbackResizeフラグを追加
3. **UserData準備**: InputTextCallback_UserData構造体を初期化
4. **標準関数呼び出し**: ImGui::InputText等を呼び出し
   - バッファ: `str->c_str()`
   - サイズ: `str->capacity() + 1`
   - コールバック: 内部InputTextCallback
   - UserData: &cb_user_data

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

```
ImGui::InputText(label, str, flags, callback, user_data)  [imgui_stdlib.cpp]
    │
    ├─ フラグチェック・設定
    │      └─ flags |= ImGuiInputTextFlags_CallbackResize
    │
    ├─ InputTextCallback_UserData作成
    │      ├─ .Str = str
    │      ├─ .ChainCallback = callback
    │      └─ .ChainCallbackUserData = user_data
    │
    └─ ImGui::InputText(label, str->c_str(), str->capacity()+1, flags, InputTextCallback, &cb_user_data)  [imgui.cpp]
           │
           └─ InputTextCallback(data)  [imgui_stdlib.cpp]
                  │
                  ├─ [CallbackResize]
                  │      ├─ str->resize(data->BufTextLen)
                  │      └─ data->Buf = str->c_str()
                  │
                  └─ [その他]
                         └─ ChainCallback(data)  [ユーザー関数]
```

### データフロー図

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

std::string* str ────────▶ InputText ─────────────▶ std::string* str
  │                           │                         (更新済み)
  ├─ c_str() ──────▶ バッファとして渡す                    │
  │                           │                         │
  └─ capacity()+1 ──▶ バッファサイズ                      │
                              │                         │
                     [コールバック発生]                    │
                              │                         │
                     InputTextCallback                   │
                              │                         │
                     ┌────────┴────────┐                 │
                     │                 │                 │
              [CallbackResize]    [その他イベント]         │
                     │                 │                 │
              str->resize()    ChainCallback()           │
                     │                 │                 │
                     └────────┬────────┘                 │
                              │                         │
                              └─────────────────────────┘
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| imgui_stdlib.h | `misc/cpp/imgui_stdlib.h` | ヘッダー | 公開API宣言 |
| imgui_stdlib.cpp | `misc/cpp/imgui_stdlib.cpp` | ソース | 実装 |
| imgui.h | `imgui.h` | ヘッダー | ImGui コアAPI（InputText等） |
