# 機能設計書 30-スプリットズーム

## 概要

本ドキュメントは、Ghosttyターミナルエミュレータにおける「スプリットズーム」機能の設計を記述する。スプリットズーム機能は、分割されたペインの1つを一時的にフルサイズで表示し、他のペインを一時的に非表示にする機能である。

### 本機能の処理概要

**業務上の目的・背景**：
スプリット機能で複数のペインを表示している際、特定のペインに集中したい場面がある。スプリットズーム機能により、選択したペインを一時的にフルサイズで表示し、作業に集中できる。ズームを解除すれば元のスプリットレイアウトに戻るため、コンテキストを失うことなく、柔軟に表示モードを切り替えられる。

**機能の利用シーン**：
- ログ出力の詳細確認
- コード編集時の画面最大化
- プレゼンテーション時の表示切り替え
- デバッグ情報の詳細確認

**主要な処理内容**：
1. toggle_split_zoomアクションの受信
2. ズーム状態のトグル（ズーム/アンズーム）
3. SplitTreeのzoomedハンドル更新
4. UIの表示更新
5. タブバーへのズーム状態インジケーター表示

**関連システム・外部連携**：
- SplitTreeデータ構造
- レンダラー（フルサイズ描画）
- タブバーUI（ズームインジケーター）

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 3 | スプリットビュー | 主画面 | ズームイン/アウトの操作 |

## 機能種別

UI制御 / 表示管理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| (なし) | - | - | toggle_split_zoomはパラメータなし | - |

### 入力データソース

- キーバインドアクション（toggle_split_zoom）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| zoomed | ?Node.Handle | ズームされたノードのハンドル（nullならアンズーム状態） |

### 出力先

- SplitTree状態
- レンダラー（表示更新）
- タブバー（ズームインジケーター）

## 処理フロー

### 処理シーケンス

```
1. toggle_split_zoomアクション受信

2. 現在の状態確認
   └─ zoomed != null ならアンズーム
   └─ zoomed == null ならズーム

3. SplitTree.zoom()呼び出し
   └─ zoomedハンドルを更新

4. UI更新
   └─ ズーム時: 選択ペインをフルサイズで表示
   └─ アンズーム時: 元のレイアウトを復元
```

### フローチャート

```mermaid
flowchart TD
    A[toggle_split_zoom] --> B{スプリット存在?}
    B -->|No| C[処理終了（実行不可）]
    B -->|Yes| D{現在ズーム中?}

    D -->|Yes| E[アンズーム処理]
    D -->|No| F[ズーム処理]

    E --> G[zoomed = null]
    F --> H[zoomed = 現在のノード]

    G --> I[レイアウト復元]
    H --> J[フルサイズ表示]

    I --> K[タブバー更新]
    J --> K

    K --> L[処理完了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-30-1 | スプリット必須 | スプリットが存在しない場合はズーム不可 | toggle_split_zoom実行時 |
| BR-30-2 | トグル動作 | ズーム中なら解除、非ズームならズーム | toggle_split_zoom実行時 |
| BR-30-3 | ズームインジケーター | タブバーにズーム状態を表示 | ズーム中 |
| BR-30-4 | リサイズでアンズーム | スプリットリサイズ操作でズームが解除される場合がある | resize_split実行時 |

### 計算ロジック

該当なし

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

該当なし（本機能はデータベースを使用しない）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 実行不可 | スプリットが存在しない | performableがfalseを返す |

### リトライ仕様

該当なし

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

該当なし

## パフォーマンス要件

- ズーム切り替え: 即時（ミリ秒オーダー）

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

特になし

## 備考

- ズーム状態はSplitTree.zoomedフィールドで管理
- isSplit関数でスプリットの存在を確認可能

---

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

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

### 推奨読解順序

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

ズーム状態のデータ構造を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | split_tree.zig | `src/datastruct/split_tree.zig` | SplitTreeのzoomedフィールド（62行目） |
| 1-2 | split_tree.zig | `src/datastruct/split_tree.zig` | zoom関数（220-226行目） |

**読解のコツ**: zoomedは`?Node.Handle`型であり、nullの場合はズームなし、値がある場合はそのハンドルのノードがズームされていることを示す。

#### Step 2: アクション定義を理解する

toggle_split_zoomアクションの定義を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Binding.zig | `src/input/Binding.zig` | toggle_split_zoomアクション（609行目） |
| 2-2 | Binding.zig | `src/input/Binding.zig` | アクションのドキュメントコメント（604-609行目） |

**主要処理フロー**:
1. **604-608行目**: ズーム機能の説明（フルサイズ表示、タブバーインジケーター）
2. **609行目**: toggle_split_zoomアクション定義（パラメータなし）

#### Step 3: apprtアクションを理解する

apprt層でのアクション定義を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | action.zig | `src/apprt/action.zig` | toggle_split_zoomアクション（153行目） |
| 3-2 | action.zig | `src/apprt/action.zig` | アクションのドキュメントコメント（151-153行目） |

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

```
キーバインド
    │
    └─ toggle_split_zoom
           │
           ├─ isSplit()確認
           │      │
           │      └─ false → performable=false
           │
           └─ true
                  │
                  ├─ zoomed != null ?
                  │      │
                  │      ├─ Yes: zoom(null) ── アンズーム
                  │      │
                  │      └─ No: zoom(current) ── ズーム
                  │
                  └─ UI更新
                         │
                         ├─ レイアウト変更
                         │
                         └─ タブバーインジケーター
```

### データフロー図

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

toggle_split_zoom ────▶ 状態確認 ────────────────▶ SplitTree.zoom()
                              │                        │
                              ▼                        ▼
                       isSplit() ────▶ true        zoomedハンドル更新
                              │
                              ▼
                       zoomed確認
                              │
                        ┌─────┴─────┐
                        ▼           ▼
                     ズーム      アンズーム
                        │           │
                        └─────┬─────┘
                              ▼
                        UI更新/描画
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| split_tree.zig | `src/datastruct/split_tree.zig` | ソース | SplitTree.zoomed/zoom関数 |
| Binding.zig | `src/input/Binding.zig` | ソース | toggle_split_zoomアクション定義 |
| action.zig | `src/apprt/action.zig` | ソース | apprtアクション定義 |
| split_tree.zig | `src/apprt/gtk/class/split_tree.zig` | ソース | GTKスプリットツリー実装 |
