# 機能設計書 60-フォーカスモード切替

## 概要

本ドキュメントは、Windows Terminal における「フォーカスモード切替」機能の設計を記述する。ToggleFocusMode アクションにより、タブバーとタイトルバーを非表示にするフォーカスモードのオン/オフを切り替える機能である。

### 本機能の処理概要

**業務上の目的・背景**：ターミナルでの作業に集中するために、タブバーやタイトルバーなどのUI要素を非表示にしてターミナル表示領域を最大化する「フォーカスモード」を提供する。フルスクリーンとは異なり、ウィンドウサイズは変更せずにUI要素のみを非表示にする。コーディング作業やログ監視など、集中力を要する作業時に有用。

**機能の利用シーン**：ユーザーがターミナル画面の表示領域を広げ、タブバーやタイトルバーの視覚的なノイズを排除して作業に集中したい場合に利用する。キーバインドでの素早いトグル操作が主な使用方法。

**主要な処理内容**：
1. ユーザーが ToggleFocusMode アクションを実行
2. TerminalPage::ToggleFocusMode が現在のフォーカスモード状態を反転
3. _isInFocusMode フラグを更新
4. _UpdateTabView でタブバーの表示/非表示を更新
5. FocusModeChanged イベントを発火し、ウィンドウコンテナに通知

**関連システム・外部連携**：TitlebarControl（タイトルバー）はフォーカスモード時に非表示となる。TerminalPage の _UpdateTabView がタブ行の表示制御を行う。

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

## 関連画面

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

## 機能種別

UIモード切替操作 / トグル操作

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| なし | - | - | パラメータなし。トグル操作（現在の状態を反転） | - |

### 入力データソース

キーバインド設定またはコマンドパレットからの ToggleFocusMode アクション。

注記：SetFocusMode アクション（IsFocusMode: Boolean パラメータ）による明示的な状態設定も可能。

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| Handled | bool | アクションが処理されたかどうか（常に true） |
| FocusModeChanged | イベント | フォーカスモード状態の変更をウィンドウコンテナに通知 |

### 出力先

TerminalPage の _isInFocusMode フラグが更新され、タブ行の表示/非表示が切り替わる。FocusModeChanged イベントが発火する。

## 処理フロー

### 処理シーケンス

```
1. TerminalPage::_HandleToggleFocusMode がアクションイベントを受信
2. ToggleFocusMode() を呼び出し
   └─ SetFocusMode(!_isInFocusMode) で状態を反転
3. SetFocusMode(inFocusMode) が実行される
   ├─ 新しい状態が現在と同じ場合は何もしない（冪等性）
   ├─ _isInFocusMode を更新
   ├─ _UpdateTabView() でタブ行の表示状態を更新
   └─ FocusModeChanged イベントを発火（nullptr）
4. args.Handled(true) を設定
```

### フローチャート

```mermaid
flowchart TD
    A[ToggleFocusMode アクション受信] --> B[TerminalPage::ToggleFocusMode]
    B --> C[SetFocusMode の反転状態で呼び出し]
    C --> D{新状態 != 現在状態?}
    D -->|Yes| E[_isInFocusMode を更新]
    D -->|No| F[何もしない]
    E --> G[_UpdateTabView でタブ行表示更新]
    G --> H[FocusModeChanged イベント発火]
    H --> I[Handled = true]
    F --> I
    I --> J[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-60-1 | トグル動作 | 現在のフォーカスモード状態を反転する | ToggleFocusMode 使用時 |
| BR-60-2 | 冪等性 | 同じ状態への設定要求は無視する（イベントも発火しない） | SetFocusMode 使用時 |
| BR-60-3 | タブ行非表示 | フォーカスモード有効時はタブバーが非表示になる | フォーカスモード ON 時 |
| BR-60-4 | タイトルバー非表示 | フォーカスモード有効時はタイトルバーが非表示になる | フォーカスモード ON 時 |
| BR-60-5 | ウィンドウサイズ維持 | フルスクリーンとは異なり、ウィンドウサイズは変更しない | 常時 |

### 計算ロジック

- トグル: `SetFocusMode(!_isInFocusMode)`
- 冪等性チェック: `if (newInFocusMode != FocusMode()) { ... }`

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

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

本機能はデータベース操作を行わない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| なし | 状態変更なし | 既に同じフォーカスモード状態の場合 | 静かにスキップ |

### リトライ仕様

リトライ処理は不要。

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

本機能にトランザクション制御はない。UIスレッド上で同期的に実行される。

## パフォーマンス要件

UIの表示/非表示切替のみで即座に完了する。

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

特になし。

## 備考

- ToggleFocusMode と SetFocusMode は別アクション。ToggleFocusMode はトグル、SetFocusMode は明示的な状態指定
- フォーカスモードとフルスクリーンモードは独立した状態であり、同時に有効にすることも可能
- FocusModeChanged イベントのサブスクライバーはウィンドウコンテナ（AppHost/IslandWindow）

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | TerminalPage.h | `src/cascadia/TerminalApp/TerminalPage.h` | _isInFocusMode フラグ（240行目）、FocusModeChanged イベント（185行目）、ToggleFocusMode/SetFocusMode メソッド宣言（128, 137行目） |
| 1-2 | ActionArgs.idl | `src/cascadia/TerminalSettingsModel/ActionArgs.idl` | SetFocusModeArgs の定義（IsFocusMode: Boolean） |

**読解のコツ**: _isInFocusMode は bool フラグで初期値 false。FocusModeChanged は `til::typed_event` で定義されたイベント。ToggleFocusMode はパラメータなし、SetFocusMode は明示的な bool パラメータを受け取る。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | AppActionHandlers.cpp | `src/cascadia/TerminalApp/AppActionHandlers.cpp` | _HandleToggleFocusMode メソッド（600-605行目）と _HandleSetFocusMode メソッド（607-615行目） |

**主要処理フロー**:
1. **600-605行目**: ToggleFocusMode() を呼び出し、Handled=true
2. **607-615行目**: SetFocusModeArgs から IsFocusMode を取得し、SetFocusMode(bool) を呼び出し

#### Step 3: TerminalPage のフォーカスモード制御を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | TerminalPage.cpp | `src/cascadia/TerminalApp/TerminalPage.cpp` | ToggleFocusMode（4040-4043行目）と SetFocusMode（4045-4054行目） |

**主要処理フロー**:
- **4040-4043行目**: ToggleFocusMode が SetFocusMode(!_isInFocusMode) を呼び出す
- **4045-4054行目**: SetFocusMode で冪等性チェック後、_isInFocusMode 更新、_UpdateTabView 呼び出し、FocusModeChanged イベント発火

#### Step 4: タブ行表示制御を理解する（補足）

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | TerminalPage.cpp | `src/cascadia/TerminalApp/TerminalPage.cpp` | _UpdateTabView メソッド: フォーカスモード/フルスクリーン時のタブ行表示制御 |

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

```
TerminalPage::_HandleToggleFocusMode (AppActionHandlers.cpp:600)
    │
    └─ TerminalPage::ToggleFocusMode (TerminalPage.cpp:4040)
           │
           └─ TerminalPage::SetFocusMode(!_isInFocusMode) (TerminalPage.cpp:4045)
                  │
                  ├─ 冪等性チェック (FocusMode() != newInFocusMode)
                  │
                  ├─ _isInFocusMode = newInFocusMode
                  │
                  ├─ _UpdateTabView() → タブ行表示/非表示
                  │
                  └─ FocusModeChanged.raise() → ウィンドウコンテナに通知

[SetFocusMode 経路]
TerminalPage::_HandleSetFocusMode (AppActionHandlers.cpp:607)
    │
    └─ SetFocusModeArgs → IsFocusMode 取得
           │
           └─ TerminalPage::SetFocusMode(isFocusMode)
```

### データフロー図

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

ToggleFocusMode      ───▶ TerminalPage                   ───▶ タブ行表示更新
アクション                    ::ToggleFocusMode                   + タイトルバー更新
(パラメータなし)                   │
                                  ▼
                             SetFocusMode(!current)
                                  │
                                  ├─ _isInFocusMode 更新
                                  ├─ _UpdateTabView() ──────────▶ タブ行
                                  └─ FocusModeChanged ──────────▶ ウィンドウコンテナ
                                                                    └─ タイトルバー
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| AppActionHandlers.cpp | `src/cascadia/TerminalApp/AppActionHandlers.cpp` | ソース | _HandleToggleFocusMode, _HandleSetFocusMode アクションハンドラー |
| TerminalPage.cpp | `src/cascadia/TerminalApp/TerminalPage.cpp` | ソース | ToggleFocusMode, SetFocusMode, _UpdateTabView の実装 |
| TerminalPage.h | `src/cascadia/TerminalApp/TerminalPage.h` | ヘッダー | _isInFocusMode, FocusModeChanged, ToggleFocusMode 等の宣言 |
| AllShortcutActions.h | `src/cascadia/TerminalSettingsModel/AllShortcutActions.h` | ヘッダー | ToggleFocusMode, SetFocusMode アクション登録 |
| ActionArgs.idl | `src/cascadia/TerminalSettingsModel/ActionArgs.idl` | IDL | SetFocusModeArgs 定義 |
| defaults.json | `src/cascadia/TerminalSettingsModel/defaults.json` | 設定 | デフォルトキーバインド定義 |
