# 機能設計書 26-BeginChild

## 概要

本ドキュメントは、Dear ImGuiライブラリにおけるBeginChild機能の設計仕様を記述する。この機能は、親ウィンドウ内に独立したスクロール/クリッピング領域を持つ子ウィンドウを作成するための関数である。

### 本機能の処理概要

**業務上の目的・背景**：複雑なUIレイアウトを実現するために、親ウィンドウ内に独立した領域を作成する必要がある。子ウィンドウは独自のスクロール、クリッピング、レイアウトを持ち、コンテンツの論理的な分離を可能にする。サイドバー、スクロール可能なリスト、分割ペインなど、多様なレイアウトパターンを実現できる。

**機能の利用シーン**：
- スクロール可能なログ領域を作成する場合
- サイドバーとメインエリアを分割する場合
- リストボックスやテーブルの内部領域として使用する場合
- フレームスタイルのグループを作成する場合

**主要な処理内容**：
1. 親ウィンドウからIDを生成する
2. 子ウィンドウフラグの検証と適用
3. サイズの計算（自動リサイズ、固定サイズ、親ウィンドウ依存）
4. 内部でBegin関数を呼び出して子ウィンドウを作成
5. ナビゲーションとフォーカスの処理

**関連システム・外部連携**：ImGuiのウィンドウ管理システム、レイアウトシステム、ナビゲーションシステムと連携する。

**権限による制御**：特になし。すべてのユーザーが任意のタイミングで呼び出し可能。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 3 | Debug Log Window | 補助機能 | スクロール可能なログ領域の作成 |
| 10 | Console | 主機能 | スクロール可能なログ領域 |
| 11 | Log | 主機能 | スクロール可能なログ領域 |
| 12 | Simple Layout | 主機能 | サイドバー・メインエリアの子ウィンドウ |
| 22 | Assets Browser | 主機能 | アセットリスト領域 |
| 24 | Layout | 補助機能 | 子ウィンドウレイアウト |

## 機能種別

ウィンドウ管理 / UI構造制御

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| str_id | const char* | Yes | 子ウィンドウの識別子 | 有効な文字列 |
| size | ImVec2 | No | 子ウィンドウのサイズ。0.0fは残りスペースを使用、負値は端からの距離 | 有効なImVec2 |
| child_flags | ImGuiChildFlags | No | 子ウィンドウの動作フラグ | ImGuiChildFlags_の組み合わせ |
| window_flags | ImGuiWindowFlags | No | ウィンドウの動作フラグ | ImGuiWindowFlags_の組み合わせ |

### 入力データソース

- 親ウィンドウのコンテキスト
- SetNextWindowSize等で事前設定されたパラメータ

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 戻り値 | bool | 子ウィンドウが表示可能な場合はtrue、クリップされている場合はfalse。必ずEndChild()を呼び出す |

### 出力先

- グローバルコンテキスト（現在のウィンドウ、ウィンドウスタック等）

## 処理フロー

### 処理シーケンス

```
1. IDの生成
   └─ 親ウィンドウのIDスタックから子ウィンドウIDを生成
2. フラグの検証
   └─ ImGuiChildFlagsとImGuiWindowFlagsの整合性を確認
3. サイズの計算
   └─ 利用可能なスペースと指定サイズからサイズを決定
4. スタイルの設定
   └─ FrameStyleの場合は専用スタイルを適用
5. ウィンドウ名の生成
   └─ 親ウィンドウ名/子ウィンドウ名_IDの形式で生成
6. Beginの呼び出し
   └─ 内部的にBegin関数を呼び出し
7. ナビゲーションの処理
   └─ NavFlattenedでない場合はナビゲーション処理を行う
```

### フローチャート

```mermaid
flowchart TD
    A[BeginChild開始] --> B[親ウィンドウからID生成]
    B --> C{フラグの検証}
    C -->|エラー| D[アサーション失敗]
    C -->|OK| E[サイズの計算]
    E --> F{FrameStyle?}
    F -->|Yes| G[スタイル変更をプッシュ]
    F -->|No| H[ウィンドウ名生成]
    G --> H
    H --> I[内部でBeginを呼び出し]
    I --> J{FrameStyle?}
    J -->|Yes| K[スタイル変更をポップ]
    J -->|No| L[ナビゲーション処理]
    K --> L
    L --> M[戻り値を返す]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | EndChild必須 | BeginChild()を呼び出したら必ずEndChild()を呼び出す | 常時 |
| BR-002 | 戻り値の意味 | falseが返っても描画処理をスキップしてEndChild()を呼び出す必要がある | 常時 |
| BR-003 | サイズ指定 | サイズ0.0fは残りスペースを使用、負値は端からの距離 | 常時 |
| BR-004 | フラグの排他性 | AlwaysAutoResizeとResizeX/Yは同時使用不可 | 常時 |
| BR-005 | ボーダー互換性 | ImGuiChildFlags_Borders == true（後方互換性のため） | 常時 |

### 計算ロジック

- サイズ計算: GetContentRegionAvail() + サイズ引数から最終サイズを決定
- 0.0fの場合: 親の残りスペースを使用
- 負値の場合: 親の端からの距離として解釈

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

### 操作別データベース影響一覧

なし（本機能はメモリ内のデータ構造のみを操作する）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | アサーション失敗 | ImGuiWindowFlagsをImGuiChildFlagsに渡した場合 | 正しいフラグ型を使用する |
| - | アサーション失敗 | ImGuiWindowFlags_AlwaysAutoResizeを指定した場合 | ImGuiChildFlags_AlwaysAutoResizeを使用する |
| - | アサーション失敗 | AlwaysAutoResizeとResizeX/Yを同時指定した場合 | どちらか一方を使用する |

### リトライ仕様

なし

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

なし

## パフォーマンス要件

- 処理時間: 通常の子ウィンドウで数マイクロ秒から数十マイクロ秒
- メモリ使用: 子ウィンドウごとにImGuiWindow構造体を使用

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

なし

## 備考

- v1.90（2023年11月）以前は第3引数がbool borderだった
- ImGuiChildFlags_Borders == trueは後方互換性のために保証されている
- BeginChild/EndChildはBegin/Endと同様に、戻り値に関わらずEndChildを呼び出す必要がある

---

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

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

### 推奨読解順序

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

ImGuiChildFlags列挙型を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | imgui.h | `imgui.h` | ImGuiChildFlags_列挙型（1212-1223行目） |

**読解のコツ**: ImGuiChildFlagsはv1.90で導入された新しいフラグ型で、以前のbool borderパラメータを置き換えた。ImGuiChildFlags_Borders == 1であることが後方互換性のポイント。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | imgui.h | `imgui.h` | BeginChild関数宣言（456-458行目） |
| 2-2 | imgui.cpp | `imgui.cpp` | BeginChild関数実装（6356-6364行目） |
| 2-3 | imgui.cpp | `imgui.cpp` | BeginChildEx関数実装（6367-6492行目） |

**主要処理フロー**:
1. **6356-6359行目**: 文字列IDからIDを生成
2. **6367-6382行目**: フラグの検証
3. **6392-6408行目**: ウィンドウフラグの設定
4. **6414-6434行目**: サイズの計算
5. **6443-6453行目**: ウィンドウ名の生成
6. **6461行目**: 内部でBeginを呼び出し
7. **6479-6490行目**: ナビゲーション処理

#### Step 3: フラグ処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | imgui.cpp | `imgui.cpp` | フラグ検証と変換（6373-6408行目） |

**主要処理フロー**:
- **6374行目**: サポートされるImGuiChildFlagsのマスク
- **6377行目**: ImGuiWindowFlags_AlwaysAutoResizeの禁止
- **6392-6398行目**: ウィンドウフラグへの変換

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

```
BeginChild(str_id, size, child_flags, window_flags)
    │
    ├─ GetCurrentWindow()->GetID(str_id)
    │
    └─ BeginChildEx(str_id, id, size, child_flags, window_flags)
           │
           ├─ GetContentRegionAvail()
           │
           ├─ CalcItemSize()
           │
           ├─ SetNextWindowSize()
           │
           ├─ PushStyleColor/PushStyleVar [FrameStyleの場合]
           │
           ├─ Begin(temp_window_name, NULL, window_flags)
           │
           ├─ PopStyleVar/PopStyleColor [FrameStyleの場合]
           │
           └─ NavInitWindow() [必要な場合]
```

### データフロー図

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

str_id ────────────────────▶
size ──────────────────────▶  BeginChild()            ──▶ bool (表示状態)
child_flags ───────────────▶     │
window_flags ──────────────▶     ▼
                           ID生成・サイズ計算
                                 │
                                 ▼
親ウィンドウ ─────────────▶ 子ウィンドウ作成
                                 │
                                 ▼
                           g.CurrentWindow 設定 ────▶ 子ウィンドウ
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| imgui.h | `imgui.h` | ヘッダ | API宣言、ImGuiChildFlags_列挙型定義 |
| imgui.cpp | `imgui.cpp` | ソース | BeginChild/BeginChildEx関数の実装 |
| imgui_demo.cpp | `imgui_demo.cpp` | ソース | 使用例 |
