# 機能設計書 86-TextColored

## 概要

本ドキュメントは、Dear ImGuiライブラリにおけるTextColored関数の機能設計を定義する。TextColoredは、指定された色でフォーマット付きテキストを表示する機能である。

### 本機能の処理概要

TextColored関数は、ImVec4で指定された色（RGBA）を使用してテキストを描画する機能を提供する。内部的にはPushStyleColor/PopStyleColorでテキスト色を一時的に変更してText関数を呼び出すショートカット関数である。

**業務上の目的・背景**：GUIアプリケーションにおいて、テキストを色分けして表示することは、情報の種類や重要度を視覚的に伝える効果的な手段である。エラーメッセージを赤で、成功メッセージを緑で表示するなど、ユーザビリティを向上させるために色付きテキストは頻繁に使用される。TextColoredは、このような色付きテキストを簡潔に表示するためのユーティリティ関数である。

**機能の利用シーン**：
- エラーメッセージを赤色で表示する場合
- 警告メッセージを黄色で表示する場合
- 成功/確認メッセージを緑色で表示する場合
- 重要な情報をハイライト表示する場合
- コンソールやログビューアで色分け表示する場合

**主要な処理内容**：
1. PushStyleColor(ImGuiCol_Text, col)でテキスト色をプッシュ
2. TextV関数でフォーマット付きテキストを描画
3. PopStyleColor()で元の色に戻す

**関連システム・外部連携**：ImGuiContext、ImGuiStyle（色スタック）、ImDrawList

**権限による制御**：なし。すべてのImGuiユーザーが利用可能。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 10 | Console | 補助機能 | 色付きログテキストの表示 |

## 機能種別

表示機能 / テキストウィジェット

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| col | const ImVec4& | Yes | テキストの色（RGBA、各成分0.0-1.0） | 範囲チェックなし |
| fmt | const char* | Yes | printf形式のフォーマット文字列 | NULLチェックなし |
| ... | 可変長引数 | No | フォーマット引数 | フォーマット文字列に対応 |

### 入力データソース

呼び出し元コードからの直接入力

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| (なし) | void | 戻り値なし。描画コマンドが生成される |

### 出力先

ImDrawList（ウィンドウの描画リスト）

## 処理フロー

### 処理シーケンス

```
1. 可変長引数の初期化
   └─ va_start(args, fmt)
2. TextColoredV関数の呼び出し
   └─ 実際の処理をTextColoredVに委譲
3. 可変長引数の終了
   └─ va_end(args)

TextColoredV内部処理:
4. スタイルカラーのプッシュ
   └─ PushStyleColor(ImGuiCol_Text, col)
5. TextV関数の呼び出し
   └─ フォーマット付きテキストの描画
6. スタイルカラーのポップ
   └─ PopStyleColor()
```

### フローチャート

```mermaid
flowchart TD
    A[TextColored開始] --> B[va_start]
    B --> C[TextColoredV呼び出し]
    C --> D[PushStyleColor テキスト色]
    D --> E[TextV呼び出し]
    E --> F[PopStyleColor]
    F --> G[va_end]
    G --> H[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | 色の一時変更 | 指定された色はこのテキストにのみ適用される | 常時 |
| BR-02 | RGBA形式 | 色はImVec4（R, G, B, A）で指定、各成分0.0-1.0 | 常時 |
| BR-03 | スタイルスタック | 内部でPushStyleColor/PopStyleColorを使用 | 常時 |

### 計算ロジック

特になし。色の変換や計算は行わず、指定された色をそのまま使用する。

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

該当なし（メモリ内操作のみ）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | - | 通常エラーは発生しない | - |

### リトライ仕様

該当なし

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

該当なし

## パフォーマンス要件

- PushStyleColor/PopStyleColorのオーバーヘッドあり（微小）
- Text関数と同等のフォーマット処理オーバーヘッド
- 1フレーム内で多数回呼び出し可能

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

- Text関数と同様、ユーザー入力をフォーマット文字列として直接使用しないこと

## 備考

- PushStyleColor(ImGuiCol_Text, col) + Text(...) + PopStyleColor() のショートカット
- TextColoredVはva_list版
- IM_FMTARGS(2)マクロによりコンパイラのフォーマット文字列チェックが有効

---

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

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

### 推奨読解順序

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

色の指定方法を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | imgui.h | `imgui.h` | ImVec4構造体（RGBA色表現） |
| 1-2 | imgui.h | `imgui.h` | ImGuiCol_Text定数 |

**読解のコツ**: ImVec4は(x, y, z, w)の4成分ベクトルで、色として使用する場合は(R, G, B, A)として解釈される。

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

TextColored関数の実装を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | imgui.h | `imgui.h` | TextColored/TextColoredV関数宣言（617-618行目） |
| 2-2 | imgui_widgets.cpp | `imgui_widgets.cpp` | TextColored/TextColoredV関数実装（292-305行目） |

**主要処理フロー**:
1. **292-298行目**: TextColored関数 - va_startで可変長引数を初期化し、TextColoredVを呼び出し、va_endで終了
2. **300-305行目**: TextColoredV関数
   - **302行目**: PushStyleColor(ImGuiCol_Text, col)で色をプッシュ
   - **303行目**: TextVでテキスト描画
   - **304行目**: PopStyleColor()で色をポップ

#### Step 3: スタイルカラースタックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | imgui.cpp | `imgui.cpp` | PushStyleColor/PopStyleColor関数 |

**主要処理フロー**:
- PushStyleColor: 現在の色を保存し、新しい色を設定
- PopStyleColor: 保存された色を復元

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

```
ImGui::TextColored(col, fmt, ...)
    │
    ├─ va_start(args, fmt)
    │
    └─ ImGui::TextColoredV(col, fmt, args)
           │
           ├─ PushStyleColor(ImGuiCol_Text, col)
           │
           ├─ TextV(fmt, args)
           │      │
           │      └─ TextEx() → RenderTextWrapped()
           │
           └─ PopStyleColor()
```

### データフロー図

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

col + fmt + ... ───▶ 色をプッシュ ───▶ TextV ───▶ 色をポップ ───▶ 描画コマンド
                          │
                          └── ImGuiCol_Text スタック
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| imgui.h | `imgui.h` | ヘッダー | TextColored/TextColoredV関数の宣言（617-618行目） |
| imgui_widgets.cpp | `imgui_widgets.cpp` | ソース | TextColored/TextColoredV関数の実装（292-305行目） |
| imgui.cpp | `imgui.cpp` | ソース | PushStyleColor/PopStyleColor関数 |
