# 機能設計書 139-CollapsingHeader

## 概要

本ドキュメントは、ImGuiライブラリにおける折りたたみヘッダーウィジェット `CollapsingHeader` の機能仕様を定義するものである。

### 本機能の処理概要

CollapsingHeaderは、折りたたみ可能なセクションヘッダーを作成する機能である。TreeNodeと異なり、IDスタックへのプッシュやインデントの追加を行わず、ヘッダー部分のみを提供する。

**業務上の目的・背景**：大量の情報を持つUIにおいて、論理的なセクション分けと表示/非表示の切り替えは必須の機能である。CollapsingHeaderは、TreeNodeよりもシンプルなセクションヘッダーとして、設定画面、インスペクター、デモウィンドウなどで広く使用される。TreeNodeとの主な違いは、インデントやIDスコープを追加しないため、後続のウィジェットがそのまま配置される点である。

**機能の利用シーン**：デモウィンドウでの各セクション表示、設定画面でのカテゴリ分け、インスペクターウィンドウでのプロパティグループ表示、メトリクスウィンドウでのデバッグ情報セクション分けなど。

**主要な処理内容**：
1. ラベルからウィジェットIDを生成
2. CollapsingHeaderフラグを付与してTreeNodeBehaviorを呼び出し
3. フレーム付きの背景描画
4. 開閉状態を返却（TreePop不要）
5. 閉じるボタンの描画（p_visible引数使用時）

**関連システム・外部連携**：SetNextItemOpen()で開閉状態を事前設定可能。

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | Demo Window | 主画面 | 各セクションの折りたたみヘッダー |
| 2 | Metrics/Debugger Window | 主画面 | 各デバッグセクションの折りたたみ表示 |
| 6 | Style Editor | 主画面 | スタイル設定のセクション分け |

## 機能種別

ユーザー入力処理 / ウィジェット描画

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| label | const char* | Yes | ヘッダーのラベル（ID生成にも使用） | NULL不可 |
| flags | ImGuiTreeNodeFlags | No | ノードの動作・表示オプション | デフォルトは0 |
| p_visible | bool* | No | 閉じるボタンの状態を管理するポインタ | NULLで閉じるボタンなし |

### 入力データソース

- ユーザーが指定するラベル/フラグ
- マウス/キーボード入力による操作
- ImGuiStorage（開閉状態の永続化）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 戻り値 | bool | ヘッダーが開いている場合true、閉じている場合false |
| p_visible | bool* | 閉じるボタンがクリックされた場合falseに設定（出力） |

### 出力先

- 画面上へのウィジェット描画
- 開閉状態のストレージ

## 処理フロー

### 処理シーケンス

```
1. ウィンドウスキップチェック
   └─ SkipItemsがtrueならfalse返却
2. p_visibleチェック（オーバーロード版）
   └─ *p_visible == falseなら何も描画せずfalse返却
3. ラベルからIDを生成
   └─ window->GetID(label)
4. CollapsingHeaderフラグを付与
   └─ ImGuiTreeNodeFlags_CollapsingHeader
5. TreeNodeBehaviorを呼び出し
   └─ 開閉状態を取得
6. 閉じるボタンの描画（p_visible引数使用時）
   └─ CloseButton()呼び出し
7. 開閉状態を返却
   └─ TreePop()は不要
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{SkipItems?}
    B -->|Yes| C[return false]
    B -->|No| D{p_visible && !*p_visible?}
    D -->|Yes| C
    D -->|No| E[ID生成]
    E --> F[flags |= CollapsingHeader]
    F --> G[TreeNodeBehavior呼び出し]
    G --> H{p_visible != NULL?}
    H -->|Yes| I[閉じるボタン描画]
    H -->|No| J[return is_open]
    I --> K{閉じるボタンクリック?}
    K -->|Yes| L[*p_visible = false]
    K -->|No| J
    L --> J
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-139-01 | TreePop不要 | CollapsingHeaderはTreePop()を呼び出す必要がない | 常時 |
| BR-139-02 | インデントなし | 後続ウィジェットにインデントは追加されない | 常時 |
| BR-139-03 | IDスコープなし | IDスタックにプッシュされない | 常時 |
| BR-139-04 | 閉じるボタン | p_visibleがNULLでない場合、閉じるボタンを表示 | p_visible != NULL |
| BR-139-05 | 非表示制御 | *p_visible == falseの場合、ヘッダー自体を表示しない | p_visible != NULL && !*p_visible |

### 計算ロジック

- CollapsingHeaderフラグ：`ImGuiTreeNodeFlags_Framed | ImGuiTreeNodeFlags_NoTreePushOnOpen | ImGuiTreeNodeFlags_NoAutoOpenOnLog`

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

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | ウィンドウスキップ | window->SkipItemsがtrue | falseを返却して処理終了 |

### リトライ仕様

リトライ処理は不要（即時応答型）

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

トランザクション管理は不要

## パフォーマンス要件

- 毎フレーム呼び出されることを想定
- TreeNodeとほぼ同等のパフォーマンス

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

特になし（ローカルUI操作のみ）

## 備考

- 内部的にはTreeNodeEx(label, ImGuiTreeNodeFlags_CollapsingHeader)と等価
- p_visible引数を使用すると「X」閉じるボタンが表示される
- 閉じるボタンは開閉状態とは独立（*p_visible=falseでも開閉状態は保持）
- SetNextItemOpen()で初期開閉状態を設定可能

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | imgui.h | `imgui.h` | ImGuiTreeNodeFlags_CollapsingHeaderの定義（1319行目） |

**読解のコツ**: CollapsingHeaderフラグは複合フラグ（Framed | NoTreePushOnOpen | NoAutoOpenOnLog）。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | imgui.h | `imgui.h` | CollapsingHeaderの関数宣言（755-756行目） |

**主要処理フロー**:
1. **755行目**: 基本形（label + flags）
2. **756行目**: 閉じるボタン付き（label + p_visible + flags）

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | imgui_widgets.cpp | `imgui_widgets.cpp` | CollapsingHeader(label, flags)の実装（7244-7251行目） |
| 3-2 | imgui_widgets.cpp | `imgui_widgets.cpp` | CollapsingHeader(label, p_visible, flags)の実装（7257-7288行目） |

**主要処理フロー**:
- **7246-7248行目**: ウィンドウ取得とスキップチェック
- **7249行目**: ID生成
- **7250行目**: TreeNodeBehavior呼び出し（CollapsingHeaderフラグ付き）
- **7263-7264行目**: *p_visible==falseの場合の早期リターン
- **7266-7270行目**: フラグ設定とTreeNodeBehavior呼び出し
- **7271-7284行目**: 閉じるボタンの描画処理

#### Step 4: 閉じるボタン処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | imgui_widgets.cpp | `imgui_widgets.cpp` | CloseButton関数 |

**主要処理フロー**:
- **7278-7279行目**: ボタン位置の計算
- **7281-7282行目**: CloseButton呼び出しと*p_visibleの更新

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

```
CollapsingHeader (imgui_widgets.cpp:7244)
    │
    └─ TreeNodeBehavior (imgui_widgets.cpp:6816)
           │
           ├─ [CollapsingHeaderフラグにより]
           │      ├─ Framedフラグ：背景フレーム描画
           │      ├─ NoTreePushOnOpen：TreePush省略
           │      └─ NoAutoOpenOnLog：ログ時の自動展開抑制
           │
           └─ 開閉状態を返却

CollapsingHeader (p_visible版)
    │
    ├─ TreeNodeBehavior
    │
    └─ CloseButton (p_visible時)
           └─ *p_visible = false (クリック時)
```

### データフロー図

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

const char* label ───▶ ID生成
                           │
ImGuiTreeNodeFlags        ▼
flags ───────────────▶ flags |= CollapsingHeader
                           │
                           ▼
bool* p_visible ─────▶ TreeNodeBehavior
                           │
                           ├───▶ ヘッダー描画
                           │
                           ▼
                       閉じるボタン処理 ───▶ *p_visible = false
                       (p_visible時)            (クリック時)
                           │
                           ▼
                       return is_open ───────▶ bool
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| imgui.h | `imgui.h` | ヘッダ | API宣言とフラグ定義 |
| imgui_widgets.cpp | `imgui_widgets.cpp` | ソース | CollapsingHeaderの実装 |
| imgui_internal.h | `imgui_internal.h` | ヘッダ | 内部関数宣言 |
