# 機能設計書 14-ShowDebugLogWindow

## 概要

本ドキュメントは、Dear ImGuiライブラリにおけるShowDebugLogWindow関数の機能設計を記載する。この関数はImGuiの重要なイベントを簡易的にログ表示するデバッグログウィンドウを提供する。

### 本機能の処理概要

ShowDebugLogWindow関数は、Dear ImGuiが発生させる重要なイベントをリアルタイムでログ表示するウィンドウを作成・表示する。エラー、フォーカス変更、ポップアップ、ナビゲーション、入力ルーティングなど、カテゴリ別にフィルタリング可能なログを提供し、開発者がUI動作のデバッグを効率的に行えるようにする。

**業務上の目的・背景**：複雑なGUIアプリケーションでは、UIの動作を追跡することが困難な場合がある。ShowDebugLogWindowは、ImGuiの内部イベントをテキストログとして可視化し、問題発生時の原因特定を支援する。特に、フォーカス遷移、ポップアップの開閉、ナビゲーション状態の変化など、目視では追いにくいイベントを記録・表示することで、デバッグ効率を向上させる。

**機能の利用シーン**：
- フォーカス関連の問題をデバッグする際
- ポップアップの開閉タイミングを確認する際
- ナビゲーション動作を検証する際
- 入力ルーティングの問題を調査する際
- エラーイベントを追跡する際

**主要な処理内容**：
1. ログカテゴリフィルタの表示（Errors、ActiveId、Focus、IO、Nav、Popup等）
2. Clear/Copy/Configure Outputsボタンの提供
3. スクロール可能なログ領域の表示
4. ログ内のID（0xXXXXXXXX形式）のホバー検出とハイライト機能
5. 出力先設定（TTY、Debugger、TestEngine）

**関連システム・外部連携**：
- ShowMetricsWindow（メトリクスウィンドウから呼び出し可能）
- DebugLocateItemOnHover（ログ内IDのホバー時にアイテムをハイライト）
- クリップボード機能（ログのコピー）

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 3 | Debug Log Window | 主画面 | デバッグログウィンドウの表示 |
| 2 | Metrics/Debugger Window | 呼び出し元 | Toolsセクションから遷移可能 |

## 機能種別

デバッグ・ログ表示

## 入力仕様

### 入力パラメータ

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

### 入力データソース

- ImGuiContext::DebugLogBuf（ログバッファ）
- ImGuiContext::DebugLogIndex（ログインデックス）
- ImGuiContext::DebugLogFlags（ログフィルタフラグ）

## 出力仕様

### 出力データ

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

### 出力先

- ImGuiウィンドウとして画面に描画
- クリップボード（Copyボタン押下時）

## 処理フロー

### 処理シーケンス

```
1. ウィンドウサイズの初期設定
   └─ SetNextWindowSize（初回使用時）
2. メインウィンドウの開始
   └─ Begin("Dear ImGui Debug Log", p_open)
3. フィルタチェックボックスの表示
   └─ All、Errors、ActiveId、Clipper、Focus、IO、Font、Nav、Popup、Selection、InputRouting
4. 操作ボタンの表示
   └─ Clear、Copy、Configure Outputs
5. ログ領域の表示
   └─ BeginChild + ListClipper + TextUnformatted
6. 自動スクロール処理
   └─ SetScrollHereY（最下部到達時）
7. ウィンドウの終了
   └─ End()
```

### フローチャート

```mermaid
flowchart TD
    A[ShowDebugLogWindow呼び出し] --> B[ウィンドウサイズ設定]
    B --> C[Begin - メインウィンドウ開始]
    C --> D{ウィンドウ可視?}
    D -->|No| E[End - 早期リターン]
    D -->|Yes| F[フィルタチェックボックス表示]
    F --> G[Clear/Copy/Outputsボタン]
    G --> H[BeginChild - ログ領域]
    H --> I[ListClipper + ログ表示]
    I --> J[自動スクロール処理]
    J --> K[EndChild]
    K --> L[End]
    E --> M[終了]
    L --> M
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | 再入防止 | 同一フレーム内での多重呼び出しを検出し早期リターン | BeginCount > 1時 |
| BR-02 | フィルタ制御 | CheckboxFlagsでログカテゴリを個別に有効/無効化 | 常時 |
| BR-03 | 自動スクロール | スクロールが最下部の場合、新規ログ追加時に自動スクロール | GetScrollY >= GetScrollMaxY時 |
| BR-04 | InputRoutingデフォルト除外 | Allチェックボックスでも InputRouting は除外（頻度が高いため） | 常時 |

### 計算ロジック

該当なし（ログ表示のみ）

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

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

## エラー処理

### エラーケース一覧

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

### リトライ仕様

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

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

該当なし

## パフォーマンス要件

- ListClipperを使用して大量のログ行を効率的に表示
- ログ表示中はClipper関連のログを一時的に無効化して無限ループを防止

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

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

## 備考

- IMGUI_DISABLE_DEBUG_TOOLSが定義されている場合、空の関数となる
- ログ内の0xXXXXXXXX形式のIDをホバーすると、対応するアイテムがハイライトされる
- IMGUI_ENABLE_TEST_ENGINE有効時はTestEngineへの出力も可能

---

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

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

### 推奨読解順序

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

ログ管理に使用されるデータ構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | imgui_internal.h | `imgui_internal.h` | ImGuiDebugLogFlags列挙型 |
| 1-2 | imgui_internal.h | `imgui_internal.h` | DebugLogBuf、DebugLogIndex（ImGuiContext内） |

**読解のコツ**: ImGuiDebugLogFlagsはログカテゴリを示すビットフラグ。EventError、EventActiveId、EventFocus等がある。

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

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

**主要処理フロー**:
1. **17686-17687行目**: ウィンドウサイズの初期設定
2. **17688-17692行目**: Begin呼び出しと早期リターン処理
3. **17694-17707行目**: フィルタチェックボックスの表示
4. **17709-17733行目**: Clear、Copy、Configure Outputsボタン
5. **17735-17748行目**: ログ領域の表示（ListClipper使用）
6. **17750行目**: End呼び出し

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | imgui.cpp | `imgui.cpp` | ShowDebugLogFlag関数（フィルタ表示ヘルパー） |
| 3-2 | imgui.cpp | `imgui.cpp` | DebugTextUnformattedWithLocateItem関数（17754-17772行目） |

**主要処理フロー**:
- DebugTextUnformattedWithLocateItemは、ログテキスト内の0xXXXXXXXX形式のIDを検出し、ホバー時にDebugLocateItemOnHoverを呼び出す

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

```
ShowDebugLogWindow()
    │
    ├─ SetNextWindowSize()
    │
    ├─ Begin("Dear ImGui Debug Log")
    │      │
    │      ├─ CheckboxFlags("All")
    │      ├─ ShowDebugLogFlag() - 各カテゴリ
    │      │
    │      ├─ SmallButton("Clear")
    │      │      └─ g.DebugLogBuf.clear()
    │      │
    │      ├─ SmallButton("Copy")
    │      │      └─ SetClipboardText()
    │      │
    │      ├─ SmallButton("Configure Outputs")
    │      │      └─ OpenPopup / BeginPopup
    │      │
    │      ├─ BeginChild("##log")
    │      │      │
    │      │      ├─ ImGuiListClipper
    │      │      │      └─ DebugTextUnformattedWithLocateItem()
    │      │      │             └─ DebugLocateItemOnHover()
    │      │      │
    │      │      └─ SetScrollHereY() - 自動スクロール
    │      │
    │      └─ EndChild()
    │
    └─ End()
```

### データフロー図

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

DebugLogBuf          ShowDebugLogWindow()           Debug Log Window描画
    │                      │                              │
    ├─ ログテキスト        ├─ ListClipperで効率表示       │
    │                      │                              │
DebugLogFlags              ├─ フィルタ適用                │
    │                      │                              │
    └─ カテゴリフラグ ─────┴─ 表示/非表示制御             │
                                                          │
p_open (bool*) ────────────────────────────────────────────┘
                         閉じるボタン押下時
                         *p_open = false
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| imgui.h | `imgui.h` | ヘッダー | ShowDebugLogWindow宣言（409行目） |
| imgui.cpp | `imgui.cpp` | ソース | ShowDebugLogWindow実装（17683-17751行目） |
| imgui_internal.h | `imgui_internal.h` | ヘッダー | ImGuiDebugLogFlags、DebugLogBuf等の定義 |
