# 機能設計書 65-新しいウィンドウを開く

## 概要

本ドキュメントは、Windows Terminalにおける新しいウィンドウを開く機能（NewWindow）の設計を記述する。

### 本機能の処理概要

新しいWindows Terminalウィンドウを起動する機能である。指定されたプロファイルまたはデフォルトプロファイルで新しいウィンドウを開く。

**業務上の目的・背景**：複数のターミナルウィンドウを並べて作業する場合や、異なるプロファイルで別ウィンドウを開きたい場合に必要な機能である。マルチモニタ環境でのターミナル作業を効率化する。

**機能の利用シーン**：新しい作業コンテキストを別ウィンドウで開始したい場合、異なるプロファイル（WSL、PowerShell等）を別ウィンドウで使用したい場合に利用される。

**主要な処理内容**：
1. `_HandleNewWindow`ハンドラが`NewWindowArgs`を取得する
2. 指定されたプロファイルを解決する
3. バックグラウンドスレッドに切り替え、`ShellExecuteExW`を使用して新しいwt.exeプロセスを起動する
4. `-w -1 new-tab`コマンドライン引数により、新しいウィンドウでのタブ作成を指示する

**関連システム・外部連携**：Win32 API（ShellExecuteExW）を使用して、新しいwt.exeプロセスを起動する。`SEE_MASK_NOASYNC`フラグにより、バックグラウンドスレッドからの安全な呼び出しを保証する。

**権限による制御**：特別な権限制御は行わない。ただし、UACプロンプトが発生する可能性がある。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | TerminalPage（メイン画面） | 主画面 | _HandleNewWindowにより新しいTerminalウィンドウを起動 |

## 機能種別

プロセス起動操作

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| ContentArgs | INewContentArgs | No | 新しいウィンドウで開くコンテンツの引数（NewTerminalArgs） | - |

ContentArgsが未指定の場合はデフォルトのNewTerminalArgsが使用される。

### 入力データソース

キーバインドアクション（ShortcutAction::NewWindow）またはコマンドパレットからのアクション呼び出し。

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 新しいwt.exeプロセス | プロセス | ShellExecuteExWで起動される新しいTerminalウィンドウ |

### 出力先

OSレベルでの新しいプロセス起動。

## 処理フロー

### 処理シーケンス

```
1. ユーザーがNewWindowアクションを実行
   └─ ActionDispatcherがイベントを発火
2. _HandleNewWindow が NewWindowArgs を取得（取得できない場合はデフォルト引数を使用）
   └─ NewWindowArgs.ContentArgs() から INewContentArgs を取得
3. プロファイルの解決
   └─ _settings.GetProfileForArgs() でプロファイルGUIDを取得し、引数に設定
4. _OpenNewWindow コルーチンを呼び出す
   └─ NewTerminalArgs でない場合は co_return で終了
5. バックグラウンドスレッドに切り替え
   └─ co_await winrt::resume_background()
6. wt.exe のパスを取得
   └─ GetWtExePath()
7. コマンドラインを構築
   └─ "-w -1 new-tab {terminalArgs.ToCommandline()}"
8. ShellExecuteExW で新しいプロセスを起動
   └─ SEE_MASK_NOASYNC フラグ付き
```

### フローチャート

```mermaid
flowchart TD
    A[NewWindowアクション受信] --> B[_HandleNewWindow]
    B --> C{NewWindowArgs取得成功?}
    C -->|Yes| D[ContentArgs取得]
    C -->|No| E[デフォルトNewTerminalArgs作成]
    D --> F[プロファイル解決]
    E --> F
    F --> G[_OpenNewWindow コルーチン]
    G --> H{NewTerminalArgs?}
    H -->|No| I[co_return 終了]
    H -->|Yes| J[バックグラウンドスレッドへ]
    J --> K[wt.exe パス取得]
    K --> L[コマンドライン構築]
    L --> M[ShellExecuteExW]
    M --> N[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-65-01 | デフォルト引数 | NewWindowArgsが未指定の場合はデフォルトのNewTerminalArgsを使用する | 引数なし実行時 |
| BR-65-02 | 非ターミナルペイン除外 | NewTerminalArgsにキャストできない場合は何もしない | 非ターミナルコンテンツ指定時 |
| BR-65-03 | 新ウィンドウ強制 | コマンドラインに `-w -1` を含めることで必ず新しいウィンドウで開く | 常に適用 |
| BR-65-04 | バックグラウンド実行 | ShellExecuteExWはバックグラウンドスレッドで実行してUIスレッドをブロックしない | 常に適用 |

### 計算ロジック

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

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | Win32エラー | ShellExecuteExWが失敗した場合 | LOG_IF_WIN32_BOOL_FALSE でログ出力 |

### リトライ仕様

リトライ処理は行わない。

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

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

## パフォーマンス要件

ShellExecuteExWはバックグラウンドスレッドで実行されるため、UIスレッドはブロックされない。

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

- ShellExecuteExWの`lpVerb`に`"open"`を使用し、通常の実行を行う。
- `SEE_MASK_NOASYNC`フラグにより、バックグラウンドスレッドからの安全な呼び出しを保証する。

## 備考

- `_OpenNewWindow`メソッドは`this`を参照しないため、weak/strong_refは不要とコメントされている。
- Terminal終了直後にUACプロンプトが表示された場合でも、`SEE_MASK_NOASYNC`により昇格版wtが正常に起動する。

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | ActionArgs.h | `src/cascadia/TerminalSettingsModel/ActionArgs.h` | `NewWindowArgs`の定義を確認。`ContentArgs()`メソッドで`INewContentArgs`を取得する |

**読解のコツ**: `NewWindowArgs`は`NewTerminalArgs`をラップする構造。`ContentArgs()`で内部の`INewContentArgs`にアクセスする。

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

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

**主要処理フロー**:
1. **944行目**: `INewContentArgs`を初期化（nullptr）
2. **948行目**: `NewWindowArgs`へのtry_asキャスト
3. **957-960行目**: 引数なしの場合のデフォルト`NewTerminalArgs`作成
4. **962-966行目**: プロファイルの解決とGUID設定
5. **969行目**: `_OpenNewWindow(newContentArgs)`呼び出し

#### Step 3: プロセス起動処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | AppActionHandlers.cpp | `src/cascadia/TerminalApp/AppActionHandlers.cpp` | `_OpenNewWindow`コルーチン（889-939行目） |

**主要処理フロー**:
- **891行目**: `INewContentArgs`から`NewTerminalArgs`へのキャスト
- **901-904行目**: 非ターミナルの場合のガード処理
- **910行目**: `co_await winrt::resume_background()`でバックグラウンドスレッドへ切り替え
- **915行目**: `GetWtExePath()`でwt.exeのパスを取得
- **919-920行目**: コマンドライン構築（`-w -1 new-tab {commandline}`）
- **928-936行目**: `SHELLEXECUTEINFOW`構造体の設定と`ShellExecuteExW`呼び出し

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

```
ActionDispatcher (ShortcutAction::NewWindow)
    |
    +-- TerminalPage::_HandleNewWindow()           [AppActionHandlers.cpp:941]
            |
            +-- NewWindowArgs.ContentArgs()        (引数取得)
            +-- _settings.GetProfileForArgs()      (プロファイル解決)
            +-- TerminalPage::_OpenNewWindow()     [AppActionHandlers.cpp:889]
                    |
                    +-- co_await resume_background()  (スレッド切替)
                    +-- GetWtExePath()                (実行ファイルパス取得)
                    +-- ShellExecuteExW()             (プロセス起動)
```

### データフロー図

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

NewWindowArgs                  _HandleNewWindow()              新しいwt.exeプロセス
(ContentArgs/profile) -------> _OpenNewWindow() ------------->
                               GetWtExePath()
                               ShellExecuteExW()
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| AppActionHandlers.cpp | `src/cascadia/TerminalApp/AppActionHandlers.cpp` | ソース | _HandleNewWindow / _OpenNewWindow実装 |
| TerminalPage.h | `src/cascadia/TerminalApp/TerminalPage.h` | ヘッダー | _OpenNewWindowの宣言 |
| ActionArgs.h | `src/cascadia/TerminalSettingsModel/ActionArgs.h` | ヘッダー | NewWindowArgs定義 |
