# 機能設計書 140-SetNextItemOpen

## 概要

本ドキュメントは、ImGuiライブラリにおける次アイテムの開閉状態設定関数 `SetNextItemOpen` の機能仕様を定義するものである。

### 本機能の処理概要

SetNextItemOpenは、次に作成されるTreeNode/CollapsingHeaderの開閉状態を事前に設定する機能である。

**業務上の目的・背景**：ツリー構造のUIにおいて、プログラム的に特定のノードを開いたり閉じたりしたい場面がある。例えば、検索結果のハイライト表示時に該当ノードを自動展開したり、初回表示時に特定のセクションをデフォルトで開いたりする場合に使用される。SetNextItemOpenを使用すると、TreeNode/CollapsingHeaderの呼び出し前に開閉状態を指定できる。

**機能の利用シーン**：ツリービューで検索結果にジャンプする際の自動展開、設定画面で特定カテゴリをデフォルトで開く、ユーザー操作に応じたツリー状態の復元、条件付きでのノード展開制御など。

**主要な処理内容**：
1. 次のアイテム用データフラグにHasOpenを設定
2. 開閉状態（OpenVal）を保存
3. 適用条件（OpenCond）を保存
4. 次のTreeNode/CollapsingHeaderで参照・消費される

**関連システム・外部連携**：TreeNode()、TreeNodeEx()、CollapsingHeader()で参照される。

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | （多くの画面で間接的に使用） | - | TreeNode/CollapsingHeaderの初期状態設定 |

## 機能種別

状態設定 / 次アイテム用パラメータ設定

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| is_open | bool | Yes | 設定する開閉状態（trueで開く、falseで閉じる） | - |
| cond | ImGuiCond | No | 適用条件 | デフォルトは0（ImGuiCond_Always） |

### ImGuiCond の値

| 値 | 説明 |
|----|------|
| ImGuiCond_Always | 常に適用 |
| ImGuiCond_Once | 初回のみ適用（その後はストレージ値を使用） |
| ImGuiCond_FirstUseEver | 初めて使用する時のみ適用 |

### 入力データソース

- アプリケーションコードから渡される状態値

## 出力仕様

### 出力データ

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

### 出力先

- グローバルコンテキスト（g.NextItemData）

## 処理フロー

### 処理シーケンス

```
1. ウィンドウスキップチェック
   └─ SkipItemsがtrueなら処理スキップ
2. NextItemDataにHasOpenフラグを設定
   └─ g.NextItemData.HasFlags |= ImGuiNextItemDataFlags_HasOpen
3. 開閉状態を保存
   └─ g.NextItemData.OpenVal = is_open
4. 適用条件を保存
   └─ g.NextItemData.OpenCond = cond ? cond : ImGuiCond_Always
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{SkipItems?}
    B -->|Yes| C[return 処理スキップ]
    B -->|No| D[HasOpenフラグ設定]
    D --> E[OpenVal = is_open]
    E --> F{cond == 0?}
    F -->|Yes| G[OpenCond = Always]
    F -->|No| H[OpenCond = cond]
    G --> I[終了]
    H --> I
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-140-01 | 次アイテム限定 | 設定は次のTreeNode/CollapsingHeaderにのみ適用 | 常時 |
| BR-140-02 | 1回消費 | 設定は使用後にクリアされる | 常時 |
| BR-140-03 | デフォルトAlways | cond==0の場合はImGuiCond_Alwaysとして扱う | cond未指定時 |
| BR-140-04 | Once/FirstUseEver同一視 | ツリーノードではOnceとFirstUseEverは同じ動作 | 常時 |

### 計算ロジック

- 条件判定：`cond ? cond : ImGuiCond_Always`

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

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

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

## エラー処理

### エラーケース一覧

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

### リトライ仕様

リトライ処理は不要

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

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

## パフォーマンス要件

- 非常に軽量な処理（フラグ設定のみ）

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

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

## 備考

- TreeNodeExのDefaultOpenフラグとは異なり、既存のストレージ値を上書きできる
- ImGuiCond_Alwaysを使用すると、ユーザーの開閉操作を無視して強制的に状態を設定
- SetNextItemStorageID()と組み合わせて、開閉状態の保存先を制御することも可能

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | imgui_internal.h | `imgui_internal.h` | ImGuiNextItemData構造体 |
| 1-2 | imgui.h | `imgui.h` | ImGuiCond列挙型 |

**読解のコツ**: NextItemDataは次のアイテムに適用する各種設定を一時的に保持する構造体。

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

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

**主要処理フロー**:
1. **757行目**: is_openとcond（オプション）を引数に取る

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

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

**主要処理フロー**:
- **7224-7226行目**: ウィンドウ取得とスキップチェック
- **7227行目**: HasOpenフラグの設定
- **7228行目**: OpenValの設定
- **7229行目**: OpenCondの設定

#### Step 4: 使用箇所を理解する

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

**主要処理フロー**:
- **6757-6778行目**: NextItemData.HasFlagsのHasOpenチェックと条件処理
- **6759-6762行目**: ImGuiCond_Always時の処理
- **6765-6776行目**: Once/FirstUseEver時の処理

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

```
SetNextItemOpen (imgui_widgets.cpp:7222)
    │
    └─ g.NextItemData
           ├─ HasFlags |= HasOpen
           ├─ OpenVal = is_open
           └─ OpenCond = cond

[次のTreeNode/CollapsingHeader呼び出し時]
    │
    └─ TreeNodeUpdateNextOpen (imgui_widgets.cpp:6745)
           │
           ├─ g.NextItemData.HasFlags & HasOpen をチェック
           │
           ├─ [ImGuiCond_Always時]
           │      └─ ストレージに強制設定
           │
           └─ [Once/FirstUseEver時]
                  └─ ストレージ未設定時のみ適用
```

### データフロー図

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

bool is_open ─────────▶ g.NextItemData.OpenVal

ImGuiCond cond ───────▶ g.NextItemData.OpenCond
                              │
                              ▼
                   [次のTreeNode/CollapsingHeader]
                              │
                              ▼
                   TreeNodeUpdateNextOpen
                              │
                              ▼
                   開閉状態の決定 ──────────▶ is_open (ノードの状態)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| imgui.h | `imgui.h` | ヘッダ | API宣言とImGuiCond定義 |
| imgui_widgets.cpp | `imgui_widgets.cpp` | ソース | SetNextItemOpenの実装 |
| imgui_internal.h | `imgui_internal.h` | ヘッダ | ImGuiNextItemData構造体定義 |
