# 画面設計書 12-Modeline

## 概要

本ドキュメントは、Doom EmacsにおけるModeline（ステータスバー）画面の設計仕様を定義するものである。doom-modelineパッケージまたは軽量版（+light）を利用した画面下部のステータスバー表示について、その表示仕様、セグメント構成、およびカスタマイズ方法を記載する。

### 本画面の処理概要

Modeline画面は、Emacsウィンドウの下部に表示されるステータスバーであり、現在のバッファ状態、カーソル位置、モード情報などを常時表示する機能である。

**業務上の目的・背景**：エディタでの作業中、ファイル名、保存状態、カーソル位置、現在のモード、Git状態など多数の情報を常に把握する必要がある。本機能は、これらの情報を画面下部の限られたスペースに効率的に配置し、ユーザーの作業コンテキスト認識を支援する。従来のEmacsモードラインより視認性が高く、アイコンや色による直感的な情報表示を実現する。

**画面へのアクセス方法**：Doom Emacsの初期化後に自動的に有効化される（`doom-after-init`フック）。手動で有効化する場合は`doom-modeline-mode`コマンドを実行する。

**主要な操作・処理内容**：
1. ファイル名とパスの表示（プロジェクトルートからの相対パス）
2. カーソル位置（行:列、ファイル内位置%）の表示
3. バッファの変更状態の視覚的表示
4. メジャーモード、マイナーモードの表示
5. Gitブランチと差分情報の表示
6. 検索マッチ数、マクロ記録状態の表示
7. ファイルエンコーディング（非UTF-8時のみ）の表示

**画面遷移**：Modelineは常時表示される要素であり、画面遷移の概念はない。ただし、magit-status-mode以外のmagitバッファでは自動的に非表示になる。

**権限による表示制御**：本機能に権限による表示制御はない。全ユーザーが同一の機能を利用可能である。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 32 | カスタムモードライン | 主機能 | doom-modelineによるステータスバー表示 |
| 4 | UI 設定 | 補助機能 | フォント、サイズ、エンコーディング表示設定 |
| 65 | Gitクライアント統合 | 補助機能 | Gitブランチ、差分情報表示 |
| 25 | 起動時ダッシュボード表示 | 補助機能 | ダッシュボード専用モードライン表示 |

## 画面種別

ステータスバー（常時表示コンポーネント）

## URL/ルーティング

Emacsモード: `doom-modeline-mode`
表示位置: ウィンドウ下部の`mode-line`

## 入出力項目

| 項目名 | 入力/出力 | データ型 | 説明 |
|--------|----------|---------|------|
| バッファ名 | 入力 | 文字列 | 現在のバッファ名 |
| ファイルパス | 入力 | 文字列 | バッファに関連付けられたファイルパス |
| カーソル位置 | 入力 | 整数 | 行番号、列番号、ファイル内位置 |
| メジャーモード | 入力 | シンボル | 現在のメジャーモード |
| Git情報 | 入力 | 文字列 | vcモードからのGit状態 |
| 検索状態 | 入力 | オブジェクト | anzu/evil-anzuからの検索マッチ情報 |
| モードライン文字列 | 出力 | 文字列 | フォーマットされたステータスバー表示 |

## 表示項目

| 項目名 | 表示位置 | 説明 |
|--------|---------|------|
| バー | 左端 | アクティブ/非アクティブウィンドウを示す縦バー |
| マッチ情報 | 左側 | 検索マッチ数、マクロ記録状態 |
| バッファ名 | 左側 | プロジェクトからの相対パス付きファイル名 |
| 位置情報 | 左側 | 行:列 位置% |
| ファイルサイズ | 右側 | バッファのサイズ |
| メジャーモード | 右側 | 現在のメジャーモード名 |
| VCS情報 | 右側 | Gitブランチとアイコン |
| エンコーディング | 右側 | 非UTF-8/非デフォルトEOL時のみ表示 |
| チェッカー状態 | 右側 | flycheck/flymakeのエラー・警告数 |

## イベント仕様

### 1-フォントサイズ変更

`doom/increase-font-size`または`doom/decrease-font-size`でフォントサイズを変更すると、モードラインの高さが自動調整される（`+modeline-resize-for-font-h`関数）。

### 2-テーマ変更

`doom-load-theme-hook`でテーマが変更されると、モードラインのバーが再描画される（`doom-modeline-refresh-bars`関数）。

### 3-検索実行

isearchまたはevil-exの検索を実行すると、anzu/evil-anzuが検索マッチ数を収集し、モードラインに表示する。

### 4-バッファ切り替え

バッファを切り替えると、バッファ名、ファイルパス、VCS情報などが更新される。キャッシュ機構により、パフォーマンスが最適化されている。

### 5-magitモード

magitバッファに入ると、magit-status-modeではプロジェクト用モードラインが表示され、その他のmagitバッファではモードラインが非表示になる（`+modeline-hide-in-non-status-buffer-h`関数）。

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

本機能はデータベースを使用しない。表示情報はEmacsの各種変数と関数から動的に取得される。

## メッセージ仕様

| メッセージ種別 | メッセージ内容 | 表示条件 |
|--------------|--------------|---------|
| なし | - | モードラインはメッセージを表示しない（情報表示のみ） |

## 例外処理

| 例外状態 | 処理内容 |
|---------|---------|
| リモートファイル | ファイルパスキャッシュをスキップ |
| TTYモード | マウスイベント変数が未定義の場合、nilに設定 |
| 非magit-statusバッファ | モードラインを非表示（hide-mode-line-mode） |

## 備考

- 標準版（doom-modeline）と軽量版（+light）の2つの実装が存在
- 軽量版は`mode-line-format`を直接操作し、より高パフォーマンス
- プロジェクト情報はprojectileを無効化して独自にキャッシュ
- ファイルエンコーディングはUTF-8以外の場合のみ表示
- EOLはOSのデフォルト（Unix: LF, Windows: CRLF）以外の場合のみ表示

---

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

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

### 推奨読解順序

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

モードラインセグメントの構造と、`mode-line-format`の概念を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | config.el | `modules/ui/modeline/config.el` | 16-27行目: doom-modeline変数の初期設定 |
| 1-2 | +light.el | `modules/ui/modeline/+light.el` | 43-47行目: `+modeline-format-alist`のデータ構造 |

**読解のコツ**: Emacsの`mode-line-format`は特殊なデータ構造であり、`:eval`フォームや`propertize`を多用する。まず標準のmode-line-formatのドキュメントを読むことを推奨。

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

モードラインの初期化処理を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | config.el | `modules/ui/modeline/config.el` | 7-9行目: doom-modeline-modeの有効化フック |

**主要処理フロー**:
1. **9行目**: `doom-after-init`フックで`doom-modeline-mode`を有効化
2. **10行目**: サイズ表示モードを有効化
3. **11行目**: 列番号表示を有効化

#### Step 3: 標準版モードラインの設定を理解する

doom-modelineパッケージの設定を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | config.el | `modules/ui/modeline/config.el` | 16-27行目: 各種表示オプションの設定 |

**主要処理フロー**:
- **16行目**: バー幅を3に設定
- **17-20行目**: GitHub、mu4e、persp-name、minor-modesを無効化
- **21行目**: メジャーモードアイコンを無効化
- **22行目**: チェッカー表示をシンプルに
- **23行目**: ファイル名をプロジェクト相対パスで表示
- **26-27行目**: エンコーディング/EOLを非デフォルト時のみ表示

#### Step 4: magit連携を理解する

magitモードでのモードライン表示制御を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | config.el | `modules/ui/modeline/config.el` | 38-43行目: magit-mode-hookでの表示制御 |

**主要処理フロー**:
- **41-42行目**: magit-status-modeではmagit用モードラインを設定
- **43行目**: その他のmagitバッファではモードラインを非表示

#### Step 5: anzu連携（検索マッチ表示）を理解する

検索時のマッチ数表示を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | config.el | `modules/ui/modeline/config.el` | 48-54行目: anzuとevil-anzuの設定 |

#### Step 6: 軽量版の実装を理解する（オプション）

+lightフラグ使用時の軽量実装を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 6-1 | +light.el | `modules/ui/modeline/+light.el` | 全体: mode-line-formatを直接操作する軽量実装 |

**主要処理フロー**:
- **175-182行目**: `+modeline-format-left`と`+modeline-format-right`のバッファローカル変数
- **524-530行目**: デフォルトモードライン定義（:main）
- **589-612行目**: `+modeline-mode`マイナーモード定義

#### Step 7: autoload関数を理解する

フォントサイズ変更時の高さ調整などを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 7-1 | autoload.el | `modules/ui/modeline/autoload.el` | 5-17行目: フォントサイズ変更時の高さ調整 |

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

```
doom-after-init
    │
    └─ doom-modeline-mode
           │
           ├─ size-indication-mode (ファイルサイズ表示)
           │
           ├─ column-number-mode (列番号表示)
           │
           ├─ doom-modeline-refresh-bars (テーマ変更時)
           │
           └─ モードライン更新
                  │
                  ├─ バッファIDキャッシュ生成
                  │      └─ +modeline--generate-buffer-id-cache-h
                  │
                  ├─ anzu検索状態取得
                  │      └─ +modeline--anzu
                  │
                  ├─ evil置換状態取得
                  │      └─ +modeline--evil-substitute
                  │
                  ├─ マクロ記録状態取得
                  │      └─ +modeline--macro-recording
                  │
                  └─ フォントサイズ調整
                         └─ +modeline-resize-for-font-h
```

### データフロー図

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

buffer-file-name   ───▶ doom-modeline-buffer-file  ───┐
                        -name-style                    │
                                                       │
line-number-at-pos ───▶ 位置計算                   ───┤
column-number                                          │
                                                       ├──▶ mode-line-format
vc-mode            ───▶ Gitブランチ抽出            ───┤
                                                       │
anzu--state        ───▶ 検索マッチ数計算           ───┤
                                                       │
flycheck-current   ───▶ エラー/警告数集計          ───┘
-errors
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| config.el | `modules/ui/modeline/config.el` | ソース | メイン設定ファイル、doom-modelineの設定 |
| +light.el | `modules/ui/modeline/+light.el` | ソース | 軽量版モードライン実装 |
| autoload.el | `modules/ui/modeline/autoload.el` | ソース | フォントサイズ変更対応、環境変数更新 |
| packages.el | `modules/ui/modeline/packages.el` | 設定 | パッケージ依存関係定義 |
