# 機能設計書 61-フルスクリーン切替

## 概要

本ドキュメントは、Windows Terminalにおけるフルスクリーン切替機能（ToggleFullscreen）の設計を記述する。

### 本機能の処理概要

ウィンドウの全画面表示を切り替える機能である。フルスクリーン状態ではタブバーとタイトルバーが非表示になり、ターミナルコンテンツが画面全体を占有する。

**業務上の目的・背景**：ターミナル作業に集中する際、画面のスペースを最大限に活用したいというニーズに応えるための機能である。特にサーバー管理やログ解析など、広い表示領域が必要な作業で有用である。

**機能の利用シーン**：ユーザーがキーバインド（デフォルトではAlt+Enter、F11）を押下した際に、ウィンドウの全画面表示/通常表示を切り替える。プレゼンテーション時やデモ時にも利用される。

**主要な処理内容**：
1. `_HandleToggleFullscreen`ハンドラがアクションイベントを受け取る
2. `ToggleFullscreen()`メソッドが現在の状態を反転させる
3. `SetFullscreen()`メソッドが内部状態`_isFullscreen`を更新し、タブビューの表示を更新する
4. `FullscreenChanged`イベントを発火して、ウィンドウホストに通知する
5. ウィンドウホスト（IslandWindow/AppHost）がウィンドウスタイルを変更して全画面表示を実現する

**関連システム・外部連携**：ウィンドウマネージャー（Win32 API）との連携により、ウィンドウスタイルの変更とサイズ調整を行う。`SetFullScreen`アクションによる明示的な状態設定にも対応する。

**権限による制御**：特別な権限制御は行わない。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | TerminalPage（メイン画面） | 主画面 | _HandleToggleFullscreenにより全画面表示を切替 |
| 4 | TitlebarControl（タイトルバー） | 参照画面 | フルスクリーン時にタイトルバーが非表示になる |

## 機能種別

状態切替操作（トグル）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| なし（ToggleFullscreen） | - | - | トグル動作のため入力パラメータなし | - |

なお、関連する`SetFullScreen`アクションは以下のパラメータを持つ。

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| IsFullScreen | bool | No | フルスクリーン状態を明示的に設定 | - |

### 入力データソース

キーバインドアクション（ShortcutAction::ToggleFullscreen）またはコマンドパレットからのアクション呼び出し。

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| _isFullscreen | bool | フルスクリーン状態フラグ |
| FullscreenChanged イベント | イベント | ウィンドウホストへの通知 |

### 出力先

ウィンドウ状態（タブバー・タイトルバーの表示/非表示、ウィンドウスタイルの変更）に反映される。

## 処理フロー

### 処理シーケンス

```
1. ユーザーがキーバインドまたはコマンドパレットからToggleFullscreenアクションを実行
   └─ ActionDispatcherがイベントを発火
2. _HandleToggleFullscreen が呼び出される
   └─ TerminalPage::ToggleFullscreen() を呼び出す
3. ToggleFullscreen() が SetFullscreen(!_isFullscreen) を呼び出す
   └─ 現在の状態を反転して SetFullscreen に渡す
4. SetFullscreen() が内部状態を更新
   └─ _isFullscreen を新しい値に設定
5. _UpdateTabView() によりタブビューの表示を更新
   └─ フルスクリーン時はタブバーを非表示にする（ShowTabsFullscreenが有効でない限り）
6. FullscreenChanged イベントを発火
   └─ AppHost/IslandWindow がウィンドウスタイルを変更
```

### フローチャート

```mermaid
flowchart TD
    A[ToggleFullscreenアクション受信] --> B[_HandleToggleFullscreen]
    B --> C[ToggleFullscreen]
    C --> D[SetFullscreen !_isFullscreen]
    D --> E{_isFullscreen == newFullscreen?}
    E -->|Yes| F[何もしない - return]
    E -->|No| G[_isFullscreen = newFullscreen]
    G --> H[_UpdateTabView]
    H --> I[FullscreenChanged.raise]
    I --> J[ウィンドウスタイル変更]
    J --> K[終了]
    F --> K
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-61-01 | トグル動作 | ToggleFullscreenは現在の状態を反転させる | 常に適用 |
| BR-61-02 | 冪等性 | SetFullscreenは現在と同じ状態を指定した場合は何もしない | SetFullscreenアクション使用時 |
| BR-61-03 | タブバー表示制御 | フルスクリーン時はShowTabsFullscreen設定に従いタブバーの表示/非表示を制御する | フルスクリーンモード中 |
| BR-61-04 | レイアウト保存 | ウィンドウレイアウト保存時にフルスクリーン状態がLaunchModeに含まれる | PersistState実行時 |

### 計算ロジック

特別な計算ロジックはない。

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

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

データベース操作は行わない。ただし、ウィンドウレイアウト保存時にApplicationStateにフルスクリーン状態が永続化される。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| なし | - | 本機能で直接的なエラー処理は行わない | - |

### リトライ仕様

リトライ処理は不要。

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

トランザクション管理は不要。UIスレッド上での同期的な状態変更のみ。

## パフォーマンス要件

ユーザー操作に対して即座に応答すること。タブビューの更新とウィンドウスタイル変更はUIスレッド上で同期的に実行される。

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

特別なセキュリティ考慮事項はない。

## 備考

- `SetFullScreen`アクションを使用することで、明示的にフルスクリーンのオン/オフを設定可能。
- フルスクリーン状態はウィンドウレイアウト保存（PersistState）時に`LaunchMode::FullscreenMode`として永続化される。
- フォーカスモード（機能No.60）と組み合わせて使用可能。

---

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

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

### 推奨読解順序

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

まず、フルスクリーンに関連する状態変数とイベントを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | TerminalPage.h | `src/cascadia/TerminalApp/TerminalPage.h` | `_isFullscreen`フラグ、`FullscreenChanged`イベント、`ToggleFullscreen()`/`SetFullscreen()`メソッド宣言を確認 |

**読解のコツ**: `til::typed_event`は軽量なイベントマクロで、`raise`で発火し、外部ハンドラが`{}`で購読する。

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

アクションハンドラがどのように呼び出されるかを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | AppActionHandlers.cpp | `src/cascadia/TerminalApp/AppActionHandlers.cpp` | `_HandleToggleFullscreen`（617-622行目）と`_HandleSetFullScreen`（624-632行目）の2つのハンドラを確認 |

**主要処理フロー**:
1. **617-622行目**: `_HandleToggleFullscreen` - パラメータなしで`ToggleFullscreen()`を呼び出す
2. **624-632行目**: `_HandleSetFullScreen` - `SetFullScreenArgs`からbool値を取得して`SetFullscreen()`を呼び出す

#### Step 3: コア処理を理解する

状態変更とイベント発火の実装を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | TerminalPage.cpp | `src/cascadia/TerminalApp/TerminalPage.cpp` | `ToggleFullscreen()`（4063-4066行目）と`SetFullscreen()`（4283-4292行目）の実装 |

**主要処理フロー**:
- **4063-4066行目**: `ToggleFullscreen()` - `SetFullscreen(!_isFullscreen)`を呼び出し、状態を反転させる
- **4283-4292行目**: `SetFullscreen()` - 冪等チェック後、`_isFullscreen`を更新し、`_UpdateTabView()`と`FullscreenChanged.raise()`を実行
- **4233-4236行目**: `Fullscreen()` - 現在のフルスクリーン状態を返すプロパティアクセサ

#### Step 4: ウィンドウレイアウト保存時の動作

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | TerminalPage.cpp | `src/cascadia/TerminalApp/TerminalPage.cpp` | `PersistState()`（2282行目付近）で`LaunchMode::FullscreenMode`として保存される |

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

```
ActionDispatcher (ShortcutAction::ToggleFullscreen)
    |
    +-- TerminalPage::_HandleToggleFullscreen()        [AppActionHandlers.cpp:617]
    |       |
    |       +-- TerminalPage::ToggleFullscreen()       [TerminalPage.cpp:4063]
    |               |
    |               +-- TerminalPage::SetFullscreen()  [TerminalPage.cpp:4283]
    |                       |
    |                       +-- _UpdateTabView()       (タブバー表示制御)
    |                       +-- FullscreenChanged.raise()
    |                               |
    |                               +-- TerminalWindow (イベント中継)
    |                                       |
    |                                       +-- AppHost / IslandWindow (ウィンドウスタイル変更)
    |
    +-- TerminalPage::_HandleSetFullScreen()            [AppActionHandlers.cpp:624]
            |
            +-- TerminalPage::SetFullscreen(bool)      [TerminalPage.cpp:4283]
```

### データフロー図

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

キーバインド/              _HandleToggleFullscreen()       _isFullscreen 更新
コマンドパレット -------->  ToggleFullscreen() ---------->  _UpdateTabView()
                           SetFullscreen()                 FullscreenChanged イベント
                                                           ウィンドウスタイル変更
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| AppActionHandlers.cpp | `src/cascadia/TerminalApp/AppActionHandlers.cpp` | ソース | アクションハンドラの実装（_HandleToggleFullscreen / _HandleSetFullScreen） |
| TerminalPage.h | `src/cascadia/TerminalApp/TerminalPage.h` | ヘッダー | ToggleFullscreen/SetFullscreen宣言、_isFullscreenフラグ、FullscreenChangedイベント |
| TerminalPage.cpp | `src/cascadia/TerminalApp/TerminalPage.cpp` | ソース | ToggleFullscreen/SetFullscreenの実装、タブビュー更新 |
| TerminalWindow.h | `src/cascadia/TerminalApp/TerminalWindow.h` | ヘッダー | FullscreenChangedイベントの中継宣言 |
| TerminalWindow.cpp | `src/cascadia/TerminalApp/TerminalWindow.cpp` | ソース | FullscreenChangedイベントの中継 |
| ActionArgs.h | `src/cascadia/TerminalSettingsModel/ActionArgs.h` | ヘッダー | SetFullScreenArgs の定義 |
