# 画面設計書 3-Debug Log Window

## 概要

ImGuiの内部デバッグログを表示するウィンドウの設計書である。フォーカス変更、ポップアップ、入力ルーティングなどの内部イベントをリアルタイムでログ出力し、開発者がImGuiの動作を理解・デバッグするためのツールを提供する。

### 本画面の処理概要

Debug Log Windowは、ImGuiの内部で発生するイベントをカテゴリ別にフィルタリングしながらログ表示するデバッグツールである。

**業務上の目的・背景**：ImGuiを使用したアプリケーション開発において、フォーカスの移動、ポップアップの開閉、ナビゲーション処理などの内部イベントを追跡する必要がある場合に使用する。これらのイベントは通常は不可視であるが、問題が発生した際にはその詳細を確認することで原因を特定できる。

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

**主要な操作・処理内容**：
1. 表示するログカテゴリ（Errors、ActiveId、Focus、IO、Nav、Popup等）を選択する
2. Clearボタンでログをクリアする
3. Copyボタンでログをクリップボードにコピーする
4. Configure Outputsで出力先（TTY、デバッガ、Test Engine）を設定する
5. ログ内のID（0xXXXXXXXX形式）にホバーすると、該当アイテムがハイライト表示される

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

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

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 14 | ShowDebugLogWindow | 主機能 | デバッグログウィンドウの表示 |
| 24 | Begin | 主機能 | ウィンドウの開始処理 |
| 25 | End | 主機能 | ウィンドウの終了処理 |
| 96 | Checkbox | 補助機能 | ログフィルタの有効/無効切り替え |
| 84 | TextUnformatted | 補助機能 | ログテキストの表示 |
| 26 | BeginChild | 補助機能 | スクロール可能なログ領域の作成 |
| 27 | EndChild | 補助機能 | 子ウィンドウの終了 |

## 画面種別

デバッグ/ログ表示画面

## URL/ルーティング

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

## 入出力項目

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

## 表示項目

| 項目名 | 説明 |
|--------|------|
| Allチェックボックス | 全カテゴリのログを一括で有効/無効にする |
| Errorsチェックボックス | エラーログの表示切替 |
| ActiveIdチェックボックス | アクティブID変更ログの表示切替 |
| Clipperチェックボックス | リストクリッパーログの表示切替 |
| Focusチェックボックス | フォーカス変更ログの表示切替 |
| IOチェックボックス | 入出力ログの表示切替 |
| Fontチェックボックス | フォント関連ログの表示切替 |
| Navチェックボックス | ナビゲーションログの表示切替 |
| Popupチェックボックス | ポップアップログの表示切替 |
| Selectionチェックボックス | 選択ログの表示切替 |
| InputRoutingチェックボックス | 入力ルーティングログの表示切替 |
| Clearボタン | ログをクリアする |
| Copyボタン | ログをクリップボードにコピーする |
| Configure Outputsボタン | 出力設定ポップアップを開く |
| ログ表示エリア | スクロール可能なログテキスト表示領域 |

## イベント仕様

### 1-ログカテゴリ切り替え

各カテゴリのチェックボックスを操作すると、g.DebugLogFlagsが更新され、以降のログ出力がフィルタリングされる。

### 2-ログクリア

Clearボタンをクリックすると、g.DebugLogBufとg.DebugLogIndexがクリアされ、ログ表示領域が空になる。

### 3-ログコピー

Copyボタンをクリックすると、現在のログ内容がクリップボードにコピーされる。

### 4-出力設定変更

Configure Outputsボタンをクリックすると、ポップアップが表示され、TTY出力、デバッガ出力、Test Engine出力の有効/無効を切り替えられる。

### 5-アイテムホバーハイライト

ログ内の0xXXXXXXXX形式のIDにマウスをホバーすると、DebugLocateItemOnHover関数が呼ばれ、該当アイテムが緑色の矩形でハイライト表示される。

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

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

## メッセージ仕様

N/A

## 例外処理

| 状態 | 処理内容 |
|------|----------|
| ウィンドウ折りたたみ状態 | Begin()がfalseを返し、End()のみ呼び出して早期リターン |
| BeginCountが1より大きい | 同一フレームで複数回呼び出された場合、早期リターン |

## 備考

- InputRoutingログは非常にスパムになるため、「All」チェックボックスには含まれない
- ログ表示にはImGuiListClipperを使用して、大量のログでも効率的に描画する
- IMGUI_DISABLE_DEBUG_TOOLSマクロが定義されている場合、この関数は空実装になる

---

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

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

### 推奨読解順序

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

Debug Logの状態を保持するデータ構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | imgui_internal.h | `imgui_internal.h` | ImGuiDebugLogFlags列挙型でログカテゴリを定義 |
| 1-2 | imgui_internal.h | `imgui_internal.h` | ImGuiContextのDebugLogBuf、DebugLogIndex、DebugLogFlagsメンバ |

**読解のコツ**: DebugLogFlagsはビットフラグで、各カテゴリのログ出力を制御する。DebugLogBufはテキストバッファ、DebugLogIndexは行インデックス。

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

ShowDebugLogWindow関数がDebug Log Windowの描画処理のエントリーポイント。

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

**主要処理フロー**:
1. **行17686-17692**: ウィンドウサイズ設定とBegin処理
2. **行17694-17707**: ログカテゴリのチェックボックス表示
3. **行17709-17733**: Clear、Copy、Configure Outputsボタン
4. **行17735-17748**: ログ表示領域（BeginChild）とListClipperによる効率的描画

#### Step 3: ログ出力関数を理解する

ImGuiがどのようにログを出力するかを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | imgui.cpp | `imgui.cpp` | IMGUI_DEBUG_LOG_*マクロとDebugLog関数 |

**主要処理フロー**:
- IMGUI_DEBUG_LOG_*マクロがログをDebugLogBufに追加
- ShowDebugLogFlagヘルパー関数がチェックボックスを表示

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

```
ImGui::ShowDebugLogWindow(bool* p_open)
    |
    +-- SetNextWindowSize()
    +-- ImGui::Begin("Dear ImGui Debug Log", p_open)
    |       |
    |       +-- CheckboxFlags("All", ...)
    |       +-- ShowDebugLogFlag("Errors", ...)
    |       +-- ShowDebugLogFlag("ActiveId", ...)
    |       +-- ShowDebugLogFlag("Focus", ...)
    |       +-- ShowDebugLogFlag("IO", ...)
    |       +-- ShowDebugLogFlag("Font", ...)
    |       +-- ShowDebugLogFlag("Nav", ...)
    |       +-- ShowDebugLogFlag("Popup", ...)
    |       +-- ShowDebugLogFlag("Selection", ...)
    |       +-- ShowDebugLogFlag("InputRouting", ...)
    |       |
    |       +-- SmallButton("Clear")
    |       +-- SmallButton("Copy")
    |       |       +-- SetClipboardText()
    |       |
    |       +-- SmallButton("Configure Outputs..")
    |       |       +-- OpenPopup("Outputs")
    |       |       +-- BeginPopup("Outputs")
    |       |
    |       +-- BeginChild("##log", ...)
    |       |       +-- ImGuiListClipper
    |       |       +-- DebugTextUnformattedWithLocateItem() [行ごと]
    |       |               +-- TextUnformatted()
    |       |               +-- DebugLocateItemOnHover()
    |       +-- EndChild()
    |
    +-- ImGui::End()
```

### データフロー図

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

p_open (bool*)  ─────────▶ ShowDebugLogWindow() ─────────▶  ウィンドウ描画
                                  |
g.DebugLogFlags ◀────────▶       |  ◀──── カテゴリ選択
                                  |
g.DebugLogBuf   ─────────▶       |  ───▶ ログテキスト表示
g.DebugLogIndex ─────────▶       |
                                  |
                                  ▼
                           クリップボード
                           (コピー時)
```

### 関連ファイル一覧

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