# 通知設計書 26-ImGuiWindowFlags_Popup

## 概要

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

### 本通知の処理概要

`ImGuiWindowFlags_Popup`は、ImGuiの内部システムがポップアップウィンドウを識別・管理するために使用するウィンドウフラグである。このフラグは`BeginPopup()`ファミリーの関数が自動的に設定するため、開発者が直接使用することは推奨されない。

**業務上の目的・背景**：ImGuiは複数種類のウィンドウタイプ（通常ウィンドウ、子ウィンドウ、ポップアップ、モーダル、ツールチップ）を区別する必要がある。各タイプには異なる動作特性（フォーカス管理、自動クローズ、スタイル適用など）があり、`ImGuiWindowFlags_Popup`フラグによってポップアップ固有の振る舞いが有効化される。このフラグにより、クリックによる自動クローズ、ポップアップスタック管理、適切なスタイル適用が実現される。

**通知の送信タイミング**：`BeginPopup()`、`BeginPopupContextItem()`、`BeginPopupContextWindow()`、`BeginPopupContextVoid()`などのポップアップ開始関数の呼び出し時に、内部的にこのフラグが追加されて`Begin()`に渡される。

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

**通知内容の概要**：ウィンドウがポップアップであることを示すビットフラグ情報を伝達する。値は`1 << 26`。

**期待されるアクション**：ImGui内部システムがポップアップ固有の処理（スタイル適用、フォーカス管理、自動クローズ判定など）を実行する。開発者はこのフラグを直接使用せず、`BeginPopup()`系関数を使用する。

## 通知種別

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

## 送信仕様

### 基本情報

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

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

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

## 通知テンプレート

### フラグ定義

| 項目 | 内容 |
|-----|------|
| フラグ名 | ImGuiWindowFlags_Popup |
| 値 | 1 << 26 (67108864) |
| 定義場所 | imgui.h:1192 |

### 注意事項

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

// 正しい使用方法
if (ImGui::BeginPopup("my_popup"))  // 内部でPopupフラグが自動設定される
{
    ImGui::Text("Popup content");
    ImGui::EndPopup();
}
```

### 添付ファイル

該当なし

## テンプレート変数

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

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| API呼び出し | BeginPopup() | 常時 | フラグ自動追加 |
| API呼び出し | BeginPopupModal() | 常時 | PopupとModalフラグ両方追加 |
| API呼び出し | BeginPopupContextItem() | 常時 | フラグ自動追加 |

### 送信抑止条件

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

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[BeginPopup呼び出し] --> B[OpenPopupStackにチェック]
    B --> C{ポップアップ開いている?}
    C -->|No| Z[false を返す]
    C -->|Yes| D[BeginPopupEx呼び出し]
    D --> E[ImGuiWindowFlags_Popup追加]
    E --> F[Begin関数呼び出し]
    F --> G{フラグ判定}
    G --> H[ポップアップ用スタイル適用]
    H --> I[ポップアップスタック管理]
    I --> J[ウィンドウ描画]
```

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

### 参照テーブル一覧

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

### 更新テーブル一覧

該当なし

## エラー処理

### エラーケース一覧

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

### リトライ仕様

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

## 配信設定

### レート制限

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

### 配信時間帯

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

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

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

## 備考

- **内部使用専用**：開発者は直接使用しないこと
- `ImGuiWindowFlags_Modal`と組み合わせて使用されることがある（BeginPopupModal）
- ポップアップは`OpenPopupStack`で管理される
- クリックによる自動クローズの判定に使用される
- `PopupRounding`と`PopupBorderSize`の適用判定に使用（ただしModalでない場合）

---

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

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

### 推奨読解順序

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | imgui.h | `imgui.h` | ImGuiWindowFlags_列挙型（1189-1194行目） |

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | imgui.cpp | `imgui.cpp` | BeginPopup関数 |
| 2-2 | imgui.cpp | `imgui.cpp` | BeginPopupEx関数（内部実装） |

**主要処理フロー**:
1. `BeginPopup()`が呼び出される
2. 内部で`BeginPopupEx()`を呼び出し、`ImGuiWindowFlags_Popup`を含むフラグを渡す
3. `Begin()`でウィンドウが作成される

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | imgui.cpp | `imgui.cpp` | Begin関数内のフラグ判定（7591-7594行目、7737行目） |
| 3-2 | imgui.cpp | `imgui.cpp` | ポップアップ自動クローズ処理 |
| 3-3 | imgui.cpp | `imgui.cpp` | ホバー判定での使用（4752-4755行目） |

**主要処理フロー**:
- **7591-7594行目**: `Popup && !Modal`でBorderSize決定
- **7737行目**: `Popup && !Modal`でRounding決定
- **4752-4755行目**: ホバー抑止判定での使用

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

```
BeginPopup(str_id, flags)
    |
    +-- GetID(str_id)
    |
    +-- IsPopupOpen(id, ImGuiPopupFlags_None)
    |
    +-- BeginPopupEx(id, flags | ImGuiWindowFlags_...)
           |
           +-- Begin(name, NULL, flags | ImGuiWindowFlags_Popup | ...)
                  |
                  +-- ウィンドウタイプ判定
                  |      (flags & ImGuiWindowFlags_Popup)
                  |
                  +-- スタイル適用
                  |      PopupRounding, PopupBorderSize
                  |
                  +-- ポップアップスタック登録
```

### データフロー図

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

user flags ─────────> BeginPopup() ─────────> window flags
                           |
                           v
                    ImGuiWindowFlags_Popup追加
                           |
                           v
                      Begin()
                           |
                           v
                    ウィンドウ作成・表示
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| imgui.h | `imgui.h` | ヘッダ | ImGuiWindowFlags_Popup定義（1192行目） |
| imgui.cpp | `imgui.cpp` | ソース | BeginPopup実装、フラグ使用箇所多数 |
| imgui_internal.h | `imgui_internal.h` | 内部ヘッダ | ImGuiPopupData構造体 |
