# 画面設計書 6-TermControl（ターミナル表示）

## 概要

本ドキュメントは、Windows Terminal の実際のターミナル表示・入力を行う TermControl の画面設計書である。各ペイン内に配置され、シェルプロセスとの接続、テキスト表示・選択・コピー・貼り付け、スクロール、検索など、ターミナルとしてのコア機能を提供するコントロールである。

### 本画面の処理概要

**業務上の目的・背景**：TermControl はターミナルエミュレータの中核コンポーネントであり、ConPTY を通じたシェルプロセスとの通信、VTシーケンスの解析・描画、ユーザー入力の処理を担当する。開発者・システム管理者がコマンドラインで作業を行うための基盤機能を全て提供する。

**画面へのアクセス方法**：新しいタブまたはペイン分割によって自動的に作成・配置される。各ペイン内に1つの TermControl が配置される。

**主要な操作・処理内容**：
1. ターミナルテキストの描画・表示（Atlas レンダリングエンジン）
2. キーボード入力の処理・VTシーケンスへの変換
3. マウス操作（選択、スクロール、右クリックメニュー）
4. テキストのコピー・貼り付け
5. テキスト検索（SearchBoxControl との連携）
6. フォントサイズ調整・リセット
7. カラースキーム変更・シェーダーエフェクト切替・不透明度調整
8. コンテキストメニュー・クイックフィックスメニュー表示
9. シェル統合（コマンド検出・作業ディレクトリ追跡）
10. UIオートメーション対応（スクリーンリーダー連携）

**画面遷移**：
- 親：Pane（TerminalPage 内の各ペイン）
- 子：SearchBoxControl（検索ボックス）

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

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 31 | テキストのコピー | 主機能 | CopyCommandButton/SelectionContextMenuによりテキストをコピー |
| 32 | テキストの貼り付け | 主機能 | PasteCommandButtonによりテキストを貼り付け |
| 33 | 全選択 | 主機能 | SelectAllによりバッファ内全テキストを選択 |
| 34 | 入力の送信 | 主機能 | SendInputによりテキストをターミナルに送信 |
| 35 | マークモード切替 | 主機能 | ToggleMarkModeによりキーボードのみのテキスト選択モードを切替 |
| 36 | ブロック選択切替 | 主機能 | ToggleBlockSelectionにより矩形選択モードを切替 |
| 37 | 選択端点の切替 | 主機能 | SwitchSelectionEndpointにより選択の操作端点を切替 |
| 38 | 選択範囲を単語に拡張 | 主機能 | ExpandSelectionToWordにより選択範囲を単語境界まで拡張 |
| 39 | 選択テキストの色付け | 補助機能 | ColorSelectionにより選択テキストの色を設定 |
| 40 | コマンドの選択 | 主機能 | SelectCommandHandlerによりシェル統合でコマンドを選択 |
| 41 | 出力の選択 | 主機能 | SelectOutputHandlerによりシェル統合でコマンド出力を選択 |
| 44 | Web検索 | 補助機能 | 選択テキストを使用してWebブラウザで検索 |
| 45 | 上にスクロール | 主機能 | マウスホイールやキー操作による上スクロール |
| 46 | 下にスクロール | 主機能 | マウスホイールやキー操作による下スクロール |
| 55 | フォントサイズの調整 | 補助機能 | AdjustFontSizeによりフォントサイズを変更 |
| 56 | フォントサイズのリセット | 補助機能 | ResetFontSizeによりフォントサイズをリセット |
| 57 | カラースキームの設定 | 補助機能 | SetOverrideColorSchemeにより配色テーマを変更 |
| 58 | シェーダーエフェクト切替 | 補助機能 | ToggleShaderEffectsによりエフェクトを切替 |
| 59 | 不透明度の調整 | 補助機能 | AdjustOpacityにより透明度を調整 |
| 78 | ConPTY接続 | 主機能 | ConPTYを使用したシェルプロセスとの接続管理 |
| 80 | 接続の再起動 | 補助機能 | ターミナル接続の再起動処理 |
| 90 | Atlas レンダリングエンジン | 主機能 | DirectXベースのテキストレンダリング |
| 93 | VT (Virtual Terminal) パーサー | 主機能 | VTエスケープシーケンスの解析処理 |
| 94 | VTアダプター | 主機能 | VTシーケンスからTerminal APIコールへの変換 |
| 95 | ターミナル入力処理 | 主機能 | キーボード・マウス入力をVTシーケンスに変換 |
| 96 | テキストバッファ | 主機能 | テキストデータの格納・管理 |
| 97 | テキスト選択 | 主機能 | マウス・キーボードによるテキスト選択の管理 |
| 105 | シェル統合対応 | 補助機能 | OSCシーケンスによるコマンド検出・作業ディレクトリ追跡 |
| 109 | UIオートメーション対応 | 補助機能 | スクリーンリーダー等との連携 |
| 117 | コンテキストメニュー表示 | 補助機能 | 右クリックでContextMenuまたはSelectionContextMenuを表示 |

## 画面種別

コンポーネント / 表示・入力

## URL/ルーティング

該当なし

## 入出力項目

| 項目名 | 入出力 | 型 | 説明 |
|--------|--------|------|------|
| IControlSettings | 入力 | IControlSettings | ターミナル制御設定 |
| IControlAppearance | 入力 | IControlAppearance | 非フォーカス時の外観設定 |
| ITerminalConnection | 入力 | ITerminalConnection | ターミナル接続（ConPTY等） |
| KeyBindings | 入力 | IKeyBindings | キーバインド設定 |
| Title | 出力 | hstring | ターミナルタイトル |
| TabColor | 出力 | Color? | タブの色 |
| TaskbarState | 出力 | uint64_t | タスクバー状態 |
| TaskbarProgress | 出力 | uint64_t | タスクバー進捗 |
| WorkingDirectory | 出力 | hstring | 現在の作業ディレクトリ |
| ConnectionState | 出力 | ConnectionState | 接続状態 |

## 表示項目

| 項目名 | 表示位置 | 説明 |
|--------|----------|------|
| SwapChainPanel | Grid中央 | DirectX描画領域（ターミナルテキスト表示） |
| SearchBoxControl | Grid上部（オーバーレイ） | テキスト検索ボックス |
| ContextMenu | CommandBarFlyout | 右クリックコンテキストメニュー |
| SelectionContextMenu | CommandBarFlyout | テキスト選択時のコンテキストメニュー |
| QuickFixButton | Button | クイックフィックスメニュー起動ボタン |

## イベント仕様

### 1-テキストコピー（CopySelectionToClipboard）

テキスト選択状態でコピー操作を実行する。dismissSelection パラメータで選択を解除するか、singleLine で改行を除去するか、withControlSequences でVTシーケンスを含めるかを制御する。CopyFormat で プレーンテキスト/HTML/RTF の形式を指定できる。

### 2-テキスト貼り付け（PasteTextFromClipboard）

クリップボードからテキストを取得し、TerminalPage の _PasteFromClipboardHandler を通じて複数行/大量テキストの確認後にターミナルに送信する。

### 3-テキスト検索

_HandleFind が呼び出されると SearchBoxControl が表示される。ユーザーの入力に応じてテキストバッファ内を検索し、一致箇所をハイライトする。大文字/小文字の区別、正規表現検索に対応。

### 4-入力処理（キーボード・マウス）

PreviewKeyDown/_KeyDownHandler でキーイベントを処理し、VTシーケンスに変換してシェルプロセスに送信する。マウスイベントは PointerPressed/Released/Moved で処理する。CharacterReceived でテキスト入力を処理する。

### 5-スクロール

PointerWheelChanged/_MouseWheelHandler でマウスホイールスクロールを処理する。プログラムからの ScrollUp/ScrollDown メソッドでも制御可能。

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

該当なし

## メッセージ仕様

該当なし（TermControl レベルではメッセージダイアログを表示しない。通知はイベントを通じて TerminalPage に伝播する）

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| 接続切断 | ConnectionStateChanged イベントを発火し、TerminalPage がInfoBarまたは通知で表示 |
| レンダリングエラー | Atlas エンジンのフォールバック処理 |
| 入力処理エラー | ログ出力のみ |

## 備考

- UserControl ベース（d:DesignWidth=1024, d:DesignHeight=768）
- AllowDrop=True でファイルドロップに対応
- TabNavigation=Cycle でTabキーフォーカスを循環
- TSF（Text Services Framework）対応で IME 入力をサポート（TsfDataProvider）
- ControlInteractivity クラスとの協調でコンテンツの分離・再接続が可能
- SwapChainPanel を使用した DirectX ベースの高パフォーマンスレンダリング

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | TermControl.h | `src/cascadia/TerminalControl/TermControl.h` | TermControl クラス定義。TsfDataProvider（24-44行目）とTermControl公開メソッド（46-100行目）。IControlSettings/IControlAppearance/ITerminalConnection を入力として受け取る |
| 1-2 | ControlInteractivity.h | `src/cascadia/TerminalControl/ControlInteractivity.h` | TermControlのコアロジック。コンテンツの分離・再接続をサポート |

**読解のコツ**: TermControl は XAML UI層、ControlInteractivity はインタラクション層、ControlCore はコアロジック層の3層構造。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | TermControl.xaml | `src/cascadia/TerminalControl/TermControl.xaml` | XAMLレイアウト。SwapChainPanel、SearchBoxControl、コンテキストメニュー、クイックフィックスボタンの配置 |

#### Step 3: 入力処理層を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | TermControl.cpp | `src/cascadia/TerminalControl/TermControl.cpp` | イベントハンドラ実装。_KeyDownHandler, _CharacterHandler, _MouseWheelHandler 等 |

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

```
Pane
  └─ TermControl (XAML UI層)
       ├─ ControlInteractivity (インタラクション層)
       │    └─ ControlCore (コアロジック層)
       │         ├─ Terminal (ターミナルエンジン)
       │         │    ├─ VT パーサー
       │         │    ├─ テキストバッファ
       │         │    └─ 選択管理
       │         └─ Renderer (描画エンジン)
       │              └─ Atlas レンダリングエンジン
       ├─ SearchBoxControl (検索UI)
       ├─ ContextMenu (右クリックメニュー)
       ├─ SelectionContextMenu (選択時メニュー)
       └─ TSF DataProvider (IME入力)
            └─ ConPTY接続
                 └─ シェルプロセス
```

### データフロー図

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

キーボード入力 ────> TermControl                   ┌──> VTシーケンス
                     └─> ControlInteractivity      │    └─> ConPTY
                          └─> ControlCore          │         └─> シェル
                               └─> Terminal        │
                                                   ├──> 描画コマンド
シェル出力 ────────> ConPTY                         │    └─> Atlas
(VTシーケンス)       └─> VT パーサー               │         └─> SwapChainPanel
                          └─> Terminal             │
                               └─> テキストバッファ │
                                                   └──> イベント通知
マウス操作 ────────> TermControl                         (TitleChanged等)
(選択/スクロール)     └─> ControlInteractivity
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| TermControl.xaml | `src/cascadia/TerminalControl/TermControl.xaml` | テンプレート | XAML レイアウト定義 |
| TermControl.h | `src/cascadia/TerminalControl/TermControl.h` | ソース | クラス宣言 |
| TermControl.cpp | `src/cascadia/TerminalControl/TermControl.cpp` | ソース | UI層実装 |
| ControlInteractivity.h | `src/cascadia/TerminalControl/ControlInteractivity.h` | ソース | インタラクション層 |
| ControlCore.h | `src/cascadia/TerminalControl/ControlCore.h` | ソース | コアロジック層 |
| SearchBoxControl.xaml | `src/cascadia/TerminalControl/SearchBoxControl.xaml` | テンプレート | 検索ボックスUI |
| Terminal.hpp | `src/cascadia/TerminalCore/Terminal.hpp` | ソース | ターミナルエンジン |
