# 機能設計書 76-GTKインスペクター

## 概要

本ドキュメントは、GhosttyターミナルエミュレータにおけるGTKインスペクター機能の設計について記載する。この機能はGTKウィジェットのデバッグツールを起動し、GTKアプリケーションのUI構造やスタイルをリアルタイムで調査することができる。

### 本機能の処理概要

**業務上の目的・背景**：
GhosttyのLinux版はGTK4を使用してUIを構築している。GTKインスペクターは、GTKアプリケーションの内部ウィジェット構造、CSSスタイル、プロパティ値などをリアルタイムで調査できる公式デバッグツールである。Ghosttyの開発者やテーマ作成者がUIの問題をデバッグしたり、カスタマイズの可能性を探ったりするのに有用である。

**機能の利用シーン**：
- GTKウィジェット階層の調査
- CSSスタイルのデバッグ
- ウィジェットプロパティの確認
- アニメーションやトランジションのデバッグ
- アクセシビリティ情報の確認

**主要な処理内容**：
1. `show_gtk_inspector`アクションの受付
2. GTK Inspectorの起動

**関連システム・外部連携**：
- GTK4 Inspector: GTK内蔵のデバッグツール
- libadwaita: Ghosttyが使用するGTKウィジェットライブラリ

**権限による制御**：
- 特に権限制御は不要（開発者向け機能）
- GTK_DEBUG環境変数が必要な場合がある

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | メインターミナルウィンドウ | 参照画面 | GTKインスペクター起動元 |

## 機能種別

デバッグ / GTKツール

## 入力仕様

### 入力パラメータ

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

### 入力データソース

- キーバインド`show_gtk_inspector`アクション
- コマンドパレットからの実行

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| GTK Inspectorウィンドウ | GtkWindow | GTKウィジェットインスペクター |

### 出力先

- 別ウィンドウとしてGTK Inspectorが起動

## 処理フロー

### 処理シーケンス

```
1. show_gtk_inspectorアクション受付
   └─ キーバインドまたはコマンドパレットから
2. アクションターゲット判定
   └─ .appターゲット（アプリケーション全体）
3. showGtkInspector関数呼び出し
   └─ GTK APIを使用
4. GTK Inspector起動
   └─ 別ウィンドウとして表示
```

### フローチャート

```mermaid
flowchart TD
    A[show_gtk_inspector アクション] --> B[Action.showGtkInspector]
    B --> C[gtk_window_set_interactive_debugging]
    C --> D[GTK Inspector ウィンドウ表示]
    D --> E[ユーザーによるデバッグ操作]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-76-1 | GTK専用 | この機能はGTKビルド（Linux）でのみ使用可能 | GTKアプリ |
| BR-76-2 | アプリターゲット | アクションはアプリケーション全体を対象とする | 常時 |
| BR-76-3 | macOS非対応 | macOSビルドではこのアクションは効果なし | macOS |

### 計算ロジック

該当なし

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

該当なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 非GTKビルド | macOSなどで実行 | 何もしない |
| - | Inspector無効 | GTKデバッグ機能が無効 | エラーなし（静かに失敗） |

### リトライ仕様

リトライは行わない。

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

該当なし

## パフォーマンス要件

- GTK Inspector起動はワンショット操作
- Inspector実行中はわずかなオーバーヘッドが発生

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

- GTK Inspectorは開発者向けツールであり、アプリケーションの内部状態を公開する
- 本番環境での使用は推奨しない

## 備考

- GTK_DEBUG=interactive環境変数でも同等の機能が起動可能
- GTK 4.x以降のインスペクターを使用
- コマンドパレットでは「GTK Inspector」として表示されない（GTK非対応としてフィルタ）

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Binding.zig | `src/input/Binding.zig` | show_gtk_inspectorアクション定義（644行目） |
| 1-2 | action.zig | `src/apprt/action.zig` | show_gtk_inspectorアクション（192行目） |

**読解のコツ**: `show_gtk_inspector`はパラメータなしのシンプルなアクション。ターゲットは`.app`（アプリケーション全体）。

#### Step 2: アクション実装を理解する

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

**主要処理フロー**:
1. **744行目**: `.show_gtk_inspector => Action.showGtkInspector()`

#### Step 3: 実際のGTK API呼び出しを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | application.zig | `src/apprt/gtk/class/application.zig` | showGtkInspector関数（GTK API呼び出し） |

**主要処理フロー**:
- `gtk_window_set_interactive_debugging(true)` を呼び出し

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

```
キーバインド / コマンドパレット
    │
    └─ show_gtk_inspector アクション
           │
           └─ application.performAction
                  │
                  └─ Action.showGtkInspector
                         │
                         └─ gtk_window_set_interactive_debugging(true)
                                │
                                └─ GTK Inspector ウィンドウ
```

### データフロー図

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

キーバインド ───▶ show_gtk_inspector アクション
                        │
                        ▼
               Action.showGtkInspector
                        │
                        ▼
         gtk_window_set_interactive_debugging
                        │
                        ▼
               GTK Inspector ウィンドウ
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Binding.zig | `src/input/Binding.zig` | ソース | アクション定義（641-644行目） |
| action.zig | `src/apprt/action.zig` | ソース | アクション定義（191-192行目） |
| application.zig | `src/apprt/gtk/class/application.zig` | ソース | performAction、showGtkInspector実装 |
| command_palette.zig | `src/apprt/gtk/class/command_palette.zig` | ソース | GTK非対応アクションのフィルタ（213行目） |
