# 通知設計書 40-TaskbarProgressChanged

## 概要

本ドキュメントは、Windows Terminal におけるタスクバープログレス変更通知（TaskbarProgressChanged）の設計仕様を記述する。TaskbarProgressChanged は、ターミナル上のプロセスがタスクバーの進捗表示を変更した際に発火するイベントであり、ファイルダウンロードやビルド進捗などの長時間処理の進捗をタスクバーに反映する。

### 本通知の処理概要

TaskbarProgressChanged は、Terminal コアが VT シーケンス（OSC 9;4 プログレスシーケンス）を受信した際に発火する通知機構であり、タスクバーのプログレスバー表示を更新するために使用される。

**業務上の目的・背景**：Windows Terminal で実行中の長時間処理（ファイルダウンロード、パッケージインストール、ビルド処理等）の進捗をタスクバーに反映することで、ユーザーはターミナルウィンドウを直接見ていなくても処理の進行状況を把握できる。これは Windows のタスクバープログレスバー API を活用した機能であり、VT シーケンス対応のシェルやツールから進捗情報が送信される。

**通知の送信タイミング**：Terminal コアが OSC 9;4 シーケンスを処理した際に、TaskbarProgressChangedCallback 経由で発火する。ControlCore の `_terminalTaskbarProgressChanged` メソッドで TaskbarProgressChanged イベントが raise される。

**通知の受信者**：ControlCore が TaskbarProgressChanged イベントを発火し、TermControl がバブル（BUBBLED_FORWARDED_TYPED_EVENT で SetTaskbarProgress として）し、TerminalPaneContent の _controlSetTaskbarProgress を経由して BasicPaneEvents.TaskbarProgressChanged が発火される。Tab がスロットル付きハンドラーで受信し、タスクバーの進捗状態を更新する。

**通知内容の概要**：引数は Object 型（null）。受信側は sender から ICoreState の TaskbarState() および TaskbarProgress() プロパティを照会する。

**期待されるアクション**：Tab は全ペインのタスクバー状態を集約（GetCombinedTaskbarState）し、TerminalPage 経由でウィンドウのタスクバープログレスバーを更新する。

## 通知種別

アプリ内通知（WinRT イベント + タスクバー表示）

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 非同期（Tab 側でスロットル + UIスレッドディスパッチ） |
| 優先度 | 低（UI装飾の更新） |
| リトライ | なし |

### 送信先決定ロジック

Terminal コアが VT シーケンスからタスクバー進捗データを受信した際に、TaskbarProgressChangedCallback で設定されたコールバックを経由して ControlCore に通知される。ControlCore は TaskbarProgressChanged イベントを raise し、TermControl、TerminalPaneContent、Tab の各層でイベントチェーンが構成される。

## 通知テンプレート

### メール通知の場合

該当なし（アプリ内イベント通知）

### 本文テンプレート

該当なし（イベント引数は null。受信側が TaskbarState() / TaskbarProgress() を照会）

### 添付ファイル

該当なし

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| （なし） | イベント引数は null。受信側は ICoreState.TaskbarState() と ICoreState.TaskbarProgress() を照会 | ControlCore / TermControl のプロパティ | - |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| VT シーケンス | OSC 9;4 プログレスシーケンス | Terminal コアが進捗データを処理した場合 | シェルやツールからの進捗情報送信 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| _pfnTaskbarProgressChanged が未設定 | コールバックが設定されていない場合はスキップ |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[シェル/ツールが OSC 9;4 シーケンスで進捗を送信] --> B[Terminal コアが VT シーケンスを処理]
    B --> C[_taskbarState / _taskbarProgress を更新]
    C --> D{_pfnTaskbarProgressChanged 設定済み?}
    D -->|No| E[スキップ]
    D -->|Yes| F[_pfnTaskbarProgressChanged コールバック呼び出し]
    F --> G[ControlCore._terminalTaskbarProgressChanged]
    G --> H[TaskbarProgressChanged.raise<br/>sender=*this, args=nullptr]
    H --> I[TermControl バブル処理<br/>SetTaskbarProgress イベント]
    I --> J[TerminalPaneContent._controlSetTaskbarProgress]
    J --> K[BasicPaneEvents.TaskbarProgressChanged.raise]
    K --> L[Tab スロットル付きハンドラー 200ms]
    L --> M[_UpdateProgressState]
    M --> N[GetCombinedTaskbarState]
    N --> O[Tab.TaskbarProgressChanged.raise]
    O --> P[TerminalPage がタスクバープログレスバーを更新]
```

## データベース参照・更新仕様

### 参照テーブル一覧

該当なし（インメモリイベント処理のみ）

### 更新テーブル一覧

該当なし

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| 不正な進捗値 | 0-100 の範囲外の値が送信された場合 | Terminal コア側でクランプ処理 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | なし |
| リトライ間隔 | - |
| リトライ対象エラー | - |

## 配信設定

### レート制限

| 項目 | 内容 |
|-----|------|
| 1分あたり上限 | Tab 側でスロットル制御（200ms、trailing） |
| 1日あたり上限 | 制限なし |

### 配信時間帯

制限なし

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

- タスクバー進捗情報はプロセス内のUI表示のみに使用される
- 不正な VT シーケンスによる誤った進捗表示の可能性があるが、セキュリティリスクは低い

## 備考

- TaskbarProgressChanged イベントは ControlCore.idl で「バックグラウンドスレッドから呼ばれるイベント」グループに属する（行196）
- Terminal コアでは _pfnTaskbarProgressChanged が null チェックされてから呼び出される（TerminalApi.cpp 行195-198）
- TermControl では BUBBLED_FORWARDED_TYPED_EVENT マクロで SetTaskbarProgress という名前でバブルされる（TermControl.h 行226）
- Tab のハンドラーでは ThrottledFunc を使用し、200ms のスロットル（trailing のみ）で頻繁な進捗更新を抑制する
- GetCombinedTaskbarState は全ペインの TaskbarState を集約し、優先度に基づいて最も重要な状態を選択する
- Tab 自身も TaskbarProgressChanged イベントを発火し（行1252）、TerminalPage がこれを受信してウィンドウレベルのタスクバー更新を行う

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | ControlCore.idl | `src/cascadia/TerminalControl/ControlCore.idl` | TaskbarProgressChanged イベント宣言（行196）。引数は Object, Object |
| 1-2 | ControlCore.h | `src/cascadia/TerminalControl/ControlCore.h` | til::typed_event<> TaskbarProgressChanged 宣言（行282） |

**読解のコツ**: このイベントは型付き EventArgs を持たない。TaskbarState / TaskbarProgress の値は ICoreState インターフェース経由で取得する。

#### Step 2: Terminal コアでの発火起点

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | TerminalApi.cpp | `src/cascadia/TerminalCore/TerminalApi.cpp` | SetTaskbarProgress 実装（行185-198）。_taskbarState / _taskbarProgress の更新後にコールバック呼び出し |
| 2-2 | Terminal.hpp | `src/cascadia/TerminalCore/Terminal.hpp` | TaskbarProgressChangedCallback 宣言（行228） |

**主要処理フロー**:
1. **行185-194**: _taskbarState と _taskbarProgress の更新ロジック
2. **行195-198**: `if (_pfnTaskbarProgressChanged) { _pfnTaskbarProgressChanged(); }` でコールバック呼び出し

#### Step 3: ControlCore でのイベント生成

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | ControlCore.cpp | `src/cascadia/TerminalControl/ControlCore.cpp` | コールバック設定（行121-122）と _terminalTaskbarProgressChanged 実装（行1645-1648） |

#### Step 4: イベントチェーン

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | TermControl.h | `src/cascadia/TerminalControl/TermControl.h` | BUBBLED_FORWARDED_TYPED_EVENT(SetTaskbarProgress, ...) マクロ（行226） |
| 4-2 | TerminalPaneContent.cpp | `src/cascadia/TerminalApp/TerminalPaneContent.cpp` | _controlSetTaskbarProgress（行172-175）。TaskbarProgressChanged.raise で再発火 |
| 4-3 | Tab.cpp | `src/cascadia/TerminalApp/Tab.cpp` | TaskbarProgressChanged ハンドラー登録（行1067-1084）。ThrottledFunc でスロットル制御。_UpdateProgressState で進捗集約 |

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

```
Terminal::SetTaskbarProgress(state, progress)
    |
    +-- _taskbarState / _taskbarProgress 更新
    +-- [if _pfnTaskbarProgressChanged]
           _pfnTaskbarProgressChanged()
                  |
                  +-- ControlCore::_terminalTaskbarProgressChanged()
                         |
                         +-- TaskbarProgressChanged.raise(*this, nullptr)
                                |
                                +-- TermControl::BUBBLED_FORWARDED_TYPED_EVENT (SetTaskbarProgress)
                                       |
                                       +-- TerminalPaneContent::_controlSetTaskbarProgress
                                       |       |
                                       |       +-- BasicPaneEvents.TaskbarProgressChanged.raise
                                       |              |
                                       |              +-- Tab (ThrottledFunc 200ms)
                                       |                     +-- _UpdateProgressState()
                                       |                     +-- GetCombinedTaskbarState()
                                       |                     +-- Tab.TaskbarProgressChanged.raise
                                       |                            |
                                       |                            +-- TerminalPage -> タスクバー更新
```

### データフロー図

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

VT シーケンス                    Terminal コア -> ControlCore         Tab -> TerminalPage
OSC 9;4 進捗シーケンス   -->  SetTaskbarProgress()           -->  _UpdateProgressState()
(state, progress)              _pfnTaskbarProgressChanged          GetCombinedTaskbarState()
                               TaskbarProgressChanged.raise         タスクバープログレスバー更新
                               バブル処理 -> スロットル
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| ControlCore.idl | `src/cascadia/TerminalControl/ControlCore.idl` | IDL定義 | TaskbarProgressChanged イベント宣言 |
| ControlCore.h | `src/cascadia/TerminalControl/ControlCore.h` | ソース | til::typed_event 宣言と TaskbarState/TaskbarProgress プロパティ |
| ControlCore.cpp | `src/cascadia/TerminalControl/ControlCore.cpp` | ソース | コールバック設定とイベント発火 |
| TerminalApi.cpp | `src/cascadia/TerminalCore/TerminalApi.cpp` | ソース | SetTaskbarProgress メソッド実装 |
| Terminal.hpp | `src/cascadia/TerminalCore/Terminal.hpp` | ソース | TaskbarProgressChangedCallback 宣言 |
| TermControl.idl | `src/cascadia/TerminalControl/TermControl.idl` | IDL定義 | SetTaskbarProgress イベント宣言 |
| TermControl.h | `src/cascadia/TerminalControl/TermControl.h` | ソース | BUBBLED_FORWARDED_TYPED_EVENT マクロ |
| BasicPaneEvents.h | `src/cascadia/TerminalApp/BasicPaneEvents.h` | ソース | BasicPaneEvents の TaskbarProgressChanged 定義 |
| TerminalPaneContent.cpp | `src/cascadia/TerminalApp/TerminalPaneContent.cpp` | ソース | _controlSetTaskbarProgress ハンドラー |
| Tab.cpp | `src/cascadia/TerminalApp/Tab.cpp` | ソース | TaskbarProgressChanged ハンドラー、_UpdateProgressState、GetCombinedTaskbarState |
