# 機能設計書 76-Dummy

## 概要

本ドキュメントは、Dear ImGuiライブラリのDummy関数の機能設計を記述する。この関数は、指定サイズのダミーアイテムを追加するためのAPI関数である。

### 本機能の処理概要

Dummy関数は、指定されたサイズの不可視のダミーアイテムを追加する。InvisibleButton()と異なり、マウスクリックの検出やナビゲーションの対象とはならない。純粋にレイアウト目的で使用され、スペースを確保するために利用される。

**業務上の目的・背景**：GUIレイアウトにおいて、任意のサイズの空白スペースを確保したい場面がある。Spacing()がstyle.ItemSpacing.y分の固定スペースを追加するのに対し、Dummy()は任意のサイズ（幅と高さの両方）を指定できる。これにより、カスタムレイアウト、グリッド配置、アラインメント調整など、より高度なレイアウト制御が可能となる。また、将来的にウィジェットを配置する予定の領域を予約する用途にも使用される。

**機能の利用シーン**：カスタムレイアウトでのスペース確保、グリッドレイアウトのセル作成、テーブル内での空白セル、画像やアイコンのプレースホルダー、ウィンドウサイズの最小値確保などで使用される。

**主要な処理内容**：
1. ウィンドウのSkipItemsフラグを確認する
2. 現在のカーソル位置から指定サイズの矩形を計算する
3. ItemSizeで指定サイズ分だけカーソルを進める
4. ItemAddで矩形を登録する（ID=0、ナビゲーション対象外）

**関連システム・外部連携**：この関数は純粋にImGui内部のレイアウト管理に関わるため、外部システムとの連携はない。

**権限による制御**：権限による制御は存在しない。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 24 | Layout | 主機能 | ダミーアイテムのデモ |

## 機能種別

レイアウト制御

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| size | const ImVec2& | Yes | ダミーアイテムのサイズ（幅、高さ） | 特になし（負の値も許容） |

### 入力データソース

ユーザーコードから直接呼び出される。

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| (なし) | void | 戻り値なし |

### 出力先

現在のウィンドウのDrawing Context（DC）のCursorPosを更新し、アイテム矩形を登録する。

## 処理フロー

### 処理シーケンス

```
1. ウィンドウのSkipItemsフラグを確認
   └─ trueの場合は即座にreturn
2. ダミーアイテムの矩形を計算
   └─ bb = (CursorPos, CursorPos + size)
3. ItemSize(size)を呼び出す
   └─ カーソル位置を進める
4. ItemAdd(bb, 0)を呼び出す
   └─ ID=0でアイテムを登録（ナビゲーション対象外）
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{SkipItems?}
    B -->|Yes| C[return]
    B -->|No| D[矩形bbを計算]
    D --> E[ItemSize size]
    E --> F[ItemAdd bb, 0]
    F --> G[終了]
    C --> G
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | 不可視アイテム | ダミーアイテムは描画されない | 常時 |
| BR-02 | 非インタラクティブ | マウスクリックやナビゲーションの対象外 | 常時 |
| BR-03 | レイアウト影響 | 指定サイズ分のスペースを確保しレイアウトに影響を与える | 常時 |

### 計算ロジック

矩形の計算：
```
bb.Min = window->DC.CursorPos
bb.Max = window->DC.CursorPos + size
```

## データベース操作仕様

該当なし（メモリ内操作のみ）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | - | 特にエラー条件なし | - |

### リトライ仕様

該当なし

## トランザクション仕様

該当なし（フレーム単位の即座反映）

## パフォーマンス要件

非常に軽量な操作。ItemSizeとItemAddの呼び出しのみ。

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

特になし（純粋なUI操作）

## 備考

- InvisibleButton()との違い：Dummy()はマウスクリックを検出しない
- Spacing()との違い：Dummy()は任意のサイズを指定可能
- カスタム描画のための領域確保にも使用可能（GetItemRectMin/Max後にDrawListで描画）

---

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

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

### 推奨読解順序

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

矩形（ImRect）に関わるデータ構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | imgui_internal.h | `imgui_internal.h` | ImRect構造体の定義を確認 |
| 1-2 | imgui.h | `imgui.h` | ImVec2構造体の定義を確認 |

**読解のコツ**: ImRectはMin（左上）とMax（右下）の2点で矩形を定義する。Dummy()はこの矩形を内部的に使用する。

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | imgui_widgets.cpp | `imgui_widgets.cpp` | Dummy関数の実装（1581-1590行目） |

**主要処理フロー**:
1. **1583行目**: GetCurrentWindow()でウィンドウを取得
2. **1584-1585行目**: SkipItemsチェック
3. **1587行目**: 矩形bbの計算（CursorPosからsize分）
4. **1588行目**: ItemSize(size)でカーソルを進める
5. **1589行目**: ItemAdd(bb, 0)でアイテムを登録

#### Step 3: 関連関数との比較

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | imgui_widgets.cpp | `imgui_widgets.cpp` | InvisibleButton関数との違い（ID付与、クリック検出） |
| 3-2 | imgui_widgets.cpp | `imgui_widgets.cpp` | Spacing関数との違い（固定サイズ vs 任意サイズ） |

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

```
ImGui::Dummy(size)
    │
    ├─ GetCurrentWindow()
    │
    ├─ SkipItemsチェック
    │
    ├─ 矩形bb計算
    │      └─ bb = ImRect(CursorPos, CursorPos + size)
    │
    ├─ ItemSize(size)
    │      └─ CursorPos更新
    │
    └─ ItemAdd(bb, 0)
           └─ ID=0でアイテム登録（ナビゲーション対象外）
```

### データフロー図

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

ImVec2 size ─────▶ Dummy() ──────────▶ DC.CursorPos
                        │                  (size分増加)
                        │
                        ├─ 矩形bb計算
                        │
                        └─ ItemAdd(bb, 0) ──▶ アイテム登録
                                              (ID=0、非インタラクティブ)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| imgui.h | `imgui.h` | ヘッダー | Dummy関数の宣言（581行目） |
| imgui_widgets.cpp | `imgui_widgets.cpp` | ソース | Dummy関数の実装（1581-1590行目） |
| imgui_internal.h | `imgui_internal.h` | 内部ヘッダー | ImRect構造体の定義 |
