# 画面設計書 19-ControlNoticeDialog（通知）

## 概要

本ドキュメントは、Windows Terminal の ControlNoticeDialog（通知）画面の設計仕様を記述する。ControlNoticeDialog は、ターミナルコントロールからの通知メッセージ（デバッグ、情報、警告、エラー）を表示する汎用ダイアログである。

### 本画面の処理概要

ControlNoticeDialog は、TermControl（ターミナル表示）から発生する各種通知メッセージをユーザーに表示するための汎用ダイアログである。通知レベル（Debug / Info / Warning / Error）に応じたタイトルと、具体的なメッセージ内容を表示する。

**業務上の目的・背景**：ターミナルコントロール内部で発生する重要なイベント（接続切断、レンダリングエラー、シェルプロセスの異常終了など）をユーザーに通知するために必要な画面である。エラーや警告をユーザーに適切に伝えることで、問題の認識と対処を促す。

**画面へのアクセス方法**：TermControl の NoticeRaised イベントが発火された際に、TerminalPage の `_ControlNoticeRaisedHandler` が呼び出され、通知レベルとメッセージに基づいてダイアログが表示される（TerminalPage.cpp 行3143-3189）。ユーザーが直接開く操作はない。

**主要な操作・処理内容**：
1. 通知メッセージの表示：通知レベルに応じたタイトル（Debug / Information / Warning / Error）とメッセージ本文を表示する
2. 確認（Primary ボタン）：「OK」ボタンでダイアログを閉じる

**画面遷移**：TermControl からの通知イベントでダイアログが自動表示される。OK ボタンで閉じて TerminalPage に戻る。

**権限による表示制御**：特になし。全ユーザーに対して通知が表示される。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 80 | 接続の再起動 | 補助機能 | 接続切断等のコントロール通知メッセージを表示 |

## 画面種別

ダイアログ（ContentDialog - インライン定義）

## URL/ルーティング

該当なし（TerminalPage.xaml 内にインライン定義される ContentDialog）

## 入出力項目

| 項目名 | 入出力 | 型 | 必須 | 説明 |
|--------|--------|-----|------|------|
| title | 入力 | hstring | Yes | 通知レベルに応じたタイトル文字列 |
| message | 入力 | hstring | Yes | 通知メッセージの本文 |

## 表示項目

| 項目名 | 型 | 説明 |
|--------|-----|------|
| Title | テキスト（動的） | 通知レベルに応じたタイトル（"Debug" / "Information" / "Warning" / "Error"） |
| NoticeMessage | Run（TextBlock内） | 通知メッセージの本文。テキスト選択可能、WrapWholeWords で折り返し表示 |
| PrimaryButtonText | ボタンラベル | "OK" |

## イベント仕様

### 1-通知イベントの受信（_ControlNoticeRaisedHandler）

TerminalPage::_ControlNoticeRaisedHandler（TerminalPage.cpp 行3143-3172）が TermControl の NoticeRaised イベントから呼び出される。UIスレッドに切り替え後、NoticeLevel に応じて以下のタイトルを設定する：
- **Debug**: "Debug"（リソースキー: NoticeDebug）
- **Info**: "Information"（リソースキー: NoticeInfo）
- **Warning**: "Warning"（リソースキー: NoticeWarning）
- **Error**: "Error"（リソースキー: NoticeError）

### 2-ダイアログ表示（_ShowControlNoticeDialog）

`_ShowControlNoticeDialog`（TerminalPage.cpp 行3174-3189）で以下の処理が行われる：
1. `FindName(L"ControlNoticeDialog")` でダイアログを遅延読み込み（行3179）
2. `ControlNoticeDialog().Title()` にタイトルを設定（行3181）
3. `NoticeMessage().Text()` にメッセージを設定（行3184）
4. `presenter.ShowDialog()` でダイアログを表示（行3187）

### 3-OK ボタン

ユーザーが「OK」ボタンをクリックするとダイアログが閉じる。戻り値の判定は行われない。

## データベース更新仕様

### 操作別データベース影響一覧

該当なし。本画面はデータベースを操作しない。

## メッセージ仕様

| メッセージID | 種別 | 表示条件 | メッセージ内容 |
|-------------|------|----------|---------------|
| NoticeDebug | タイトル | NoticeLevel::Debug | "Debug" |
| NoticeInfo | タイトル | NoticeLevel::Info | "Information" |
| NoticeWarning | タイトル | NoticeLevel::Warning | "Warning" |
| NoticeError | タイトル | NoticeLevel::Error | "Error" |
| ControlNoticeDialog.PrimaryButtonText | ボタンラベル | 常時 | "OK" |

## 例外処理

- DialogPresenter が存在しない場合：`_dialogPresenter.get()` の null チェックにより、ダイアログ表示がスキップされる（行3176）
- UIスレッドへの復帰失敗時：`weakThis.get()` の null チェックで早期リターン（行3148）

## 備考

- DefaultButton は Primary に設定されている（TerminalPage.xaml 行137）
- x:Load="False" により遅延読み込みされる（TerminalPage.xaml 行136）
- メッセージテキストは選択可能（IsTextSelectionEnabled="True"）でコンテキストメニューからコピー可能（TerminalPage.xaml 行138-144）
- タイトルとメッセージの両方が動的に設定される点が他の確認ダイアログと異なる
- NoticeLevel の switch 文に default は含まれるが、対応するリソース文字列は設定されない（将来の拡張に対応可能な構造）

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | TerminalPage.xaml | `src/cascadia/TerminalApp/TerminalPage.xaml` | ControlNoticeDialog の XAML 定義（行133-145）。TextBlock 内に Run 要素（NoticeMessage）を持つ構造を確認 |

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | TerminalPage.cpp | `src/cascadia/TerminalApp/TerminalPage.cpp` | `_ControlNoticeRaisedHandler`（行3143-3172）で NoticeLevel に応じたタイトル設定。`_ShowControlNoticeDialog`（行3174-3189）でダイアログのタイトル・メッセージ設定と表示 |

**主要処理フロー**:
1. **行3143**: `_ControlNoticeRaisedHandler` が NoticeRaised イベントから呼び出される
2. **行3147**: `wil::resume_foreground(Dispatcher())` でUIスレッドに切り替え
3. **行3154-3168**: NoticeLevel の switch 文でタイトルを選択
4. **行3170**: `_ShowControlNoticeDialog(title, message)` を呼び出す
5. **行3179**: `FindName` で遅延読み込み
6. **行3181-3184**: タイトルとメッセージを設定
7. **行3187**: `presenter.ShowDialog` で表示

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

```
TermControl::NoticeRaised イベント
    |
    +-- TerminalPage::_ControlNoticeRaisedHandler (TerminalPage.cpp:3143)
            |
            +-- wil::resume_foreground (UIスレッド復帰)
            |
            +-- NoticeLevel switch (タイトル選択)
            |       +-- Debug --> "Debug"
            |       +-- Info --> "Information"
            |       +-- Warning --> "Warning"
            |       +-- Error --> "Error"
            |
            +-- _ShowControlNoticeDialog (TerminalPage.cpp:3174)
                    |
                    +-- FindName("ControlNoticeDialog")
                    +-- Title 設定
                    +-- NoticeMessage.Text 設定
                    +-- DialogPresenter::ShowDialog
```

### データフロー図

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

TermControl                TerminalPage                        ControlNoticeDialog
  NoticeRaised         --> _ControlNoticeRaisedHandler     --> タイトル設定
    Level              --> NoticeLevel switch                  (Debug/Info/Warning/Error)
    Message            --> _ShowControlNoticeDialog        --> メッセージ設定
                            |                                  |
                            +-- FindName (遅延読み込み)     --> ダイアログ表示
                            +-- ShowDialog
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| TerminalPage.xaml | `src/cascadia/TerminalApp/TerminalPage.xaml` | ソース（XAML） | ControlNoticeDialog のインライン定義（行133-145） |
| TerminalPage.cpp | `src/cascadia/TerminalApp/TerminalPage.cpp` | ソース（実装） | _ControlNoticeRaisedHandler / _ShowControlNoticeDialog の実装 |
| Resources.resw | `src/cascadia/TerminalApp/Resources/en-US/Resources.resw` | リソース | 通知タイトル・ボタンテキストの文字列リソース（行687-700） |
