# 機能設計書 36-GTKアプリ

## 概要

本ドキュメントは、Ghosttyターミナルエミュレータにおける GTKベースのGUIアプリケーション実装の設計を定義する。

### 本機能の処理概要

GTKアプリ機能は、Linux向けのGTK/libadwaitaベースのGUIアプリケーションを提供する。ウィンドウ管理、タブ、スプリット、設定UI等のネイティブなLinuxデスクトップ体験を実現する。

**業務上の目的・背景**：LinuxデスクトップでGNOME、KDE等のデスクトップ環境と統合されたネイティブなターミナル体験を提供する。GTK/libadwaitaを使用することで、モダンなUIコンポーネントとテーマ対応を実現。

**機能の利用シーン**：
- Linux（GNOME、KDE等）でGhosttyを使用する場合
- X11またはWayland環境でターミナルを使用する場合
- GTKテーマと統合されたターミナルが必要な場合

**主要な処理内容**：
1. GTKアプリケーションの初期化
2. メインウィンドウの作成と管理
3. イベントループの実行
4. アクションの処理とUI更新

**関連システム・外部連携**：
- GTK 4.x / libadwaita
- X11 / Wayland（ウィンドウプロトコル）
- D-Bus（プロセス間通信）
- GSettings（設定管理）

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | メインターミナルウィンドウ | 主画面 | GTKベースのターミナルUI |
| 2 | クイックターミナル | 補助画面 | ドロップダウンターミナル |

## 機能種別

アプリケーションランタイム / GUI管理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| - | - | - | 起動時パラメータは設定ファイルとCLIオプションで指定 | - |

### 入力データソース

- コマンドライン引数
- 設定ファイル（~/.config/ghostty/config）
- 環境変数

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| - | - | GUIウィンドウ表示 |

### 出力先

- 画面表示（GTKウィンドウ）

## 処理フロー

### 処理シーケンス

```
1. アプリケーション初期化
   └─ App.init()
       ├─ Application GObjectの作成
       └─ 設定の読み込み
2. アプリケーション実行
   └─ App.run()
       ├─ GTKメインループ開始
       └─ アクティベーションシグナル処理
3. ウィンドウ作成
   └─ Window.new()
       ├─ ウィンドウテンプレートの初期化
       ├─ アクションマップの設定
       └─ タブビューの設定
4. サーフェス作成
   └─ Surface.init()
       ├─ ターミナルサーフェスの初期化
       └─ レンダリングの開始
5. イベント処理ループ
   └─ GTKイベントループ内で処理
6. 終了処理
   └─ App.terminate()
```

### フローチャート

```mermaid
flowchart TD
    A[main開始] --> B[App.init]
    B --> C[Application GObject作成]
    C --> D[App.run]
    D --> E[GTKメインループ]
    E --> F{アクティベーション}
    F -->|初回| G[Window.new]
    G --> H[Surface作成]
    H --> I[ターミナル表示]
    F -->|既存| J[既存ウィンドウにフォーカス]
    I --> E
    J --> E
    E --> K{終了シグナル}
    K -->|Yes| L[App.terminate]
    L --> M[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-36-01 | シングルインスタンス | gtk-single-instance設定でインスタンス管理 | detect/on/off |
| BR-36-02 | アプリケーションID | デバッグビルドとリリースビルドで異なるID | ビルドモード |
| BR-36-03 | libadwaita必須 | Ghostty 1.2以降でlibadwaitaが必須依存 | 常時 |
| BR-36-04 | アプリスレッド描画 | OpenGLのGLAreaはアプリスレッドから描画が必要 | must_draw_from_app_thread |

### 計算ロジック

特になし。

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 初期化失敗 | GTK/libadwaitaが利用不可 | エラーメッセージ表示 |
| - | ウィンドウ作成失敗 | ディスプレイに接続不可 | エラーメッセージ表示 |

### リトライ仕様

リトライは行わない。

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

トランザクションは使用しない。

## パフォーマンス要件

- 起動時間: 1秒以内（初回起動）
- UIレスポンス: 16ms以内（60fps）

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

- Flatpak/Snapでのサンドボックス環境をサポート

## 備考

- GTK 4.xとlibadwaitaを使用
- X11とWaylandの両方をサポート
- Flatpak/Snapパッケージングをサポート

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | App.zig | `src/apprt/gtk/App.zig` | GTKアプリケーションのエントリーポイント |

**主要処理フロー**:
- **25-28行目**: application_id定義（デバッグ/リリースで異なる）
- **39-52行目**: init関数 - Application GObjectの作成
- **54-56行目**: run関数 - GTKメインループ実行
- **58-63行目**: terminate関数 - アプリケーション終了

#### Step 2: アプリケーションGObjectを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | application.zig | `src/apprt/gtk/class/application.zig` | Application GObjectクラス |

**読解のコツ**: GObjectシステムを理解することで、GTK実装の全体像が把握できる。

#### Step 3: ウィンドウ実装を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | window.zig | `src/apprt/gtk/class/window.zig` | Window GObjectクラス |
| 3-2 | tab.zig | `src/apprt/gtk/class/tab.zig` | Tab GObjectクラス |

#### Step 4: サーフェス実装を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Surface.zig | `src/apprt/gtk/Surface.zig` | サーフェス管理 |
| 4-2 | surface.zig | `src/apprt/gtk/class/surface.zig` | Surface GObjectクラス |

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

```
main
    │
    └─ App.init
           │
           ├─ Application.new
           │      └─ GObject初期化
           │
           └─ App.run
                  │
                  └─ Application.run
                         │
                         ├─ activate シグナル
                         │      └─ Window.new
                         │              ├─ Tab.new
                         │              └─ Surface.init
                         │
                         └─ GTKメインループ
                                ├─ イベント処理
                                ├─ アクション処理
                                └─ レンダリング
```

### データフロー図

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

コマンドライン ───▶ 設定解析 ──────────────────────────▶ 設定オブジェクト
設定ファイル             │
                         │
                    App.init ───────────────────────────▶ Application
                         │
                    App.run ────────────────────────────▶ GTKメインループ
                         │
ユーザー入力 ───────▶ イベント処理 ──────────────────────▶ アクション実行
                         │
                    レンダリング ───────────────────────▶ 画面表示
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| App.zig | `src/apprt/gtk/App.zig` | ソース | GTKアプリケーションエントリーポイント |
| application.zig | `src/apprt/gtk/class/application.zig` | ソース | Application GObjectクラス |
| window.zig | `src/apprt/gtk/class/window.zig` | ソース | Window GObjectクラス |
| tab.zig | `src/apprt/gtk/class/tab.zig` | ソース | Tab GObjectクラス |
| Surface.zig | `src/apprt/gtk/Surface.zig` | ソース | サーフェス管理 |
| surface.zig | `src/apprt/gtk/class/surface.zig` | ソース | Surface GObjectクラス |
| winproto.zig | `src/apprt/gtk/winproto.zig` | ソース | ウィンドウプロトコル（X11/Wayland） |
| key.zig | `src/apprt/gtk/key.zig` | ソース | キーイベント処理 |
| gsettings.zig | `src/apprt/gtk/gsettings.zig` | ソース | GSettings連携 |
| flatpak.zig | `src/apprt/gtk/flatpak.zig` | ソース | Flatpak対応 |
