# 機能設計書 13-タブ色の設定

## 概要

本ドキュメントは、Windows Terminalにおけるタブに任意の色を設定する機能（SetTabColor アクション）の設計を記述する。

### 本機能の処理概要

タブの背景色をプログラム的に設定またはリセットする機能である。SetTabColorアクションを通じて、指定された色をタブのランタイムカラーとして適用する。色が指定されない場合は、カスタムカラーをリセットしてデフォルトの色に戻す。

**業務上の目的・背景**：複数のタブを使い分ける際に、タブに色を付けることで視覚的に素早く識別できるようにする。例えば、本番環境は赤、開発環境は緑といった色分けにより、誤操作を防止できる。

**機能の利用シーン**：キーバインドやコマンドパレットからSetTabColorアクションを実行して、タブに特定の色を設定する場面で使用される。シェルスクリプトやプロファイル設定から自動的にタブ色を設定する場合にも利用可能。

**主要な処理内容**：
1. SetTabColorアクションの受信とパラメータ（TabColor）の取得
2. 対象タブの特定（sender指定またはフォーカス中のタブ）
3. 色が指定されている場合はSetRuntimeTabColorによるタブ色の設定
4. 色が未指定の場合はResetRuntimeTabColorによるタブ色のリセット
5. _RecalculateAndApplyTabColor による色の再計算と適用

**関連システム・外部連携**：外部連携なし。

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | TerminalPage（メイン画面） | 主画面 | _HandleSetTabColorによりタブに色を設定 |
| 12 | ColorPickupFlyout（カラー選択） | 参照画面 | カラーピッカーからタブの色を選択・設定 |

## 機能種別

UI操作 / プロパティ更新

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| TabColor | Windows.Foundation.IReference<Windows.UI.Color> | No | タブに設定する色。未指定の場合はカスタム色をリセット | なし |

### 入力データソース

キーバインド、コマンドパレット、またはプログラム的なアクション実行によりSetTabColorArgsとして渡される。

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| タブ背景色 | Windows.UI.Color | 更新後のタブ背景色 |
| タブカラーインジケーター | Windows.UI.Color | タブステータスの色インジケーター |

### 出力先

タブヘッダーUI（TabViewItem の背景色）

## 処理フロー

### 処理シーケンス

```
1. _HandleSetTabColor が呼び出される
   └─ ActionEventArgs から SetTabColorArgs を取得
2. SetTabColorArgs から TabColor を取得
   └─ IReference<Color> として保持
3. 対象タブを特定
   └─ _senderOrFocusedTab(sender) でタブを取得
4. 色の有無で分岐
   ├─ 色あり → activeTab->SetRuntimeTabColor(tabColor.Value())
   │   ├─ _runtimeTabColor に色を設定
   │   ├─ _RecalculateAndApplyTabColor() で色を適用
   │   └─ _tabStatus.TabColorIndicator(color) でインジケーター更新
   └─ 色なし → activeTab->ResetRuntimeTabColor()
       ├─ _runtimeTabColor をリセット
       ├─ _RecalculateAndApplyTabColor() で色を再計算
       └─ TabColorIndicator を透明色に設定
5. args.Handled(true) を設定
```

### フローチャート

```mermaid
flowchart TD
    A[SetTabColor アクション受信] --> B[SetTabColorArgs 取得]
    B --> C{TabColor 指定あり?}
    C -->|Yes| D[SetRuntimeTabColor: 色を設定]
    C -->|No| E[ResetRuntimeTabColor: 色をリセット]
    D --> F[_RecalculateAndApplyTabColor]
    E --> F
    F --> G[TabColorIndicator 更新]
    G --> H[Handled = true]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-13-01 | 色指定時の設定 | TabColor が指定された場合、ランタイムタブ色として設定する | TabColor が IReference で値を持つ場合 |
| BR-13-02 | 色未指定時のリセット | TabColor が未指定の場合、ランタイムタブ色をリセットしてデフォルト色に戻す | TabColor が null の場合 |
| BR-13-03 | 色の優先順位 | ランタイムタブ色はテーマ色やコントロール背景色よりも優先される | ランタイムタブ色が設定されている場合 |
| BR-13-04 | インジケーター連動 | タブ色の設定時にTabColorIndicatorも同時に更新される | 常時 |

### 計算ロジック

_RecalculateAndApplyTabColor メソッドにて、ランタイム色、テーマ色、コントロール背景色の優先順位に基づいてタブの最終色を算出する。

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

データベース操作なし。タブ色はメモリ上の_runtimeTabColorプロパティとして保持される。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| なし | タブ未取得 | _senderOrFocusedTabがnullptrを返した場合 | 処理をスキップし、args.Handled(true)のみ設定 |

### リトライ仕様

リトライ不要。

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

トランザクション管理なし。

## パフォーマンス要件

即座にUI更新が行われること。

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

特になし。

## 備考

- タブ色の設定はセッション間で永続化されない
- No.14「タブ色ピッカーを開く」機能と連携して、GUIからの色選択も可能
- プロファイル設定のtabColorプロパティで起動時のデフォルト色を設定可能

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | ActionArgs.idl | `src/cascadia/TerminalSettingsModel/ActionArgs.idl` | **305-309行目**: SetTabColorArgs の定義。TabColor プロパティ（IReference<Color>型）を持つ |

**読解のコツ**: `Windows.Foundation.IReference<T>` はnullable値型のラッパー。null の場合は色未指定を意味する。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | AppActionHandlers.cpp | `src/cascadia/TerminalApp/AppActionHandlers.cpp` | **682-704行目**: _HandleSetTabColor の実装。色の有無で SetRuntimeTabColor / ResetRuntimeTabColor を呼び分ける |

**主要処理フロー**:
1. **685行目**: IReference<Color> tabColor を宣言
2. **687-690行目**: SetTabColorArgs から TabColor を取得
3. **692行目**: _senderOrFocusedTab で対象タブを特定
4. **694-697行目**: tabColor がある場合、SetRuntimeTabColor を呼び出し
5. **698-701行目**: tabColor がない場合、ResetRuntimeTabColor を呼び出し

#### Step 3: Tab クラスの色管理処理

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Tab.cpp | `src/cascadia/TerminalApp/Tab.cpp` | **1876-1900行目**: SetRuntimeTabColor / ResetRuntimeTabColor の実装 |

**主要処理フロー**:
- **1876-1883行目**: SetRuntimeTabColor - _runtimeTabColor に色を設定し、_RecalculateAndApplyTabColor と TabColorIndicator を更新
- **1893-1900行目**: ResetRuntimeTabColor - _runtimeTabColor をリセットし、色を再計算

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

```
TerminalPage::_HandleSetTabColor (AppActionHandlers.cpp:682)
    |
    +-- SetTabColorArgs::TabColor() で色取得
    |
    +-- _senderOrFocusedTab(sender) でタブ特定
    |
    +-- Tab::SetRuntimeTabColor(color) (Tab.cpp:1876)
    |       +-- _runtimeTabColor.emplace(color)
    |       +-- _RecalculateAndApplyTabColor()
    |       +-- _tabStatus.TabColorIndicator(color)
    |
    +-- Tab::ResetRuntimeTabColor() (Tab.cpp:1893)
            +-- _runtimeTabColor.reset()
            +-- _RecalculateAndApplyTabColor()
            +-- _tabStatus.TabColorIndicator(Transparent)
```

### データフロー図

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

SetTabColorArgs      TerminalPage                     TabViewItem
(TabColor: Color) -> ::_HandleSetTabColor() -------> 背景色更新
                         |                           TabColorIndicator
                         v
                     Tab::SetRuntimeTabColor()
                     / ResetRuntimeTabColor()
                         |
                         v
                     _RecalculateAndApplyTabColor()
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| AppActionHandlers.cpp | `src/cascadia/TerminalApp/AppActionHandlers.cpp` | ソース | _HandleSetTabColor の実装 |
| Tab.cpp | `src/cascadia/TerminalApp/Tab.cpp` | ソース | SetRuntimeTabColor / ResetRuntimeTabColor の実装 |
| Tab.h | `src/cascadia/TerminalApp/Tab.h` | ヘッダー | Tab クラスの宣言 |
| TerminalPage.h | `src/cascadia/TerminalApp/TerminalPage.h` | ヘッダー | _HandleSetTabColor の宣言 |
| ActionArgs.idl | `src/cascadia/TerminalSettingsModel/ActionArgs.idl` | IDL | SetTabColorArgs の型定義 |
