# 通知設計書 34-StringSentEventArgs

## 概要

本ドキュメントは、Windows Terminal におけるテキスト文字列送信通知（StringSentEventArgs）の設計仕様を記述する。StringSentEventArgs は、テキスト文字列がターミナルに送信される際に TermControl から発火されるイベントであり、送信されるテキスト全体をブロードキャストする。

### 本通知の処理概要

StringSentEventArgs は、ターミナルコントロールへのテキスト文字列送信をリスナーにブロードキャストするための通知機構である。SendInput メソッドおよびペースト操作（_pasteTextWithBroadcast）から発火される。

**業務上の目的・背景**：Windows Terminal のブロードキャスト入力機能において、キー単位の入力（KeySent / CharSent）だけでなく、文字列単位の入力（SendInput やペースト操作）も他のペインに転送する必要がある。StringSentEventArgs は、アクションやキーバインドを通じた文字列送信やドラッグ&ドロップによるテキスト入力、クリップボードからのペーストなど、文字列レベルの入力をブロードキャストする。

**通知の送信タイミング**：TermControl の `SendInput` メソッドまたは `_pasteTextWithBroadcast` メソッドが呼ばれた際に発火する。StringSent イベントにリスナーが登録されている場合のみ、StringSentEventArgs オブジェクトが生成されイベントが発火する。

**通知の受信者**：StringSent イベントをサブスクライブしているリスナー。主にブロードキャスト入力機能を利用するアプリケーション層のコンポーネントが受信する。

**通知内容の概要**：送信されるテキスト文字列（Text, hstring型）の1つの情報を含む。KeySentEventArgs や CharSentEventArgs と異なり、文字列全体を一度に伝達する。

**期待されるアクション**：受信側は、受け取ったテキスト文字列を自身のターミナル接続に転送（RawWriteString または PasteText 経由）することで、ブロードキャスト入力を実現する。

## 通知種別

アプリ内通知（WinRT イベント）

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期（イベント raise は呼び出し元スレッド上で即時実行） |
| 優先度 | 高（ユーザー入力のリアルタイム処理） |
| リトライ | なし |

### 送信先決定ロジック

StringSent イベントにリスナーが登録されているかどうかを `if (StringSent)` で確認し、リスナーがある場合のみ StringSentEventArgs を生成してイベントを発火する。

## 通知テンプレート

### メール通知の場合

該当なし（アプリ内イベント通知）

### 本文テンプレート

該当なし（構造化データとしてイベント引数を伝達）

### 添付ファイル

該当なし

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| Text | 送信されるテキスト文字列（hstring） | SendInput の引数 wstr / _pasteTextWithBroadcast の引数 text | Yes |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| 文字列入力 | SendInput メソッド呼び出し | StringSent イベントにリスナーが存在する場合 | アクション等からの文字列入力 |
| ペースト操作 | _pasteTextWithBroadcast メソッド呼び出し | StringSent イベントにリスナーが存在する場合 | クリップボードペーストやドラッグ&ドロップ |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| リスナー未登録 | StringSent イベントにリスナーがない場合、オブジェクト生成とイベント発火をスキップ |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A1[アクション/キーバインド実行] --> B[SendInput 呼び出し]
    A2[ペースト/ドラッグ&ドロップ] --> C[_pasteTextWithBroadcast 呼び出し]
    B --> D[PreviewInput 解除]
    D --> E{StringSent リスナー存在?}
    C --> E
    E -->|Yes| F[StringSentEventArgs 生成<br/>Text]
    E -->|No| G[スキップ]
    F --> H[StringSent.raise イベント発火]
    H --> I1[RawWriteString でターミナルに送信]
    H --> I2[PasteText でターミナルに送信]
    G --> I1
    G --> I2
```

## データベース参照・更新仕様

### 参照テーブル一覧

該当なし（インメモリイベント処理のみ）

### 更新テーブル一覧

該当なし

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| 特になし | StringSentEventArgs の生成は単純なデータコピーであり失敗しない | - |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | なし |
| リトライ間隔 | - |
| リトライ対象エラー | - |

## 配信設定

### レート制限

| 項目 | 内容 |
|-----|------|
| 1分あたり上限 | 制限なし |
| 1日あたり上限 | 制限なし |

### 配信時間帯

制限なし

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

- テキスト文字列にはパスワードや機密コマンドが含まれる可能性があるが、プロセス内のイベント通知であり外部送信は行わない
- ブロードキャスト入力はユーザーが明示的に有効化する機能である

## 備考

- StringSentEventArgs は KeySent / CharSent と合わせてブロードキャスト入力の3本柱を構成する
- SendInput は PreviewInput をクリア（空文字列で呼び出し）した後にイベントを発火する
- _pasteTextWithBroadcast はドラッグ&ドロップやクリップボードペースト操作で使用され、「ペーストしたかのように」テキストを送信する
- コメントには "Paste this text, and raise a StringSent, to potentially broadcast this text to other controls in the app" と記載されている

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | EventArgs.idl | `src/cascadia/TerminalControl/EventArgs.idl` | StringSentEventArgs の IDL 定義（行146-149）。Text プロパティのみ |
| 1-2 | EventArgs.h | `src/cascadia/TerminalControl/EventArgs.h` | StringSentEventArgs の C++ 実装（行235-242）。コンストラクタで hstring を受け取る |

**読解のコツ**: StringSentEventArgs は最もシンプルな EventArgs であり、Text プロパティ1つのみを持つ。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | TermControl.cpp | `src/cascadia/TerminalControl/TermControl.cpp` | SendInput メソッド（行910-922）。StringSent リスナー存在チェックとイベント発火 |

**主要処理フロー**:
1. **行913**: `PreviewInput(hstring{})` で入力プレビューを解除
2. **行916**: `if (StringSent)` でリスナー存在チェック
3. **行918**: `StringSent.raise(*this, winrt::make<StringSentEventArgs>(wstr))` でイベント発火
4. **行921**: `RawWriteString(wstr)` でターミナル接続に入力を送信

#### Step 3: 追加のエントリーポイント（_pasteTextWithBroadcast）

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | TermControl.cpp | `src/cascadia/TerminalControl/TermControl.cpp` | _pasteTextWithBroadcast メソッド（行3211-3219）。ペースト操作からの StringSent 発火 |

**主要処理フロー**:
- **行3214**: `if (StringSent)` でリスナー存在チェック
- **行3216**: `StringSent.raise(*this, winrt::make<StringSentEventArgs>(text))` でイベント発火
- **行3218**: `_core.PasteText(text)` でペースト処理を実行

#### Step 4: イベント宣言

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | TermControl.idl | `src/cascadia/TerminalControl/TermControl.idl` | StringSent イベント宣言（行82）|
| 4-2 | TermControl.h | `src/cascadia/TerminalControl/TermControl.h` | til::typed_event 宣言（行217）|

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

```
[パターン1: SendInput]
TermControl::SendInput(wstr)
    |
    +-- PreviewInput(hstring{})  ← プレビュー解除
    |
    +-- [if StringSent リスナー存在]
    |       StringSentEventArgs 生成
    |       StringSent.raise(*this, args)
    |
    +-- RawWriteString(wstr)
           +-- ControlCore::SendInput

[パターン2: ペースト/ドラッグ&ドロップ]
TermControl::_pasteTextWithBroadcast(text)
    |
    +-- [if StringSent リスナー存在]
    |       StringSentEventArgs 生成
    |       StringSent.raise(*this, args)
    |
    +-- _core.PasteText(text)
```

### データフロー図

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

テキスト文字列               TermControl                     リスナー / ターミナル接続
(SendInput / Paste)   -->  SendInput() or             -->  StringSent イベント発火
                           _pasteTextWithBroadcast()        -> ブロードキャスト先へ転送
                           StringSentEventArgs生成           -> RawWriteString / PasteText
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| EventArgs.idl | `src/cascadia/TerminalControl/EventArgs.idl` | IDL定義 | StringSentEventArgs の WinRT インターフェース定義 |
| EventArgs.h | `src/cascadia/TerminalControl/EventArgs.h` | ソース | StringSentEventArgs の C++ 実装 |
| EventArgs.cpp | `src/cascadia/TerminalControl/EventArgs.cpp` | ソース | WinRT 生成コードのインクルード |
| TermControl.idl | `src/cascadia/TerminalControl/TermControl.idl` | IDL定義 | StringSent イベントの宣言 |
| TermControl.h | `src/cascadia/TerminalControl/TermControl.h` | ソース | StringSent の til::typed_event 宣言 |
| TermControl.cpp | `src/cascadia/TerminalControl/TermControl.cpp` | ソース | SendInput / _pasteTextWithBroadcast 内での StringSent イベント発火ロジック |
