# 通知設計書 34-ConfigErrorRecoveryEnableTooltip

## 概要

本ドキュメントは、Dear ImGuiライブラリにおけるConfigErrorRecoveryEnableTooltipフラグによる「回復可能エラーツールチップ通知」機能の設計を定義する。この機能は、エラーリカバリー処理中に発生した回復可能なエラーをツールチップで視覚的に通知し、開発者がエラーを迅速に認識・対処できるようにする開発支援ツールである。

### 本通知の処理概要

ConfigErrorRecoveryEnableTooltipは、ImGuiIO構造体内のbool設定フラグであり、回復可能なエラー（Begin/End不一致、スタック不整合など）が発生した際に、エラーツールチップを表示して開発者に通知する機能を制御する。

**業務上の目的・背景**：Dear ImGuiでは、Begin()/End()やPush()/Pop()の呼び出し不一致など、回復可能なプログラミングエラーが発生することがある。従来はアサートで即座にクラッシュしていたが、エラーリカバリー機能の導入により、これらのエラーから自動回復しつつ、開発者にエラーを通知することが可能になった。ツールチップ通知は、アサートを無効化した状態でもエラーを視覚的に確認できる手段を提供する。

**通知の送信タイミング**：ErrorLog()関数が呼び出されたタイミング、つまり回復可能なエラーが検出された時点で即座に通知される。フレーム内で複数のエラーが発生した場合は、最大20件までツールチップに表示される。

**通知の受信者**：開発者が受信者となる。エラーツールチップが画面上に表示され、エラーが発生したウィンドウが赤枠でハイライトされる。

**通知内容の概要**：以下の情報がツールチップに表示される：
- エラーが発生したウィンドウ名
- エラーメッセージの内容
- エラー数が多い場合は「(and more errors)」と表示
- アサート有効化ボタン（Ctrlキー押下時）

**期待されるアクション**：開発者は、ツールチップの情報を確認してエラーの原因を特定し、Begin/Endの対応関係やスタック操作を修正する。必要に応じてアサートを有効化し、詳細なデバッグを行う。

## 通知種別

アプリ内通知（エラーツールチップ）

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期（エラー発生時即時表示） |
| 優先度 | 高（開発時エラー） |
| リトライ | 無（毎フレーム再評価） |

### 送信先決定ロジック

以下の条件がすべて満たされた場合にツールチップが表示される：
1. io.ConfigErrorRecoveryがtrue（デフォルトtrue）
2. io.ConfigErrorRecoveryEnableTooltipがtrue（デフォルトtrue）
3. 回復可能なエラーが発生（ErrorLog()が呼び出された）
4. フレームスコープ内（g.WithinFrameScope == true）

## 通知テンプレート

### フラグ仕様

| 項目 | 内容 |
|-----|------|
| フラグ名 | ConfigErrorRecoveryEnableTooltip |
| 型 | bool |
| 所属構造体 | ImGuiIO |
| デフォルト値 | true |

### 関連フラグ

| フラグ名 | 型 | デフォルト | 説明 |
|---------|-----|---------|------|
| ConfigErrorRecovery | bool | true | エラーリカバリー機能全体の有効/無効 |
| ConfigErrorRecoveryEnableAssert | bool | true | 回復可能エラー時にアサートを発生させるか |
| ConfigErrorRecoveryEnableDebugLog | bool | true | 回復可能エラーをデバッグログに出力するか |

### エラーメッセージテンプレート

```
In window 'ウィンドウ名': エラーメッセージ
```

### 追加情報（フレーム終了時）

```
(Hold Ctrl to: [Enable Asserts] )
```

### 添付ファイル

該当なし

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| ConfigErrorRecoveryEnableTooltip | 機能有効/無効 | ImGuiIO | Yes |
| ErrorCountCurrentFrame | 現フレームエラー数 | ImGuiContext | Yes |
| CurrentWindow | 現在のウィンドウ | ImGuiContext | Yes |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| エラー発生 | ErrorLog()呼び出し | ConfigErrorRecoveryEnableTooltip == true | 回復可能エラー検出 |
| フレーム終了 | ErrorCheckEndFrameFinalizeErrorTooltip | ErrorCountCurrentFrame > 0 | エラー発生時の追加UI |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| ConfigErrorRecovery == false | エラーリカバリー機能全体が無効 |
| ConfigErrorRecoveryEnableTooltip == false | ツールチップ通知が無効 |
| g.WithinFrameScope == false | フレームスコープ外 |
| エラー数が20を超過 | 「(and more errors)」メッセージに集約 |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[回復可能エラー発生] --> B[ErrorLog呼び出し]
    B --> C{ConfigErrorRecoveryEnableTooltip?}
    C -->|false| D[ツールチップなし]
    C -->|true| E{WithinFrameScope?}
    E -->|false| D
    E -->|true| F[BeginErrorTooltip]
    F --> G{ErrorCountCurrentFrame < 20?}
    G -->|Yes| H[エラーメッセージ表示]
    G -->|No| I["(and more errors)"表示]
    H --> J[ウィンドウを赤枠ハイライト]
    I --> J
    J --> K[EndErrorTooltip]
    K --> L[ErrorCountCurrentFrame++]
    L --> M[フレーム終了処理]
    M --> N{ErrorCountCurrentFrame > 0?}
    N -->|No| O[終了]
    N -->|Yes| P[BeginErrorTooltip]
    P --> Q[アサート有効化ボタン表示]
    Q --> R[EndErrorTooltip]
    R --> O
```

## データベース参照・更新仕様

### 参照テーブル一覧

| テーブル名 | 用途 | 備考 |
|-----------|------|------|
| ImGuiIO | 設定参照 | ConfigErrorRecovery* |
| ImGuiContext | 状態管理 | ErrorCountCurrentFrame等 |

### テーブル別参照項目詳細

#### ImGuiIO

| 参照項目（カラム名） | 用途 | 取得条件 |
|-------------------|------|---------|
| ConfigErrorRecovery | 機能全体有効判定 | 常時 |
| ConfigErrorRecoveryEnableAssert | アサート有効判定 | 常時 |
| ConfigErrorRecoveryEnableDebugLog | ログ出力判定 | 常時 |
| ConfigErrorRecoveryEnableTooltip | ツールチップ有効判定 | 常時 |

#### ImGuiContext

| 参照項目（カラム名） | 用途 | 取得条件 |
|-------------------|------|---------|
| CurrentWindow | エラー発生ウィンドウ | エラー発生時 |
| WithinFrameScope | フレームスコープ判定 | 常時 |
| ErrorFirst | 初回エラー判定 | エラー発生時 |
| ErrorCountCurrentFrame | 現フレームエラー数 | 毎フレームリセット |

### 更新テーブル一覧

| テーブル名 | 操作 | 概要 |
|-----------|------|------|
| ImGuiContext | UPDATE | ErrorCountCurrentFrameをインクリメント |
| ImGuiIO | UPDATE | ConfigErrorRecoveryEnableAssert（ボタン押下時） |

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| Begin/End不一致 | BeginとEndの呼び出し数不一致 | ツールチップ表示 + 自動回復 |
| スタック不整合 | Push/Popの不整合 | ツールチップ表示 + 自動回復 |
| 不正なウィンドウ操作 | 無効なウィンドウに対する操作 | ツールチップ表示 + 自動回復 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | なし（毎フレーム再評価） |
| リトライ間隔 | なし |
| リトライ対象エラー | なし |

## 配信設定

### レート制限

| 項目 | 内容 |
|-----|------|
| 1フレームあたり上限 | 20件（超過分は集約メッセージ） |
| 1日あたり上限 | 制限なし |

### 配信時間帯

制限なし（開発時常時有効）

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

- 開発者向けデバッグ機能のため、本番ビルドでは状況に応じて無効化を検討
- ただし、すべての回復通知手段を無効化することは推奨されない（アサート、ログ、ツールチップ、コールバックのいずれかは有効であるべき）

## 備考

- v1.91.2（2024年9月）で追加されたエラーリカバリー機能の一部
- 3つの通知オプション（Assert、DebugLog、Tooltip）のすべてを無効化しようとすると、自動的に全て有効化される（imgui_demo.cpp参照）
- ツールチップはマウスに追従するが、Ctrlキー押下で位置がロックされ、ボタンクリックが可能になる
- プログラマー席では必ずアサートまたはツールチップを有効にすることが強く推奨される

---

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

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

### 推奨読解順序

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

まず、関連するデータ構造とフラグの定義を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | imgui.h | `imgui.h` | 2462-2465行目：ConfigErrorRecovery*フラグの定義とコメント |
| 1-2 | imgui.h | `imgui.h` | 2458-2461行目：エラーリカバリー機能の説明コメント |

**読解のコツ**: ConfigErrorRecoveryEnableTooltipはConfigErrorRecovery関連の4つのフラグの一つ。全体の動作を理解するには、関連フラグすべてを確認する必要がある。

#### Step 2: 初期化を理解する

フラグの初期化処理を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | imgui.cpp | `imgui.cpp` | 1632-1635行目：ImGuiIOコンストラクタでのデフォルト値設定（true） |

**主要処理フロー**:
- **1632行目**: ConfigErrorRecovery = true
- **1633行目**: ConfigErrorRecoveryEnableAssert = true
- **1634行目**: ConfigErrorRecoveryEnableDebugLog = true
- **1635行目**: ConfigErrorRecoveryEnableTooltip = true

#### Step 3: エラーログ処理を理解する

エラー検出とツールチップ表示の処理を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | imgui.cpp | `imgui.cpp` | 11026-11069行目：ErrorLog関数実装 |
| 3-2 | imgui.cpp | `imgui.cpp` | 11044-11060行目：ツールチップ表示処理 |

**主要処理フロー**:
- **11044行目**: ConfigErrorRecoveryEnableTooltipの判定
- **11046行目**: BeginErrorTooltipでツールチップ開始
- **11048-11055行目**: エラーメッセージ表示（20件まで）
- **11051-11052行目**: ウィンドウの赤枠ハイライト
- **11057行目**: EndErrorTooltip
- **11059行目**: ErrorCountCurrentFrameのインクリメント

#### Step 4: フレーム終了時の追加UIを理解する

フレーム終了時のアサート有効化ボタンなどの処理を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | imgui.cpp | `imgui.cpp` | 11105-11118行目：ErrorCheckEndFrameFinalizeErrorTooltipの後半部分 |

**主要処理フロー**:
- **11105行目**: ErrorCountCurrentFrame > 0の判定
- **11110行目**: "Enable Asserts"ボタン
- **11111行目**: ConfigErrorRecoveryEnableAssertをtrueに設定

#### Step 5: エラーツールチップの実装を理解する

BeginErrorTooltip/EndErrorTooltipの実装を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | imgui.cpp | `imgui.cpp` | 11123-11150行目：BeginErrorTooltip/EndErrorTooltip実装 |

**主要処理フロー**:
- **11126行目**: "##Tooltip_Error"ウィンドウの検索
- **11127行目**: Ctrlキーで位置ロック
- **11128行目**: 赤みがかった背景色の設定
- **11129-11141行目**: ツールチップウィンドウの作成と配置

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

```
[回復可能エラー発生]
    |
    +-- ErrorLog(msg) (imgui.cpp:11026)
            |
            +-- デバッグログ出力（ConfigErrorRecoveryEnableDebugLog）
            |
            +-- ツールチップ表示（ConfigErrorRecoveryEnableTooltip）
            |       |
            |       +-- BeginErrorTooltip() (imgui.cpp:11123)
            |       |       |
            |       |       +-- ウィンドウ作成/位置設定
            |       |
            |       +-- Text("In window '...': ...")
            |       |
            |       +-- ウィンドウ赤枠ハイライト
            |       |
            |       +-- EndErrorTooltip() (imgui.cpp:11147)
            |
            +-- ErrorCountCurrentFrame++
            |
            +-- return ConfigErrorRecoveryEnableAssert
                    |
                    (アサート発生判定)

[フレーム終了]
    |
    +-- ErrorCheckEndFrameFinalizeErrorTooltip() (imgui.cpp:11071)
            |
            +-- if (ErrorCountCurrentFrame > 0)
                    |
                    +-- BeginErrorTooltip()
                    |
                    +-- "Enable Asserts"ボタン
                    |
                    +-- EndErrorTooltip()
```

### データフロー図

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

エラー発生 --------> ErrorLog ----------------> ツールチップ表示
  (msg)                |                        赤枠ハイライト
                       |
                       v
ConfigError* ------> 条件判定
                       |
                       +-- ConfigErrorRecoveryEnableTooltip
                       |
                       v
                  BeginErrorTooltip
                       |
                       v
CurrentWindow ----> メッセージ組み立て -------> "In window 'X': msg"
                       |
                       v
                  AddRect（赤枠）
                       |
                       v
                  EndErrorTooltip
                       |
                       v
ErrorCount --------> インクリメント -----------> ErrorCountCurrentFrame++
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| imgui.h | `imgui.h` | ヘッダー | ConfigErrorRecoveryEnableTooltip定義（2465行目） |
| imgui.cpp | `imgui.cpp` | ソース | 初期化（1635行目）、ErrorLog（11026行目）、BeginErrorTooltip（11123行目） |
| imgui_internal.h | `imgui_internal.h` | ヘッダー | BeginErrorTooltip/EndErrorTooltip宣言（3712-3713行目） |
| imgui_demo.cpp | `imgui_demo.cpp` | サンプル | 設定UI（547-551行目） |
| docs/CHANGELOG.txt | `docs/CHANGELOG.txt` | 履歴 | v1.91.2機能追加記録（1808行目） |
