# 機能設計書 15-ShowIDStackToolWindow

## 概要

本ドキュメントは、Dear ImGuiライブラリにおけるShowIDStackToolWindow関数の機能設計を記載する。この関数はウィジェットの一意なID生成元を調査するためのIDスタックツールウィンドウを提供する。

### 本機能の処理概要

ShowIDStackToolWindow関数は、ImGuiウィジェットの一意なIDがどのように生成されているかを可視化するツールウィンドウを表示する。マウスでアイテムをホバーすると、そのアイテムのIDスタック（各PushID呼び出しの履歴）を表示し、最終的なIDの生成過程を確認できる。これにより、ID衝突問題の診断やデバッグが容易になる。

**業務上の目的・背景**：ImGuiでは、各ウィジェットは一意のIDで識別される。このIDは、IDスタック（PushID/PopIDの呼び出し履歴）とウィジェット自身のラベルをハッシュして生成される。ID衝突が発生すると、ウィジェットが正しく動作しなくなるため、IDの生成過程を理解することは重要である。ShowIDStackToolWindowは、この問題の診断を支援するためのツールを提供する。

**機能の利用シーン**：
- ID衝突エラーが発生した際の原因調査
- 動的に生成されるウィジェットのID構造を確認する際
- PushID/PopIDの使い方を学習する際
- 複雑なウィジェット階層のデバッグ時

**主要な処理内容**：
1. ホバーされたアイテムのIDを検出・表示
2. IDスタックの各レベル（Seed、PushID引数、Result）をテーブル形式で表示
3. ID生成パスの文字列表現を提供
4. Ctrl+Cでパスをクリップボードにコピーする機能
5. 非ASCII文字の16進数エンコードオプション

**関連システム・外部連携**：
- ShowMetricsWindow（メトリクスウィンドウから呼び出し可能）
- DebugHookIdInfo（ID情報のフック）
- クリップボード機能（パスのコピー）

**権限による制御**：本機能に権限制御はない。ただし、IMGUI_DISABLE_DEBUG_TOOLSが定義されている場合は空の関数となる。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 4 | ID Stack Tool Window | 主画面 | IDスタックツールウィンドウの表示 |
| 2 | Metrics/Debugger Window | 呼び出し元 | Toolsセクションから遷移可能 |

## 機能種別

デバッグ・ID分析

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| p_open | bool* | No | ウィンドウの開閉状態を制御するポインタ。NULLの場合は閉じるボタンなし | NULL許容 |

### 入力データソース

- ImGuiContext::DebugItemPathQuery（IDパスクエリ情報）
- ImGuiContext::DebugIDStackTool（ツールの設定状態）
- ホバーされたアイテムのID情報

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 戻り値 | void | 戻り値なし |
| *p_open | bool | ユーザーがウィンドウを閉じた場合falseに設定 |

### 出力先

- ImGuiウィンドウとして画面に描画
- クリップボード（Ctrl+Cでパスコピー時）

## 処理フロー

### 処理シーケンス

```
1. ウィンドウサイズの初期設定
   └─ SetNextWindowSize（初回使用時）
2. メインウィンドウの開始
   └─ Begin("Dear ImGui ID Stack Tool", p_open)
3. メインIDの表示
   └─ Text("0x%08X", query->MainID)
4. オプションの表示
   └─ Checkbox("Hex-encode non-ASCII")
   └─ Checkbox("Ctrl+C: copy path")
5. パス情報の表示
   └─ Text("- Path \"%s\"", result_path)
6. IDスタックテーブルの表示
   └─ BeginTable + TableSetupColumn + TableHeadersRow
   └─ 各レベルの Seed/PushID/Result を表示
7. ウィンドウの終了
   └─ End()
```

### フローチャート

```mermaid
flowchart TD
    A[ShowIDStackToolWindow呼び出し] --> B[ウィンドウサイズ設定]
    B --> C[Begin - メインウィンドウ開始]
    C --> D{ウィンドウ可視?}
    D -->|No| E[End - 早期リターン]
    D -->|Yes| F[メインID表示]
    F --> G[オプションチェックボックス]
    G --> H{Ctrl+C押下?}
    H -->|Yes| I[パスをクリップボードにコピー]
    H -->|No| J[パス情報表示]
    I --> J
    J --> K{クエリ結果あり?}
    K -->|Yes| L[IDスタックテーブル表示]
    K -->|No| M[End]
    L --> M
    E --> N[終了]
    M --> N
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | 再入防止 | 同一フレーム内での多重呼び出しを検出し早期リターン | BeginCount > 1時 |
| BR-02 | ホバー検出 | マウスでアイテムをホバーするとIDスタッククエリが実行される | ツールウィンドウ表示中 |
| BR-03 | 16進数エンコード | 非ASCII文字をオプションで16進数表示可能 | OptHexEncodeNonAsciiChars有効時 |
| BR-04 | コピー通知 | Ctrl+Cでコピー後、一定時間"*COPIED*"を表示 | コピー実行後0.75秒間 |

### 計算ロジック

- ID生成: 各レベルのSeed + PushID引数をハッシュして次のIDを生成
- コピー通知点滅: `time_since_copy < 0.75f && ImFmod(time_since_copy, 0.25f) < 0.25f * 0.5f`

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

該当なし（インメモリ動作）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| 早期リターン | 多重呼び出し | 同一フレーム内で複数回呼び出し | 自動的に処理をスキップ |

### リトライ仕様

該当なし（毎フレーム呼び出し）

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

該当なし

## パフォーマンス要件

- ホバー検出はマウス位置に基づく効率的な判定
- IDスタック情報はキャッシュされ、同一アイテムに対しては再計算しない

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

該当なし（ローカルUI表示のみ）

## 備考

- IMGUI_DISABLE_DEBUG_TOOLSが定義されている場合、空の関数となる
- 旧名称はShowStackToolWindow()であったが、1.90.0でShowIDStackToolWindow()に改名された
- IMGUI_ENABLE_TEST_ENGINE有効時はテストエンジンからラベル情報を取得可能

---

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

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

### 推奨読解順序

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

IDスタック管理に使用されるデータ構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 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ベクターに各レベルの情報が格納される。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | imgui.h | `imgui.h` | ShowIDStackToolWindow関数の宣言（410行目） |
| 2-2 | imgui.cpp | `imgui.cpp` | ShowIDStackToolWindow関数の実装（18050行目〜） |

**主要処理フロー**:
1. **18053-18054行目**: ウィンドウサイズの初期設定
2. **18055-18059行目**: Begin呼び出しと早期リターン処理
3. **18061-18064行目**: クエリとツール設定の取得、パス生成
4. **18065-18067行目**: メインID表示とヘルプマーカー
5. **18071-18082行目**: オプションチェックボックスとCtrl+C処理
6. **18084-18088行目**: パス情報の表示
7. **18091-18112行目**: IDスタックテーブルの表示

#### Step 3: ヘルパー関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | imgui.cpp | `imgui.cpp` | DebugItemPathQuery_GetResultAsPath関数 |
| 3-2 | imgui.cpp | `imgui.cpp` | DebugItemPathQuery_FormatLevelInfo関数 |

**主要処理フロー**:
- これらの関数はIDスタック情報を人間が読みやすい形式にフォーマットする

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

```
ShowIDStackToolWindow()
    │
    ├─ SetNextWindowSize()
    │
    ├─ Begin("Dear ImGui ID Stack Tool")
    │      │
    │      ├─ DebugItemPathQuery_GetResultAsPath()
    │      │      └─ IDパスを文字列に変換
    │      │
    │      ├─ Text("0x%08X") - メインID表示
    │      │
    │      ├─ Checkbox("Hex-encode non-ASCII")
    │      ├─ Checkbox("Ctrl+C: copy path")
    │      │
    │      ├─ [条件付き] Shortcut() + SetClipboardText()
    │      │
    │      ├─ Text("- Path ...") - パス表示
    │      │
    │      └─ [条件付き] BeginTable("##table")
    │             ├─ TableSetupColumn("Seed")
    │             ├─ TableSetupColumn("PushID")
    │             ├─ TableSetupColumn("Result")
    │             ├─ TableHeadersRow()
    │             └─ 各レベルの情報を表示
    │
    └─ End()
```

### データフロー図

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

ホバーアイテム       ShowIDStackToolWindow()         ID Stack Tool描画
    │                      │                              │
    ├─ マウス位置          ├─ IDスタッククエリ             │
    │                      │                              │
DebugItemPathQuery         ├─ パス文字列生成              │
    │                      │                              │
    └─ 各レベル情報 ───────┴─ テーブル形式で表示           │
                                                          │
p_open (bool*) ────────────────────────────────────────────┘
                         閉じるボタン押下時
                         *p_open = false
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| imgui.h | `imgui.h` | ヘッダー | ShowIDStackToolWindow宣言（410行目） |
| imgui.cpp | `imgui.cpp` | ソース | ShowIDStackToolWindow実装（18050-18114行目） |
| imgui_internal.h | `imgui_internal.h` | ヘッダー | ImGuiDebugItemPathQuery等の定義 |
