# 通知設計書 29-ShowLoadWarningsDialog

## 概要

本ドキュメントは、Windows TerminalにおけるShowLoadWarningsDialogイベント通知の設計を記述する。設定ファイルの読み込み時に警告が発生した場合に、その警告メッセージをユーザーに表示するためのダイアログ表示をトリガーするイベントである。

### 本通知の処理概要

ShowLoadWarningsDialogは、設定ファイル（settings.json）の読み込み・保存時に検証警告が検出された場合に、Content Dialogを使用してユーザーに警告内容を一覧表示するイベント通知である。

**業務上の目的・背景**：Windows Terminalの設定ファイルは手動編集が可能なJSONファイルであり、無効な設定値や非推奨の設定が含まれる可能性がある。これらの問題はアプリケーションの動作に支障をきたす可能性があるため、ユーザーに警告を表示して修正を促す必要がある。致命的なエラーとは異なり、警告は設定の読み込み自体は成功しているが、一部の設定値に問題がある場合に発行される。

**通知の送信タイミング**：設定ファイルの初回ロード完了時（_OnLoaded内、結果がS_FALSEの場合）、設定の再読み込み時（UpdateSettingsHandler内、結果がS_FALSEの場合）、および設定UIの保存時（MainPage::SaveButton_Click内、WriteSettingsToDiskが警告を返した場合）に発火する。

**通知の受信者**：TerminalWindow::_ShowLoadWarningsDialog関数がイベントをハンドルし、モーダルなContent Dialogを表示する。

**通知内容の概要**：SettingsLoadWarningsの列挙値のリスト（IVectorView<SettingsLoadWarnings>）が送信される。各警告はリソースキーに対応し、ローカライズされた警告テキストに変換される。

**期待されるアクション**：ユーザーが警告ダイアログの内容を確認し、必要に応じて設定ファイルを修正する。ダイアログには「OK」ボタンのみがあり、警告を確認するだけのモーダルダイアログである。

## 通知種別

アプリ内通知（WinRT TypedEvent: `TypedEventHandler<Object, IVectorView<SettingsLoadWarnings>>`）/ Content Dialogで表示

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期（イベントハンドラの直接呼び出し） |
| 優先度 | 中 |
| リトライ | 無 |

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

WinRTのTypedEventメカニズムにより、イベントにサブスクライブしたハンドラに通知される。TerminalPage -> TerminalWindow のイベントチェーンで伝播する。

## 通知テンプレート

### ダイアログ表示

| 項目 | 内容 |
|-----|------|
| タイトル | "Settings Validation Errors"（SettingsValidateErrorTitle リソースキー） |
| 内容 | 各警告のローカライズ済みテキストを改行区切りで表示 |
| ボタン | Close（OK）ボタンのみ |
| テキスト選択 | 有効（IsTextSelectionEnabled = true） |
| テキスト折り返し | 有効（TextWrapping = Wrap） |

### 本文テンプレート

```
ShowLoadWarningsDialog.raise(*this, warnings)
// warnings: IVectorView<SettingsLoadWarnings>
```

### 添付ファイル

該当なし

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| warnings | 設定読み込み警告のリスト | SettingsLoadEventArgs.Warnings() / _settingsClone.Warnings() | Yes |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| 内部処理 | TerminalWindow::_OnLoaded | _initialLoadResult.Result() == S_FALSE | 初回ロード時に警告がある場合 |
| 内部処理 | TerminalWindow::UpdateSettingsHandler | args.Result() == S_FALSE | 設定再読み込み時に警告がある場合 |
| 画面操作 | MainPage::SaveButton_Click | WriteSettingsToDisk()がfalse返却 | 設定UIから保存時に警告がある場合 |
| 内部処理 | TerminalPage（設定UI経由） | 設定UIのShowLoadWarningsDialogイベント | 設定エディタ内の警告転送 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| 設定読み込みが完全に成功 | Result == S_OK の場合（警告なし） |
| 設定読み込みがエラー | Result がFAILED(hr)の場合（エラーダイアログが代わりに表示される） |
| 警告リストが空 | 警告が0件の場合（ただし通常S_FALSEが返る時は警告がある） |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[設定読み込み/保存完了] --> B{結果}
    B -->|S_OK| C[正常完了、ダイアログなし]
    B -->|S_FALSE| D[ShowLoadWarningsDialog発火]
    B -->|FAILED| E[エラーダイアログ表示]
    D --> F[TerminalWindow::_ShowLoadWarningsDialog]
    F --> G[各警告テキストのローカライズ]
    G --> H[TextBlockに警告テキストを追加]
    H --> I[ContentDialog作成]
    I --> J[ShowDialog呼び出し]
    J --> K[ユーザーがOKをクリック]
    K --> L[終了]
```

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

### 参照テーブル一覧

該当なし

### 更新テーブル一覧

該当なし

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| ダイアログ表示失敗 | 既に別のダイアログが表示中 | ShowDialog内で既存ダイアログとの排他制御が行われる |
| リソースキー未定義 | 未知の警告タイプ | _GetWarningTextが空文字列を返し、該当警告はスキップされる |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | 0 |
| リトライ間隔 | N/A |
| リトライ対象エラー | N/A |

## 配信設定

### レート制限

該当なし（設定読み込みのたびに最大1回表示）

### 配信時間帯

制限なし

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

- 表示される警告テキストはリソースファイルからのローカライズ済み文字列であり、ユーザー入力は含まれない
- ダイアログはモーダルであり、他の操作をブロックする
- 設定ファイルの内容自体はダイアログに表示されない

## 備考

- ShowLoadWarningsDialogは複数の発火元を持つが、全て同じ_ShowLoadWarningsDialog関数で処理される
- TerminalPage内の設定UI（MainPage）からの警告も、イベントチェーンを経由してTerminalWindow::_ShowLoadWarningsDialogで表示される
- ダイアログのコンテキストメニューにはTextMenuFlyoutが設定されており、コピー操作が可能
- settingsLoadWarningsLabels配列でSettingsLoadWarnings列挙値とリソースキーのマッピングが定義されている

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | TerminalPage.idl | `src/cascadia/TerminalApp/TerminalPage.idl` | ShowLoadWarningsDialogイベントの定義（行100） |
| 1-2 | TerminalWindow.idl | `src/cascadia/TerminalApp/TerminalWindow.idl` | SettingsChangedイベントとの関係 |

**読解のコツ**: ShowLoadWarningsDialogはSettingsChangedとは独立したイベントであり、警告表示に特化している。

#### Step 2: エントリーポイント（発火元）を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | TerminalWindow.cpp | `src/cascadia/TerminalApp/TerminalWindow.cpp` | _OnLoaded内の呼び出し（行533-536） |
| 2-2 | TerminalWindow.cpp | `src/cascadia/TerminalApp/TerminalWindow.cpp` | UpdateSettingsHandler内の呼び出し（行819-822） |
| 2-3 | MainPage.cpp | `src/cascadia/TerminalSettingsEditor/MainPage.cpp` | SaveButton_Click内の呼び出し（行728-731） |

**主要処理フロー**:
1. **TerminalWindow.cpp 行533-536**: 初回ロード時、`settingsLoadedResult == S_FALSE` の場合に `_ShowLoadWarningsDialog(nullptr, _initialLoadResult.Warnings())` を呼び出す
2. **TerminalWindow.cpp 行819-822**: 再読み込み時、`args.Result() == S_FALSE` の場合に同様に呼び出す
3. **MainPage.cpp 行728-731**: 設定保存時、`WriteSettingsToDisk()` が失敗した場合に `ShowLoadWarningsDialog.raise()` でイベント発火

#### Step 3: ダイアログ表示処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | TerminalWindow.cpp | `src/cascadia/TerminalApp/TerminalWindow.cpp` | _ShowLoadWarningsDialog関数（行474-504） |

**主要処理フロー**:
- **行476**: タイトルテキスト取得（"SettingsValidateErrorTitle"リソース）
- **行479-480**: TextBlock作成とコンテキストメニュー設定
- **行486-495**: 各警告テキストのローカライズと追加
- **行497-501**: ContentDialog作成とプロパティ設定
- **行503**: `ShowDialog(dialog)` でモーダルダイアログ表示

#### Step 4: 設定UIからの転送を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | TerminalPage.cpp | `src/cascadia/TerminalApp/TerminalPage.cpp` | 設定UIのShowLoadWarningsDialogイベント転送（行4343-4348） |

**主要処理フロー**:
- **行4343-4348**: MainPageのShowLoadWarningsDialogイベントを購読し、TerminalPageのShowLoadWarningsDialogイベントとして再発火する

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

```
[初回ロード/再読み込みパス]
TerminalWindow::_OnLoaded / UpdateSettingsHandler
    |
    +-- TerminalWindow::_ShowLoadWarningsDialog(warnings)
           |
           +-- _GetWarningText(warning) [各警告テキスト取得]
           +-- ContentDialog作成
           +-- ShowDialog()

[設定UIパス]
MainPage::SaveButton_Click
    |
    +-- ShowLoadWarningsDialog.raise() [MainPage]
           |
           +-- TerminalPage::ShowLoadWarningsDialog.raise() [転送]
                  |
                  +-- TerminalWindow::_ShowLoadWarningsDialog(warnings)
                         |
                         +-- (同上)
```

### データフロー図

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

SettingsLoadWarnings     _ShowLoadWarningsDialog       Content Dialog
(警告列挙値リスト)  ---> _GetWarningText()で        --> ユーザーに
                          ローカライズ                    警告テキスト表示
                          TextBlockに追加                  (モーダル)
                          ContentDialog表示
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| TerminalWindow.cpp | `src/cascadia/TerminalApp/TerminalWindow.cpp` | ソース（実装） | _ShowLoadWarningsDialog実装 |
| TerminalWindow.h | `src/cascadia/TerminalApp/TerminalWindow.h` | ソース（ヘッダ） | 関数宣言 |
| TerminalPage.cpp | `src/cascadia/TerminalApp/TerminalPage.cpp` | ソース（実装） | 設定UIからの警告転送 |
| TerminalPage.idl | `src/cascadia/TerminalApp/TerminalPage.idl` | IDL | ShowLoadWarningsDialogイベント定義 |
| TerminalPage.h | `src/cascadia/TerminalApp/TerminalPage.h` | ソース（ヘッダ） | イベント宣言 |
| MainPage.cpp | `src/cascadia/TerminalSettingsEditor/MainPage.cpp` | ソース（実装） | SaveButton_Clickからの発火 |
| MainPage.idl | `src/cascadia/TerminalSettingsEditor/MainPage.idl` | IDL | ShowLoadWarningsDialogイベント定義 |
| MainPage.h | `src/cascadia/TerminalSettingsEditor/MainPage.h` | ソース（ヘッダ） | イベント宣言 |
