# 機能設計書 91-タブ概要

## 概要

本ドキュメントは、Ghosttyターミナルエミュレータにおける「タブ概要」機能の設計を記述する。タブ概要（Tab Overview）は、開いている全てのタブを一覧表示し、視覚的にタブの切り替えや管理を行える機能である。

### 本機能の処理概要

タブ概要機能は、複数のタブを持つウィンドウにおいて、全タブのサムネイルまたは一覧を表示し、ユーザーが直感的にタブを選択・切り替えできるようにする機能である。

**業務上の目的・背景**：ターミナルを多数のタブで使用するユーザーにとって、タブバーだけでは全てのタブを把握しにくい場合がある。タブ概要機能により、全タブを一望でき、効率的なタブ管理が可能になる。特に作業内容に応じて多数のタブを開くパワーユーザーにとって、迅速なコンテキストスイッチを実現する。

**機能の利用シーン**：多数のタブを開いている状況で、特定のタブを素早く見つけて切り替えたい場合に利用される。キーバインドやコマンドパレットからトグル操作で表示・非表示を切り替える。

**主要な処理内容**：
1. ユーザーがキーバインドまたはコマンドパレットからtoggle_tab_overviewアクションを実行
2. アプリケーションランタイム（apprt）がタブ概要UIをトグル表示
3. GTKの場合はlibadwaita 1.4以上のAdwTabOverviewウィジェットを使用
4. ユーザーがタブを選択すると該当タブにフォーカスが移動
5. 概要ビューを閉じて通常のターミナル操作に戻る

**関連システム・外部連携**：GTK環境ではlibadwaita 1.4以上が必要。macOS環境では別途ネイティブUIで実装される可能性がある。

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | メインターミナルウィンドウ | 主画面 | タブ概要のトグル表示元となる画面 |

## 機能種別

UI制御 / タブ管理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| なし | - | - | パラメータなしのトグル操作 | - |

### 入力データソース

- キーバインド設定（`keybind = toggle_tab_overview`）
- コマンドパレットからの選択

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 表示状態 | bool | タブ概要の表示/非表示状態 |

### 出力先

- 画面表示（タブ概要オーバーレイ）

## 処理フロー

### 処理シーケンス

```
1. ユーザーがtoggle_tab_overviewアクションを実行
   └─ キーバインドまたはコマンドパレット経由
2. Surface.performBindingActionがアクションを処理
   └─ rt_app.performActionを呼び出し
3. アプリケーションランタイムがtoggle_tab_overviewを受信
   └─ GTKの場合: Action.toggleTabOverview関数を実行
4. タブ概要UIの表示/非表示をトグル
   └─ 現在の状態に応じて表示または非表示に切り替え
5. ユーザーがタブを選択するとフォーカス移動
   └─ 概要ビューを閉じて該当タブを表示
```

### フローチャート

```mermaid
flowchart TD
    A[toggle_tab_overview実行] --> B{タブ概要は表示中?}
    B -->|Yes| C[タブ概要を非表示]
    B -->|No| D{libadwaita 1.4以上?}
    D -->|Yes| E[タブ概要を表示]
    D -->|No| F[機能利用不可]
    C --> G[通常画面に戻る]
    E --> H{タブ選択?}
    H -->|Yes| I[選択タブにフォーカス]
    H -->|No/キャンセル| G
    I --> G
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-91-1 | 環境要件 | Linux GTK環境ではlibadwaita 1.4以上が必要 | GTK環境使用時 |
| BR-91-2 | トグル動作 | 同じアクションで表示/非表示を切り替え | 常時 |

### 計算ロジック

特になし

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

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

本機能はデータベースを使用しない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 機能非対応 | libadwaita 1.4未満の環境 | 機能が無効化される（エラー表示なし） |

### リトライ仕様

リトライ不要

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

トランザクション不要（UI操作のみ）

## パフォーマンス要件

即座にUIが応答すること（100ms以内）

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

特になし

## 備考

- Linux GTK環境専用機能
- macOSでの対応状況は別途確認が必要
- `ghostty +version`でlibadwaitaバージョンを確認可能

---

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

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

### 推奨読解順序

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

まず、アクションの定義を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | action.zig | `src/apprt/action.zig` | Action unionのtoggle_tab_overview定義（109行目）を確認 |
| 1-2 | Binding.zig | `src/input/Binding.zig` | Action enumのtoggle_tab_overview定義（570行目）を確認 |

**読解のコツ**: Zigのunion型は複数の型を一つの型として扱う。Action unionの各フィールドがアクションの種類を表す。

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

キーバインドからアクションが実行される流れを追う。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Surface.zig | `src/Surface.zig` | performBindingAction関数のtoggle_tab_overview処理（5714-5718行目） |

**主要処理フロー**:
1. **5714行目**: toggle_tab_overviewアクションのマッチング
2. **5715-5718行目**: rt_app.performActionを呼び出してアプリケーションランタイムに委譲

#### Step 3: GTKランタイムの処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | application.zig | `src/apprt/gtk/class/application.zig` | performAction内のtoggle_tab_overview処理（751行目） |

**主要処理フロー**:
- **751行目**: Action.toggleTabOverview関数を呼び出し

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

```
Surface.performBindingAction
    │
    ├─ toggle_tab_overviewアクションを検出
    │
    └─ rt_app.performAction(.toggle_tab_overview)
           │
           └─ GTK Application.performAction
                  │
                  └─ Action.toggleTabOverview(target)
                         │
                         └─ GTKウィンドウのタブ概要UIをトグル
```

### データフロー図

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

キーバインド ───▶ Surface.performBindingAction ───▶ UIトグル
                        │
                        ▼
               apprt.performAction
                        │
                        ▼
               GTK toggleTabOverview
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| action.zig | `src/apprt/action.zig` | ソース | アクション定義（apprtレベル） |
| Binding.zig | `src/input/Binding.zig` | ソース | キーバインドアクション定義 |
| command.zig | `src/input/command.zig` | ソース | コマンドパレット用コマンド定義 |
| Surface.zig | `src/Surface.zig` | ソース | サーフェスレベルのアクション処理 |
| application.zig | `src/apprt/gtk/class/application.zig` | ソース | GTKアプリケーションのアクション処理 |
