# 機能設計書 66-ウィンドウの識別

## 概要

本ドキュメントは、Windows Terminalにおけるウィンドウの識別機能（IdentifyWindow / IdentifyWindows）の設計を記述する。

### 本機能の処理概要

現在のウィンドウのIDと名前をオーバーレイ（TeachingTip「トースト」）で表示する機能である。単一ウィンドウの識別と全ウィンドウ一斉識別の2つのアクションが存在する。

**業務上の目的・背景**：マルチウィンドウ環境で複数のTerminalウィンドウを開いている場合、どのウィンドウがどのID・名前を持っているかを素早く確認するための機能である。ウィンドウ管理やリモート操作のコンテキスト確認に有用。

**機能の利用シーン**：複数のTerminalウィンドウを開いて作業している際に、各ウィンドウのIDや名前を確認したい場合に利用される。特にウィンドウ名を指定したアクション（例：`-w`オプション）を使用する前の確認に有用。

**主要な処理内容**：
1. `_HandleIdentifyWindow`：現在のウィンドウのみの識別情報を表示する
2. `_HandleIdentifyWindows`：`IdentifyWindowsRequested`イベントを発火し、Monarch経由で全Peasant（全ウィンドウ）に識別情報表示を指示する
3. `IdentifyWindow()`メソッドがTeachingTip（WindowIdToast）を遅延ロードし、トーストとして表示する
4. ウィンドウ名が変更された場合にも自動的にIdentifyWindowが呼び出される

**関連システム・外部連携**：Monarch/Peasantアーキテクチャ（ウィンドウ間通信）と連携。`IdentifyWindows`アクションはMonarchを経由して全ウィンドウに通知される。

**権限による制御**：特別な権限制御は行わない。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | TerminalPage（メイン画面） | 主画面 | _HandleIdentifyWindow/IdentifyWindowsによりウィンドウ情報をオーバーレイ表示 |

## 機能種別

情報表示操作

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| なし | - | - | パラメータなし | - |

### 入力データソース

キーバインドアクション（ShortcutAction::IdentifyWindow / ShortcutAction::IdentifyWindows）またはウィンドウ名変更時の自動呼び出し。

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| WindowIdToast | TeachingTip | ウィンドウIDと名前を表示するオーバーレイUI |
| IdentifyWindowsRequested イベント | イベント | 全ウィンドウへの識別要求（IdentifyWindowsの場合） |

### 出力先

画面上にTeachingTip（トースト）としてウィンドウID・名前を表示。

## 処理フロー

### 処理シーケンス

```
1. ユーザーがIdentifyWindowまたはIdentifyWindowsアクションを実行
   └─ ActionDispatcherがイベントを発火
2a. [IdentifyWindow の場合] _HandleIdentifyWindow が呼び出される
   └─ IdentifyWindow() を直接呼び出す
2b. [IdentifyWindows の場合] _HandleIdentifyWindows が呼び出される
   └─ IdentifyWindowsRequested イベントを発火
   └─ Monarch 経由で全 Peasant に配信
   └─ 各 Peasant の IdentifyWindow() が呼び出される
3. IdentifyWindow() がTeachingTipを遅延ロード
   └─ WindowIdToast が null なら FindName("WindowIdToast") でロード
4. TeachingTipのテーマを更新
   └─ _UpdateTeachingTipTheme()
5. トーストを開く
   └─ _windowIdToast->Open()
```

### フローチャート

```mermaid
flowchart TD
    A{IdentifyWindow or IdentifyWindows?}
    A -->|IdentifyWindow| B[_HandleIdentifyWindow]
    A -->|IdentifyWindows| C[_HandleIdentifyWindows]
    B --> D[IdentifyWindow]
    C --> E[IdentifyWindowsRequested.raise]
    E --> F[Monarch経由で全Peasantに配信]
    F --> D
    D --> G{_windowIdToast == null?}
    G -->|Yes| H[FindName でTeachingTipをロード]
    H --> I[Toastオブジェクト作成]
    G -->|No| J[テーマ更新]
    I --> J
    J --> K[_windowIdToast->Open]
    K --> L[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-66-01 | 遅延ロード | WindowIdToastのTeachingTipは初回使用時にFindNameで遅延ロードされる | 初回表示時 |
| BR-66-02 | ライトディスミス無効 | IsLightDismissEnabled=falseに設定。マルチウィンドウでの問題を回避 | 常に適用 |
| BR-66-03 | 名前変更時の自動表示 | ウィンドウ名が変更された場合（初期化完了後）、IdentifyWindowが自動的に呼び出される | WindowNameプロパティ変更時 |
| BR-66-04 | IdentifyWindowsの全配信 | IdentifyWindowsはMonarch経由で全Peasantに配信される | IdentifyWindowsアクション実行時 |

### 計算ロジック

特別な計算ロジックはない。

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

データベース操作は行わない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| なし | - | TeachingTipがXAML Islandsで正常に動作しない既知の問題あり | microsoft-ui-xaml#4382 |

### リトライ仕様

リトライ処理は不要。

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

トランザクション管理は不要。

## パフォーマンス要件

TeachingTipの遅延ロードにより、初回表示時に若干の遅延が発生する可能性がある。

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

特別なセキュリティ考慮事項はない。

## 備考

- `_HandleIdentifyWindows`のコメントに記載の通り、TeachingTipはXAML Islandsで奇妙な動作をする既知の問題がある（microsoft-ui-xaml#4382）。
- ウィンドウ名が設定されていない場合、名前は「<unnamed-window>」として表示される。
- `_windowPropertyChanged`イベントハンドラにより、ウィンドウ名変更時にStartupState::Initializedであれば自動的にIdentifyWindowが呼び出される。

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | TerminalPage.h | `src/cascadia/TerminalApp/TerminalPage.h` | `IdentifyWindow()`メソッド宣言（154行目）、`IdentifyWindowsRequested`イベント（192行目）を確認 |

**読解のコツ**: `_windowIdToast`は`std::shared_ptr<Toast>`型で、TeachingTipをラップする。Toastクラスは一定時間後に自動で閉じるUIコンポーネント。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | AppActionHandlers.cpp | `src/cascadia/TerminalApp/AppActionHandlers.cpp` | `_HandleIdentifyWindows`（984-989行目）と`_HandleIdentifyWindow`（1000-1005行目）の2つのハンドラ |

**主要処理フロー**:
1. **984-989行目**: `_HandleIdentifyWindows` - `IdentifyWindowsRequested.raise()`で全ウィンドウへの通知を発火
2. **1000-1005行目**: `_HandleIdentifyWindow` - `IdentifyWindow()`を直接呼び出す

#### Step 3: 表示処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | TerminalPage.cpp | `src/cascadia/TerminalApp/TerminalPage.cpp` | `IdentifyWindow()`（4521-4543行目）の実装 |

**主要処理フロー**:
- **4525-4536行目**: TeachingTipの遅延ロードとToastオブジェクトの作成
- **4532行目**: `IsLightDismissEnabled(false)`設定
- **4537行目**: テーマの更新
- **4541行目**: `_windowIdToast->Open()`でトーストを表示

#### Step 4: 自動表示を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | TerminalPage.cpp | `src/cascadia/TerminalApp/TerminalPage.cpp` | `_windowPropertyChanged`（5509-5523行目）でWindowName変更時にIdentifyWindowを呼び出す |

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

```
ActionDispatcher
    |
    +-- TerminalPage::_HandleIdentifyWindows()      [AppActionHandlers.cpp:984]
    |       |
    |       +-- IdentifyWindowsRequested.raise()
    |               |
    |               +-- Monarch → 全Peasant → IdentifyWindow()
    |
    +-- TerminalPage::_HandleIdentifyWindow()       [AppActionHandlers.cpp:1000]
            |
            +-- TerminalPage::IdentifyWindow()      [TerminalPage.cpp:4521]
                    |
                    +-- FindName("WindowIdToast")   (遅延ロード - 初回のみ)
                    +-- Toast::Open()               (トースト表示)
```

### データフロー図

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

IdentifyWindowアクション -> _HandleIdentifyWindow() ->     WindowIdToast表示
                            IdentifyWindow()

IdentifyWindowsアクション -> _HandleIdentifyWindows() ->   IdentifyWindowsRequested
                             Monarch配信 ->                 全ウィンドウでToast表示
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| AppActionHandlers.cpp | `src/cascadia/TerminalApp/AppActionHandlers.cpp` | ソース | _HandleIdentifyWindow(s)ハンドラ |
| TerminalPage.h | `src/cascadia/TerminalApp/TerminalPage.h` | ヘッダー | IdentifyWindow宣言、IdentifyWindowsRequestedイベント |
| TerminalPage.cpp | `src/cascadia/TerminalApp/TerminalPage.cpp` | ソース | IdentifyWindow実装、_windowPropertyChanged |
| TerminalWindow.h | `src/cascadia/TerminalApp/TerminalWindow.h` | ヘッダー | IdentifyWindow中継宣言 |
| TerminalWindow.cpp | `src/cascadia/TerminalApp/TerminalWindow.cpp` | ソース | IdentifyWindow中継実装 |
