# 画面設計書 24-GlobalAppearance（外観設定）

## 概要

本ドキュメントは、Windows Terminal のグローバル外観設定画面（GlobalAppearance）の設計を記述する。テーマ、タブ表示、タイトルバー、通知領域、アニメーションなどのUI外観に関するグローバル設定を管理する画面である。

### 本画面の処理概要

**業務上の目的・背景**：ターミナルアプリケーション全体の視覚的な外観をカスタマイズするための設定画面である。テーマの選択、タブバーの表示制御、タイトルバーの構成、ウィンドウの常時最前面表示、通知領域アイコンの制御、アクリルエフェクトの設定など、ユーザーインターフェースの見た目や振る舞いを統合的に設定できる。

**画面へのアクセス方法**：MainPage（設定ナビゲーション）の左側ナビゲーションから「外観」項目をクリックすることでアクセスする。

**主要な操作・処理内容**：
1. テーマの選択（Dark/Light/System/カスタムテーマ）
2. 新しいタブの挿入位置の設定
3. タイトルバーにタブを表示する設定
4. タブの常時表示設定
5. フルスクリーン時のタブ表示設定
6. タブ行のアクリルエフェクト設定
7. タイトルバーにタイトルを表示する設定
8. 常に最前面表示の設定
9. タブ幅モードの設定
10. アニメーションの有効/無効設定（反転表示）
11. 通知アイコンの常時表示・通知領域への最小化設定
12. ウィンドウの自動非表示設定
13. 管理者シールド表示設定
14. 非フォーカス時アクリルエフェクト設定

**画面遷移**：
- 遷移元：MainPage（設定ナビゲーション）
- 遷移先：なし（MainPageのcontentFrame内で表示される設定ページ）

**権限による表示制御**：特に権限による制御はない。AlwaysShowTabs は ShowTabsInTitlebar の状態に連動して有効/無効が制御される。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 82 | 設定の読み込み・保存 | 主機能 | テーマ・フォントサイズ・背景透明度のグローバル設定を編集 |
| 84 | 設定UI | 主機能 | 外観設定のUI表示と編集 |
| 107 | テーマ管理 | 補助機能 | テーマの選択と適用 |

## 画面種別

編集（設定）

## URL/ルーティング

UWP/WinUI アプリケーションのためURL/ルーティングは適用されない。MainPage の contentFrame 内に Frame.Navigate で表示される。ナビゲーションパラメータとして GlobalAppearanceViewModel が渡される。

## 入出力項目

| 項目名 | 入出力 | データ型 | 説明 |
|--------|--------|----------|------|
| CurrentTheme | 入出力 | Theme | テーマ選択 |
| CurrentNewTabPosition | 入出力 | EnumEntry | 新しいタブの位置 |
| ShowTabsInTitlebar | 入出力 | Boolean | タイトルバーにタブ表示 |
| AlwaysShowTabs | 入出力 | Boolean | タブの常時表示 |
| ShowTabsFullscreen | 入出力 | Boolean | フルスクリーン時タブ表示 |
| UseAcrylicInTabRow | 入出力 | Boolean | タブ行アクリルエフェクト |
| ShowTitleInTitlebar | 入出力 | Boolean | タイトルバーにタイトル表示 |
| AlwaysOnTop | 入出力 | Boolean | 常に最前面表示 |
| CurrentTabWidthMode | 入出力 | EnumEntry | タブ幅モード |
| InvertedDisableAnimations | 入出力 | Boolean | アニメーション有効（反転表示） |
| AlwaysShowNotificationIcon | 入出力 | Boolean | 通知アイコン常時表示 |
| MinimizeToNotificationArea | 入出力 | Boolean | 通知領域への最小化 |
| AutoHideWindow | 入出力 | Boolean | ウィンドウ自動非表示 |
| ShowAdminShield | 入出力 | Boolean | 管理者シールド表示 |
| EnableUnfocusedAcrylic | 入出力 | Boolean | 非フォーカス時アクリル |

## 表示項目

| 表示領域 | 項目名 | コントロール種別 | 説明 |
|----------|--------|-----------------|------|
| 外観設定 | Globals_Theme | ComboBox | テーマ選択（ThemeNameConverterで表示名変換） |
| 外観設定 | Globals_NewTabPosition | ComboBox | 新しいタブの位置 |
| 外観設定 | Globals_ShowTitlebar | ToggleSwitch | タイトルバーにタブ表示（Toggledイベント付き） |
| 外観設定 | Globals_AlwaysShowTabs | ToggleSwitch | タブ常時表示（ShowTabsInTitlebar連動で有効制御） |
| 外観設定 | Globals_ShowTabsFullscreen | ToggleSwitch | フルスクリーン時タブ表示 |
| 外観設定 | Globals_AcrylicTabRow | ToggleSwitch | タブ行アクリル |
| 外観設定 | Globals_ShowTitleInTitlebar | ToggleSwitch | タイトル表示 |
| 外観設定 | Globals_AlwaysOnTop | ToggleSwitch | 最前面表示 |
| 外観設定 | Globals_TabWidthMode | ComboBox | タブ幅モード |
| 外観設定 | Globals_DisableAnimationsReversed | ToggleSwitch | アニメーション有効（UIDが"Reversed"） |
| 外観設定 | Globals_AlwaysShowNotificationIcon | ToggleSwitch | 通知アイコン常時表示 |
| 外観設定 | Globals_MinimizeToNotificationArea | ToggleSwitch | 通知領域最小化 |
| 外観設定 | Globals_AutoHideWindow | ToggleSwitch | 自動非表示 |
| 外観設定 | Globals_ShowAdminShield | ToggleSwitch | 管理者シールド |
| 外観設定 | Globals_EnableUnfocusedAcrylic | ToggleSwitch | 非フォーカス時アクリル |

## イベント仕様

### 1-OnNavigatedTo

MainPage からナビゲートされた時に発火する。ナビゲーションパラメータから GlobalAppearanceViewModel を取得する。テレメトリログとして "NavigatedToPage" イベント（PageId="globalAppearance"）を記録する。

### 2-ShowTitlebarToggled

ShowTabsInTitlebar の ToggleSwitch が切り替えられた時に発火する。ViewModel の ShowTitlebarToggled メソッドが呼び出され、関連する設定項目の状態を更新する。

### 3-各設定項目の変更

各設定項目は x:Bind の Mode=TwoWay で ViewModel と双方向バインドされている。

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 設定変更 | settings.json（ファイル） | UPDATE | MainPage の SaveButton 経由で全設定を一括保存 |

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

本画面自体は直接ファイルに書き込まない。MainPage の SaveButton 経由で永続化される。

## メッセージ仕様

特になし。

## 例外処理

特になし。全項目が ToggleSwitch または ComboBox であり、不正入力の可能性は低い。

## 備考

- DisableAnimations 設定は反転表示（InvertedDisableAnimations）されている。UIDが "Globals_DisableAnimationsReversed" となっているのは GH#9124 対応のため。
- AlwaysShowTabs は ShowTabsInTitlebar が false の場合のみ有効化される（InvertBoolean コンバーター使用）。
- テーマ選択の ComboBox では ThemeNameConverter 静的メソッドにより Theme オブジェクトの表示名が変換される。

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | GlobalAppearanceViewModel.idl | `src/cascadia/TerminalSettingsEditor/GlobalAppearanceViewModel.idl` | テーマ関連（ThemeList, CurrentTheme）、各 PERMANENT_OBSERVABLE_PROJECTED_SETTING、ShowTitlebarToggled メソッドを確認する |

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | GlobalAppearance.cpp | `src/cascadia/TerminalSettingsEditor/GlobalAppearance.cpp` | コンストラクタ（行19-22）と OnNavigatedTo（行24-35）を確認 |

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | GlobalAppearance.xaml | `src/cascadia/TerminalSettingsEditor/GlobalAppearance.xaml` | 単一 StackPanel 内の SettingContainer 群の構造を理解する |

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

```
MainPage._Navigate("GlobalAppearance_Nav")
    |
    +-- contentFrame.Navigate(typeof(GlobalAppearance), GlobalAppearanceViewModel)
            |
            +-- GlobalAppearance::OnNavigatedTo
            |       +-- ViewModel 取得
            |       +-- TraceLogging
            |
            +-- ShowTitlebarToggled (ToggleSwitch変更時)
                    +-- ViewModel.ShowTitlebarToggled()
```

### データフロー図

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

GlobalAppearanceViewModel --------> GlobalAppearance Page  -----> ToggleSwitch / ComboBox
(設定データ)                          |                             |
                                      +-- x:Bind TwoWay             +-- ViewModel プロパティ更新
                                                                     |
GlobalAppSettings -----------------> ViewModel              -----> settings.json (MainPage経由)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| GlobalAppearance.xaml | `src/cascadia/TerminalSettingsEditor/GlobalAppearance.xaml` | テンプレート | UI レイアウト定義 |
| GlobalAppearance.cpp | `src/cascadia/TerminalSettingsEditor/GlobalAppearance.cpp` | ソース | 初期化・ナビゲーション処理 |
| GlobalAppearanceViewModel.idl | `src/cascadia/TerminalSettingsEditor/GlobalAppearanceViewModel.idl` | IDL | ViewModel インターフェース定義 |
| GlobalAppearanceViewModel.h | `src/cascadia/TerminalSettingsEditor/GlobalAppearanceViewModel.h` | ソース | ViewModel クラス定義 |
| GlobalAppearanceViewModel.cpp | `src/cascadia/TerminalSettingsEditor/GlobalAppearanceViewModel.cpp` | ソース | ViewModel 実装 |
| CommonResources.xaml | `src/cascadia/TerminalSettingsEditor/CommonResources.xaml` | リソース | 共通スタイル定義 |
