# 機能設計書 97-CheckboxFlags

## 概要

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

### 本機能の処理概要

CheckboxFlagsは、ビットフラグ操作用のチェックボックスウィジェットを作成するためのUI機能である。整数型のフラグ変数に対して、特定のビットフラグをオン/オフする操作を行う。通常のCheckboxと異なり、複数のフラグを1つの変数で管理する場合に便利である。また、一部のビットのみがオンの場合は「不確定状態（Mixed Value）」として表示される。

**業務上の目的・背景**：GUIアプリケーションにおいて、複数のオプションをビットフラグで管理するケースは一般的である。例えば、ウィンドウフラグ（ImGuiWindowFlags）、描画フラグ、機能有効化フラグなどである。CheckboxFlagsはこれらのフラグを個別に操作するための専用ウィジェットを提供し、ビット演算を内部で処理することで開発者の負担を軽減する。

**機能の利用シーン**：コンフィグオプションの設定、ウィンドウフラグの編集、レンダリングオプションの切り替え、権限設定、機能セットの選択などで使用される。

**主要な処理内容**：
1. 現在のフラグ状態を確認（全ビットオン、一部オン、全オフ）
2. 一部オンの場合はMixedValueフラグを設定
3. 内部でCheckbox関数を呼び出す
4. クリックされた場合、対象ビットをセット/クリア
5. 状態変更（pressed）を戻り値として返す

**関連システム・外部連携**：ImGuiのCheckbox機能を内部で使用。int、unsigned int、ImS64、ImU64の各型に対応したオーバーロードを提供。

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | CheckboxFlagsは画面機能マッピングに直接関連付けられていないが、Demo Window等でウィンドウフラグの設定に使用される |

## 機能種別

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

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| label | const char* | Yes | チェックボックスのラベルテキスト | NULL終端文字列 |
| flags | int* / unsigned int* / ImS64* / ImU64* | Yes | フラグ変数へのポインタ | 有効なポインタ |
| flags_value | int / unsigned int / ImS64 / ImU64 | Yes | 操作対象のビットフラグ値 | 有効なビットパターン |

### 入力データソース

- 呼び出し元からの直接指定

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| pressed | bool | 状態が変更されたかどうか |
| *flags | int等 | 更新されたフラグ値 |

### 出力先

- 戻り値として呼び出し元に返却
- ポインタ経由でフラグ変数を更新

## 処理フロー

### 処理シーケンス

```
1. フラグ状態の確認
   └─ all_on = (*flags & flags_value) == flags_value
   └─ any_on = (*flags & flags_value) != 0

2. Mixed Value判定
   └─ !all_on && any_on の場合、MixedValueフラグをセット

3. Checkbox呼び出し
   └─ Checkbox(label, &all_on)を呼び出し

4. フラグ更新
   └─ クリックされた場合:
       └─ all_on == true: *flags |= flags_value（ビットをセット）
       └─ all_on == false: *flags &= ~flags_value（ビットをクリア）

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

### フローチャート

```mermaid
flowchart TD
    A[開始: CheckboxFlags] --> B[フラグ状態確認]
    B --> C{all_on?}
    C -->|Yes| D[通常Checkbox呼び出し]
    C -->|No| E{any_on?}
    E -->|Yes| F[MixedValueフラグ設定]
    E -->|No| D
    F --> G[Checkbox呼び出し]
    D --> H{pressed?}
    G --> H
    H -->|No| I[return pressed]
    H -->|Yes| J{all_on == true?}
    J -->|Yes| K[*flags に flags_value をセット]
    J -->|No| L[*flags から flags_value をクリア]
    K --> I
    L --> I
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-97-01 | 全ビットオン | flags_valueの全ビットがオンの場合、チェック状態を表示 | (flags & flags_value) == flags_value |
| BR-97-02 | 部分オン | 一部のビットのみオンの場合、MixedValue（不確定状態）を表示 | (flags & flags_value) != 0 && (flags & flags_value) != flags_value |
| BR-97-03 | 全オフ | flags_valueの全ビットがオフの場合、未チェック状態を表示 | (flags & flags_value) == 0 |
| BR-97-04 | セット操作 | クリックでオンにする場合、OR演算でビットをセット | all_on == true |
| BR-97-05 | クリア操作 | クリックでオフにする場合、AND NOT演算でビットをクリア | all_on == false |

### 計算ロジック

- 全ビットオン判定: `(*flags & flags_value) == flags_value`
- 部分オン判定: `(*flags & flags_value) != 0`
- ビットセット: `*flags |= flags_value`
- ビットクリア: `*flags &= ~flags_value`

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

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

## エラー処理

### エラーケース一覧

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

### リトライ仕様

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

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

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

## パフォーマンス要件

- Checkboxのラッパーであり、オーバーヘッドは最小限
- ビット演算は非常に高速

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

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

## 備考

- int、unsigned int、ImS64、ImU64の4つのオーバーロードが存在
- 内部でテンプレート関数CheckboxFlagsTを使用
- MixedValue表示は自動的に処理される

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | imgui.h | `imgui.h` | 637-638行目: CheckboxFlags関数のAPI宣言（int/unsigned intオーバーロード） |
| 1-2 | imgui_internal.h | `imgui_internal.h` | ImS64/ImU64オーバーロードの宣言 |

**読解のコツ**: CheckboxFlagsはビット演算の理解が必要。flags_valueは通常、1つのビットまたは複数ビットの組み合わせを表す。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | imgui_widgets.cpp | `imgui_widgets.cpp` | 1317-1320行目: CheckboxFlags(int*)の実装 |
| 2-2 | imgui_widgets.cpp | `imgui_widgets.cpp` | 1322-1325行目: CheckboxFlags(unsigned int*)の実装 |

**主要処理フロー**:
- 各オーバーロードはCheckboxFlagsT<T>テンプレート関数を呼び出す

#### Step 3: 内部実装を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | imgui_widgets.cpp | `imgui_widgets.cpp` | 1290-1315行目: CheckboxFlagsT関数の実装 |

**主要処理フロー**:
- **1293行目**: all_on判定（全ビットがオンか）
- **1294行目**: any_on判定（一部ビットがオンか）
- **1296-1300行目**: MixedValue設定とCheckbox呼び出し（部分オン時）
- **1302-1304行目**: 通常のCheckbox呼び出し（全オンまたは全オフ時）
- **1307-1312行目**: クリック時のフラグ更新（セットまたはクリア）

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

```
ImGui::CheckboxFlags(label, flags, flags_value)
    │
    └─ CheckboxFlagsT<T>(label, flags, flags_value)
           │
           ├─ フラグ状態確認
           │      ├─ all_on = (*flags & flags_value) == flags_value
           │      └─ any_on = (*flags & flags_value) != 0
           │
           ├─ [部分オン時] MixedValueフラグ設定
           │      └─ g.NextItemData.ItemFlags |= ImGuiItemFlags_MixedValue
           │
           ├─ Checkbox(label, &all_on)
           │      └─ 通常のCheckbox処理（描画含む）
           │
           └─ [クリック時] フラグ更新
                  ├─ [all_on] *flags |= flags_value
                  └─ [!all_on] *flags &= ~flags_value
```

### データフロー図

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

flags (int*等) ────────────> ビット状態確認 ─────────────────> all_on, any_on
                                │
flags_value (int等) ───────────────────────────────────────> ビット演算パラメータ
                                │
label (文字列) ────────────> Checkbox呼び出し ──────────────> pressed
                                │
                            [pressed時]
                            ビット演算 ─────────────────────> *flags (更新)
                                │
                            return pressed ─────────────────> bool (状態変更有無)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| imgui.h | `imgui.h` | ヘッダー | CheckboxFlags APIの宣言（int/unsigned int） |
| imgui_internal.h | `imgui_internal.h` | ヘッダー | CheckboxFlags APIの宣言（ImS64/ImU64）、CheckboxFlagsT |
| imgui_widgets.cpp | `imgui_widgets.cpp` | ソース | CheckboxFlags/CheckboxFlagsTの実装 |
