# 機能設計書 55-フォントサイズの調整

## 概要

本ドキュメントは、Windows Terminal における「フォントサイズの調整」機能の設計を記述する。AdjustFontSize アクションにより、ターミナルのフォントサイズを指定したデルタ値で拡大・縮小する機能である。

### 本機能の処理概要

**業務上の目的・背景**：ターミナル画面の可読性を向上させるために、ユーザーがリアルタイムでフォントサイズを変更できるようにする。プレゼンテーション時のフォント拡大や、多くの情報を一度に表示するためのフォント縮小など、状況に応じた柔軟なサイズ調整を可能にする。Ctrl+マウスホイールによる直感的な操作にも対応する。

**機能の利用シーン**：ユーザーがターミナルの文字が小さすぎる/大きすぎると感じた場合に、キーバインド（通常 Ctrl+= / Ctrl+-）やマウスホイール操作でフォントサイズを段階的に調整する。

**主要な処理内容**：
1. ユーザーが AdjustFontSize アクションを実行（キーバインド/マウスホイール/コマンドパレット経由）
2. ActionArgs から AdjustFontSizeArgs を取得し、Delta 値を読み取る
3. _ApplyToActiveControls で全アクティブコントロールに処理を適用
4. ControlCore::AdjustFontSize で現在のフォントサイズに Delta を加算
5. フォントサイズの下限チェック（最小 1.0f）を適用
6. フォント情報を更新し、レンダリングサイズを再計算

**関連システム・外部連携**：DirectX ベースのレンダリングエンジン（Atlas）がフォントサイズ変更を反映する。プロファイル設定の FontSize 値は変更せず、ランタイムのフォントサイズのみを変更する。

**権限による制御**：特になし。すべてのユーザーが利用可能。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | TerminalPage（メイン画面） | 主画面 | _HandleAdjustFontSizeによりフォントサイズを拡大/縮小 |
| 6 | TermControl（ターミナル表示） | 主画面 | AdjustFontSizeによりフォントサイズを変更 |

## 機能種別

外観設定操作 / ランタイム設定変更

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| Delta | Single (float) | Yes | フォントサイズの増減量。正の値で拡大、負の値で縮小 | 結果が 1.0f 未満にならないよう下限チェック |

### 入力データソース

キーバインド設定、マウスホイール操作、またはコマンドパレットからの AdjustFontSize アクション。

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| Handled | bool | フォントサイズの変更が成功したかどうか |
| フォントサイズ | float | 変更後のフォントサイズ |

### 出力先

ターミナルコントロールのフォントが変更サイズで再描画される。ControlCore 内部の _desiredFont と _actualFont が更新される。

## 処理フロー

### 処理シーケンス

```
1. TerminalPage::_HandleAdjustFontSize がアクションイベントを受信
   └─ ActionArgs から AdjustFontSizeArgs を取得（Delta 値）
2. _ApplyToActiveControls で control.AdjustFontSize(delta) を呼び出し
3. ControlCore::AdjustFontSize(fontSizeDelta) が実行される
   └─ ターミナルの書き込みロックを取得（LockForWriting）
4. _setFontSizeUnderLock が呼び出される
   ├─ 新しいフォントサイズ = 現在サイズ + delta
   ├─ 最小値チェック: max(newSize, 1.0f)
   ├─ _desiredFont を新サイズで再構築
   ├─ _actualFont を新サイズで再構築
   ├─ BuiltinGlyphs、ColorGlyphs、CellSize の設定を適用
   └─ _updateFont() でフォントを更新
5. フォントサイズが実際に変更された場合
   └─ _refreshSizeUnderLock() でレイアウトを再計算
```

### フローチャート

```mermaid
flowchart TD
    A[AdjustFontSize アクション受信] --> B[AdjustFontSizeArgs から Delta 取得]
    B --> C[_ApplyToActiveControls]
    C --> D[ControlCore::AdjustFontSize]
    D --> E[LockForWriting 取得]
    E --> F[新サイズ = 現在サイズ + Delta]
    F --> G[max で最小値 1.0f を保証]
    G --> H[_desiredFont, _actualFont を再構築]
    H --> I[_updateFont でフォント更新]
    I --> J{サイズが変更された?}
    J -->|Yes| K[_refreshSizeUnderLock でレイアウト再計算]
    J -->|No| L[終了]
    K --> L
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-55-1 | 最小フォントサイズ | フォントサイズは 1.0f 未満にならない | 常時 |
| BR-55-2 | ランタイム変更 | プロファイル設定の FontSize は変更せず、ランタイムのフォントサイズのみ変更 | 常時 |
| BR-55-3 | 即時反映 | フォントサイズ変更は即座にレンダリングに反映される | 常時 |

### 計算ロジック

- `newSize = max(currentFontSize + delta, 1.0f)`
- フォントサイズ変更の判定: `before != after`（_actualFont の GetSize() を比較）

## データベース操作仕様

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

本機能はデータベース操作を行わない。ランタイムのフォント設定のみを変更する。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| なし | サイズ変更失敗 | フォントサイズが変更前と同じ場合 | _refreshSizeUnderLock をスキップ |
| なし | ActionArgs 取得失敗 | AdjustFontSizeArgs へのキャストが失敗 | 処理をスキップ |

### リトライ仕様

リトライ処理は不要。

## トランザクション仕様

ターミナルの書き込みロック（LockForWriting）を取得して排他制御を行う。

## パフォーマンス要件

フォントサイズ変更時にレンダリングの再計算が必要。ただし、_refreshSizeUnderLock は前後のサイズが変わらない場合はスキップされる最適化が施されている。

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

特になし。

## 備考

- AdjustFontSize はランタイム変更のみ。永続化されない。設定値に戻すには ResetFontSize（No.56）を使用する。
- Ctrl+マウスホイールでの操作時は ControlInteractivity.cpp が AdjustFontSize を呼び出す経路もある。

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | ActionArgs.idl | `src/cascadia/TerminalSettingsModel/ActionArgs.idl` | AdjustFontSizeArgs の定義（Delta プロパティ、Single 型） |
| 1-2 | ControlCore.h | `src/cascadia/TerminalControl/ControlCore.h` | AdjustFontSize, _setFontSizeUnderLock, _desiredFont, _actualFont の宣言 |

**読解のコツ**: `Single` は WinRT の float 型に対応する。`_desiredFont` はユーザーが望むフォント設定、`_actualFont` はレンダリングエンジンが実際に使用するフォント情報。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | AppActionHandlers.cpp | `src/cascadia/TerminalApp/AppActionHandlers.cpp` | _HandleAdjustFontSize メソッド（559-568行目） |

**主要処理フロー**:
1. **559-568行目**: AdjustFontSizeArgs から Delta を取得し、control.AdjustFontSize(delta) を呼び出す
2. **567行目**: _ApplyToActiveControls の戻り値で Handled を設定

#### Step 3: ControlCore のフォントサイズ変更処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | ControlCore.cpp | `src/cascadia/TerminalControl/ControlCore.cpp` | AdjustFontSize メソッド（1166-1174行目）と _setFontSizeUnderLock（1120-1146行目） |

**主要処理フロー**:
- **1166-1174行目**: LockForWriting 取得、_setFontSizeUnderLock に現在サイズ+delta を渡し、変更ありなら _refreshSizeUnderLock
- **1120-1146行目**: フォントサイズの下限チェック、_desiredFont/_actualFont の再構築、_updateFont 呼び出し

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

```
TerminalPage::_HandleAdjustFontSize (AppActionHandlers.cpp:559)
    │
    ├─ ActionArgs.try_as<AdjustFontSizeArgs>() → Delta 取得
    │
    └─ _ApplyToActiveControls
           │
           └─ ControlCore::AdjustFontSize (ControlCore.cpp:1166)
                  │
                  ├─ LockForWriting
                  │
                  └─ _setFontSizeUnderLock(currentSize + delta)
                         │
                         ├─ max(newSize, 1.0f) → 下限チェック
                         ├─ _desiredFont 再構築
                         ├─ _actualFont 再構築
                         ├─ _updateFont()
                         │
                         └─ (変更あり) _refreshSizeUnderLock()
```

### データフロー図

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

AdjustFontSizeArgs   ───▶ TerminalPage                ───▶ フォント再描画
(Delta: float)             ::_HandleAdjustFontSize
                                │
                                ▼
                           ControlCore::AdjustFontSize
                                │
                                ├─ 現在フォントサイズ + Delta
                                │
                                ▼
                           _setFontSizeUnderLock
                                │
                                ├─ _desiredFont 更新
                                ├─ _actualFont 更新
                                ▼
                           _updateFont() ─────────────▶ レンダリング更新
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| AppActionHandlers.cpp | `src/cascadia/TerminalApp/AppActionHandlers.cpp` | ソース | _HandleAdjustFontSize アクションハンドラー |
| ControlCore.cpp | `src/cascadia/TerminalControl/ControlCore.cpp` | ソース | AdjustFontSize, _setFontSizeUnderLock の実装 |
| ControlCore.h | `src/cascadia/TerminalControl/ControlCore.h` | ヘッダー | AdjustFontSize メソッド宣言 |
| ControlCore.idl | `src/cascadia/TerminalControl/ControlCore.idl` | IDL | AdjustFontSize の IDL 定義 |
| ControlInteractivity.cpp | `src/cascadia/TerminalControl/ControlInteractivity.cpp` | ソース | マウスホイールからの AdjustFontSize 呼び出し |
| ActionArgs.idl | `src/cascadia/TerminalSettingsModel/ActionArgs.idl` | IDL | AdjustFontSizeArgs 定義 |
| AllShortcutActions.h | `src/cascadia/TerminalSettingsModel/AllShortcutActions.h` | ヘッダー | AdjustFontSize アクション登録 |
| TermControl.cpp | `src/cascadia/TerminalControl/TermControl.cpp` | ソース | TermControl の AdjustFontSize ラッパー |
