# 機能設計書 137-TreePush

## 概要

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

### 本機能の処理概要

TreePushは、ツリー階層をプッシュする（インデント追加 + IDスタックプッシュ）機能である。TreeNode()が開いている場合に自動的に呼び出されるが、手動でも使用可能。

**業務上の目的・背景**：TreeNode()を使用せずに、インデントとIDスコープを手動で管理したい場合がある。例えば、カスタムツリー表示の実装、TreeNodeと異なる見た目のツリー構造の実現、または条件に応じたインデント制御などの場面で使用される。TreePushは、Indent()とPushID()の組み合わせをシンプルに行うためのヘルパー関数である。

**機能の利用シーン**：カスタムツリービューの実装、TreeNodeを使わない階層表示、条件付きインデント制御、ループ内での動的IDスコープ管理など。

**主要な処理内容**：
1. Indent()の呼び出し（インデント追加）
2. ウィンドウのTreeDepthをインクリメント
3. PushID()の呼び出し（IDスタックプッシュ）

**関連システム・外部連携**：TreePop()と必ずペアで使用。TreeNode()が開いている場合に内部で自動呼び出しされる。

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

## 関連画面

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

## 機能種別

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

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| str_id | const char* | Yes | IDとして使用する文字列 | - |
| ptr_id | const void* | No | IDとして使用するポインタ（オーバーロード版） | - |

### 入力データソース

- ユーザーが指定するID

## 出力仕様

### 出力データ

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

### 出力先

- ウィンドウのインデント状態
- ウィンドウのTreeDepthカウンタ
- IDスタック

## 処理フロー

### 処理シーケンス

```
1. 現在のウィンドウを取得
   └─ GetCurrentWindow()
2. インデントを追加
   └─ Indent()
3. TreeDepthをインクリメント
   └─ window->DC.TreeDepth++
4. IDスタックにプッシュ
   └─ PushID(str_id/ptr_id)
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[GetCurrentWindow]
    B --> C[Indent]
    C --> D[TreeDepth++]
    D --> E[PushID]
    E --> F[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-137-01 | ペア必須 | TreePush()には必ずTreePop()が対応する | 常時 |
| BR-137-02 | TreeNode連動 | TreeNode()が開くとTreePushが自動呼び出しされる | TreeNode戻り値true時 |
| BR-137-03 | 等価操作 | TreePush ≈ Indent() + PushID() | 常時 |

### 計算ロジック

- TreeDepth管理：`window->DC.TreeDepth++`

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

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | - | - | - |

### リトライ仕様

リトライ処理は不要

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

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

## パフォーマンス要件

- 非常に軽量な処理（状態変更のみ）

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

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

## 備考

- TreePushOverrideID()という内部関数も存在する
- IDスタックが空になることを防ぐため、TreePopでのチェックが重要
- TreePush/TreePopの対応が崩れるとIDの一意性が損なわれる

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | imgui_internal.h | `imgui_internal.h` | ImGuiWindowのDC.TreeDepthメンバ |

**読解のコツ**: TreeDepthはインデントレベルの追跡に使用される。

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

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

**主要処理フロー**:
1. **751行目**: 文字列ID版
2. **752行目**: ポインタID版

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | imgui_widgets.cpp | `imgui_widgets.cpp` | TreePush(str_id)の実装（7157-7163行目） |
| 3-2 | imgui_widgets.cpp | `imgui_widgets.cpp` | TreePush(ptr_id)の実装（7165-7171行目） |

**主要処理フロー**:
- **7159行目**: GetCurrentWindow()
- **7160行目**: Indent()呼び出し
- **7161行目**: TreeDepthインクリメント
- **7162行目**: PushID()呼び出し

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

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

**主要処理フロー**:
- **7177行目**: Indent()
- **7178行目**: TreeDepth++
- **7179行目**: PushOverrideID()（PushIDとは異なる）

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

```
TreePush (imgui_widgets.cpp:7157)
    │
    ├─ GetCurrentWindow
    │
    ├─ Indent
    │      └─ window->DC.Indent += style.IndentSpacing
    │
    └─ PushID
           └─ IDスタックにプッシュ

TreeNodeBehavior (内部呼び出し元)
    │
    └─ TreePush (is_open && !NoTreePushOnOpen時)
```

### データフロー図

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

const char* str_id ───▶ GetCurrentWindow
      または              │
const void* ptr_id        ▼
                       Indent() ──────────────────▶ インデント状態
                          │
                          ▼
                       TreeDepth++ ───────────────▶ DC.TreeDepth
                          │
                          ▼
                       PushID() ──────────────────▶ IDスタック
```

### 関連ファイル一覧

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