# 機能設計書 96-Checkbox

## 概要

本ドキュメントはImGuiのCheckbox機能について、その処理内容、入出力仕様、実装詳細を記述した機能設計書である。

### 本機能の処理概要

Checkboxは、オン/オフの2状態を切り替えるチェックボックスウィジェットを作成するためのUI機能である。ブール値へのポインタを受け取り、ユーザーのクリック操作に応じて値を切り替える。状態が変更された場合にtrueを返す。

**業務上の目的・背景**：GUIアプリケーションにおいて、設定のオン/オフ、オプションの有効/無効、項目の選択/非選択など、2値の状態を表現する必要がある場面は非常に多い。Checkboxはこれらのニーズに対応する最も基本的なUIコンポーネントであり、ユーザーにとって直感的で理解しやすいインタラクションを提供する。

**機能の利用シーン**：設定画面のオプション切り替え、フィルターの有効/無効、機能のオン/オフ、リストアイテムの選択、同意確認、デバッグオプションの切り替えなどで使用される。

**主要な処理内容**：
1. チェックボックスのサイズを計算する（正方形、GetFrameHeight()ベース）
2. ラベルとチェックボックスの全体領域を確定する
3. ButtonBehaviorでクリック状態を判定する
4. クリックされた場合、bool値を反転する
5. 状態に応じた色でフレームを描画する
6. チェック済みの場合はチェックマークを描画する
7. ラベルテキストを描画する
8. 状態変更（pressed）を戻り値として返す

**関連システム・外部連携**：ImGuiのDrawList描画システム、マルチセレクトシステム（複数選択対応）、Mixed Value対応（三状態チェックボックス）と連携する。

**権限による制御**：BeginDisabled/EndDisabledで無効化可能。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | Demo Window | 補助機能 | 各種チェックボックスの表示 |
| 3 | Debug Log Window | 補助機能 | ログフィルタの有効/無効切り替え |
| 6 | Style Editor | 主機能 | スタイル設定の切り替え |
| 11 | Log | 補助機能 | オートスクロールの切り替え |
| 13 | Property Editor | 補助機能 | ブールプロパティの編集 |
| 23 | Widgets | 主機能 | チェックボックスのデモ |

## 機能種別

UIウィジェット / ユーザー入力処理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| label | const char* | Yes | チェックボックスのラベルテキスト | NULL終端文字列 |
| v | bool* | Yes | チェック状態を格納するブール変数へのポインタ | 有効なポインタ |

### 入力データソース

- 呼び出し元からの直接指定
- ImGuiStyleからのスタイル設定値

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| pressed | bool | 状態が変更されたかどうか |
| *v | bool | 更新されたチェック状態（trueでオン、falseでオフ） |

### 出力先

- 戻り値として呼び出し元に返却
- ポインタ経由でブール変数を更新
- ImDrawList（現在のウィンドウの描画リスト）

## 処理フロー

### 処理シーケンス

```
1. ウィンドウの取得とスキップチェック
   └─ GetCurrentWindow()で現在のウィンドウを取得
   └─ SkipItemsがtrueの場合はfalseを返す

2. サイズ計算
   └─ square_sz = GetFrameHeight()でチェックボックスサイズを取得
   └─ ラベルサイズを計算
   └─ 全体のバウンディングボックスを作成

3. アイテム登録
   └─ ItemSize()でレイアウト領域を確保
   └─ ItemAdd()で描画リストに追加

4. マルチセレクト対応（オプション）
   └─ IsMultiSelect時はMultiSelectItemHeader/Footerを使用

5. インタラクション判定
   └─ ButtonBehavior()でhovered/held/pressed状態を取得
   └─ クリック時に*vを反転

6. 状態更新
   └─ 値が変更された場合、MarkItemEdited()を呼び出し

7. 描画
   └─ RenderNavCursor()でナビゲーションカーソルを描画
   └─ RenderFrame()でチェックボックス背景を描画
   └─ MixedValue時は矩形、チェック時はチェックマークを描画
   └─ ラベルを描画

8. ログ出力
   └─ LogEnabled時は"[x]"または"[ ]"をログに出力

9. 結果返却
   └─ pressed状態を返す
```

### フローチャート

```mermaid
flowchart TD
    A[開始: Checkbox] --> B{SkipItems?}
    B -->|Yes| C[return false]
    B -->|No| D[サイズ計算]
    D --> E[ItemSize/ItemAdd]
    E --> F{ItemAdd成功?}
    F -->|No| C
    F -->|Yes| G{MultiSelect?}
    G -->|Yes| H[MultiSelect処理]
    G -->|No| I[ButtonBehavior]
    H --> I
    I --> J{クリック?}
    J -->|Yes| K[*v を反転]
    J -->|No| L[描画処理]
    K --> L
    L --> M{MixedValue?}
    M -->|Yes| N[矩形を描画]
    M -->|No| O{*v == true?}
    N --> P[ラベル描画]
    O -->|Yes| Q[チェックマーク描画]
    O -->|No| P
    Q --> P
    P --> R[return pressed]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-96-01 | 正方形サイズ | チェックボックスはGetFrameHeight()サイズの正方形 | 常時 |
| BR-96-02 | クリック時の反転 | クリックされると*vの値を反転する | 常時 |
| BR-96-03 | MixedValue対応 | ImGuiItemFlags_MixedValueフラグ時は矩形で「不確定状態」を表示 | フラグ設定時 |
| BR-96-04 | マルチセレクト対応 | MultiSelect環境では範囲選択に対応 | MultiSelect環境下 |

### 計算ロジック

- チェックボックスサイズ: `square_sz = GetFrameHeight()`
- 全体幅: `square_sz + (label_size.x > 0 ? ItemInnerSpacing.x + label_size.x : 0)`
- チェックマークパディング: `pad = ImMax(1.0f, IM_TRUNC(square_sz / 6.0f))`

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

データベース操作なし（UI描画のみ）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 早期リターン | window->SkipItems == true | falseを返す |
| - | 早期リターン | ItemAdd失敗 | falseを返す |

### リトライ仕様

リトライ不要（フレームごとに再評価）

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

トランザクション管理なし（即時処理）

## パフォーマンス要件

- 単一フレーム内で多数のCheckboxを描画可能
- マルチセレクト対応によるオーバーヘッドは最小限

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

- ポインタ引数のバリデーションは呼び出し元の責任

## 備考

- ImGuiItemFlags_MixedValueを使用すると三状態（不確定状態）を表示可能
- 複数選択時は一部がオン、一部がオフの場合にMixedValueを使用
- ログ出力では"[x]"（オン）、"[ ]"（オフ）、"[~]"（不確定）として表現

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | imgui.h | `imgui.h` | 636行目: Checkbox関数のAPI宣言を確認 |
| 1-2 | imgui.h | `imgui.h` | ImGuiCol_FrameBg、ImGuiCol_CheckMark等の色定義 |
| 1-3 | imgui.h | `imgui.h` | ImGuiItemFlags_MixedValueの定義 |

**読解のコツ**: CheckboxはButtonBehaviorを使用しつつ、独自の描画（チェックマーク）を行う。MixedValueは三状態表示の重要な概念。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | imgui_widgets.cpp | `imgui_widgets.cpp` | 1215-1288行目: Checkbox関数の実装 |

**主要処理フロー**:
1. **1217-1219行目**: ウィンドウ取得とスキップチェック
2. **1223行目**: GetIDでラベルからID生成
3. **1226行目**: GetFrameHeight()でサイズ取得
4. **1228行目**: 全体のバウンディングボックス計算
5. **1230-1237行目**: ItemAdd、マルチセレクトチェック
6. **1244-1245行目**: ButtonBehavior呼び出し
7. **1250-1251行目**: クリック時の値反転
8. **1253-1258行目**: 値変更時のMarkItemEdited
9. **1262-1278行目**: 描画処理（フレーム、チェックマーク、ラベル）
10. **1281-1282行目**: ログ出力

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

```
ImGui::Checkbox(label, v)
    │
    ├─ GetCurrentWindow()
    │
    ├─ window->GetID(label)
    │
    ├─ CalcTextSize(label)
    │
    ├─ GetFrameHeight()
    │      └─ 正方形サイズを取得
    │
    ├─ ItemSize() / ItemAdd()
    │
    ├─ MultiSelectItemHeader() [マルチセレクト時]
    │
    ├─ ButtonBehavior()
    │
    ├─ MultiSelectItemFooter() [マルチセレクト時]
    │
    ├─ MarkItemEdited() [値変更時]
    │
    ├─ RenderNavCursor()
    │
    ├─ RenderFrame()
    │      └─ チェックボックス背景
    │
    ├─ RenderCheckMark() または AddRectFilled()
    │      └─ チェックマークまたは不確定状態表示
    │
    └─ RenderText()
           └─ ラベル描画
```

### データフロー図

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

label (文字列) ────────────> GetID ─────────────────────────> ImGuiID
                                │
v (bool*) ─────────────────────────────────────────────────> *v (更新)
                                │
                            サイズ計算
                                │
マウス/キーボード状態 ─────> ButtonBehavior ─────────────────> pressed
                                │
                            クリック時 → *v 反転
                                │
                            RenderFrame ────────────────────> DrawList (背景)
                            RenderCheckMark ────────────────> DrawList (チェック)
                            RenderText ─────────────────────> DrawList (ラベル)
                                │
                            return pressed ─────────────────> bool (状態変更有無)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| imgui.h | `imgui.h` | ヘッダー | Checkbox APIの宣言、色定義 |
| imgui_widgets.cpp | `imgui_widgets.cpp` | ソース | Checkboxの実装 |
| imgui.cpp | `imgui.cpp` | ソース | ButtonBehavior、RenderCheckMark等 |
| imgui_draw.cpp | `imgui_draw.cpp` | ソース | チェックマーク描画関数 |
