# 通知設計書 15-IsPopupOpen

## 概要

本ドキュメントは、Dear ImGuiライブラリにおける`IsPopupOpen()`関数の設計仕様を記載する。この関数は、指定したポップアップが現在開いているかどうかを照会するための通知メカニズムを提供する。

### 本通知の処理概要

`IsPopupOpen()`は、ポップアップスタックを参照して、指定されたIDのポップアップが開いているかどうかを確認する照会関数である。文字列ID版とImGuiID版の2つのオーバーロードが存在し、ImGuiPopupFlagsを使用して検索範囲を制御できる。

**業務上の目的・背景**：GUIアプリケーションにおいて、ポップアップの状態に応じて処理を分岐させたい場面は多い。例えば、特定のポップアップが開いている間は他の操作を無効化したり、ポップアップの有無に応じてUIを変更したりする必要がある。この関数は、そのような状態確認を行うための標準的な手段を提供する。

**通知の送信タイミング**：この関数は照会専用であり、呼び出されたタイミングで現在のポップアップスタック状態を確認する。状態を変更する「送信」は行わない。

**通知の受信者**：呼び出し元のアプリケーションコード。戻り値としてbool値を受け取る。

**通知内容の概要**：指定されたポップアップID（またはフラグに応じた任意のポップアップ）が現在開いているかどうかの真偽値。

**期待されるアクション**：戻り値に基づいて、アプリケーションが適切な処理分岐を行う。

## 通知種別

内部API呼び出し / 状態照会

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期（照会のみ） |
| 優先度 | N/A（状態変更なし） |
| リトライ | N/A |

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

この関数は照会専用のため、送信先決定ロジックは存在しない。ポップアップスタックを読み取り、結果を返す。

## 通知テンプレート

### API呼び出し形式

| 項目 | 内容 |
|-----|------|
| 関数名（文字列版） | IsPopupOpen(const char* str_id, ImGuiPopupFlags flags) |
| 関数名（ID版） | IsPopupOpen(ImGuiID id, ImGuiPopupFlags popup_flags) |
| 戻り値 | bool（ポップアップが開いている場合true） |
| 引数1 | str_id/id: ポップアップの識別子 |
| 引数2 | flags/popup_flags: 検索オプション |

### 使用例

```cpp
// 特定のポップアップが開いているか確認
if (ImGui::IsPopupOpen("my_popup"))
{
    // my_popupが開いている時の処理
}

// 任意のポップアップが開いているか確認（現在のレベル）
if (ImGui::IsPopupOpen("", ImGuiPopupFlags_AnyPopupId))
{
    // 何らかのポップアップが開いている
}

// 任意のポップアップが開いているか確認（全レベル）
if (ImGui::IsPopupOpen("", ImGuiPopupFlags_AnyPopupId | ImGuiPopupFlags_AnyPopupLevel))
{
    // ポップアップスタックに何かある
}
```

### 添付ファイル

| ファイル名 | 形式 | 条件 | 説明 |
|----------|------|------|------|
| N/A | N/A | N/A | この通知には添付ファイルは存在しない |

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| id | ポップアップID | str_id ? GetID(str_id) : 引数id | AnyPopupId未使用時 |
| popup_flags | 検索オプション | 関数引数 | No（デフォルト0） |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| 照会 | 関数呼び出し | 常時実行可能 | ポップアップ状態の確認 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| N/A | 照会関数のため抑止条件なし |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[IsPopupOpen呼び出し] --> B{AnyPopupIdフラグ?}
    B -->|Yes| C{AnyPopupLevelフラグ?}
    C -->|Yes| D{OpenPopupStack.Size > 0?}
    D -->|Yes| E[return true]
    D -->|No| F[return false]
    C -->|No| G{OpenPopupStack.Size > BeginPopupStack.Size?}
    G -->|Yes| E
    G -->|No| F
    B -->|No| H{AnyPopupLevelフラグ?}
    H -->|Yes| I[全スタック検索]
    I --> J{id一致するエントリ?}
    J -->|Yes| E
    J -->|No| F
    H -->|No| K{現在レベルでid一致?}
    K -->|Yes| E
    K -->|No| F
```

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

### 参照テーブル一覧

| テーブル名 | 用途 | 備考 |
|-----------|------|------|
| g.OpenPopupStack | 開いているポップアップ | ImGuiPopupData配列 |
| g.BeginPopupStack | 現在のポップアップ階層 | 現在の深さ確認 |

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

#### g.OpenPopupStack

| 参照項目（カラム名） | 用途 | 取得条件 |
|-------------------|------|---------|
| PopupId | ポップアップ識別 | 各エントリのID |
| Size | スタックサイズ | 存在確認 |

### 更新テーブル一覧

| テーブル名 | 操作 | 概要 |
|-----------|------|------|
| N/A | N/A | この関数は参照のみで更新なし |

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| アサート失敗 | AnyPopupLevelと文字列IDの組み合わせ | ID版を使用するか、文字列IDを指定しない |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | N/A（照会のみ） |
| リトライ間隔 | N/A |
| リトライ対象エラー | N/A |

## 配信設定

### レート制限

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

### 配信時間帯

即座に実行される同期処理のため、配信時間帯の制限なし。

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

この関数は読み取り専用であり、内部状態を変更しない。セキュリティ上のリスクは存在しない。

## 備考

- ImGuiPopupFlags_AnyPopupIdを使用する場合、idパラメータは無視される（0であるべき）
- 文字列ID版でImGuiPopupFlags_AnyPopupLevelを使用するとアサートが発生する
- ImGuiID版のIsPopupOpenは内部でも使用される（例：ClosePopupsOverWindow）
- ImGuiPopupFlags_AnyPopup = AnyPopupId | AnyPopupLevel の組み合わせで「何かポップアップが開いているか」を確認可能

---

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

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

### 推奨読解順序

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

ポップアップスタックとフラグの定義を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | imgui.h | `imgui.h` | ImGuiPopupFlags_列挙型（1337-1352行） |
| 1-2 | imgui.h | `imgui.h` | AnyPopupId, AnyPopupLevel, AnyPopup定義（1347-1349行） |
| 1-3 | imgui_internal.h | `imgui_internal.h` | ImGuiPopupData構造体 |

**読解のコツ**: AnyPopupId=1<<10、AnyPopupLevel=1<<11、AnyPopup=両方のOR。

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

IsPopupOpen関数の実装を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | imgui.cpp | `imgui.cpp` | IsPopupOpen(ImGuiID版)関数（12056行目） |
| 2-2 | imgui.cpp | `imgui.cpp` | IsPopupOpen(文字列版)関数（12087行目） |

**主要処理フロー（ImGuiID版）**:
1. **12059-12068行**: AnyPopupIdフラグ処理
2. **12064-12065行**: AnyPopupLevelならスタックサイズで判定
3. **12066-12067行**: そうでなければ現在レベルより上があるか判定
4. **12071-12078行**: AnyPopupLevel + 特定ID → 全スタック検索
5. **12081-12082行**: 現在レベルでのID一致確認

**主要処理フロー（文字列版）**:
1. **12090行**: AnyPopupIdなら0、そうでなければGetID
2. **12091-12092行**: 文字列ID + AnyPopupLevelはアサート
3. **12093行**: ID版を呼び出し

#### Step 3: 使用例を確認する

内部での使用例を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | imgui.cpp | `imgui.cpp` | OpenPopupEx内での使用（12179行） |
| 3-2 | imgui_widgets.cpp | `imgui_widgets.cpp` | Combo/Menu系での使用 |

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

```
IsPopupOpen(const char* str_id)  [imgui.cpp:12087]
    |
    +-- AnyPopupIdチェック → id = 0 or GetID(str_id)
    |
    +-- AnyPopupLevel + str_idチェック → アサート
    |
    +-- IsPopupOpen(ImGuiID id)  [imgui.cpp:12056]
            |
            +-- AnyPopupIdフラグ判定
            |       +-- AnyPopupLevel → OpenPopupStack.Size > 0
            |       +-- else → OpenPopupStack.Size > BeginPopupStack.Size
            |
            +-- 特定ID判定
                    +-- AnyPopupLevel → 全スタック検索
                    +-- else → 現在レベル確認
```

### データフロー図

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

str_id ────────────▶ GetID() ──────────────▶ popup_id
                          |
popup_flags ───────▶ フラグ解析 ──────────────────────────▶ 検索モード
                          |
                          v
g.OpenPopupStack ──▶ スタック検索 ──▶ bool (開いているか)
g.BeginPopupStack ─────┘
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| imgui.h | `imgui.h` | ヘッダー | IsPopupOpen関数宣言（878行目） |
| imgui.h | `imgui.h` | ヘッダー | 関数説明コメント（875-877行目） |
| imgui.cpp | `imgui.cpp` | ソース | IsPopupOpen(ImGuiID)実装（12056行目） |
| imgui.cpp | `imgui.cpp` | ソース | IsPopupOpen(const char*)実装（12087行目） |
| imgui.h | `imgui.h` | ヘッダー | ImGuiPopupFlags定義（1337-1352行） |
| imgui_internal.h | `imgui_internal.h` | 内部ヘッダー | 内部版IsPopupOpen宣言（3320行目） |
