# 画面設計書 4-ID Stack Tool Window

## 概要

ImGuiのIDスタックをデバッグするためのツールウィンドウの設計書である。UIアイテムのID生成過程を可視化し、ID衝突問題のデバッグを支援する。

### 本画面の処理概要

ID Stack Tool Windowは、マウスでホバーしたUIアイテムのIDスタック（PushID呼び出しの履歴）を表示し、最終的なIDがどのように計算されているかを可視化するデバッグツールである。

**業務上の目的・背景**：ImGuiではウィジェットの一意性をIDで管理しており、同じIDを持つウィジェットが存在するとクリックやフォーカスの動作が不正になる。ID衝突は特にループ内でウィジェットを生成する場合に発生しやすく、このツールを使用することでIDスタックの構造を理解し、問題を解決できる。

**画面へのアクセス方法**：
1. Metrics/Debugger Windowの「Show ID Stack Tool」チェックボックスを有効にする
2. Demo Windowのメニューバーから「Tools」→「ID Stack Tool」を選択
3. コード内で直接`ImGui::ShowIDStackToolWindow()`を呼び出す

**主要な操作・処理内容**：
1. ウィンドウを開いた状態で任意のUIアイテムにマウスをホバーする
2. ホバーしたアイテムのIDスタック情報がテーブルに表示される
3. 「Hex-encode non-ASCII」オプションで非ASCII文字の表示形式を切り替える
4. Ctrl+Cでパスをクリップボードにコピーする

**画面遷移**：
- 遷移元：Demo Window（Tools Menu）、Metrics/Debugger Window、またはアプリケーションコードからの直接呼び出し
- 遷移先：なし

**権限による表示制御**：なし（デバッグ用途のため権限制御は不要）

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 15 | ShowIDStackToolWindow | 主機能 | IDスタックツールウィンドウの表示 |
| 24 | Begin | 主機能 | ウィンドウの開始処理 |
| 25 | End | 主機能 | ウィンドウの終了処理 |
| 85 | Text | 補助機能 | IDスタック情報の表示 |
| 135 | TreeNode | 補助機能 | IDスタックのツリー表示 |

## 画面種別

デバッグ/分析画面

## URL/ルーティング

N/A（Immediate Mode GUIのため、URLやルーティングの概念は適用されない）

## 入出力項目

| 項目名 | 型 | 入力/出力 | 必須 | 説明 |
|--------|-----|----------|------|------|
| p_open | bool* | 入出力 | 任意 | ウィンドウの表示状態を制御するポインタ |

## 表示項目

| 項目名 | 説明 |
|--------|------|
| メインID | 現在ホバー中のアイテムの最終ID（0xXXXXXXXX形式） |
| Hex-encode non-ASCIIチェックボックス | 非ASCII文字を16進数でエンコードするかどうか |
| Ctrl+C: copy pathチェックボックス | Ctrl+Cでパスをコピーする機能の有効/無効 |
| *COPIED*インジケータ | コピー成功時に点滅表示 |
| Pathテキスト | IDパスの文字列表現 |
| Labelテキスト | Test Engine使用時のアイテムラベル |
| IDスタックテーブル | Seed、PushID、Resultの3列テーブル |

## イベント仕様

### 1-アイテムホバー

UIアイテムにマウスをホバーすると、g.DebugItemPathQueryが更新され、そのアイテムのIDスタック情報が取得される。

### 2-Hex-encodeオプション切り替え

「Hex-encode non-ASCII」チェックボックスを切り替えると、tool->OptHexEncodeNonAsciiCharsが更新され、パス表示の形式が変わる。

### 3-パスコピー

「Ctrl+C: copy path」が有効な状態でCtrl+Cを押すと、現在のパス文字列がクリップボードにコピーされ、「*COPIED*」インジケータが点滅する。

### 4-IDスタック表示

ホバーしたアイテムのIDスタックがテーブル形式で表示される。各行にはSeed（前段のID）、PushID（この段で追加された識別子）、Result（この段の結果ID）が表示される。

## データベース更新仕様

N/A（Dear ImGuiはUIライブラリであり、データベース操作は行わない）

## メッセージ仕様

N/A

## 例外処理

| 状態 | 処理内容 |
|------|----------|
| ウィンドウ折りたたみ状態 | Begin()がfalseを返し、End()のみ呼び出して早期リターン |
| BeginCountが1より大きい | 同一フレームで複数回呼び出された場合、早期リターン |
| アイテム未ホバー | IDスタックテーブルは空のまま表示 |

## 備考

- IMGUI_ENABLE_TEST_ENGINEが定義されている場合、Labelにアイテムのデバッグラベルが表示される
- IDスタックテーブルの最終行（最終ID）は背景色でハイライトされる
- IMGUI_DISABLE_DEBUG_TOOLSマクロが定義されている場合、この関数は空実装になる
- 旧名称はShowStackToolWindow()であったが、1.90.0でShowIDStackToolWindow()に改名された

---

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

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

### 推奨読解順序

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

ID Stack Toolの状態を保持するデータ構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | imgui_internal.h | `imgui_internal.h` | ImGuiDebugItemPathQuery構造体でクエリ結果を保持 |
| 1-2 | imgui_internal.h | `imgui_internal.h` | ImGuiIDStackTool構造体でツール設定を保持 |
| 1-3 | imgui_internal.h | `imgui_internal.h` | ImGuiStackLevelInfo構造体でスタック各段の情報を保持 |

**読解のコツ**: ImGuiDebugItemPathQueryはホバーしたアイテムのID情報を追跡し、Resultsベクターに各PushIDレベルの情報を格納する。

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

ShowIDStackToolWindow関数がID Stack Tool Windowの描画処理のエントリーポイント。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | imgui.cpp | `imgui.cpp` | ShowIDStackToolWindow()関数（行18050以降）がエントリーポイント |

**主要処理フロー**:
1. **行18053-18059**: ウィンドウサイズ設定とBegin処理
2. **行18061-18067**: クエリ結果の取得とヘルプマーカー表示
3. **行18069-18082**: オプションチェックボックスとCtrl+Cコピー処理
4. **行18084-18088**: Path、Label（Test Engine時）の表示
5. **行18091-18112**: IDスタックテーブルの描画

#### Step 3: ID追跡メカニズムを理解する

ImGuiがどのようにIDスタックを追跡するかを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | imgui.cpp | `imgui.cpp` | DebugHookIdInfo関数でID情報をフック |
| 3-2 | imgui.cpp | `imgui.cpp` | DebugItemPathQuery_*関数群でクエリ処理 |

**主要処理フロー**:
- DebugHookIdInfo(): PushID等の呼び出し時にID情報を記録
- DebugItemPathQuery_FormatLevelInfo(): 各スタックレベルの情報をフォーマット
- DebugItemPathQuery_GetResultAsPath(): パス文字列を生成

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

```
ImGui::ShowIDStackToolWindow(bool* p_open)
    |
    +-- SetNextWindowSize()
    +-- ImGui::Begin("Dear ImGui ID Stack Tool", p_open)
    |       |
    |       +-- DebugItemPathQuery_GetResultAsPath()
    |       |
    |       +-- Text("0x%08X", query->MainID)
    |       +-- MetricsHelpMarker()
    |       |
    |       +-- Checkbox("Hex-encode non-ASCII")
    |       +-- Checkbox("Ctrl+C: copy path")
    |       +-- Shortcut(ImGuiMod_Ctrl | ImGuiKey_C)
    |       |       +-- SetClipboardText()
    |       |
    |       +-- Text("- Path \"%s\"")
    |       +-- Text("- Label \"%s\"")  [Test Engine時]
    |       |
    |       +-- BeginTable("##table", 3)
    |       |       +-- TableSetupColumn("Seed")
    |       |       +-- TableSetupColumn("PushID")
    |       |       +-- TableSetupColumn("Result")
    |       |       +-- TableHeadersRow()
    |       |       |
    |       |       +-- [ループ: query->Results]
    |       |       |       +-- TableNextColumn()
    |       |       |       +-- Text("0x%08X")  [Seed]
    |       |       |       +-- TableNextColumn()
    |       |       |       +-- DebugItemPathQuery_FormatLevelInfo()
    |       |       |       +-- TableNextColumn()
    |       |       |       +-- Text("0x%08X")  [Result]
    |       |       |       +-- TableSetBgColor()  [最終行]
    |       |       |
    |       +-- EndTable()
    |
    +-- ImGui::End()
```

### データフロー図

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

p_open (bool*)  ─────────▶ ShowIDStackToolWindow() ─────────▶  ウィンドウ描画
                                  |
マウスホバー    ─────────▶       |
                                  |
g.DebugItemPathQuery ◀───▶       |  ◀──── ID情報収集
                                  |
g.DebugIDStackTool   ◀───▶       |  ◀──── ツール設定
                                  |
                                  ▼
                           クリップボード
                           (コピー時)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| imgui.cpp | `imgui.cpp` | ソース | ShowIDStackToolWindow()の実装 |
| imgui.h | `imgui.h` | ヘッダー | ShowIDStackToolWindow()のAPI宣言 |
| imgui_internal.h | `imgui_internal.h` | ヘッダー | ImGuiDebugItemPathQuery等の内部構造体定義 |
