# 機能設計書 40-ウィンドウ選択ナビゲーション

## 概要

本ドキュメントは、Doom Emacsにおけるウィンドウ選択ナビゲーション機能の設計を記載する。この機能は、ace-window、switch-window、winumパッケージを使用して、複数ウィンドウ間の素早い切り替えを実現する。

### 本機能の処理概要

**業務上の目的・背景**：複数のウィンドウを同時に開いて作業する際、目的のウィンドウへの移動に時間がかかることがある。ウィンドウ選択ナビゲーション機能は、ヒント文字や番号を使用して瞬時にウィンドウを選択できるようにし、マルチウィンドウでの作業効率を大幅に向上させる。

**機能の利用シーン**：
- 多数のウィンドウが開いている状態で特定のウィンドウに移動する場合
- キーボードのみでウィンドウ間を素早く切り替える場合
- ウィンドウ番号を指定して直接移動する場合（+numbersフラグ）

**主要な処理内容**：
1. ace-window（デフォルト）またはswitch-window（+switch-windowフラグ）の初期化
2. other-windowコマンドのリマップ
3. ヒント文字（qwerty配列）によるウィンドウ選択
4. winum（+numbersフラグ）による番号指定選択
5. Evil統合によるキーバインド

**関連システム・外部連携**：
- ace-windowパッケージ（デフォルト）
- switch-windowパッケージ（+switch-windowフラグ時）
- winumパッケージ（+numbersフラグ時）

**権限による制御**：特になし

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 30 | Window Select | 主機能 | 番号・ヒント文字によるウィンドウ選択 |

## 機能種別

UI操作 / ナビゲーション

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| aw-keys | list | No | ace-windowのヒント文字 | 文字リスト |
| aw-scope | symbol | No | 選択対象のスコープ | 'frame |
| switch-window-shortcut-style | symbol | No | switch-windowのスタイル | 'qwerty |

### 入力データソース

- ユーザーのキー入力
- ウィンドウリスト

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 選択されたウィンドウ | window | フォーカス対象のウィンドウ |

### 出力先

選択されたウィンドウへのフォーカス移動

## 処理フロー

### 処理シーケンス

```
1. ace-window または switch-window コマンド呼び出し
   └─ other-window からリマップ
2. ウィンドウリストの取得
   └─ 現在フレーム内のウィンドウ
3. ヒント文字の表示
   └─ 各ウィンドウに文字を割り当て
4. ユーザー入力待機
   └─ ヒント文字の入力
5. ウィンドウ選択実行
   └─ 対象ウィンドウにフォーカス移動
```

### フローチャート

```mermaid
flowchart TD
    A[ウィンドウ選択開始] --> B{使用パッケージ}
    B -->|+switch-window| C[switch-window]
    B -->|デフォルト| D[ace-window]
    C --> E[ヒント表示]
    D --> E
    E --> F{+numbersフラグ?}
    F -->|Yes| G[winum番号表示]
    F -->|No| H[ヒント文字表示]
    G --> I[ユーザー入力待機]
    H --> I
    I --> J{入力タイプ}
    J -->|数字| K[winum-select-window-N]
    J -->|文字| L[ace-window/switch-window選択]
    K --> M[ウィンドウフォーカス]
    L --> M
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-40-1 | スコープ | 現在のフレーム内のウィンドウのみ対象 | aw-scope = 'frame |
| BR-40-2 | 背景表示 | 選択中は背景をぼかして視認性向上 | aw-background = t |
| BR-40-3 | ヒント文字 | qwerty配列の文字を使用 | aw-keys または switch-window-shortcut-style |
| BR-40-4 | +numbers時 | 0-9キーでウィンドウ選択可能 | modulep! +numbers |
| BR-40-5 | モードライン非変更 | winumはモードラインを変更しない | winum-auto-setup-mode-line = nil |

### 計算ロジック

特になし

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

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

該当なし（データベース操作を行わない）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 無効な入力 | 存在しないウィンドウ番号 | 操作をキャンセル |

### リトライ仕様

該当なし

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

該当なし

## パフォーマンス要件

- ヒント表示が即座に行われること
- ウィンドウ選択が遅延なく実行されること

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

特になし

## 備考

- ace-windowパッケージのピン留めバージョン: 77115afc1b0b9f633084cf7479c767988106c196
- switch-windowパッケージのピン留めバージョン: 8f771b571a1e60fac2d2a9845c0a5a52d5b440df
- winumパッケージのピン留めバージョン: c5455e866e8a5f7eab6a7263e2057aff5f1118b9

---

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

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

### 推奨読解順序

#### Step 1: パッケージ定義を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | packages.el | `modules/ui/window-select/packages.el` | 依存パッケージの条件付き定義 |

**読解のコツ**: `modulep!`でフラグに応じたパッケージ選択を行っている。

**主要処理フロー**:
- **4-5行目**: +switch-windowフラグ時はswitch-window、それ以外はace-windowを使用
- **8-9行目**: +numbersフラグ時にwinumを追加

#### Step 2: 設定ファイルを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | config.el | `modules/ui/window-select/config.el` | 各パッケージの設定 |

**主要処理フロー**:
- **3-9行目**: switch-window設定（+switch-windowフラグ時）
  - **7行目**: other-windowをswitch-windowにリマップ
  - **9行目**: qwertyショートカットスタイル
- **12-21行目**: ace-window設定（デフォルト）
  - **16行目**: other-windowをace-windowにリマップ
  - **18-19行目**: +numbersフラグなしの場合のヒント文字設定
  - **20-21行目**: スコープと背景設定
- **24-42行目**: winum設定（+numbersフラグ時）
  - **26行目**: doom-switch-window-hookで読み込み
  - **30行目**: モードライン自動設定を無効化
  - **31行目**: winum-mode有効化
  - **32-42行目**: Evilウィンドウマップへの番号キーバインド

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

```
other-window (リマップ)
    │
    ├─ (+switch-windowフラグ)
    │      └─ switch-window
    │             └─ ウィンドウ選択
    │
    └─ (デフォルト)
           └─ ace-window
                  │
                  ├─ aw-keys でヒント文字決定
                  │
                  └─ ウィンドウ選択

(+numbersフラグ)
    │
    └─ winum-mode
           │
           └─ evil-window-map
                  ├─ 0: winum-select-window-0-or-10
                  ├─ 1: winum-select-window-1
                  ├─ 2: winum-select-window-2
                  │  ...
                  └─ 9: winum-select-window-9
```

### データフロー図

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

キー入力 ──────────▶ コマンド判定 ──────▶ ace-window/switch-window
    │                    │
ウィンドウリスト ──▶ ヒント文字割り当て ▶ 視覚的表示
    │                    │
ヒント入力 ────────▶ ウィンドウ特定 ────▶ フォーカス移動
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| config.el | `modules/ui/window-select/config.el` | ソース | パッケージ設定 |
| packages.el | `modules/ui/window-select/packages.el` | 設定 | 依存パッケージ定義 |
