# 機能設計書 138-TreePop

## 概要

本ドキュメントは、ImGuiライブラリにおけるツリー階層ポップ関数 `TreePop` の機能仕様を定義するものである。

### 本機能の処理概要

TreePopは、ツリー階層をポップする（インデント解除 + IDスタックポップ）機能である。TreeNode()やTreePush()に対応するクローズ処理として必ず呼び出す必要がある。

**業務上の目的・背景**：TreeNode()が開いている場合にプッシュされた階層状態を正しく解除するために必要な関数である。TreePush/TreePopのバランスが崩れると、インデントやIDスタックが不整合になり、UIの表示崩れやID衝突が発生する。TreePopは、Unindent()とPopID()の組み合わせに加えて、階層接続線の描画やナビゲーション処理も担当する。

**機能の利用シーン**：TreeNode()がtrueを返した後のクローズ処理、TreePush()後のクローズ処理、ツリー構造の描画終了時など。

**主要な処理内容**：
1. Unindent()の呼び出し（インデント解除）
2. ウィンドウのTreeDepthをデクリメント
3. 階層接続線の描画処理（DrawLinesフラグ使用時）
4. ナビゲーション処理（NavLeftJumpsToParentフラグ使用時）
5. TreeNodeStackからのデータポップ
6. PopID()の呼び出し（IDスタックポップ）

**関連システム・外部連携**：TreeNode()/TreePush()と必ずペアで使用。

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | （間接的に多くの画面で使用） | - | TreeNodeの終了処理として使用 |

## 機能種別

階層管理 / IDスタック管理

## 入力仕様

### 入力パラメータ

パラメータなし

### 入力データソース

- ウィンドウのTreeDepth状態
- TreeNodeStack（開いているノードの情報）
- IDスタック

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| (なし) | void | 戻り値なし |

### 出力先

- ウィンドウのインデント状態
- ウィンドウのTreeDepthカウンタ
- IDスタック
- 描画リスト（階層接続線）

## 処理フロー

### 処理シーケンス

```
1. 現在のウィンドウを取得
   └─ g.CurrentWindow
2. インデントを解除
   └─ Unindent()
3. TreeDepthをデクリメント
   └─ window->DC.TreeDepth--
4. TreeNodeStackデータの処理
   └─ 対応するデータが存在する場合
      ├─ ナビゲーション処理（NavLeftJumpsToParent時）
      ├─ 階層接続線の描画（DrawLinesフラグ時）
      └─ スタックからポップ
5. IDスタックからポップ
   └─ PopID()
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[GetCurrentWindow]
    B --> C[Unindent]
    C --> D[TreeDepth--]
    D --> E{TreeNodeStackデータあり?}
    E -->|Yes| F[ナビゲーション処理]
    E -->|No| K[PopID]
    F --> G{DrawLines?}
    G -->|Yes| H[接続線描画]
    G -->|No| I[スタックポップ]
    H --> I
    I --> J[マスククリア]
    J --> K
    K --> L[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-138-01 | ペア必須 | TreePush/TreeNode(true)には必ずTreePop()が対応する | 常時 |
| BR-138-02 | IDスタック保護 | IDスタックが空にならないようにチェック | 常時 |
| BR-138-03 | データ整合性 | TreeNodeStackのIDとIDスタックの先頭が一致することを確認 | デバッグ時 |
| BR-138-04 | 等価操作 | TreePop ≈ Unindent() + PopID() + 追加処理 | 常時 |

### 計算ロジック

- TreeDepth管理：`window->DC.TreeDepth--`
- マスク計算：`tree_depth_mask = (1 << window->DC.TreeDepth)`

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

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | アサーション | IDスタックが1要素しかない | IM_ASSERTで停止（デバッグビルド） |

### リトライ仕様

リトライ処理は不要

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

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

## パフォーマンス要件

- 非常に軽量な処理（状態変更と条件付き描画）
- 階層接続線描画時はやや負荷増加

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

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

## 備考

- TreePush/TreePopの対応が崩れるとIM_ASSERTで停止する
- NavLeftJumpsToParentフラグ使用時は、左矢印キーで親ノードにジャンプ可能
- DrawLinesフラグ使用時は階層接続線が描画される（実験的機能）

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | imgui_internal.h | `imgui_internal.h` | ImGuiTreeNodeStackData構造体 |
| 1-2 | imgui_internal.h | `imgui_internal.h` | ImGuiWindowのDC.TreeDepth、TreeHasStackDataDepthMask |

**読解のコツ**: TreeNodeStackDataはノード描画に必要な情報（ID、フラグ、描画位置等）を保持。

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

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

**主要処理フロー**:
1. **753行目**: 引数なし、戻り値void

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | imgui_widgets.cpp | `imgui_widgets.cpp` | TreePopの実装（7182-7212行目） |

**主要処理フロー**:
- **7184-7185行目**: コンテキストとウィンドウ取得
- **7186行目**: Unindent()呼び出し
- **7188行目**: TreeDepthデクリメント
- **7189行目**: マスク計算
- **7191-7208行目**: TreeNodeStackデータの処理
  - **7197-7199行目**: ナビゲーション処理
  - **7202-7203行目**: 階層接続線描画
  - **7205行目**: スタックポップ
- **7210行目**: IDスタック保護のASSERT
- **7211行目**: PopID()呼び出し

#### Step 4: 関連処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | imgui_widgets.cpp | `imgui_widgets.cpp` | TreeNodeDrawLineToTreePop（7140-7155行目） |

**主要処理フロー**:
- **7152行目**: 接続線の描画（DrawList->AddLine）

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

```
TreePop (imgui_widgets.cpp:7182)
    │
    ├─ Unindent
    │      └─ window->DC.Indent -= style.IndentSpacing
    │
    ├─ [TreeNodeStackデータ処理]
    │      │
    │      ├─ NavMoveRequestResolveWithPastTreeNode
    │      │      └─ ナビゲーション左移動の解決
    │      │
    │      └─ TreeNodeDrawLineToTreePop
    │             └─ DrawList->AddLine
    │
    └─ PopID
           └─ IDスタックからポップ
```

### データフロー図

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

(パラメータなし)          Unindent() ──────────────▶ インデント状態

window->DC.TreeDepth ──▶ TreeDepth-- ─────────────▶ DC.TreeDepth

TreeNodeStack ─────────▶ データ処理
                              │
                              ├─ ナビゲーション ────▶ NavMoveResult
                              │
                              └─ 接続線描画 ────────▶ DrawList

IDスタック ────────────▶ PopID() ──────────────────▶ IDスタック
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| imgui.h | `imgui.h` | ヘッダ | API宣言 |
| imgui_widgets.cpp | `imgui_widgets.cpp` | ソース | TreePopの実装 |
| imgui_internal.h | `imgui_internal.h` | ヘッダ | TreeNodeStackData等の内部構造体 |
