# 機能設計書 67-ウィンドウ名の変更

## 概要

本ドキュメントは、Windows Terminalにおけるウィンドウ名の変更機能（RenameWindow）の設計を記述する。

### 本機能の処理概要

ウィンドウに任意の名前を付ける機能である。`RenameWindowArgs`で指定された名前をMonarchに通知し、名前の一意性が検証された上でウィンドウ名が設定される。

**業務上の目的・背景**：マルチウィンドウ環境で各ウィンドウを識別しやすくするために、ユーザーが自由にウィンドウ名を設定できるようにする機能である。`-w`オプションでのウィンドウ指定や、ウィンドウの識別表示に使用される。

**機能の利用シーン**：複数のTerminalウィンドウを開いて作業する際に、「開発用」「本番サーバー」「ログ監視」などの分かりやすい名前を付けて管理する場合に利用される。

**主要な処理内容**：
1. `_HandleRenameWindow`ハンドラが`RenameWindowArgs`から新しい名前を取得する
2. `RenameWindowRequestedArgs`を作成し、`RenameWindowRequested`イベントを発火する
3. TerminalWindowの`_RenameWindowRequested`がイベントを受け取り、`WindowName()`を設定する
4. ウィンドウ名の変更が完了すると、`IdentifyWindow()`が自動的に呼び出される

**関連システム・外部連携**：Monarch/Peasantアーキテクチャを使用したウィンドウ名の一意性検証。

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | TerminalPage（メイン画面） | 主画面 | _HandleRenameWindowによりウィンドウに名前を付ける |

## 機能種別

データ更新操作

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| Name | winrt::hstring | No | 設定するウィンドウ名。空文字列の場合は名前をクリアする | - |

### 入力データソース

キーバインドアクション（ShortcutAction::RenameWindow）またはコマンドパレットからのアクション呼び出し。WindowRenamer UIからの入力も間接的に同じパスを使用する。

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| RenameWindowRequested イベント | イベント | ウィンドウ名変更要求 |
| WindowName プロパティ | winrt::hstring | 更新されたウィンドウ名 |

### 出力先

ウィンドウプロパティ（WindowProperties::WindowName）に反映される。

## 処理フロー

### 処理シーケンス

```
1. ユーザーがRenameWindowアクションを実行
   └─ ActionDispatcherがイベントを発火
2. _HandleRenameWindow が RenameWindowArgs を取得
   └─ realArgs.Name() で新しい名前を取得
3. RenameWindowRequestedArgs を作成
   └─ winrt::make_self<RenameWindowRequestedArgs>(newName)
4. RenameWindowRequested イベントを発火
   └─ TerminalWindow::_RenameWindowRequested が受け取る
5. TerminalWindow が WindowName() を設定
   └─ WindowProperties::WindowName に新しい名前を設定
6. _windowPropertyChanged により IdentifyWindow() が呼び出される
   └─ ウィンドウ名が表示される
```

### フローチャート

```mermaid
flowchart TD
    A[RenameWindowアクション受信] --> B[_HandleRenameWindow]
    B --> C{RenameWindowArgs取得成功?}
    C -->|No| Z[終了]
    C -->|Yes| D[Name取得]
    D --> E[RenameWindowRequestedArgs作成]
    E --> F[RenameWindowRequested.raise]
    F --> G[TerminalWindow._RenameWindowRequested]
    G --> H[WindowName設定]
    H --> I[_windowPropertyChanged]
    I --> J[IdentifyWindow - 名前表示]
    J --> Z
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-67-01 | 名前の設定 | RenameWindowArgsのNameプロパティで指定された名前がウィンドウ名として設定される | 常に適用 |
| BR-67-02 | 自動識別表示 | ウィンドウ名変更後、StartupState::Initialized状態であればIdentifyWindowが自動呼び出しされる | 初期化完了後 |
| BR-67-03 | レイアウト保存 | ウィンドウ名はPersistState時にRenameWindowアクションとしてレイアウトに保存される | レイアウト保存時 |

### 計算ロジック

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

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

データベース操作は行わない。ただし、ApplicationState（JSON形式）にウィンドウレイアウトの一部として保存される。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| なし | リネーム失敗 | 名前が既に他のウィンドウで使用されている場合 | RenameFailed コールバックで通知 |

### リトライ仕様

リトライ処理は不要。ユーザーが別の名前で再試行可能。

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

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

## パフォーマンス要件

ユーザー操作に対して即座に応答すること。

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

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

## 備考

- ウィンドウ名の変更はアクションとしてレイアウト保存時に記録される（TerminalPage.cpp:2268行目付近）。
- `_RequestWindowRename`メソッドは非同期でMonarchに検証を依頼するため、即座に結果を取得できない。失敗時は`RenameFailed`で通知される。
- 空の名前を設定することでウィンドウ名をクリアできる。

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | TerminalPage.h | `src/cascadia/TerminalApp/TerminalPage.h` | `RenameWindowRequestedArgs`構造体（57-67行目）、`RenameWindowRequested`イベント（193行目）を確認 |
| 1-2 | ActionArgs.h | `src/cascadia/TerminalSettingsModel/ActionArgs.h` | `RENAME_WINDOW_ARGS`マクロ（246-247行目）: `Name`（winrt::hstring）のみ |

**読解のコツ**: `RenameWindowRequestedArgs`はTerminalPage.h内でinlineに定義されている構造体。`ProposedName()`メソッドで提案された名前にアクセスする。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | AppActionHandlers.cpp | `src/cascadia/TerminalApp/AppActionHandlers.cpp` | `_HandleRenameWindow`（1007-1020行目）のハンドラ実装 |

**主要処理フロー**:
1. **1012行目**: `RenameWindowArgs`へのtry_asキャスト
2. **1014行目**: `realArgs.Name()`で新しい名前を取得
3. **1015行目**: `RenameWindowRequestedArgs`を作成
4. **1016行目**: `RenameWindowRequested.raise()`でイベント発火

#### Step 3: イベントハンドリングを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | TerminalWindow.cpp | `src/cascadia/TerminalApp/TerminalWindow.cpp` | `_RenameWindowRequested`（1363-1366行目）でWindowNameを設定 |

**主要処理フロー**:
- **1365行目**: `WindowName(args.ProposedName())`で名前を設定

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

```
ActionDispatcher (ShortcutAction::RenameWindow)
    |
    +-- TerminalPage::_HandleRenameWindow()        [AppActionHandlers.cpp:1007]
            |
            +-- RenameWindowRequestedArgs 作成
            +-- RenameWindowRequested.raise()
                    |
                    +-- TerminalWindow::_RenameWindowRequested()  [TerminalWindow.cpp:1363]
                            |
                            +-- WindowName(proposedName)
                                    |
                                    +-- _windowPropertyChanged() [TerminalPage.cpp:5509]
                                            |
                                            +-- IdentifyWindow() (自動表示)
```

### データフロー図

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

RenameWindowArgs           _HandleRenameWindow()           WindowName 更新
(Name) ------------------>  RenameWindowRequested -------->  IdentifyWindow 自動表示
                            _RenameWindowRequested()
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| AppActionHandlers.cpp | `src/cascadia/TerminalApp/AppActionHandlers.cpp` | ソース | _HandleRenameWindowハンドラ |
| TerminalPage.h | `src/cascadia/TerminalApp/TerminalPage.h` | ヘッダー | RenameWindowRequestedArgs構造体、RenameWindowRequestedイベント |
| TerminalPage.cpp | `src/cascadia/TerminalApp/TerminalPage.cpp` | ソース | _RequestWindowRename、_windowPropertyChanged |
| TerminalWindow.cpp | `src/cascadia/TerminalApp/TerminalWindow.cpp` | ソース | _RenameWindowRequested実装 |
| ActionArgs.h | `src/cascadia/TerminalSettingsModel/ActionArgs.h` | ヘッダー | RENAME_WINDOW_ARGS / RenameWindowArgs定義 |
