# 画面設計書 35-Profiles_Appearance（外観設定）

## 概要

本ドキュメントは、Windows Terminal の設定画面における「プロファイル外観設定」画面（Profiles_Appearance）の設計仕様を記述する。プロファイルの配色スキーム、フォント、背景画像、透明度、カーソル形状など外観に関する設定項目を編集するサブページである。

### 本画面の処理概要

**業務上の目的・背景**：ターミナルの視覚的なカスタマイズはユーザー体験の重要な要素である。本画面は、プロファイルごとの外観設定を包括的に編集するためのページであり、配色スキームの選択、フォント設定、背景画像、透明度、カーソル形状、パディング、スクロールバーの表示など多様な設定項目を提供する。また、リアルタイムプレビュー機能により、設定変更の結果を即座に確認できる。非フォーカス時の外観設定（Unfocused Appearance）も管理できる。

**画面へのアクセス方法**：Profiles_Base（基本設定）ページの「外観」ナビゲーターボタンをクリックして遷移する。MainPage のナビゲーションからプロファイル選択後、サブページとして遷移する。

**主要な操作・処理内容**：
1. リアルタイムターミナルプレビューによる外観確認
2. 外観設定（Appearances コントロール委譲）：配色スキーム、フォントファミリ・サイズ・ウェイト、カーソル形状・色、背景画像設定等
3. 透明度グループ：不透明度スライダー、アクリル効果の有効/無効
4. ウィンドウグループ：パディング（上下左右）、スクロールバー表示設定
5. 非フォーカス時外観の作成・編集・削除

**画面遷移**：Profiles_Base（基本設定）から遷移する。MainPage のパンくずリスト（Breadcrumb）に追加される。

**権限による表示制御**：IsBaseLayer（デフォルトプロファイル）の場合、免責事項テキストが表示される。EditableUnfocusedAppearance プロパティにより非フォーカス外観セクションの表示が制御される。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 82 | 設定の読み込み・保存 | 主機能 | プロファイルの配色・フォント・背景画像・透明度の設定 |
| 84 | 設定UI | 主機能 | プロファイル外観設定のUI表示 |
| 108 | カラースキーム管理 | 補助機能 | プロファイルの配色スキーム選択 |

## 画面種別

編集

## URL/ルーティング

設定画面内のNavigationViewによるページ遷移。Profiles_Base の ProfileSubPage.Appearance として遷移される。NavigateToProfileArgs（Profile + WindowRoot）がパラメータとして渡される。

## 入出力項目

### プレビュー

| No | 項目名 | 型 | 入力/出力 | 必須 | 説明 |
|----|--------|-----|----------|------|------|
| 1 | コントロールプレビュー | TermControl | 出力 | - | 400x180 のターミナルプレビュー。設定変更をリアルタイム反映 |

### 外観設定（Appearances コントロール委譲）

| No | 項目名 | 型 | 入力/出力 | 必須 | 説明 |
|----|--------|-----|----------|------|------|
| 2 | Appearances コントロール | local:Appearances | 入力/出力 | - | 配色・フォント・カーソル・背景画像等の外観設定をまとめたコントロール |

### 透明度

| No | 項目名 | 型 | 入力/出力 | 必須 | 説明 |
|----|--------|-----|----------|------|------|
| 3 | 不透明度（Profile_Opacity） | Slider + TextBlock | 入力 | - | 0-100% の不透明度設定 |
| 4 | アクリル使用（Profile_UseAcrylic） | ToggleSwitch | 入力 | - | アクリル効果の有効/無効 |

### ウィンドウ

| No | 項目名 | 型 | 入力/出力 | 必須 | 説明 |
|----|--------|-----|----------|------|------|
| 5 | パディング（Profile_Padding） | NumberBox x 4 | 入力 | - | 上下左右のパディング設定（0-100） |
| 6 | スクロールバー表示（Profile_ScrollbarVisibility） | ComboBox | 入力 | - | スクロールバーの表示モード選択 |

### 非フォーカス外観

| No | 項目名 | 型 | 入力/出力 | 必須 | 説明 |
|----|--------|-----|----------|------|------|
| 7 | 非フォーカス外観作成ボタン | Button | 入力 | - | 非フォーカス時の外観設定を作成。未作成時に表示 |
| 8 | 非フォーカス外観削除ボタン | Button（DeleteStyle） | 入力 | - | 非フォーカス時の外観設定を削除。作成済み時に表示 |
| 9 | 非フォーカス外観設定 | local:Appearances | 入力/出力 | - | 非フォーカス時の外観設定コントロール |

## 表示項目

| No | 項目名 | 表示形式 | 説明 |
|----|--------|----------|------|
| 1 | ターミナルプレビュー | TermControl（400x180） | 現在の設定を反映したリアルタイムプレビュー |
| 2 | BaseLayer 免責事項 | DisclaimerStyle テキスト | デフォルトプロファイル編集時の注意書き |
| 3 | 不透明度表示 | パーセント文字列 | スライダー横に現在の不透明度を表示 |
| 4 | パディング設定 UI | 3x3 グリッドの NumberBox | 視覚的なパディング設定（十字配置） |

## イベント仕様

### 1-プレビュー更新

ProfileViewModel または DefaultAppearance のプロパティが変更されると、_onProfilePropertyChanged が呼び出される。ThrottledFunc により100msのデバウンス後に TermSettings を再生成し、PreviewControl.UpdateControlSettings() でプレビューを更新する。

### 2-非フォーカス外観の作成

CreateUnfocusedAppearance_Click イベントハンドラにより、テレメトリを送信後、ProfileViewModel.CreateUnfocusedAppearance() を呼び出す。HasUnfocusedAppearance が true になり、非フォーカス外観の Appearances コントロールが表示される。

### 3-非フォーカス外観の削除

DeleteUnfocusedAppearance_Click イベントハンドラにより、ProfileViewModel.DeleteUnfocusedAppearance() を呼び出す。HasUnfocusedAppearance が false になり、非フォーカス外観セクションが非表示となる。

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

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

本画面はデータベースを使用しない。設定は settings.json ファイルに保存される。

| 操作（イベント） | 対象 | 操作種別 | 概要 |
|----------------|------|---------|------|
| 外観設定変更 | settings.json (profiles) | UPDATE | プロファイルの外観設定を更新 |
| 非フォーカス外観作成 | settings.json (profiles.unfocusedAppearance) | INSERT | 非フォーカス外観設定を追加 |
| 非フォーカス外観削除 | settings.json (profiles.unfocusedAppearance) | DELETE | 非フォーカス外観設定を削除 |

## メッセージ仕様

| No | メッセージID | 種別 | メッセージ内容 | 表示条件 |
|----|-------------|------|---------------|----------|
| 1 | Profile_BaseLayerDisclaimer | 情報 | デフォルトプロファイル編集の注意書き | IsBaseLayer が true の場合 |

## 例外処理

- プレビュー更新は ThrottledFunc（100ms デバウンス、trailing モード）で制御され、連続的な設定変更時の過負荷を防止する
- PreviewConnection がターミナルプレビュー用のダミー接続として使用される

## 備考

- Appearances コントロールは外観設定を包括的にまとめた再利用可能なカスタムコントロールであり、DefaultAppearance と UnfocusedAppearance の両方で使用される
- パディング設定は十字型のレイアウト（3x3 グリッド）で視覚的にわかりやすく配置されている
- 不透明度は PercentageToPercentageValue / PercentageToPercentageString コンバーターを使用してパーセント表示される
- PreviewConnection は PowerlineGlyphs の表示対応プロパティを持ち、フォント設定に応じてプレビュー内容を切り替える

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Profiles_Appearance.idl | `src/cascadia/TerminalSettingsEditor/Profiles_Appearance.idl` | ページクラスのインターフェース定義 |
| 1-2 | Profiles_Appearance.h | `src/cascadia/TerminalSettingsEditor/Profiles_Appearance.h` | ページの構造体定義。PreviewConnection とプレビュー更新ロジック |

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Profiles_Appearance.cpp | `src/cascadia/TerminalSettingsEditor/Profiles_Appearance.cpp` | 17-21行目: コンストラクタでPreviewConnection生成。23-59行目: OnNavigatedTo でプレビューコントロール初期化とテレメトリ送信 |

**主要処理フロー**:
1. **17-21行目**: PreviewConnection 生成
2. **29-37行目**: PreviewControl の初期化（TermSettings、カーソル表示、無効状態設定）
3. **43-46行目**: PropertyChanged イベントの購読
4. **88-107行目**: ThrottledFunc によるプレビュー更新

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Profiles_Appearance.xaml | `src/cascadia/TerminalSettingsEditor/Profiles_Appearance.xaml` | 53-76行目: プレビューエリア。78-80行目: Appearances コントロール。82-203行目: 透明度・ウィンドウ設定。205-248行目: 非フォーカス外観 |

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

```
Profiles_Base (基本設定ページ)
    |
    +-- Profiles_Appearance (外観設定サブページ)
            |
            +-- ProfileViewModel
            |       +-- DefaultAppearance (AppearanceViewModel)
            |       +-- UnfocusedAppearance (AppearanceViewModel)
            |       +-- TermSettings() (プレビュー用設定生成)
            |       +-- CreateUnfocusedAppearance()
            |       +-- DeleteUnfocusedAppearance()
            |
            +-- PreviewConnection (ダミー接続)
            |       +-- DisplayPowerlineGlyphs()
            |
            +-- TermControl (プレビュー)
            |       +-- UpdateControlSettings()
            |
            +-- Appearances (外観設定コントロール)
                    +-- Appearance (DefaultAppearance / UnfocusedAppearance)
                    +-- SourceProfile
                    +-- WindowRoot
```

### データフロー図

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

設定変更 -----------------> PropertyChanged ---------> ThrottledFunc (100ms debounce)
                                                            |
                                                    TermSettings() 再生成
                                                            |
                                                    UpdateControlSettings()
                                                            |
                                                    TermControl プレビュー更新

透明度スライダー ----------> PercentageToPercentageValue --> Profile.Opacity
パディング NumberBox ------> Profile.LeftPadding/TopPadding/RightPadding/BottomPadding
スクロールバー ComboBox --> Profile.CurrentScrollState
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Profiles_Appearance.xaml | `src/cascadia/TerminalSettingsEditor/Profiles_Appearance.xaml` | ソース | ページのXAMLレイアウト定義 |
| Profiles_Appearance.cpp | `src/cascadia/TerminalSettingsEditor/Profiles_Appearance.cpp` | ソース | ページのコードビハインド |
| Profiles_Appearance.h | `src/cascadia/TerminalSettingsEditor/Profiles_Appearance.h` | ソース | ヘッダー定義 |
| Profiles_Appearance.idl | `src/cascadia/TerminalSettingsEditor/Profiles_Appearance.idl` | ソース | WinRT インターフェース定義 |
| Appearances.xaml | `src/cascadia/TerminalSettingsEditor/Appearances.xaml` | ソース | 外観設定の共通コントロール |
| PreviewConnection.h | `src/cascadia/TerminalSettingsEditor/PreviewConnection.h` | ソース | プレビュー用ダミー接続 |
| ProfileViewModel.h | `src/cascadia/TerminalSettingsEditor/ProfileViewModel.h` | ソース | プロファイル ViewModel |
| CommonResources.xaml | `src/cascadia/TerminalSettingsEditor/CommonResources.xaml` | リソース | 共通スタイル・テンプレートリソース |
