# 画面設計書 23-Ophints

## 概要

本ドキュメントは、Doom EmacsのOphints（Operation Hints）機能の画面設計について記述します。Ophints は、編集操作（ヤンク、削除、インデント等）の対象リージョンを一時的にハイライト表示し、ユーザーに視覚的なフィードバックを提供する機能です。

### 本画面の処理概要

Ophintsは、テキスト編集操作を実行した際に、その操作が影響を与えた範囲（リージョン）を短時間ハイライト表示することで、「何をしたのか」を視覚的に明確にする機能を提供します。

**業務上の目的・背景**：テキストエディタでの編集作業において、特に大きなリージョンを対象とした操作（複数行のヤンク、削除、インデント変更など）では、操作結果を即座に把握することが困難な場合があります。Ophintsは操作対象を一時的にハイライトすることで、ユーザーが操作結果を確認し、意図しない変更を早期に検出できるようにします。

**画面へのアクセス方法**：Ophintsは自動的に動作するため、明示的な画面アクセスは不要です。以下の操作時に自動的にハイライトが表示されます：
- Evil使用時：evil-gogglesパッケージによる視覚フィードバック
- 非Evil使用時：gogglesパッケージによる視覚フィードバック

**主要な操作・処理内容**：
1. 編集コマンド（ヤンク、削除、インデント等）を実行
2. コマンドに関連付けられたadviceが発火
3. 操作対象リージョンの開始・終了位置を取得
4. リージョンにオーバーレイを作成しフェイスを適用
5. 短時間後（デフォルト0.1秒）にオーバーレイを削除

**画面遷移**：Ophintsは独立した画面ではなく、編集バッファ上で動作する視覚エフェクトです。他の画面への遷移機能はありません。

**権限による表示制御**：権限による制御はありません。Evilモードの有無によってバックエンドパッケージが切り替わります。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | Doomコアシステム | 主機能 | 操作対象リージョンのハイライト表示 |

## 画面種別

視覚エフェクト（オーバーレイ表示）

## URL/ルーティング

N/A（Emacsバッファ上で動作するため、URLの概念なし）

## 入出力項目

| 項目名 | 入力/出力 | データ型 | 説明 |
|--------|----------|----------|------|
| evil-goggles-duration | 入力 | float | ハイライト表示時間（デフォルト0.1秒） |
| evil-goggles-pulse | 入力 | boolean | パルスアニメーションの有無 |
| evil-goggles-enable-delete | 入力 | boolean | 削除操作のハイライト有無 |
| evil-goggles-enable-change | 入力 | boolean | 変更操作のハイライト有無 |

## 表示項目

| 操作 | フェイス | 説明 |
|------|----------|------|
| yank | evil-goggles-yank-face | ヤンク（コピー）操作のハイライト |
| delete | evil-goggles-delete-face | 削除操作のハイライト（デフォルト無効） |
| change | evil-goggles-change-face | 変更操作のハイライト（デフォルト無効） |
| indent | evil-goggles-indent-face | インデント操作のハイライト |
| join | evil-goggles-join-face | 行結合操作のハイライト |

## イベント仕様

### 1-Evil操作でのハイライト

Evilコマンド実行時にevil-gogglesがリージョンをハイライトします。

**処理フロー**：
1. Evilコマンド（y, d, c, >, <, J等）を実行
2. `evil-goggles--commands` に登録されたadviceが発火
3. コマンドの種類に応じたフェイスを選択
4. 操作対象リージョンにオーバーレイを作成
5. `evil-goggles-duration`（0.1秒）後にオーバーレイを削除

### 2-非Evil操作でのハイライト

gogglesパッケージがprog-modeとtext-modeで動作します。

**処理フロー**：
1. undo、insert-register、kill-word等のコマンドを実行
2. goggles-modeのアドバイスが発火
3. 操作対象リージョンにオーバーレイを作成
4. 短時間後にオーバーレイを削除

## データベース更新仕様

N/A（データベースを使用しない）

## メッセージ仕様

N/A（メッセージ表示なし）

## 例外処理

| 例外条件 | 処理内容 |
|----------|----------|
| delete操作 | デフォルトでハイライト無効（操作結果が明白なため） |
| change操作 | デフォルトでハイライト無効（操作結果が明白なため） |
| パルス効果 | 遅いため無効化 |

## 備考

- evil-gogglesはEvil使用時のみ有効
- gogglesは非Evil使用時にprog-modeとtext-modeで有効
- lispyvilleパッケージ使用時は追加のコマンドもサポート
- delete/change操作のハイライトは明白なため意図的に無効化

---

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

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

### 推奨読解順序

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

コマンドとフェイスのマッピング、設定変数が中心的なデータ構造です。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | config.el | `modules/ui/ophints/config.el` | `evil-goggles-duration`、`evil-goggles-pulse`、`evil-goggles-enable-*` の設定を確認（行7-12） |

**読解のコツ**: `setq` で設定される変数がハイライト動作を制御します。`evil-goggles--commands` はコマンドとアドバイスのマッピングリストです。

#### Step 2: Evil使用時のエントリーポイントを理解する

evil-gogglesパッケージの設定がエントリーポイントです。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | config.el | `modules/ui/ophints/config.el` | `use-package! evil-goggles` ブロック（行3-26） |

**主要処理フロー**:
1. **行3**: `:editor evil` モジュール有効時のみ読み込み
2. **行5**: `doom-first-input` フックで `evil-goggles-mode` を有効化
3. **行7-12**: 表示時間、パルス、削除/変更操作の無効化を設定
4. **行14-26**: 追加コマンドのマッピング登録（`evil-magit-yank-whole-line`、`+evil:yank-unindented`、`+eval:region`）

#### Step 3: lispyville連携を理解する

lispyvilleパッケージ使用時の追加コマンド登録を確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | config.el | `modules/ui/ophints/config.el` | lispyvilleコマンドの登録（行27-64） |

**主要処理フロー**:
- **行27-64**: `:editor lispy` モジュール有効時、lispyvilleのdelete、yank、change、indent、joinコマンドを登録

#### Step 4: 非Evil使用時のエントリーポイントを理解する

gogglesパッケージの設定を確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | config.el | `modules/ui/ophints/config.el` | `use-package! goggles` ブロック（行66-73） |

**主要処理フロー**:
1. **行66**: `:editor evil` 無効時のみ読み込み
2. **行67**: `prog-mode` と `text-mode` で `goggles-mode` を有効化
3. **行70-73**: undo、register-paste、kill-word、undo-fuコマンドの定義

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

```
編集コマンド実行
    │
    ├─ Evil使用時 ──────────────────────────────────────┐
    │                                                    │
    │   evil-goggles-mode                               │
    │       │                                            │
    │       ├─ evil-yank ──────▶ evil-goggles-yank-face │
    │       ├─ evil-delete ────▶ (無効化)               │
    │       ├─ evil-change ────▶ (無効化)               │
    │       ├─ evil-indent ────▶ evil-goggles-indent-face
    │       └─ evil-join ──────▶ evil-goggles-join-face │
    │                                                    │
    │   lispyville使用時                                │
    │       │                                            │
    │       ├─ lispyville-yank ────▶ evil-goggles-yank-face
    │       ├─ lispyville-delete ──▶ evil-goggles-delete-face
    │       └─ lispyville-indent ──▶ evil-goggles-indent-face
    │                                                    │
    └─ 非Evil使用時 ────────────────────────────────────┤
                                                         │
        goggles-mode                                    │
            │                                            │
            ├─ undo ────────────▶ goggles-undo-face     │
            ├─ insert-register ─▶ goggles-paste-face    │
            ├─ kill-word ───────▶ goggles-delete-face   │
            └─ undo-fu-only-* ──▶ goggles-undo-face     │
                                                         │
                        オーバーレイ表示 ◀───────────────┘
                             │
                             ▼ (0.1秒後)
                        オーバーレイ削除
```

### データフロー図

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

編集コマンド ─────▶ adviceトリガー ─────▶ オーバーレイ作成
                          │
                          ├─ リージョン開始位置
                          └─ リージョン終了位置

evil-goggles-duration ───▶ タイマー設定 ───▶ オーバーレイ削除
        │
        └─ 0.1秒

コマンド種別 ───▶ フェイス選択 ───▶ ハイライト色・スタイル
        │
        ├─ yank   → evil-goggles-yank-face
        ├─ indent → evil-goggles-indent-face
        └─ join   → evil-goggles-join-face
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| config.el | `modules/ui/ophints/config.el` | ソース | パッケージ設定、コマンド登録 |
| packages.el | `modules/ui/ophints/packages.el` | 設定 | evil-goggles、gogglesパッケージの依存定義 |
| README.org | `modules/ui/ophints/README.org` | ドキュメント | モジュール説明書 |
| .doommodule | `modules/ui/ophints/.doommodule` | 設定 | Doomモジュールメタデータ |
