# 通知設計書 27-ImGuiWindowFlags_Modal

## 概要

本ドキュメントは、ImGuiライブラリにおける`ImGuiWindowFlags_Modal`内部フラグの仕様と動作を定義する設計書である。このフラグは、`BeginPopupModal()`関数で使用される内部専用フラグであり、モーダルダイアログウィンドウを識別するために使用される。

### 本通知の処理概要

`ImGuiWindowFlags_Modal`は、ImGuiの内部システムがモーダルダイアログウィンドウを識別・管理するために使用するウィンドウフラグである。このフラグは`BeginPopupModal()`関数が自動的に設定するため、開発者が直接使用することは推奨されない。

**業務上の目的・背景**：モーダルダイアログは、ユーザーの即座の対応を必要とする重要な情報やアクションを提示するUIパターンである。モーダルが開いている間、背後のUIへの操作がブロックされ、ユーザーはモーダルに対応するまで他の操作ができない。このフラグにより、背景ブロッキング、暗転効果、自動クローズ無効化などのモーダル固有の振る舞いが実現される。

**通知の送信タイミング**：`BeginPopupModal()`関数の呼び出し時に、内部的にこのフラグが`ImGuiWindowFlags_Popup`と`ImGuiWindowFlags_NoCollapse`と共に追加されて`Begin()`に渡される。

**通知の受信者**：ImGuiの内部ウィンドウ管理システムが受信者である。`Begin()`関数内およびその後のウィンドウ処理でこのフラグを参照し、モーダル固有の処理を行う。

**通知内容の概要**：ウィンドウがモーダルダイアログであることを示すビットフラグ情報を伝達する。値は`1 << 27`。

**期待されるアクション**：ImGui内部システムがモーダル固有の処理（背景ブロッキング、暗転描画、クリック外での自動クローズ無効化など）を実行する。開発者はこのフラグを直接使用せず、`BeginPopupModal()`関数を使用する。

## 通知種別

内部ウィンドウフラグ（ビットフラグ）

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期 |
| 優先度 | 高（ウィンドウタイプ決定に影響） |
| リトライ | 無 |

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

フラグは`BeginPopupModal()`関数内で自動的に設定され、`Begin()`関数に渡される。ユーザーによる直接設定は非推奨。

## 通知テンプレート

### フラグ定義

| 項目 | 内容 |
|-----|------|
| フラグ名 | ImGuiWindowFlags_Modal |
| 値 | 1 << 27 (134217728) |
| 定義場所 | imgui.h:1193 |

### 注意事項

```cpp
// 直接使用は非推奨（内部使用専用）
// ImGuiWindowFlags_Modal = 1 << 27  // Don't use! For internal use by BeginPopupModal()

// 正しい使用方法
if (ImGui::BeginPopupModal("Confirm", NULL, ImGuiWindowFlags_AlwaysAutoResize))
{
    ImGui::Text("Are you sure?");
    if (ImGui::Button("OK")) { ImGui::CloseCurrentPopup(); }
    ImGui::EndPopup();
}
```

### 添付ファイル

該当なし

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| flags | ウィンドウフラグ | 内部自動設定 | Yes |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| API呼び出し | BeginPopupModal() | 常時 | Popup、Modal、NoCollapseフラグ追加 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| なし | BeginPopupModal関数は常にこのフラグを設定 |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[BeginPopupModal呼び出し] --> B[OpenPopupStackチェック]
    B --> C{ポップアップ開いている?}
    C -->|No| Z[false を返す]
    C -->|Yes| D[初回表示の場合:中央配置]
    D --> E[フラグ追加: Popup | Modal | NoCollapse]
    E --> F[Begin関数呼び出し]
    F --> G{Modalフラグ判定}
    G --> H[WindowRounding使用]
    H --> I[WindowBorderSize使用]
    I --> J[ModalDimBgColor設定]
    J --> K[背景ブロッキング有効化]
    K --> L[ウィンドウ描画]
```

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

### 参照テーブル一覧

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

### 更新テーブル一覧

該当なし

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| 直接使用 | ユーザーがフラグを直接指定 | 警告なし（非推奨のため） |

### リトライ仕様

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

## 配信設定

### レート制限

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

### 配信時間帯

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

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

特になし。内部フラグは視覚的な表示と動作制御のみに影響する。

## 備考

- **内部使用専用**：開発者は直接使用しないこと
- `ImGuiWindowFlags_Popup`と組み合わせて使用される
- モーダルは`WindowRounding`を使用（`PopupRounding`ではない）
- モーダルは`WindowBorderSize`を使用（`PopupBorderSize`ではない）
- 背景の暗転には`ImGuiCol_ModalWindowDimBg`が使用される
- モーダルはクリック外での自動クローズが無効化される
- ESCキーによるクローズも無効化される（デフォルト）

---

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

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

### 推奨読解順序

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | imgui.h | `imgui.h` | ImGuiWindowFlags_Modal定義（1193行目） |

**読解のコツ**: `[Internal]`セクションに定義されており、`Don't use!`コメントが付いている点に注意。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | imgui.cpp | `imgui.cpp` | BeginPopupModal関数（12397-12433行目） |

**主要処理フロー**:
1. **12406行目**: IsPopupOpenでポップアップ開状態を確認
2. **12414-12421行目**: 初回表示時の中央配置処理
3. **12423行目**: `Popup | Modal | NoCollapse`フラグの追加
4. **12424行目**: Begin関数呼び出し

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | imgui.cpp | `imgui.cpp` | Begin関数内のModalフラグ判定（7591-7594行目、7737行目、8003-8004行目） |
| 3-2 | imgui.cpp | `imgui.cpp` | ホバー抑止判定での使用（4752-4753行目） |
| 3-3 | imgui.cpp | `imgui.cpp` | モーダル検索関数（12099-12116行目） |

**主要処理フロー**:
- **7594行目**: `(Popup | Tooltip) && !Modal`でPopupBorderSize使用を除外
- **7737行目**: `Popup && !Modal`でPopupRounding使用を除外
- **8003-8004行目**: Modalフラグ判定でModalDimBgColor設定
- **4752-4753行目**: Modalウィンドウはホバーを抑止

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

```
BeginPopupModal(name, p_open, flags)
    |
    +-- GetID(name)
    |
    +-- IsPopupOpen(id, ImGuiPopupFlags_None)
    |
    +-- SetNextWindowPos(center, ImGuiCond_FirstUseEver)
    |
    +-- Begin(name, p_open, flags | Popup | Modal | NoCollapse)
           |
           +-- ウィンドウタイプ判定
           |      (flags & ImGuiWindowFlags_Modal)
           |
           +-- WindowRounding = style.WindowRounding
           |
           +-- WindowBorderSize = style.WindowBorderSize
           |
           +-- ModalDimBgColor設定
           |
           +-- 背景ブロッキング
```

### データフロー図

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

user flags ─────────> BeginPopupModal() ─────────> window flags
                           |
                           v
                    Popup | Modal | NoCollapseフラグ追加
                           |
                           v
                      Begin()
                           |
                           v
                    モーダル処理適用
                           |
                           v
                    背景暗転 + ブロッキング
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| imgui.h | `imgui.h` | ヘッダ | ImGuiWindowFlags_Modal定義（1193行目） |
| imgui.cpp | `imgui.cpp` | ソース | BeginPopupModal実装（12397-12433行目） |
| imgui.cpp | `imgui.cpp` | ソース | GetTopMostAndVisiblePopupModal（12109-12116行目） |
| imgui.cpp | `imgui.cpp` | ソース | FindBlockingModal（12132-12153行目） |
