# 機能設計書 182-TableSetBgColor

## 概要

本ドキュメントは、ImGuiライブラリのTableSetBgColor関数の機能設計を記述する。この関数はテーブルのセル、行、または列の背景色を設定するためのAPIである。

### 本機能の処理概要

TableSetBgColor関数は、テーブル内のセル、行（RowBg0/RowBg1）の背景色を動的に設定する機能を提供する。これにより、条件に応じた視覚的なハイライト表示が可能となる。

**業務上の目的・背景**：データテーブルにおいて、特定の条件に合致する行やセルを視覚的に強調表示することは、ユーザーの情報認識を助ける重要な機能である。例えば、エラー状態の行を赤色で表示したり、選択中のセルを異なる色でハイライトしたりする用途に使用される。

**機能の利用シーン**：
- 条件に応じた行のハイライト表示（警告、エラー、選択状態など）
- 交互行の背景色設定（zebra striping）のカスタマイズ
- 特定セルの強調表示
- ホバー状態やアクティブ状態の視覚的フィードバック

**主要な処理内容**：
1. 対象（セル/行）と色の検証
2. ターゲットタイプに応じた処理分岐
3. セル背景色の場合：RowCellDataに色情報を格納
4. 行背景色の場合：RowBgColor配列に色を格納
5. 描画時に設定された色を反映

**関連システム・外部連携**：
- BeginTable/EndTableとの連携（テーブルコンテキスト内でのみ使用可能）
- TableNextRow/TableNextColumnとの連携（現在位置の管理）
- スタイルシステム（ImGuiCol_TableRowBg等）との連携

**権限による制御**：本機能に権限制御はない。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 26 | Tables | 補助機能 | セル背景色の設定 |

## 機能種別

描画設定処理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| target | ImGuiTableBgTarget | Yes | 背景色の対象（CellBg/RowBg0/RowBg1） | ImGuiTableBgTarget_None以外 |
| color | ImU32 | Yes | 設定する色（RGBA形式） | IM_COL32_DISABLEの場合は0に変換 |
| column_n | int | No | 列インデックス（デフォルト: -1 = 現在の列） | CellBgの場合のみ有効 |

### ImGuiTableBgTarget列挙型

| 値 | 説明 |
|-----|------|
| ImGuiTableBgTarget_None | 無効 |
| ImGuiTableBgTarget_RowBg0 | 行の背景色0（主に偶数行） |
| ImGuiTableBgTarget_RowBg1 | 行の背景色1（主に奇数行） |
| ImGuiTableBgTarget_CellBg | セルの背景色 |

### 入力データソース

- 現在のImGuiコンテキスト（g.CurrentTable）
- テーブルの現在位置情報（CurrentColumn, RowPosY1/Y2）

## 出力仕様

### 出力データ

なし（void関数）

### 出力先

- セル背景色：table->RowCellData配列
- 行背景色：table->RowBgColor配列

## 処理フロー

### 処理シーケンス

```
1. コンテキストからCurrentTableを取得
   └─ テーブル外での呼び出しはアサーション失敗
2. ターゲットの検証
   └─ ImGuiTableBgTarget_Noneの場合はアサーション
3. 色の正規化
   └─ IM_COL32_DISABLEは0に変換
4. ターゲットタイプに応じた処理分岐
   ├─ CellBg: RowCellDataに格納
   └─ RowBg0/RowBg1: RowBgColorに格納
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{CurrentTable存在?}
    B -->|No| C[アサーション失敗]
    B -->|Yes| D{target != None?}
    D -->|No| C
    D -->|Yes| E{color == DISABLE?}
    E -->|Yes| F[color = 0]
    E -->|No| G{target == CellBg?}
    F --> G
    G -->|Yes| H[行がクリップ外?]
    H -->|Yes| I[return]
    H -->|No| J[RowCellDataに格納]
    G -->|No| K{target == RowBg0/1?}
    K -->|Yes| L[行がクリップ外?]
    L -->|Yes| I
    L -->|No| M[RowBgColorに格納]
    K -->|No| C
    J --> N[終了]
    M --> N
    I --> N
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-182-01 | クリップ領域チェック | 行が表示領域外の場合は処理をスキップ | RowPosY1 > InnerClipRect.Max.Y |
| BR-182-02 | 列インデックス補完 | column_nが-1の場合は現在の列を使用 | CellBg対象時 |
| BR-182-03 | 列可視性チェック | 非表示列へのセル背景色設定は無視 | CellBg対象時 |
| BR-182-04 | 色の無効化 | IM_COL32_DISABLEは0に変換される | 常時 |

### 計算ロジック

特になし

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

該当なし（ImGuiはUIライブラリであり、データベース操作は行わない）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| N/A | アサーション | テーブルコンテキスト外での呼び出し | IM_ASSERT_USER_ERROR_RET |
| N/A | アサーション | target == ImGuiTableBgTarget_None | IM_ASSERT |
| N/A | アサーション | RowBg対象でcolumn_n != -1 | IM_ASSERT |

### リトライ仕様

該当なし

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

該当なし

## パフォーマンス要件

- 大量のセルに対して呼び出しても描画パフォーマンスに大きな影響を与えないこと
- クリップ領域外の行は早期リターンで効率化

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

該当なし

## 備考

- 背景色は行の描画時（TableEndRow）に実際に描画される
- セル背景色は個別の描画コマンドとして処理される
- 行背景色はImGuiTableFlags_RowBgと組み合わせて使用可能
- 透過色を使用することで、下層の背景色と合成した表示が可能

---

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

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

### 推奨読解順序

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

まず、背景色を保持するデータ構造を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | imgui.h | `imgui.h` | ImGuiTableBgTarget列挙型の定義 |
| 1-2 | imgui_internal.h | `imgui_internal.h` | ImGuiTable構造体のRowBgColor、RowCellDataフィールド |

**読解のコツ**: RowBgColorは2要素の配列で、交互行の背景色に対応。RowCellDataはセル個別の背景色を保持する。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | imgui_tables.cpp | `imgui_tables.cpp` | TableSetBgColor関数（1818-1859行目） |

**主要処理フロー**:
1. **1820-1823行目**: コンテキスト取得とアサーション
2. **1825-1826行目**: 色の正規化（IM_COL32_DISABLE処理）
3. **1831-1844行目**: CellBg処理
4. **1846-1854行目**: RowBg0/RowBg1処理

#### Step 3: 描画処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | imgui_tables.cpp | `imgui_tables.cpp` | TableEndRow関数で背景色が実際に描画される |

**主要処理フロー**:
- RowBgColorの描画
- RowCellDataを使用したセル背景色の描画

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

```
ImGui::TableSetBgColor()
    │
    ├─ (検証: CurrentTable, target)
    │
    ├─ [CellBg] RowCellDataに格納
    │      └─ 可視性チェック
    │
    └─ [RowBg0/1] RowBgColorに格納
           └─ クリップチェック

その後、TableEndRow()で描画
    │
    ├─ RowBgColorの描画
    └─ RowCellDataの描画
```

### データフロー図

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

target, color ───▶ TableSetBgColor() ───▶ table->RowBgColor[]
column_n                    │               table->RowCellData[]
                            │
                            └─▶ (TableEndRow時に描画)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| imgui.h | `imgui.h` | ヘッダー | API宣言、ImGuiTableBgTarget列挙型定義 |
| imgui_tables.cpp | `imgui_tables.cpp` | ソース | TableSetBgColor実装 |
| imgui_internal.h | `imgui_internal.h` | 内部ヘッダー | ImGuiTable構造体、ImGuiTableCellData構造体定義 |
| imgui_demo.cpp | `imgui_demo.cpp` | デモ | 使用例（Background colorセクション） |
