# 機能設計書 133-ColorButton

## 概要

本ドキュメントは、ImGuiライブラリにおけるカラーボタンウィジェット `ColorButton` の機能仕様を定義するものである。

### 本機能の処理概要

ColorButtonは、指定された色を矩形で表示するボタンウィジェットを作成する機能である。クリック時にtrueを返し、ホバー時にはツールチップで色の詳細を表示する。

**業務上の目的・背景**：GUIアプリケーションにおいて、現在選択されている色をプレビュー表示したり、色をクリックしてカラーピッカーを開くトリガーとして使用したりする場面が多い。ColorButtonは、色の視覚的な表示と、ボタンとしての操作性を両立したウィジェットを提供する。ColorEdit4やColorPicker4と組み合わせて使用されることが多い。

**機能の利用シーン**：スタイルエディタでの色プレビュー表示、カラーパレットでの色選択UI、色の履歴表示、ドラッグ&ドロップによる色の転送元として、またはマテリアルエディタでの色確認用ボタンなど。

**主要な処理内容**：
1. 矩形領域の計算とアイテムサイズの設定
2. ボタン動作（ホバー、クリック）の処理
3. 透明度対応のチェッカーボード背景描画（オプション）
4. 色の矩形描画
5. 枠線の描画（オプション）
6. ドラッグ&ドロップソースとしての機能
7. ホバー時のツールチップ表示

**関連システム・外部連携**：ドラッグ&ドロップペイロードとして `IMGUI_PAYLOAD_TYPE_COLOR_3F` または `IMGUI_PAYLOAD_TYPE_COLOR_4F` を使用。ColorEdit4、ColorPicker4と連携して使用される。

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 6 | Style Editor | 主画面 | スタイルエディタでのカラープレビュー |
| 23 | Widgets | 参照画面 | カラーエディタのデモ表示 |

## 機能種別

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

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| desc_id | const char* | Yes | 説明用ID（ツールチップ表示に使用、ラベルとしては表示されない） | NULL不可 |
| col | const ImVec4& | Yes | RGBA色値（0.0〜1.0） | 各要素は0.0〜1.0の範囲が推奨 |
| flags | ImGuiColorEditFlags | No | カラーエディタの動作オプション | デフォルトは0 |
| size | const ImVec2& | No | ボタンサイズ | (0,0)でデフォルトサイズ |

### 入力データソース

- ユーザーが指定する色値（ImVec4）
- マウス入力によるボタン操作

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 戻り値 | bool | ボタンがクリックされた場合true、それ以外false |

### 出力先

- 画面上へのウィジェット描画
- ドラッグ&ドロップペイロード（ドラッグ開始時）

## 処理フロー

### 処理シーケンス

```
1. ウィンドウスキップチェック
   └─ SkipItemsがtrueならfalse返却
2. ボタン領域の計算
   └─ サイズ引数または デフォルトサイズ（フレーム高さ）を使用
3. アイテムサイズの設定とアイテム追加
   └─ ItemSize、ItemAddの呼び出し
4. ボタン動作の処理
   └─ ButtonBehaviorで hovered、held、pressed を取得
5. フラグに基づく表示オプションの調整
   └─ NoAlpha、AlphaOpaque時の処理
6. HSV→RGB変換（必要時）
   └─ InputHSVフラグ時
7. 背景描画
   └─ 透明度対応のチェッカーボード、または単色
8. 枠線描画
   └─ NoBorderフラグ未設定時
9. ドラッグ&ドロップソース処理
   └─ NoDragDropフラグ未設定時
10. ツールチップ表示
    └─ NoTooltipフラグ未設定かつホバー時
11. pressed を返却
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{SkipItems?}
    B -->|Yes| C[return false]
    B -->|No| D[ボタン領域計算]
    D --> E[ItemSize, ItemAdd]
    E --> F{ItemAdd成功?}
    F -->|No| C
    F -->|Yes| G[ButtonBehavior]
    G --> H{InputHSV?}
    H -->|Yes| I[HSV→RGB変換]
    H -->|No| J[背景描画処理]
    I --> J
    J --> K{AlphaPreviewHalf?}
    K -->|Yes| L[半透明プレビュー描画]
    K -->|No| M[通常の色描画]
    L --> N[枠線描画]
    M --> N
    N --> O{NoDragDrop?}
    O -->|No| P[D&Dソース設定]
    O -->|Yes| Q{NoTooltip?}
    P --> Q
    Q -->|No| R[ツールチップ表示]
    Q -->|Yes| S[return pressed]
    R --> S
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-133-01 | サイズデフォルト | size引数が(0,0)の場合、フレーム高さを使用 | サイズ未指定時 |
| BR-133-02 | チェッカーボード | 透明度がある場合、チェッカーボード背景を表示 | AlphaNoBgフラグ未設定時 |
| BR-133-03 | ラベル非表示 | desc_idはボタン横には表示されない | 常時 |
| BR-133-04 | D&Dペイロード型 | NoAlphaフラグ時はCOLOR_3F、それ以外はCOLOR_4F | D&D開始時 |
| BR-133-05 | 枠線デフォルト表示 | NoBorderフラグ未設定時は枠線を表示 | 常時 |

### 計算ロジック

- ボタンサイズ：`(size.x == 0.0f ? default_size : size.x, size.y == 0.0f ? default_size : size.y)`
- グリッドステップ：`ImMin(size.x, size.y) / 2.99f`
- 角丸：`ImMin(g.Style.FrameRounding, grid_step * 0.5f)`

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

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | ウィンドウスキップ | window->SkipItemsがtrue | falseを返却して処理終了 |
| - | アイテム追加失敗 | ItemAddがfalse | falseを返却して処理終了 |

### リトライ仕様

リトライ処理は不要（即時応答型）

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

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

## パフォーマンス要件

- 毎フレーム呼び出されることを想定した軽量実装
- チェッカーボード描画はやや負荷が高い

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

特になし（ローカルUI操作のみ）

## 備考

- desc_idはツールチップとID生成に使用されるが、ボタン横には表示されない
- 透明度プレビュー時は半分が不透明、半分が透明の表示が可能（AlphaPreviewHalf）
- ColorEdit4のプレビュー部分としても内部的に使用される

---

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

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

### 推奨読解順序

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

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

**読解のコツ**: NoBorder、NoDragDrop、NoTooltipなどColorButton固有のフラグに注目。

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

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

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

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

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

**主要処理フロー**:
- **6392-6403行目**: ウィンドウ取得、ID生成、サイズ計算、アイテム追加
- **6405-6406行目**: ButtonBehaviorでボタン動作取得
- **6408-6414行目**: フラグ処理とHSV→RGB変換
- **6415-6442行目**: 背景と色の描画処理
- **6443-6450行目**: 枠線描画
- **6452-6464行目**: ドラッグ&ドロップソース処理
- **6466-6468行目**: ツールチップ表示

#### Step 4: ヘルパー関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | imgui_widgets.cpp | `imgui_widgets.cpp` | RenderColorRectWithAlphaCheckerboard |
| 4-2 | imgui_widgets.cpp | `imgui_widgets.cpp` | ColorTooltip |

**主要処理フロー**:
- チェッカーボード付き矩形の描画方法
- ツールチップでの色情報表示

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

```
ColorButton (imgui_widgets.cpp:6390)
    │
    ├─ GetCurrentWindow
    ├─ window->GetID
    ├─ GetFrameHeight
    ├─ ItemSize
    ├─ ItemAdd
    │
    ├─ ButtonBehavior
    │
    ├─ ColorConvertHSVtoRGB (InputHSV時)
    │
    ├─ RenderColorRectWithAlphaCheckerboard
    │      └─ AddRectFilled (複数回)
    │
    ├─ DrawList->AddRectFilled
    ├─ RenderNavCursor
    ├─ RenderFrameBorder
    ├─ DrawList->AddRect
    │
    ├─ BeginDragDropSource (D&D時)
    │      ├─ SetDragDropPayload
    │      ├─ ColorButton (再帰呼び出し)
    │      ├─ SameLine
    │      ├─ TextEx
    │      └─ EndDragDropSource
    │
    └─ ColorTooltip (ホバー時)
           └─ BeginTooltipEx / EndTooltip
```

### データフロー図

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

const ImVec4& col ───▶ HSV→RGB変換（必要時）
(RGBA)                     │
                           ▼
ImGuiColorEdit       背景描画処理
Flags flags ─────────▶ (チェッカーボード/単色)
                           │
                           ▼
const ImVec2& size ───▶ 色矩形描画
                           │
                           ▼
マウス入力 ──────────▶ ButtonBehavior ──────▶ bool pressed
                           │
                           ▼
                   D&Dペイロード設定 ──────▶ COLOR_3F/4F
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| imgui.h | `imgui.h` | ヘッダ | API宣言とフラグ定義 |
| imgui_widgets.cpp | `imgui_widgets.cpp` | ソース | ColorButtonの実装 |
| imgui_internal.h | `imgui_internal.h` | ヘッダ | 内部関数宣言 |
| imgui_draw.cpp | `imgui_draw.cpp` | ソース | 描画プリミティブ実装 |
