# 画面設計書 21-MainPage（設定ナビゲーション）

## 概要

本ドキュメントは、Windows Terminal の設定画面全体のメインコンテナである MainPage（設定ナビゲーション）画面の設計を記述する。この画面は設定UIのルートとして機能し、左側のナビゲーションペインと右側のコンテンツフレームで構成される。

### 本画面の処理概要

**業務上の目的・背景**：Windows Terminal のユーザーが、アプリケーション全体の設定を視覚的に管理するためのエントリーポイントである。テキストベースの settings.json を直接編集する代わりに、GUI ベースで直感的に設定変更を行うことを可能にする。NavigationView パターンを採用しており、左側のナビゲーションから各設定カテゴリにアクセスできる。

**画面へのアクセス方法**：メインのターミナル画面（TerminalPage）から Ctrl+, ショートカットキーまたは設定メニューを通じてアクセスする。TerminalPage の `_HandleOpenSettings` アクションによって設定UIが起動される。

**主要な操作・処理内容**：
1. 左側ナビゲーションから各設定ページ（起動設定、操作設定、外観設定、レンダリング設定、互換性設定、配色一覧、アクション一覧、新規タブメニュー設定、拡張機能管理）への遷移
2. プロファイル一覧からの各プロファイル設定ページへの遷移
3. BreadcrumbBar によるパンくずナビゲーション（サブページ階層の表示と移動）
4. 設定の保存（Save ボタン）とリセット（Reset ボタン）
5. settings.json ファイルを直接開く（Open JSON ナビゲーションアイテム）
6. ポータブルモード時の情報表示

**画面遷移**：
- 遷移元：TerminalPage（Ctrl+, または設定メニュー）
- 遷移先：Launch、Interaction、GlobalAppearance、Rendering、Compatibility、ColorSchemes、Actions、NewTabMenu、Extensions、AddProfile、Profiles_Base、Profiles_Appearance、Profiles_Terminal、Profiles_Advanced、Profiles_Base_Orphaned
- 設定画面を閉じるとTerminalPageに戻る

**権限による表示制御**：特に権限による制御はないが、ポータブルモード（CascadiaSettings.IsPortableMode）の場合、画面下部にポータブルモードの情報メッセージが表示される。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 81 | 設定を開く | 主機能 | 設定画面のメインコンテナ。ナビゲーションとコンテンツフレームを管理 |
| 82 | 設定の読み込み・保存 | 主機能 | SaveButton/ResetButtonによる設定の保存・リセット操作 |
| 84 | 設定UI | 主機能 | NavigationViewによる各設定ページへの遷移管理 |

## 画面種別

ナビゲーション / コンテナ

## URL/ルーティング

UWP/WinUI アプリケーションのためURL/ルーティングは適用されない。NavigationView の ItemInvoked イベントと Frame.Navigate メソッドによるページ遷移を行う。各ナビゲーションアイテムには Tag プロパティ（例: "Launch_Nav", "Interaction_Nav" 等）が設定されており、これによって遷移先が決定される。

## 入出力項目

| 項目名 | 入出力 | データ型 | 説明 |
|--------|--------|----------|------|
| CascadiaSettings | 入力 | Model::CascadiaSettings | 設定画面全体で使用する設定データ（コンストラクタで受け取り、クローンを作成） |
| SettingsTarget | 出力（イベント） | Model::SettingsTarget | OpenJsonイベント経由でJSON設定ファイルの種別を通知 |
| Breadcrumbs | 出力（表示） | IObservableVector<IInspectable> | パンくずナビゲーションの項目リスト |

## 表示項目

| 表示領域 | 項目名 | 説明 |
|----------|--------|------|
| ナビゲーション | LaunchNavItem | 起動設定へのリンク（アイコン: E7B5） |
| ナビゲーション | InteractionNavItem | 操作設定へのリンク（アイコン: E7C9） |
| ナビゲーション | AppearanceNavItem | 外観設定へのリンク（アイコン: E771） |
| ナビゲーション | ColorSchemesNavItem | 配色一覧へのリンク（アイコン: E790） |
| ナビゲーション | RenderingNavItem | レンダリング設定へのリンク（アイコン: E7F8） |
| ナビゲーション | CompatibilityNavItem | 互換性設定へのリンク（アイコン: EC7A） |
| ナビゲーション | ActionsNavItem | アクション一覧へのリンク（アイコン: E765、InfoBadge付き） |
| ナビゲーション | NewTabMenuNavItem | 新規タブメニュー設定へのリンク（アイコン: E71D） |
| ナビゲーション | ExtensionsNavItem | 拡張機能管理へのリンク（アイコン: EA86） |
| ナビゲーション | Nav_Profiles（ヘッダー） | プロファイルセクションヘッダー |
| ナビゲーション | BaseLayerMenuItem | プロファイルデフォルト設定へのリンク（アイコン: E81E） |
| ナビゲーション | OpenJsonNavItem（フッター） | JSON設定ファイルを開くリンク（アイコン: E713） |
| ヘッダー | NavigationBreadcrumbBar | パンくずナビゲーション（最大幅1000px） |
| コンテンツ | contentFrame | 各設定ページを表示するFrame（DrillInNavigationTransitionInfoアニメーション付き） |
| フッター | SaveButton | 設定保存ボタン（AccentButtonStyle） |
| フッター | ResetButton | 設定リセットボタン |
| フッター | PortableModeNote | ポータブルモード情報テキスト（条件付き表示） |

## イベント仕様

### 1-SettingsNav_Loaded

NavigationView のロード完了時に発火する。初期表示として最初のナビゲーションアイテム（Launch）を選択状態にし、対応するページをcontentFrameにナビゲートする。プロファイル一覧の初期化（`_InitializeProfilesList`）もここで行われる。

### 2-SettingsNav_ItemInvoked

ナビゲーションアイテムがクリックされた時に発火する。クリックされたアイテムの Tag プロパティに基づいて、対応する設定ページを contentFrame にナビゲートする。Tag と遷移先の対応は以下の通り:
- "Launch_Nav" -> Launch ページ
- "Interaction_Nav" -> Interaction ページ
- "GlobalAppearance_Nav" -> GlobalAppearance ページ
- "ColorSchemes_Nav" -> ColorSchemes ページ
- "Rendering_Nav" -> Rendering ページ
- "Compatibility_Nav" -> Compatibility ページ
- "Actions_Nav" -> Actions ページ
- "NewTabMenu_Nav" -> NewTabMenu ページ
- "Extensions_Nav" -> Extensions ページ
- "GlobalProfile_Nav" -> Profiles_Base ページ（デフォルトプロファイル）
- "OpenJson_Nav" -> OpenJson イベントを発火

### 3-SaveButton_Click

設定保存ボタンのクリック時に発火する。変更された設定をクローンから元の設定オブジェクトに書き戻し、settings.json ファイルに永続化する。

### 4-ResetButton_Click

設定リセットボタンのクリック時に発火する。設定のクローンを再作成し、変更を破棄して元の設定に戻す。

### 5-BreadcrumbBar_ItemClicked

パンくずナビゲーションの項目がクリックされた時に発火する。クリックされたBreadcrumb項目のTagとSubPageに基づいて、対応するページに戻る遷移を行う。

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| SaveButton_Click | settings.json（ファイル） | UPDATE | CascadiaSettings クローンの内容を settings.json ファイルに書き出す |

### テーブル別更新項目詳細

本アプリケーションはデータベースを使用せず、settings.json ファイルを設定の永続化先として使用する。

#### settings.json

| 操作 | 項目 | 更新値・取得条件 | 備考 |
|-----|------|-----------------|------|
| UPDATE | 全設定項目 | 設定クローンの現在の値 | SaveButton_Click時にファイル全体を書き出し |

## メッセージ仕様

| 種別 | メッセージID | 表示条件 | 内容 |
|------|-------------|----------|------|
| 情報 | Settings_PortableModeNote | ポータブルモード時 | ポータブルモードで動作中であることを通知 |
| 警告 | Settings_UnsavedSettingsWarning | 未保存の変更がある場合 | 未保存の設定変更があることを警告（現在Collapsed） |

## 例外処理

- 設定ファイルの読み込みエラー: ShowLoadWarningsDialog イベントを通じて警告ダイアログを表示
- ページナビゲーション失敗: 遷移先ページのコンストラクタまたはOnNavigatedToで例外が発生した場合は、既存のページを維持

## 備考

- NavigationView の IsBackButtonVisible は "Collapsed" に設定されており、戻るボタンは表示されない。代わりに BreadcrumbBar でナビゲーション階層を管理する。
- テーマ対応: Dark / Light / HighContrast の3テーマに対応し、SettingsPageBackground カラーを切り替える。
- 設定変更はクローンベースで行われる。SaveButton を押すまで元の設定には反映されない。
- ActionsNavItem には InfoBadge が付与されており、未確認のアクション変更がある場合にバッジが表示される。

---

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

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

### 推奨読解順序

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

MainPage は CascadiaSettings を受け取り、そのクローンを作成して設定変更を管理する。Breadcrumb 構造と BreadcrumbSubPage 列挙型がナビゲーション階層を表現する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | MainPage.h | `src/cascadia/TerminalSettingsEditor/MainPage.h` | Breadcrumb 構造体（Tag, Label, SubPage プロパティ）と MainPage クラスのメンバ変数（_settingsSource, _settingsClone, _breadcrumbs）を理解する |
| 1-2 | MainPage.idl | `src/cascadia/TerminalSettingsEditor/MainPage.idl` | MainPage のパブリックインターフェース（Breadcrumbs, OpenJson イベント等）を確認する |

**読解のコツ**: WINRT_PROPERTY マクロはプロパティの getter/setter を自動生成する。til::typed_event はイベントの型定義に使われる。

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

MainPage のコンストラクタと SettingsNav_Loaded が初期化のエントリーポイントとなる。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | MainPage.cpp | `src/cascadia/TerminalSettingsEditor/MainPage.cpp` | コンストラクタ（行1-30付近）で CascadiaSettings のクローン作成と ViewModel の初期化を確認する |

**主要処理フロー**:
1. **コンストラクタ**: CascadiaSettings を受け取りクローンを作成、各 ViewModel を初期化
2. **SettingsNav_Loaded**: プロファイル一覧の初期化、初期ページへのナビゲーション
3. **SettingsNav_ItemInvoked**: Tag ベースのページルーティング
4. **SaveButton_Click / ResetButton_Click**: 設定の永続化 / リセット

#### Step 3: ナビゲーション処理を理解する

_Navigate メソッド群がページ遷移のコアロジックである。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | MainPage.cpp | `src/cascadia/TerminalSettingsEditor/MainPage.cpp` | _Navigate メソッドのオーバーロード群を確認する。Tag 文字列に基づく遷移、プロファイル遷移、NTMEntry 遷移、Extension 遷移の4パターンがある |

#### Step 4: XAML レイアウトを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | MainPage.xaml | `src/cascadia/TerminalSettingsEditor/MainPage.xaml` | NavigationView の構造、MenuItems（各ナビゲーションアイテム）、Grid レイアウト（ScrollViewer + contentFrame + フッター）を理解する |

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

```
MainPage (コンストラクタ)
    |
    +-- CascadiaSettings.Copy() (設定クローン作成)
    +-- ViewModel 初期化 (ColorSchemesPageVM, ActionsVM, NewTabMenuVM, ExtensionsVM)
    |
    +-- SettingsNav_Loaded
    |       |
    |       +-- _InitializeProfilesList (プロファイルナビゲーションアイテムの動的生成)
    |       +-- _Navigate (初期ページへの遷移)
    |
    +-- SettingsNav_ItemInvoked
    |       |
    |       +-- _PreNavigateHelper (遷移前処理)
    |       +-- _Navigate (Tag文字列ベース)
    |               |
    |               +-- contentFrame.Navigate (ページ遷移)
    |               +-- Breadcrumbs 更新
    |
    +-- SaveButton_Click
    |       |
    |       +-- _settingsClone.WriteSettingsToDisk()
    |
    +-- ResetButton_Click
            |
            +-- _settingsSource.Copy() (クローン再作成)
```

### データフロー図

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

CascadiaSettings --------> MainPage                 -----> contentFrame (各設定ページ表示)
(設定データ)                  |                               |
                              +-- Copy() でクローン作成        +-- BreadcrumbBar (ナビゲーション階層)
                              +-- ViewModel 群へ配布           |
                              |                               +-- SaveButton -> settings.json
NavigationViewItem --------> SettingsNav_ItemInvoked  -----> Frame.Navigate (ページ遷移)
(ユーザー操作)                 |
                              +-- Tag プロパティ解析
                              +-- _Navigate メソッド呼び出し
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| MainPage.xaml | `src/cascadia/TerminalSettingsEditor/MainPage.xaml` | テンプレート | UI レイアウト定義（NavigationView + Frame） |
| MainPage.h | `src/cascadia/TerminalSettingsEditor/MainPage.h` | ソース | クラス定義（Breadcrumb 構造体、メンバ変数） |
| MainPage.cpp | `src/cascadia/TerminalSettingsEditor/MainPage.cpp` | ソース | ナビゲーションロジック、設定保存/リセット処理 |
| MainPage.idl | `src/cascadia/TerminalSettingsEditor/MainPage.idl` | IDL | WinRT パブリックインターフェース定義 |
| CommonResources.xaml | `src/cascadia/TerminalSettingsEditor/CommonResources.xaml` | リソース | 共通スタイル・テンプレート定義 |
| ColorSchemesPageViewModel.idl | `src/cascadia/TerminalSettingsEditor/ColorSchemesPageViewModel.idl` | IDL | 配色管理ViewModel |
| ActionsViewModel.idl | `src/cascadia/TerminalSettingsEditor/ActionsViewModel.idl` | IDL | アクション管理ViewModel |
