# 機能設計書 134-SetColorEditOptions

## 概要

本ドキュメントは、ImGuiライブラリにおけるカラーエディタのデフォルトオプション設定関数 `SetColorEditOptions` の機能仕様を定義するものである。

### 本機能の処理概要

SetColorEditOptionsは、ColorEdit4、ColorPicker4などのカラー関連ウィジェットのデフォルトオプションを初期化・設定する機能である。

**業務上の目的・背景**：アプリケーション全体で統一したカラーエディタの表示形式やピッカータイプを設定したい場合がある。例えば、全てのカラーエディタでHSV表示をデフォルトにしたり、特定のピッカースタイル（Hueホイール/Hueバー）を標準として使用したりする場合に、SetColorEditOptionsを使用することで、各ウィジェット呼び出し時に個別にフラグを指定する必要がなくなる。ユーザーは右クリックメニューから一部の設定を変更可能。

**機能の利用シーン**：アプリケーション起動時のグローバル設定初期化、設定画面での表示形式変更適用、プロジェクト固有のカラーエディタスタイル設定など。

**主要な処理内容**：
1. フラグのバリデーション（必須オプションの補完）
2. 各カテゴリ（Display、DataType、Picker、Input）で1つだけが選択されていることの確認
3. グローバルコンテキスト（g.ColorEditOptions）への設定保存

**関連システム・外部連携**：ColorEdit3/4、ColorPicker3/4、ColorButtonがこの設定を参照する。

**権限による制御**：特になし。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 6 | Style Editor | 主画面 | スタイルエディタでの設定が影響を受ける |
| 23 | Widgets | 参照画面 | カラーエディタのデモ表示 |

## 機能種別

設定管理 / グローバル状態変更

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| flags | ImGuiColorEditFlags | Yes | デフォルトとして設定するオプションフラグ | 各カテゴリで1つのオプションのみ |

### 入力データソース

- アプリケーションコードから渡されるフラグ値

## 出力仕様

### 出力データ

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

### 出力先

- グローバルコンテキスト（g.ColorEditOptions）

## 処理フロー

### 処理シーケンス

```
1. Displayマスクのチェック
   └─ 未設定ならデフォルト値を補完
2. DataTypeマスクのチェック
   └─ 未設定ならデフォルト値を補完
3. Pickerマスクのチェック
   └─ 未設定ならデフォルト値を補完
4. Inputマスクのチェック
   └─ 未設定ならデフォルト値を補完
5. 各マスクで1オプションのみ選択されていることを確認
   └─ IM_ASSERTでチェック
6. g.ColorEditOptionsに設定を保存
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{DisplayMask設定?}
    B -->|No| C[デフォルトを補完]
    B -->|Yes| D{DataTypeMask設定?}
    C --> D
    D -->|No| E[デフォルトを補完]
    D -->|Yes| F{PickerMask設定?}
    E --> F
    F -->|No| G[デフォルトを補完]
    F -->|Yes| H{InputMask設定?}
    G --> H
    H -->|No| I[デフォルトを補完]
    H -->|Yes| J[ASSERT: 各1オプションのみ]
    I --> J
    J --> K[g.ColorEditOptions = flags]
    K --> L[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-134-01 | 排他オプション | 各カテゴリで1つのオプションのみ選択可能 | 常時 |
| BR-134-02 | デフォルト補完 | 未設定カテゴリにはDefaultOptions_から補完 | カテゴリ未設定時 |
| BR-134-03 | グローバル影響 | 設定は全てのカラーウィジェットに影響 | 常時 |
| BR-134-04 | ユーザー上書き可 | 個別のウィジェット呼び出しでフラグ指定すると上書きされる | フラグ指定時 |

### 計算ロジック

- マスク適用：`(flags & ImGuiColorEditFlags_DisplayMask_) == 0`でチェック
- デフォルト補完：`flags |= ImGuiColorEditFlags_DefaultOptions_ & ImGuiColorEditFlags_DisplayMask_`
- 排他チェック：`ImIsPowerOfTwo(flags & Mask_)`で2の累乗かを確認

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

### 操作別データベース影響一覧

本機能はデータベース操作を行わない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | アサーション失敗 | 同カテゴリで複数オプション選択 | IM_ASSERTで停止（デバッグビルド） |

### リトライ仕様

リトライ処理は不要（即時設定型）

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

トランザクション管理は不要

## パフォーマンス要件

- 起動時に1回呼び出されることを想定
- 処理コストは無視できるレベル

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

特になし（ローカルUI設定のみ）

## 備考

- 通常はアプリケーション起動時に1回だけ呼び出す
- NoOptionsフラグを使用するとユーザーによる変更を禁止できる
- デフォルト設定は `ImGuiColorEditFlags_Uint8 | ImGuiColorEditFlags_DisplayRGB | ImGuiColorEditFlags_InputRGB | ImGuiColorEditFlags_PickerHueBar`

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | imgui.h | `imgui.h` | ImGuiColorEditFlags列挙型の定義（1871-1910行目） |
| 1-2 | imgui.h | `imgui.h` | DefaultOptions_の定義（1910行目） |

**読解のコツ**: DisplayMask_、DataTypeMask_、PickerMask_、InputMask_の各マスク定数に注目。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | imgui.h | `imgui.h` | SetColorEditOptionsの関数宣言（737行目） |

**主要処理フロー**:
1. **737行目**: 関数シグネチャの確認

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | imgui_widgets.cpp | `imgui_widgets.cpp` | SetColorEditOptionsの実装（6475-6491行目） |

**主要処理フロー**:
- **6477行目**: グローバルコンテキスト取得
- **6478-6479行目**: DisplayMaskの補完
- **6480-6481行目**: DataTypeMaskの補完
- **6482-6483行目**: PickerMaskの補完
- **6484-6485行目**: InputMaskの補完
- **6486-6489行目**: 各マスクで1オプションのみかをASSERT
- **6490行目**: g.ColorEditOptionsに設定保存

#### Step 4: 使用箇所を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | imgui_widgets.cpp | `imgui_widgets.cpp` | ColorPicker4でのオプション参照（6046-6053行目） |

**主要処理フロー**:
- **6047行目**: `g.ColorEditOptions`からピッカータイプを取得

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

```
SetColorEditOptions (imgui_widgets.cpp:6475)
    │
    └─ GImGui (グローバルコンテキスト)
           └─ ColorEditOptions (設定保存先)
                  │
                  └─ 参照される箇所
                         ├─ ColorEdit4
                         ├─ ColorPicker4
                         └─ ColorPickerOptionsPopup
```

### データフロー図

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

ImGuiColorEdit    ───▶ マスクチェック
Flags flags              │
                         ▼
                   デフォルト補完
                         │
                         ▼
                   排他チェック
                   (IM_ASSERT)
                         │
                         ▼
                   g.ColorEditOptions ──▶ グローバル設定
                                              │
                                              ▼
                                         ColorEdit4
                                         ColorPicker4
                                         で参照
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| imgui.h | `imgui.h` | ヘッダ | API宣言とフラグ定義 |
| imgui_widgets.cpp | `imgui_widgets.cpp` | ソース | SetColorEditOptionsの実装 |
| imgui_internal.h | `imgui_internal.h` | ヘッダ | ImGuiContext構造体（ColorEditOptions含む） |
