# 通知設計書 7-BeginPopupModal

## 概要

本ドキュメントは、Dear ImGuiライブラリにおけるBeginPopupModal API関数の設計・動作仕様を記載したものである。BeginPopupModalはモーダルダイアログを開始するためのAPI関数で、背後のインタラクションをブロックする特殊なポップアップウィンドウを作成する。

### 本通知の処理概要

BeginPopupModalは、ユーザーが閉じることができない（閉じるボタンなしの）モーダルダイアログを開始する。背後のすべてのウィンドウとのインタラクションがブロックされ、背景が暗転効果で表示される。タイトルバーを持ち、閉じるボタンが必要な場合はp_openパラメータを使用する。

**業務上の目的・背景**：モーダルダイアログは、ユーザーの注意を特定の操作に集中させる必要がある場面で使用される。確認ダイアログ、重要な設定変更、エラー通知など、ユーザーが応答するまで他の操作を許可しない状況で必要となる。BeginPopupModalは、この要件を満たす標準的なインターフェースを提供する。

**通知の送信タイミング**：毎フレームのレンダリングループ内で呼び出される。OpenPopup()でモーダルが開かれた後、BeginPopupModal()でモーダルが開いているかを確認し、開いていればコンテンツを追加する。

**通知の受信者**：Dear ImGuiの内部ポップアップスタック管理システムとレンダリングシステム。背景の暗転効果と入力ブロッキングが適用される。

**通知内容の概要**：モーダルダイアログウィンドウの開始リクエスト。名前（タイトル）、オプションのp_open（閉じるボタン制御）、ImGuiWindowFlagsを指定可能。

**期待されるアクション**：関数がtrueを返した場合、呼び出し側はモーダル内にコンテンツを配置し、EndPopup()を呼び出す必要がある。p_openがfalseになった場合、モーダルは自動的に閉じられる。

## 通知種別

UI内部通知（ImGuiウィンドウシステム内での状態変更通知）

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期 |
| 優先度 | 高（モーダルは他の操作をブロック） |
| リトライ | 無 |

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

BeginPopupModalの呼び出しは、OpenPopupStackの現在のレベルに対して行われる。モーダルIDは現在のウィンドウのIDスタックに対して相対的に計算される。

## 通知テンプレート

### API関数シグネチャ

| 項目 | 内容 |
|-----|------|
| 関数名 | BeginPopupModal |
| 戻り値 | bool |
| 引数 | const char* name, bool* p_open = NULL, ImGuiWindowFlags flags = 0 |
| 定義場所 | imgui.h:846 |

### 本文テンプレート

```cpp
// 基本的な使用パターン（閉じるボタンなし）
if (ImGui::Button("確認ダイアログを開く"))
    ImGui::OpenPopup("確認");

if (ImGui::BeginPopupModal("確認"))
{
    ImGui::Text("本当によろしいですか？");
    if (ImGui::Button("はい"))
    {
        // 処理を実行
        ImGui::CloseCurrentPopup();
    }
    ImGui::SameLine();
    if (ImGui::Button("いいえ"))
        ImGui::CloseCurrentPopup();
    ImGui::EndPopup();
}

// 閉じるボタン付きのパターン
static bool modal_open = true;
if (ImGui::Button("設定を開く"))
{
    modal_open = true;
    ImGui::OpenPopup("設定");
}

if (ImGui::BeginPopupModal("設定", &modal_open))
{
    ImGui::Text("設定項目...");
    ImGui::EndPopup();
}
```

### 添付ファイル

該当なし

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| name | モーダルのタイトル（ID兼用） | 呼び出し元から渡される | Yes |
| p_open | 閉じるボタン制御用ポインタ | 呼び出し元から渡される | No |
| flags | ウィンドウフラグ | 呼び出し元から渡される | No |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| API呼び出し | BeginPopupModal()呼び出し | モーダルが開いている | IsPopupOpen(id)がtrue |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| IsPopupOpen(id)がfalse | 指定IDのモーダルが開いていない |
| *p_openがfalse（p_open指定時） | 呼び出し前にfalseが設定されている場合 |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[BeginPopupModal呼び出し] --> B[IDを計算]
    B --> C{IsPopupOpen?}
    C -->|No| D[NextWindowData.ClearFlags]
    D --> E{p_open != NULL?}
    E -->|Yes| F[*p_open = false]
    E -->|No| G[false返却]
    F --> G
    C -->|Yes| H{位置指定あり?}
    H -->|No| I[画面中央に配置設定]
    H -->|Yes| J[フラグ追加]
    I --> J
    J --> K[Begin呼び出し]
    K --> L{is_open?}
    L -->|Yes| M[true返却]
    L -->|No| N[EndPopup呼び出し]
    N --> O{p_open && !*p_open?}
    O -->|Yes| P[ClosePopupToLevel]
    O -->|No| Q[false返却]
    P --> Q
    G --> R[終了]
    M --> R
    Q --> R
```

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

### 参照テーブル一覧

| テーブル名 | 用途 | 備考 |
|-----------|------|------|
| ImGuiContext (GImGui) | グローバルコンテキスト | ポップアップスタック管理 |
| ImGuiViewport | ビューポート情報 | 画面中央配置用 |

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

#### ImGuiContext

| 参照項目（カラム名） | 用途 | 取得条件 |
|-------------------|------|---------|
| OpenPopupStack | 開いているポップアップのスタック | 常時 |
| BeginPopupStack | Begin済みポップアップのスタック | 常時 |
| CurrentWindow | 現在のウィンドウ | ID計算用 |
| NextWindowData | 次ウィンドウデータ | 位置指定確認 |

#### ImGuiViewport

| 参照項目（カラム名） | 用途 | 取得条件 |
|-------------------|------|---------|
| GetCenter() | 画面中央座標 | 位置未指定時 |

### 更新テーブル一覧

| テーブル名 | 操作 | 概要 |
|-----------|------|------|
| BeginPopupStack | PUSH | モーダル開始時 |
| NextWindowData | UPDATE | 位置設定 |
| OpenPopupStack | POP | ClosePopupToLevel時 |

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| Begin失敗 | ウィンドウがクリップされている場合 | EndPopup()を自動呼び出し |
| p_openがfalse | 呼び出し前にfalseが設定 | モーダルを閉じる |

### リトライ仕様

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

## 配信設定

### レート制限

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

### 配信時間帯

制限なし（即座に実行される同期処理）

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

特になし。ローカルUIレンダリング処理のため、外部通信やデータ永続化は行わない。

## 備考

- モーダルは背後のインタラクションをすべてブロックする
- 背景にImGuiCol_ModalWindowDimBgカラーによる暗転効果が適用される
- デフォルトで画面中央に配置される（SetNextWindowPosで上書き可能）
- ImGuiWindowFlags_Popup、ImGuiWindowFlags_Modal、ImGuiWindowFlags_NoCollapseが自動的に追加される
- p_openを指定すると閉じるボタンが表示される
- p_openがfalseに設定されるとモーダルは閉じられる
- trueを返した場合は必ずEndPopup()を呼び出すこと

---

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

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

### 推奨読解順序

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

モーダル関連のフラグとスタイル設定を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | imgui.h | `imgui.h` | ImGuiWindowFlags_Modal定義（1193行目） |
| 1-2 | imgui.h | `imgui.h` | ImGuiCol_ModalWindowDimBg（暗転色） |
| 1-3 | imgui_internal.h | `imgui_internal.h` | ImGuiPopupData構造体（1471-1483行目） |

**読解のコツ**: モーダルフラグがポップアップフラグと組み合わせて使用されることを理解する。

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

BeginPopupModalの宣言と実装を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | imgui.h | `imgui.h` | BeginPopupModal API宣言（846行目） |
| 2-2 | imgui.h | `imgui.h` | モーダルの説明コメント（844行目） |
| 2-3 | imgui.cpp | `imgui.cpp` | BeginPopupModal実装（12401-12433行目） |

**主要処理フロー**:
1. **12405-12411行目**: IsPopupOpenチェックとp_open処理
2. **12414-12421行目**: 画面中央配置設定
3. **12423行目**: フラグ追加（Popup, Modal, NoCollapse）
4. **12424行目**: Begin呼び出し
5. **12425-12430行目**: 結果処理とClosePopupToLevel

#### Step 3: 暗転効果の仕組みを理解する

モーダル背景の暗転がどのように描画されるか確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | imgui.cpp | `imgui.cpp` | モーダル暗転描画処理 |

**主要処理フロー**:
- ImGuiCol_ModalWindowDimBgを使用した背景描画

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

```
BeginPopupModal(name, p_open, flags) [imgui.cpp:12401]
    │
    ├─ CurrentWindow->GetID(name) [ID計算]
    │
    ├─ IsPopupOpen(id) [ポップアップ状態確認]
    │
    ├─ GetMainViewport()->GetCenter() [条件付き: 中央配置]
    │
    ├─ SetNextWindowPos() [条件付き: 位置設定]
    │
    └─ Begin(name, p_open, flags) [ウィンドウ開始]
           │
           ├─ モーダル暗転描画
           │
           └─ BeginPopupStack.push_back()
```

### データフロー図

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

name               ───▶ BeginPopupModal()        ───▶ bool
p_open                    │
flags                     ▼
                       ID計算
                          │
OpenPopupStack     ───▶ IsPopupOpen(id)
                          │
                          ▼ (trueの場合)
                     位置設定（中央）
                          │
                          ▼
                       Begin()                  ───▶ モーダルウィンドウ
                          │
                          ├─ 暗転背景描画
                          │
                          └─ 入力ブロッキング
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| imgui.h | `imgui.h` | ソース | API宣言・フラグ定義 |
| imgui.cpp | `imgui.cpp` | ソース | 実装本体 |
| imgui_internal.h | `imgui_internal.h` | ソース | ImGuiPopupData構造体定義 |
| imgui_draw.cpp | `imgui_draw.cpp` | ソース | ImGuiCol_ModalWindowDimBg定義 |
