# 機能設計書 84-スクリーンキーボード

## 概要

本ドキュメントは、Ghosttyターミナルエミュレータにおけるスクリーンキーボード（オンスクリーンキーボード）機能の設計仕様を記載する。

### 本機能の処理概要

スクリーンキーボード機能は、GTK環境（Linux）において、画面上に仮想キーボードを表示する機能である。タッチデバイスやアクセシビリティ目的で使用される。

**業務上の目的・背景**：
物理キーボードが使用できない環境（タブレット、タッチスクリーン端末）やアクセシビリティの観点から仮想キーボードが必要な場合に、ターミナル操作を可能にする。特にGNOME環境では「スクリーンキーボード」アクセシビリティ機能と連携する。

**機能の利用シーン**：
- タッチスクリーンデバイスでターミナルを操作する場合
- アクセシビリティ機能として仮想キーボードを使用する場合
- キーバインドからshow_on_screen_keyboardアクションを実行する場合

**主要な処理内容**：
1. キーバインドアクション`show_on_screen_keyboard`を受け取る
2. apprt（アプリケーションランタイム）のアクションとして`show_on_screen_keyboard`を実行
3. GTK環境でネイティブのオンスクリーンキーボードを表示

**関連システム・外部連携**：
- GTK（GNOME Toolkit）
- GNOME Screen Keyboard アクセシビリティ機能
- システムの入力メソッドフレームワーク

**権限による制御**：
特に権限による制御はない。ただし、GNOME環境では「スクリーンキーボード」アクセシビリティ機能が有効である必要がある。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | メインターミナルウィンドウ | 主画面 | スクリーンキーボードの呼び出し元 |

## 機能種別

ユーザー操作 / アクセシビリティ

## 入力仕様

### 入力パラメータ

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

### 入力データソース

- キーバインドアクション

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| オンスクリーンキーボード表示 | UI | システムの仮想キーボードを表示 |

### 出力先

システムのオンスクリーンキーボードUI

## 処理フロー

### 処理シーケンス

```
1. アクション受信
   └─ show_on_screen_keyboardアクション
2. プラットフォーム判定
   └─ GTK環境のみ有効
3. アクション実行
   └─ rt_app.performAction(.show_on_screen_keyboard)
4. GTK処理
   └─ ネイティブのオンスクリーンキーボードを表示
```

### フローチャート

```mermaid
flowchart TD
    A[show_on_screen_keyboard アクション] --> B{GTK環境?}
    B -->|No| C[何もしない]
    B -->|Yes| D[performAction実行]
    D --> E[GTKオンスクリーンキーボード表示]
    E --> F{GNOME環境?}
    F -->|Yes| G{アクセシビリティ機能有効?}
    G -->|Yes| H[キーボード表示]
    G -->|No| I[表示なし/警告]
    F -->|No| J[環境固有の処理]
    C --> K[終了]
    H --> K
    I --> K
    J --> K
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-84-01 | GTK限定 | 本機能はLinux（GTK）環境でのみ実装 | 常時 |
| BR-84-02 | GNOME要件 | GNOME環境では「スクリーンキーボード」アクセシビリティ機能が必要 | GNOME使用時 |
| BR-84-03 | macOS非対応 | macOSでは本アクションは未実装 | macOS使用時 |

### 計算ロジック

特になし。

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 無視 | 非GTK環境での実行 | 何もしない |
| - | 無視 | アクセシビリティ機能無効 | 何もしない（ログ出力のみ） |

### リトライ仕様

リトライは行わない。

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

該当なし。

## パフォーマンス要件

特になし。

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

- オンスクリーンキーボードでのパスワード入力時は、通常のキーボードと同様のセキュリティ考慮が必要
- キーストロークのログ記録などには注意

## 備考

- GNOME以外のLinuxデスクトップ環境での動作は未検証
- macOSでは本機能は未実装（コマンドパレットでもフィルタリングされる）

---

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

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

### 推奨読解順序

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

まず、アクションの定義を理解することが重要。

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

**読解のコツ**: `show_on_screen_keyboard`はパラメータなしのアクションで、Linux（GTK）環境でのみ実装されている。

**主要処理フロー**:
- **Binding.zig 646-652行目**: アクションのドキュメントと定義

#### Step 2: Surfaceでのアクション処理を理解する

アクションがSurfaceでどのように処理されるか。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Surface.zig | `src/Surface.zig` | show_on_screen_keyboardのperformAction呼び出し |

#### Step 3: GTK実装を理解する

GTK環境での実装。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | surface.zig | `src/apprt/gtk/class/surface.zig` | GTKでのオンスクリーンキーボード表示処理 |

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

```
キーバインドアクション
    │
    └─ show_on_screen_keyboard
           │
           ▼
    Surface.zig
           │
           └─ rt_app.performAction(.show_on_screen_keyboard)
                  │
                  ▼
           [GTK環境のみ]
                  │
                  ▼
           gtk/class/surface.zig
                  │
                  ▼
           GTKオンスクリーンキーボードAPI
                  │
                  ▼
           システムキーボード表示
```

### データフロー図

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

キーバインド ───▶ アクション判定 ───▶ プラットフォーム判定
                                              │
                                              ▼
                                    [GTK環境のみ]
                                              │
                                              ▼
                                    performAction
                                              │
                                              ▼
                                    GTK API呼び出し
                                              │
                                              ▼
                                    オンスクリーンキーボード表示
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Binding.zig | `src/input/Binding.zig` | ソース | アクション定義（show_on_screen_keyboard） |
| action.zig | `src/apprt/action.zig` | ソース | apprレベルのアクション定義 |
| Surface.zig | `src/Surface.zig` | ソース | アクション処理のディスパッチ |
| surface.zig | `src/apprt/gtk/class/surface.zig` | ソース | GTK固有の実装 |
| application.zig | `src/apprt/gtk/class/application.zig` | ソース | GTKアプリケーションレベルの処理 |
| command_palette.zig | `src/apprt/gtk/class/command_palette.zig` | ソース | コマンドパレットでのフィルタリング |
