# 機能設計書 37-選択端点の切替

## 概要

本ドキュメントは、Windows Terminal における「選択端点の切替」機能（SwitchSelectionEndpoint アクション）の設計を記述する。テキスト選択時の操作端点（カーソル移動で動く側）を開始点と終了点の間で切り替える機能である。

### 本機能の処理概要

**業務上の目的・背景**：マークモードやキーボード選択において、選択範囲の始点と終点のどちらを操作するかを切り替える機能である。これにより、選択範囲の両端を自由に調整できるようになり、選択範囲の精密な制御が可能となる。

**機能の利用シーン**：マークモードでテキストを選択中に、選択範囲の開始位置を調整したい場合に使用する。例えば、終了位置を先に決めてから開始位置を動かしたい場合に、端点を切り替えて調整する。

**主要な処理内容**：
1. _HandleSwitchSelectionEndpoint でアクションを受信
2. TermControl.SwitchSelectionEndpoint を呼び出し
3. ControlCore 経由で Terminal::SwitchSelectionEndpoint を実行
4. 選択端点フラグ（_selectionEndpoint）の状態に応じて3パターンで切り替え
5. 選択UIを更新

**関連システム・外部連携**：なし

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 6 | TermControl（ターミナル表示） | 主画面 | SwitchSelectionEndpoint により選択端点を切替 |
| 1 | TerminalPage（メイン画面） | 主画面 | _HandleSwitchSelectionEndpoint でアクションを処理 |

## 機能種別

テキスト操作 / 選択制御

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| (なし) | - | - | SwitchSelectionEndpoint アクションはパラメータを持たない | - |

### 入力データソース

- 現在の選択状態（IsSelectionActive）
- 現在の選択端点（_selectionEndpoint）
- 選択の開始点と終了点

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| (なし) | - | 選択端点が切り替わり、選択UIが更新される |

### 出力先

- Terminal の _selectionEndpoint フラグ
- Terminal の選択 pivot 値

## 処理フロー

### 処理シーケンス

```
1. _HandleSwitchSelectionEndpoint が sender と ActionEventArgs を受信
   └─ _senderOrActiveControl で TermControl を取得
2. TermControl.SwitchSelectionEndpoint → ControlCore.SwitchSelectionEndpoint
   └─ LockForWriting でロック取得
3. Terminal::SwitchSelectionEndpoint の分岐処理
   ├─ [Start && End フラグ両方] → End のみに切り替え（開始固定、終了を移動対象に）
   │   └─ _anchorInactiveSelectionEndpoint = true
   ├─ [End フラグのみ] → Start のみに切り替え（終了固定、開始を移動対象に）
   │   └─ pivot を end の位置に設定
   └─ [Start フラグのみ] → End のみに切り替え（開始固定、終了を移動対象に）
       └─ pivot を start の位置に設定
4. _updateSelectionUI で選択UIを更新
```

### フローチャート

```mermaid
flowchart TD
    A[SwitchSelectionEndpoint アクション受信] --> B[TermControl.SwitchSelectionEndpoint]
    B --> C[ControlCore.SwitchSelectionEndpoint]
    C --> D{選択がアクティブ?}
    D -->|No| Z[false を返す]
    D -->|Yes| E{現在の _selectionEndpoint}
    E -->|Start+End| F["End のみに設定\n_anchorInactiveSelectionEndpoint = true"]
    E -->|End のみ| G["Start のみに設定\npivot = end"]
    E -->|Start のみ| H["End のみに設定\npivot = start"]
    F --> I[_updateSelectionUI]
    G --> I
    H --> I
    I --> J[true を返す]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-37-01 | 選択必須 | 選択がアクティブでない場合は切り替えができない（false を返す） | IsSelectionActive が false |
| BR-37-02 | 両端点選択時 | Start と End の両方が選択されている場合（カーソル移動中）、End のみに切り替える | Start && End フラグ |
| BR-37-03 | End 移動中 | End を移動中の場合、Start に切り替え、pivot を end の位置に設定 | End フラグのみ |
| BR-37-04 | Start 移動中 | Start を移動中の場合、End に切り替え、pivot を start の位置に設定 | Start フラグのみ |

### 計算ロジック

なし

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

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

本機能はデータベースを使用しない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 選択なし | テキストが選択されていない状態で実行 | false を返し、アクションを未処理とする |
| - | コントロール未取得 | アクティブな TermControl がない | 何もしない |

### リトライ仕様

リトライは行わない。

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

Terminal::SwitchSelectionEndpoint の実行中は LockForWriting でロックを保持する。

## パフォーマンス要件

即座に端点切替が完了すること。

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

特になし。

## 備考

- SelectionEndpoint は Start と End のビットフラグで管理されている
- pivot は選択の固定点を表し、ユーザーが選択範囲を動かす際の基準となる
- _anchorInactiveSelectionEndpoint は非アクティブな端点を固定するためのフラグ

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | AppActionHandlers.cpp | `src/cascadia/TerminalApp/AppActionHandlers.cpp` | _HandleSwitchSelectionEndpoint がエントリーポイント |

**主要処理フロー**:
1. **1437-1445行目**: _senderOrActiveControl で TermControl を取得し、control.SwitchSelectionEndpoint() の戻り値を handled に設定

#### Step 2: ControlCore 層

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | ControlCore.cpp | `src/cascadia/TerminalControl/ControlCore.cpp` | SwitchSelectionEndpoint の実装 |

**主要処理フロー**:
- **1415-1425行目**: LockForWriting、選択アクティブ確認、_terminal->SwitchSelectionEndpoint() 呼び出し、_updateSelectionUI

#### Step 3: Terminal コア層

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | TerminalSelection.cpp | `src/cascadia/TerminalCore/TerminalSelection.cpp` | Terminal::SwitchSelectionEndpoint の3パターン分岐 |

**主要処理フロー**:
- **408-431行目**: SelectionEndpoint フラグの状態に基づく3パターンの端点切り替えロジック

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

```
TerminalPage::_HandleSwitchSelectionEndpoint (AppActionHandlers.cpp:1437)
    |
    +-- TermControl::SwitchSelectionEndpoint (TermControl.cpp:2583)
           |
           +-- ControlCore::SwitchSelectionEndpoint (ControlCore.cpp:1415)
                  |
                  +-- Terminal::SwitchSelectionEndpoint (TerminalSelection.cpp:408)
                  +-- _updateSelectionUI
```

### データフロー図

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

_selectionEndpoint   --> SwitchSelectionEndpoint          --> _selectionEndpoint 更新
  (Start/End フラグ)     |                                      pivot 更新
                         v
                     3パターン分岐                         --> _updateSelectionUI
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| AppActionHandlers.cpp | `src/cascadia/TerminalApp/AppActionHandlers.cpp` | ソース | _HandleSwitchSelectionEndpoint アクションハンドラ |
| TermControl.cpp | `src/cascadia/TerminalControl/TermControl.cpp` | ソース | SwitchSelectionEndpoint の委譲 |
| TermControl.h | `src/cascadia/TerminalControl/TermControl.h` | ヘッダ | SwitchSelectionEndpoint 宣言 |
| ControlCore.cpp | `src/cascadia/TerminalControl/ControlCore.cpp` | ソース | SwitchSelectionEndpoint の実装 |
| TerminalSelection.cpp | `src/cascadia/TerminalCore/TerminalSelection.cpp` | ソース | Terminal::SwitchSelectionEndpoint の実装 |
| Terminal.hpp | `src/cascadia/TerminalCore/Terminal.hpp` | ヘッダ | SwitchSelectionEndpoint 宣言 |
