# 通知設計書 29-ImGuiHoveredFlags_AllowWhenBlockedByPopup

## 概要

本ドキュメントは、ImGuiライブラリにおける`ImGuiHoveredFlags_AllowWhenBlockedByPopup`フラグの仕様と動作を定義する設計書である。このフラグは、`IsItemHovered()`および`IsWindowHovered()`関数で使用され、ポップアップによってブロックされている状態でもホバー判定を許可するために使用される。

### 本通知の処理概要

`ImGuiHoveredFlags_AllowWhenBlockedByPopup`は、ポップアップウィンドウが開いていてホバー判定が通常ブロックされる状況でも、trueを返すことを許可するホバーフラグである。これにより、ポップアップの背後にあるアイテムやウィンドウに対するホバー状態を検知できる。

**業務上の目的・背景**：ポップアップが開いている間、通常は背後のアイテムへのホバーはブロックされ、誤操作を防止している。しかし、特定のシナリオでは、ポップアップが開いていても背後のアイテムのホバー状態を知りたい場合がある。例えば、ドラッグ&ドロップ操作中にポップアップが表示されていても、ドロップ先のホバー状態を確認したい場合などである。このフラグはそのようなケースに対応する。

**通知の送信タイミング**：`IsItemHovered()`または`IsWindowHovered()`関数の呼び出し時に、引数としてこのフラグが渡される。フラグが設定されている場合、ポップアップによるブロックを無視してホバー判定が行われる。

**通知の受信者**：ImGuiのホバー判定システムが受信者である。`ItemHoverable()`関数内でこのフラグを参照し、ブロック条件を調整する。

**通知内容の概要**：ポップアップによるブロックを無視するかどうかを示すビットフラグ情報を伝達する。値は`1 << 5`。

**期待されるアクション**：開発者はこのフラグを使用して、ポップアップ表示中でも背後のアイテムのホバー状態を取得し、適切な視覚的フィードバックやアクションを提供する。

## 通知種別

ホバーフラグ（ビットフラグ）

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期 |
| 優先度 | 中 |
| リトライ | 無 |

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

フラグは`IsItemHovered()`/`IsWindowHovered()`の引数として渡され、内部でホバー判定条件に適用される。

## 通知テンプレート

### フラグ定義

| 項目 | 内容 |
|-----|------|
| フラグ名 | ImGuiHoveredFlags_AllowWhenBlockedByPopup |
| 値 | 1 << 5 (32) |
| 定義場所 | imgui.h:1450 |

### 使用例

```cpp
// ポップアップ表示中でもホバー判定を行う
if (ImGui::IsItemHovered(ImGuiHoveredFlags_AllowWhenBlockedByPopup))
{
    ImGui::SetTooltip("Hovered even with popup open");
}

// ウィンドウのホバー判定（ポップアップブロック無視）
if (ImGui::IsWindowHovered(ImGuiHoveredFlags_AllowWhenBlockedByPopup))
{
    // ポップアップが開いていてもこのウィンドウにホバー中
}

// RectOnlyフラグに含まれている
// ImGuiHoveredFlags_RectOnly = AllowWhenBlockedByPopup | AllowWhenBlockedByActiveItem | AllowWhenOverlapped
```

### 添付ファイル

該当なし

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| flags | ホバーフラグ | 呼び出し元引数 | No |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| API呼び出し | IsItemHovered() | フラグ指定時 | ホバー判定条件変更 |
| API呼び出し | IsWindowHovered() | フラグ指定時 | ホバー判定条件変更 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| ポップアップ未表示 | ポップアップがない場合は通常のホバー判定と同じ |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[IsItemHovered呼び出し] --> B{AllowWhenBlockedByPopupフラグ?}
    B -->|No| C{ポップアップでブロック中?}
    C -->|Yes| D[false を返す]
    C -->|No| E[通常のホバー判定]
    B -->|Yes| E
    E --> F{ホバー条件満たす?}
    F -->|Yes| G[true を返す]
    F -->|No| D
```

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

### 参照テーブル一覧

該当なし（ImGuiはメモリベースの即時モードGUI）

### 更新テーブル一覧

該当なし

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| 無効なフラグ組み合わせ | なし | フラグは安全に組み合わせ可能 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | 0 |
| リトライ間隔 | 該当なし |
| リトライ対象エラー | なし |

## 配信設定

### レート制限

| 項目 | 内容 |
|-----|------|
| 1分あたり上限 | 無制限 |
| 1日あたり上限 | 無制限 |

### 配信時間帯

制限なし（フレームごとに評価）

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

特になし。UIフラグはユーザー入力の検知のみに使用される。

## 備考

- ポップアップによるブロックを無視する
- モーダルによるブロックは**無視しない**（モーダルは常にブロック）
- `ImGuiHoveredFlags_RectOnly`に含まれている
- `BeginPopupContextWindow()`の内部実装で使用される（ポップアップブロック時でもホバー判定を行う）
- 他のAllowWhenBlockedByXXXフラグと組み合わせ可能

---

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

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

### 推奨読解順序

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

フラグの定義位置を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | imgui.h | `imgui.h` | ImGuiHoveredFlags_列挙型（1445-1477行目） |
| 1-2 | imgui.h | `imgui.h` | AllowWhenBlockedByPopup定義（1450行目） |

**読解のコツ**: 他のAllowWhenBlockedByXXXフラグ（ActiveItem、Overlapped等）との関係を理解する。

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

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

**主要処理フロー**:
1. `IsItemHovered(flags)`が呼び出される
2. 内部でホバー条件のチェックが行われる
3. フラグに応じてブロック条件が調整される

#### Step 3: フラグが使用される箇所を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | imgui.cpp | `imgui.cpp` | ホバー判定処理（4749-4765行目） |
| 3-2 | imgui.cpp | `imgui.cpp` | BeginPopupContextWindow内での使用（12519行目） |

**主要処理フロー**:
- **4752-4755行目**: Modalウィンドウは常にブロック、Popupは`AllowWhenBlockedByPopup`フラグで制御
- **12519行目**: `IsWindowHovered(ImGuiHoveredFlags_AllowWhenBlockedByPopup)`の使用例

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

```
IsItemHovered(flags) / IsWindowHovered(flags)
    |
    +-- ItemHoverable() / WindowHoveringChecks()
           |
           +-- フォーカスウィンドウ取得
           |
           +-- if (focused_root_window->Flags & ImGuiWindowFlags_Modal)
           |      -> want_inhibit = true (モーダルは常にブロック)
           |
           +-- else if (focused_root_window->Flags & ImGuiWindowFlags_Popup)
           |      && !(flags & ImGuiHoveredFlags_AllowWhenBlockedByPopup)
           |      -> want_inhibit = true
           |
           +-- ホバー判定実行
```

### データフロー図

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

hover flags ───────────> IsItemHovered() ───────────> bool (ホバー状態)
                              |
                              v
                    AllowWhenBlockedByPopup評価
                              |
                              v
                    ブロック条件判定
                              |
                              v
                    ホバー判定結果
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| imgui.h | `imgui.h` | ヘッダ | ImGuiHoveredFlags_AllowWhenBlockedByPopup定義（1450行目） |
| imgui.cpp | `imgui.cpp` | ソース | ホバー判定処理（4749-4765行目） |
| imgui.cpp | `imgui.cpp` | ソース | BeginPopupContextWindowでの使用（12519行目） |
| imgui_demo.cpp | `imgui_demo.cpp` | デモ | 使用例（2167行目、2247行目） |
