# 機能設計書 87-TextDisabled

## 概要

本ドキュメントは、Dear ImGuiライブラリにおけるTextDisabled関数の機能設計を定義する。TextDisabledは、無効化されたスタイル（薄いグレー）でフォーマット付きテキストを表示する機能である。

### 本機能の処理概要

TextDisabled関数は、現在のスタイルで定義されたImGuiCol_TextDisabled色を使用してテキストを描画する機能を提供する。内部的にはPushStyleColor/PopStyleColorでテキスト色を一時的に変更してText関数を呼び出すショートカット関数である。

**業務上の目的・背景**：GUIアプリケーションにおいて、現在利用できない機能や非アクティブな情報を視覚的に区別することは、ユーザビリティ向上に重要である。TextDisabledは、無効化されたメニュー項目の説明、条件を満たさない場合の注意書き、二次的な情報など、ユーザーが「現在操作できない」または「重要度が低い」と認識すべきテキストを表示するために使用される。

**機能の利用シーン**：
- 無効化された機能の説明テキストを表示する場合
- 条件を満たさない場合のヒントテキストを表示する場合
- 二次的・補助的な情報を目立たなく表示する場合
- ヘルプテキストや注釈を薄いグレーで表示する場合
- コメントやメタ情報を表示する場合

**主要な処理内容**：
1. グローバルスタイルからImGuiCol_TextDisabled色を取得
2. PushStyleColor(ImGuiCol_Text, style.Colors[ImGuiCol_TextDisabled])で色をプッシュ
3. TextV関数でフォーマット付きテキストを描画
4. PopStyleColor()で元の色に戻す

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

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | 全画面 | 補助機能 | 無効化テキストの表示 |

## 機能種別

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

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| fmt | const char* | Yes | printf形式のフォーマット文字列 | NULLチェックなし |
| ... | 可変長引数 | No | フォーマット引数 | フォーマット文字列に対応 |

### 入力データソース

- 呼び出し元コードからの直接入力
- ImGuiStyle::Colors[ImGuiCol_TextDisabled]（現在のテーマで定義された無効化テキスト色）

## 出力仕様

### 出力データ

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

### 出力先

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

## 処理フロー

### 処理シーケンス

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

TextDisabledV内部処理:
4. グローバルコンテキストの取得
   └─ ImGuiContext& g = *GImGui
5. スタイルカラーのプッシュ
   └─ PushStyleColor(ImGuiCol_Text, g.Style.Colors[ImGuiCol_TextDisabled])
6. TextV関数の呼び出し
   └─ フォーマット付きテキストの描画
7. スタイルカラーのポップ
   └─ PopStyleColor()
```

### フローチャート

```mermaid
flowchart TD
    A[TextDisabled開始] --> B[va_start]
    B --> C[TextDisabledV呼び出し]
    C --> D[GImGuiからコンテキスト取得]
    D --> E[PushStyleColor ImGuiCol_TextDisabled色]
    E --> F[TextV呼び出し]
    F --> G[PopStyleColor]
    G --> H[va_end]
    H --> I[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | スタイル依存 | 色は現在のスタイル（StyleColorsDark/Light/Classic）に依存 | 常時 |
| BR-02 | 一時的な色変更 | 指定された色はこのテキストにのみ適用される | 常時 |
| BR-03 | テーマ対応 | スタイルエディタで変更されたTextDisabled色が自動的に反映される | 常時 |

### 計算ロジック

特になし。スタイルから取得した色をそのまま使用する。

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

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

## エラー処理

### エラーケース一覧

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

### リトライ仕様

該当なし

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

該当なし

## パフォーマンス要件

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

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

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

## 備考

- PushStyleColor(ImGuiCol_Text, style.Colors[ImGuiCol_TextDisabled]) + Text(...) + PopStyleColor() のショートカット
- TextDisabledVはva_list版
- IM_FMTARGS(1)マクロによりコンパイラのフォーマット文字列チェックが有効
- スタイルを変更するとTextDisabledの色も自動的に変更される

---

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

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

### 推奨読解順序

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

スタイル色定義を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | imgui.h | `imgui.h` | ImGuiCol_TextDisabled列挙値 |
| 1-2 | imgui.h | `imgui.h` | ImGuiStyle構造体のColors配列 |

**読解のコツ**: ImGuiCol_TextDisabledはImGuiCol_列挙型の値であり、g.Style.Colors配列のインデックスとして使用される。

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | imgui.h | `imgui.h` | TextDisabled/TextDisabledV関数宣言（619-620行目） |
| 2-2 | imgui_widgets.cpp | `imgui_widgets.cpp` | TextDisabled/TextDisabledV関数実装（307-321行目） |

**主要処理フロー**:
1. **307-313行目**: TextDisabled関数 - va_startで可変長引数を初期化し、TextDisabledVを呼び出し、va_endで終了
2. **315-321行目**: TextDisabledV関数
   - **317行目**: ImGuiContext& g = *GImGui でグローバルコンテキストを取得
   - **318行目**: PushStyleColor(ImGuiCol_Text, g.Style.Colors[ImGuiCol_TextDisabled])で色をプッシュ
   - **319行目**: TextVでテキスト描画
   - **320行目**: PopStyleColor()で色をポップ

#### Step 3: スタイル色の定義を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | imgui.cpp | `imgui.cpp` | StyleColorsDark等での色定義 |

**主要処理フロー**:
- StyleColorsDark: ImGuiCol_TextDisabled = ImVec4(0.50f, 0.50f, 0.50f, 1.00f) 等

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

```
ImGui::TextDisabled(fmt, ...)
    │
    ├─ va_start(args, fmt)
    │
    └─ ImGui::TextDisabledV(fmt, args)
           │
           ├─ GImGui（グローバルコンテキスト）
           │
           ├─ g.Style.Colors[ImGuiCol_TextDisabled]
           │
           ├─ PushStyleColor(ImGuiCol_Text, ...)
           │
           ├─ TextV(fmt, args)
           │
           └─ PopStyleColor()
```

### データフロー図

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

fmt + ...   ───▶ スタイル色取得 ───▶ 色をプッシュ ───▶ TextV ───▶ 描画コマンド
                      │
                      └── g.Style.Colors[ImGuiCol_TextDisabled]
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| imgui.h | `imgui.h` | ヘッダー | TextDisabled/TextDisabledV関数の宣言（619-620行目）、ImGuiCol_列挙型 |
| imgui_widgets.cpp | `imgui_widgets.cpp` | ソース | TextDisabled/TextDisabledV関数の実装（307-321行目） |
| imgui.cpp | `imgui.cpp` | ソース | スタイル色定義（StyleColorsDark等） |
