# 通知設計書 20-ImGuiPopupFlags_NoOpenOverExistingPopup

## 概要

本ドキュメントは、Dear ImGuiライブラリにおける`ImGuiPopupFlags_NoOpenOverExistingPopup`フラグの設計仕様を記載する。このフラグは、同じレベルに既にポップアップが存在する場合に新しいポップアップを開かないことを指定する。

### 本通知の処理概要

`ImGuiPopupFlags_NoOpenOverExistingPopup`は、OpenPopup系関数およびBeginPopupContext系関数で使用され、ポップアップスタックの同じレベルに既にポップアップが存在する場合に、新しいポップアップのオープンを抑制する。これにより、意図しないポップアップの上書きや競合を防ぐことができる。

**業務上の目的・背景**：複数のコンテキストメニューや確認ダイアログが競合する可能性がある場合、既存のポップアップを優先して新しいポップアップを開かないようにしたいケースがある。例えば、右クリックで既にコンテキストメニューが開いている状態で、別の領域を右クリックしても既存のメニューを維持したい場合などに使用される。

**通知の送信タイミング**：このフラグ自体は送信を行わない。OpenPopupEx関数の冒頭で、IsPopupOpen(0, AnyPopupId)で既存ポップアップの存在を確認し、存在する場合は早期リターンする。

**通知の受信者**：OpenPopupEx関数内の既存ポップアップチェックロジック。

**通知内容の概要**：同じレベルにポップアップが存在する場合は新しいポップアップを開かない指示。

**期待されるアクション**：既存のポップアップが維持され、新しいポップアップは開かれない。

## 通知種別

フラグ定数 / ポップアップ動作オプション

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| フラグ値 | 1 << 7 = 128 |
| カテゴリ | オープン制御 |
| 排他性 | なし（他のフラグと併用可能） |

### フラグ処理ロジック

OpenPopupEx関数内で以下の順序で処理される：
1. NoOpenOverExistingPopupフラグが設定されているか確認
2. IsPopupOpen(0, ImGuiPopupFlags_AnyPopupId)で任意のポップアップが開いているか確認
3. 開いている場合は早期リターン（ポップアップを開かない）

## 通知テンプレート

### フラグ定義

| 項目 | 内容 |
|-----|------|
| フラグ名 | ImGuiPopupFlags_NoOpenOverExistingPopup |
| 値 | 1 << 7 (= 128) |
| 定義場所 | imgui.h:1345 |

### 使用例

```cpp
// 既存ポップアップがある場合は開かない
if (ImGui::Button("Show Settings"))
{
    ImGui::OpenPopup("settings", ImGuiPopupFlags_NoOpenOverExistingPopup);
}
if (ImGui::BeginPopup("settings"))
{
    ImGui::Text("Settings");
    ImGui::EndPopup();
}

// BeginPopupContext系でも使用可能
if (ImGui::BeginPopupContextItem("context", ImGuiPopupFlags_NoOpenOverExistingPopup))
{
    ImGui::MenuItem("Option");
    ImGui::EndPopup();
}

// IsAnyPopupOpen()チェックと同等の効果
// 以下は同じ動作：
// if (!ImGui::IsPopupOpen("", ImGuiPopupFlags_AnyPopupId))
//     ImGui::OpenPopup("my_popup");
// ↓ フラグで簡潔に書ける
ImGui::OpenPopup("my_popup", ImGuiPopupFlags_NoOpenOverExistingPopup);
```

### 添付ファイル

| ファイル名 | 形式 | 条件 | 説明 |
|----------|------|------|------|
| N/A | N/A | N/A | フラグ定義のため添付ファイルなし |

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| N/A | N/A | N/A | フラグ定義のため変数なし |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| API呼び出し | OpenPopup/OpenPopupEx | フラグが設定されている | 既存ポップアップチェック |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| 既存ポップアップあり | IsPopupOpen(0, AnyPopupId) == true |

## 処理フロー

### フラグ処理フロー

```mermaid
flowchart TD
    A[OpenPopupEx呼び出し] --> B{NoOpenOverExistingPopupフラグ?}
    B -->|No| C[通常のオープン処理へ]
    B -->|Yes| D{IsPopupOpen AnyPopupId?}
    D -->|Yes| E[早期リターン]
    D -->|No| C
    C --> F[ポップアップオープン処理]
    E --> G[終了（ポップアップ開かず）]
    F --> G
```

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

### 参照テーブル一覧

| テーブル名 | 用途 | 備考 |
|-----------|------|------|
| g.OpenPopupStack | 既存ポップアップ確認 | サイズ確認 |
| g.BeginPopupStack | 現在レベル確認 | サイズ比較 |

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

#### g.OpenPopupStack

| 参照項目（カラム名） | 用途 | 取得条件 |
|-------------------|------|---------|
| Size | 既存ポップアップ存在確認 | g.OpenPopupStack.Size > g.BeginPopupStack.Size |

### 更新テーブル一覧

| テーブル名 | 操作 | 概要 |
|-----------|------|------|
| N/A | N/A | このフラグ使用時は更新されない（早期リターン） |

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| 特になし | N/A | フラグ使用にエラーケースなし |

### リトライ仕様

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

## 配信設定

### レート制限

| 項目 | 内容 |
|-----|------|
| 1分あたり上限 | N/A |
| 1日あたり上限 | N/A |

### 配信時間帯

フラグ定義のため配信概念なし。

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

フラグ定義であり、セキュリティ上のリスクは存在しない。

## 備考

- このフラグは「!IsAnyPopupOpen() prior to OpenPopup()」と同等の効果を持つ
- imgui.hのコメントに明記されている通り、テスト「!IsAnyPopupOpen()」の代替手段
- 同じレベル（BeginPopupStack.Size）でのポップアップ存在のみチェック
- 異なるレベル（ネストしたポップアップ）には影響しない
- デモコードでも使用例がコメントで示されている（imgui_demo.cpp:7111）

---

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

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

### 推奨読解順序

#### Step 1: フラグ定義を理解する

ImGuiPopupFlags_列挙型の定義を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | imgui.h | `imgui.h` | ImGuiPopupFlags_NoOpenOverExistingPopup定義（1345行目） |
| 1-2 | imgui.h | `imgui.h` | コメント「don't open if there's already a popup at the same level」 |

**読解のコツ**: NoOpenOverExistingPopup = 1 << 7 = 128。コメントに「same level of the popup stack」とある点に注目。

#### Step 2: OpenPopupExでの処理を理解する

OpenPopupEx関数内でのNoOpenOverExistingPopupフラグ処理を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | imgui.cpp | `imgui.cpp` | OpenPopupEx関数（12172行目） |
| 2-2 | imgui.cpp | `imgui.cpp` | NoOpenOverExistingPopupチェック（12178-12180行） |

**主要処理フロー**:
1. **12178行**: NoOpenOverExistingPopupフラグ確認
2. **12179行**: IsPopupOpen(0, AnyPopupId)で既存ポップアップ確認
3. **12180行**: 存在する場合はreturn（早期リターン）

#### Step 3: ヘルパーコメントを確認する

APIコメントでの説明を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | imgui.h | `imgui.h` | Use ImGuiPopupFlags_NoOpenOverExistingPopup説明（854行目） |
| 3-2 | imgui_demo.cpp | `imgui_demo.cpp` | 使用例コメント（7111行目） |

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

```
OpenPopup() / BeginPopupContext*()
    |
    +-- OpenPopupEx(id, popup_flags)  [imgui.cpp:12172]
            |
            +-- {popup_flags & NoOpenOverExistingPopup?}
            |       |
            |       +-- Yes: IsPopupOpen(0, AnyPopupId)
            |               |
            |               +-- true: return (ポップアップ開かない)
            |               |
            |               +-- false: 続行
            |
            +-- (以降の通常処理)
```

### データフロー図

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

popup_flags (NoOpenOverExistingPopup含む)
        |
        +──▶ OpenPopupEx
                |
                +──▶ フラグチェック
                |           |
                |           +──▶ IsPopupOpen(0, AnyPopupId)
                |                       |
                |                       +──▶ g.OpenPopupStack.Size > g.BeginPopupStack.Size
                |
                +──▶ 結果判定
                        |
                        +──▶ true: 早期リターン（開かない）
                        |
                        +──▶ false: 通常オープン処理
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| imgui.h | `imgui.h` | ヘッダー | ImGuiPopupFlags_NoOpenOverExistingPopup定義（1345行目） |
| imgui.h | `imgui.h` | ヘッダー | 使用方法コメント（854行目） |
| imgui.cpp | `imgui.cpp` | ソース | OpenPopupEx実装（12172行目） |
| imgui.cpp | `imgui.cpp` | ソース | フラグチェック処理（12178-12180行） |
| imgui.cpp | `imgui.cpp` | ソース | IsPopupOpen(AnyPopupId)実装（12056-12067行） |
| imgui_demo.cpp | `imgui_demo.cpp` | デモ | 使用例コメント（7111行目） |
