# 画面設計書 25-Popups

## 概要

本ドキュメントは、Dear ImGuiのデモセクション「Popups & Modal windows」の設計書です。Demo Window内の折りたたみセクションとして、ポップアップとモーダルウィンドウの使用方法をデモンストレーションします。

### 本画面の処理概要

**業務上の目的・背景**：本セクションは、Dear ImGuiのポップアップ・モーダルウィンドウシステムの包括的なリファレンスです。通常のポップアップ、コンテキストメニュー、モーダルダイアログの実装方法を示します。ポップアップはImmediate Mode GUIにおいて特殊な扱いとなり、表示状態がライブラリ内部で管理されます。ユーザーは外部クリックまたはESCキーでポップアップを閉じることができます。アプリケーションでダイアログ、コンテキストメニュー、ツールチップを実装する際の参考となります。

**画面へのアクセス方法**：Demo Windowの「Popups & Modal windows」CollapsingHeaderをクリックすることでセクションが展開されます。DemoWindowPopups関数がShowDemoWindow()から呼び出されることで表示されます。

**主要な操作・処理内容**：
1. Popups - 基本的なポップアップの使用方法
2. Context menus - 右クリックコンテキストメニュー
3. Modals - モーダルダイアログの実装
4. Menus inside a regular window - 通常ウィンドウ内でのメニュー

**画面遷移**：Demo Windowの一部として表示されます。CollapsingHeaderで折りたたみ/展開可能です。各サブセクションはTreeNodeで階層化されています。

**権限による表示制御**：本セクションでは権限による表示制御は実装されていません。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 162 | BeginPopup | 主機能 | ポップアップの開始 |
| 163 | BeginPopupModal | 主機能 | モーダルポップアップの開始 |
| 164 | EndPopup | 主機能 | ポップアップの終了 |
| 165 | OpenPopup | 主機能 | ポップアップを開く |
| 167 | CloseCurrentPopup | 主機能 | 現在のポップアップを閉じる |
| 168 | BeginPopupContextItem | 補助機能 | コンテキストメニューの表示 |
| 169 | BeginPopupContextWindow | 補助機能 | ウィンドウコンテキストメニュー |
| 157 | BeginTooltip | 補助機能 | ツールチップの開始 |
| 158 | EndTooltip | 補助機能 | ツールチップの終了 |

## 画面種別

デモセクション（CollapsingHeader）

## URL/ルーティング

N/A（Dear ImGuiはImmediate Mode GUIライブラリのため、URL/ルーティングの概念は適用されません）

## 入出力項目

| 項目名 | 型 | 入力/出力 | 説明 |
|--------|-----|----------|------|
| なし | - | - | 本セクションは引数を受け取らない |

## 表示項目

### Popups セクション
| 項目名 | 表示形式 | 説明 |
|--------|----------|------|
| Select.. ボタン | Button + BeginPopup | 選択用ポップアップ |
| Toggle.. ボタン | Button + BeginPopup | トグル用ポップアップ（スタック可能） |
| With a menu.. ボタン | Button + BeginPopup | メニューバー付きポップアップ |

### Context menus セクション
| 項目名 | 表示形式 | 説明 |
|--------|----------|------|
| Selectable リスト | Selectable + BeginPopupContextItem | 各アイテムのコンテキストメニュー |
| Value テキスト | Text + BeginPopupContextItem | テキストへのコンテキストメニュー |
| Button | Button + BeginPopupContextItem | ボタンへのコンテキストメニュー |

### Modals セクション
| 項目名 | 表示形式 | 説明 |
|--------|----------|------|
| Delete.. ボタン | Button + BeginPopupModal | 削除確認モーダル |
| Stacked modals.. ボタン | Button + BeginPopupModal | スタック可能なモーダル |

## イベント仕様

### 1-ポップアップを開く

Button()がtrueを返した後にOpenPopup("popup_id")を呼び出すと、ポップアップが開きます。BeginPopup()はポップアップが開いている場合にtrueを返します。

### 2-ポップアップを閉じる

ポップアップ外をクリックするか、ESCキーを押すと自動的に閉じます。CloseCurrentPopup()で明示的に閉じることもできます。

### 3-コンテキストメニュー

BeginPopupContextItem()は、直前のアイテム上で右クリックされた場合にtrueを返します。IDを指定しない場合、直前のアイテムのIDが使用されます。

### 4-モーダルダイアログ

BeginPopupModal()で開始されたポップアップは、外部クリックで閉じません。明示的にCloseCurrentPopup()を呼び出すか、×ボタン（bool*を渡した場合）でのみ閉じます。

### 5-スタックされたポップアップ

ポップアップ内で別のOpenPopup()を呼び出すと、ポップアップがスタックされます。前のポップアップは暗くなりますが、閉じません。

### 6-ウィンドウコンテキストメニュー

BeginPopupContextWindow()は、ウィンドウの空白領域で右クリックされた場合にコンテキストメニューを表示します。

## データベース更新仕様

N/A（本デモセクションはデータベースを使用しません。すべてのデータはローカル変数またはstatic変数で管理されます）

## メッセージ仕様

| メッセージID | 種別 | 表示条件 | メッセージ内容 |
|--------------|------|----------|----------------|
| MSG-001 | 確認 | 削除モーダル表示時 | "All those beautiful files will be deleted.\nThis operation cannot be undone!" |
| MSG-002 | 情報 | ポップアップ内 | "Hello from popup!" |
| MSG-003 | 情報 | スタックモーダル内 | "Hello from Stacked The First" |

## 例外処理

| 例外状況 | 処理内容 |
|----------|----------|
| CollapsingHeaderが折りたたまれている場合 | 早期リターンで処理をスキップ |
| ポップアップが開いていない場合 | BeginPopup()がfalseを返し、内部コードはスキップ |

## 備考

- ポップアップの表示状態はImGuiが内部的に管理するため、ユーザーがbool変数を保持する必要がない
- モーダルダイアログはImGuiCol_ModalWindowDimBgで背景が暗くなる
- SetNextWindowPos()をImGuiCond_Appearingで使用すると、ポップアップ出現時に位置を設定できる
- GetMainViewport()->GetCenter()でビューポートの中央を取得し、モーダルを中央に配置可能
- OpenPopupOnItemClick()は、アイテム上でのクリックに応じてポップアップを開く便利関数

---

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

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

### 推奨読解順序

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

処理の起点となる関数を特定します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | imgui_demo.cpp | `imgui_demo.cpp` | DemoWindowPopups関数（行5225-5520）がエントリーポイント |

**主要処理フロー**:
1. **行5227**: CollapsingHeader("Popups & Modal windows")で折りたたみセクションを開始
2. **行5230-5246**: ポップアップの基本的な説明コメント
3. **行5248-5339**: Popupsセクション
4. **行5341-5426**: Context menusセクション
5. **行5428-5503**: Modalsセクション
6. **行5505-5519**: Menus inside a regular windowセクション

#### Step 2: 基本的なポップアップを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | imgui_demo.cpp | `imgui_demo.cpp` | Popupsセクション（行5248-5339）を理解する |

**主要処理フロー**:
- **行5261-5272**: Button + OpenPopup + BeginPopupの基本パターン
- **行5275-5312**: トグルポップアップとスタックされたポップアップ
- **行5315-5336**: メニューバー付きポップアップ

#### Step 3: コンテキストメニューを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | imgui_demo.cpp | `imgui_demo.cpp` | Context menusセクション（行5341-5426）を理解する |

**主要処理フロー**:
- **行5358-5375**: Selectable + BeginPopupContextItem（暗黙的ID）
- **行5380-5402**: Text + BeginPopupContextItem（明示的ID）
- **行5408-5422**: Button + BeginPopupContextItem（###演算子でID安定化）

#### Step 4: モーダルダイアログを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | imgui_demo.cpp | `imgui_demo.cpp` | Modalsセクション（行5428-5503）を理解する |

**主要処理フロー**:
- **行5433-5458**: 削除確認モーダル（中央配置、AlwaysAutoResize）
- **行5460-5500**: スタックされたモーダル（メニューバー付き）

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

```
ShowDemoWindow()
    |
    +-- DemoWindowPopups()
            |
            +-- ImGui::CollapsingHeader("Popups & Modal windows")
            |
            +-- TreeNode("Popups")
            |       |
            |       +-- Button("Select..") -> OpenPopup("my_select_popup")
            |       |       +-- BeginPopup("my_select_popup") / EndPopup()
            |       |               +-- Selectable() [選択アイテム]
            |       |
            |       +-- Button("Toggle..") -> OpenPopup("my_toggle_popup")
            |       |       +-- BeginPopup("my_toggle_popup") / EndPopup()
            |       |               +-- MenuItem() [トグルアイテム]
            |       |               +-- Button("Stacked Popup") -> OpenPopup("another popup")
            |       |
            |       +-- Button("With a menu..") -> OpenPopup("my_file_popup")
            |               +-- BeginPopup(..., ImGuiWindowFlags_MenuBar) / EndPopup()
            |                       +-- BeginMenuBar() / EndMenuBar()
            |
            +-- TreeNode("Context menus")
            |       |
            |       +-- Selectable() + BeginPopupContextItem() [暗黙的ID]
            |       +-- Text() + BeginPopupContextItem("my popup") [明示的ID]
            |       +-- Button() + BeginPopupContextItem() [###演算子]
            |
            +-- TreeNode("Modals")
            |       |
            |       +-- Button("Delete..") -> OpenPopup("Delete?")
            |       |       +-- SetNextWindowPos(center, ImGuiCond_Appearing)
            |       |       +-- BeginPopupModal("Delete?") / EndPopup()
            |       |               +-- Checkbox() / Button("OK", "Cancel")
            |       |               +-- CloseCurrentPopup()
            |       |
            |       +-- Button("Stacked modals..") -> OpenPopup("Stacked 1")
            |               +-- BeginPopupModal("Stacked 1") / EndPopup()
            |                       +-- Button("Add another modal..") -> OpenPopup("Stacked 2")
            |                       +-- BeginPopupModal("Stacked 2") / EndPopup()
            |
            +-- TreeNode("Menus inside a regular window")
                    |
                    +-- MenuItem("Menu item")
                    +-- BeginMenu("Menu inside a regular window") / EndMenu()
```

### データフロー図

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

ボタンクリック ---------> OpenPopup() --------------------> ポップアップ表示状態
                              |                                (内部管理)
                              v
右クリック ------------> BeginPopupContextItem() ---------> コンテキストメニュー
                              |
                              v
                         BeginPopup() / BeginPopupModal()
                              |
ユーザー操作 -----------> ポップアップ内処理 -------------> 選択結果
(選択/キャンセル)             |                                |
                              |                                v
外部クリック/ESC -------> CloseCurrentPopup() ------------> ポップアップ閉じる
                              |
                              v
                         EndPopup() -----------------------> 描画終了
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| imgui_demo.cpp | `imgui_demo.cpp` | ソース | DemoWindowPopups関数の実装（行5222-5520） |
| imgui.h | `imgui.h` | ヘッダー | ポップアップ関連API定義（BeginPopup, OpenPopup等） |
| imgui.cpp | `imgui.cpp` | ソース | ポップアップ関連関数の実装 |
