# 機能設計書 92-UIオートメーション レンダリング

## 概要

本ドキュメントは、Windows Terminal / Console Host におけるUIオートメーション（UIA）連携用レンダリングエンジン（UiaEngine）の機能設計を記述する。スクリーンリーダー等の支援技術にテキスト変更やカーソル移動を通知するアクセシビリティ基盤である。

### 本機能の処理概要

UIオートメーション レンダリングエンジンは、実際の画面描画を行うのではなく、テキストバッファの変更やカーソルの移動、選択範囲の変更といったイベントを追跡し、UIオートメーションクライアント（スクリーンリーダー等）に通知する。

**業務上の目的・背景**：アクセシビリティは現代のソフトウェアにおいて必須の要件である。視覚障害を持つユーザーがターミナルを操作する際、スクリーンリーダー（NVDA、Narrator等）がテキスト内容やカーソル位置を音声で伝える必要がある。UiaEngineはこの連携を実現するためのレンダリングエンジンとして機能する。

**機能の利用シーン**：スクリーンリーダーがアクティブな状態でターミナルを使用する場合に、テキストの変更やカーソル移動を支援技術に通知する。1つのTermControlにつき1つのUiaEngineが存在し、フォーカスのあるコントロールのみが有効化される。

**主要な処理内容**：
1. テキストバッファ変更の検出と通知（TextBufferChanged イベント）
2. カーソル位置変更の検出と通知（CursorChanged イベント）
3. 選択範囲変更の検出と通知（SelectionChanged イベント）
4. 新規テキスト出力の通知（NewOutput イベント）
5. Enable/Disable による排他制御（同時に1つのUiaEngineのみアクティブ）

**関連システム・外部連携**：IUiaEventDispatcher インターフェースを通じてUIオートメーションイベントをディスパッチする。IRenderEngine インターフェース経由でRendererから呼び出される。

**権限による制御**：特になし。UIオートメーションの有効/無効は Enable()/Disable() メソッドで制御される。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 6 | TermControl（ターミナル表示） | 主画面 | UIオートメーションイベントの発火元 |

## 機能種別

イベント通知処理 / アクセシビリティ連携

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| dispatcher | IUiaEventDispatcher* | Yes | UIAイベントのディスパッチャー | NULLでないこと |
| psrRegion | til::rect* | Yes | 変更された領域 | - |
| newText | std::wstring_view | No | 新しく追加されたテキスト | - |

### 入力データソース

- Renderer から IRenderEngine インターフェース経由でイベント通知を受領
- テキストバッファ変更・カーソル移動・選択変更がトリガー

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| TextBufferChanged | UIAイベント | テキストバッファ変更通知 |
| CursorChanged | UIAイベント | カーソル位置変更通知 |
| SelectionChanged | UIAイベント | 選択範囲変更通知 |
| NewOutput | UIAイベント | 新規テキスト出力通知 |

### 出力先

IUiaEventDispatcher 経由で UIオートメーションクライアントに通知

## 処理フロー

### 処理シーケンス

```
1. StartPaint() - 描画サイクル開始
   └─ 有効状態チェック、描画フラグ設定
2. Invalidate() / InvalidateCursor() / InvalidateSelection() - 変更検出
   └─ 各フラグ（_textBufferChanged/_cursorChanged/_selectionChanged）をセット
3. NotifyNewText() - 新規テキストバッファリング
   └─ _newOutput に新しいテキストを追加
4. PaintBufferLine() etc. - 描画メソッド（no-op）
   └─ 実際の描画は行わない
5. EndPaint() - 描画サイクル完了
   └─ フラグに基づいてIUiaEventDispatcherのイベントを発火
6. Present() - 完了
   └─ no-op
```

### フローチャート

```mermaid
flowchart TD
    A[StartPaint] --> B{有効?}
    B -->|No| C[S_FALSE]
    B -->|Yes| D[描画中フラグON]
    D --> E[Invalidate系メソッド]
    E --> F[変更フラグ更新]
    F --> G[EndPaint]
    G --> H{テキスト変更?}
    H -->|Yes| I[TextBufferChanged通知]
    H -->|No| J{カーソル変更?}
    I --> J
    J -->|Yes| K[CursorChanged通知]
    J -->|No| L{選択変更?}
    K --> L
    L -->|Yes| M[SelectionChanged通知]
    L -->|No| N{新出力あり?}
    M --> N
    N -->|Yes| O[NewOutput通知]
    N -->|No| P[描画中フラグOFF]
    O --> P
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-92-01 | 排他制御 | 同時に1つのUiaEngineのみがアクティブ | 複数TermControl存在時 |
| BR-92-02 | 無効時バッファクリア | Disable時に_newOutputバッファをクリア | Disable()呼び出し時 |
| BR-92-03 | 描画no-op | PaintBufferLine等の描画メソッドは何も描画しない | 常時 |
| BR-92-04 | テキスト出力バッファリング | NotifyNewTextで受信したテキストをバッファリングし、EndPaint時にまとめて通知 | テキスト出力時 |

### 計算ロジック

特になし。

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

該当なし。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| E_INVALIDARG | 引数エラー | コンストラクタでdispatcherがNULL | THROW_HR_IF_NULLで例外送出 |
| S_FALSE | 描画不要 | エンジンが無効状態 | 描画をスキップ |

### リトライ仕様

リトライは行わない。

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

該当なし。

## パフォーマンス要件

- WaitUntilCanRender() メソッドにより、スクリーンリーダーが処理できるペースに描画を制限
- テキスト出力はバッファリングしてEndPaint時にまとめて通知することで通知頻度を最適化

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

特になし。UIオートメーションはOS標準のアクセシビリティフレームワークを使用。

## 備考

- UiaEngine はGdiEngineやAtlasEngineと共存し、Rendererに複数エンジンとして登録される
- UiaEngineヘッダーのコメントに「Only one UiaEngine may present information at a time」と明記

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | IUiaEventDispatcher.h | `src/types/IUiaEventDispatcher.h` | UIAイベントディスパッチャーのインターフェース定義 |
| 1-2 | UiaRenderer.hpp | `src/renderer/uia/UiaRenderer.hpp` | UiaEngineクラス定義。メンバー変数の意味を理解 |

**読解のコツ**: UiaEngine は IRenderEngine の全メソッドを実装するが、大半は no-op（何もしない）実装。変更検出フラグ（_textBufferChanged, _cursorChanged, _selectionChanged）が核心。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | UiaRenderer.cpp | `src/renderer/uia/UiaRenderer.cpp` | UiaEngine の全メソッド実装 |

**主要処理フロー**:
1. **16-26行目**: コンストラクタ。dispatcherのNULLチェック、各フラグ初期化
2. **34-38行目**: Enable() - _isEnabled = true
3. **46-56行目**: Disable() - _isEnabled = false、_newOutputのクリア
4. **65-69行目**: Invalidate() - _textBufferChanged = true
5. **78行目以降**: InvalidateCursor() - カーソル領域の変更検出

#### Step 3: イベント通知を理解する

EndPaint() メソッド内でフラグに基づいてイベントをディスパッチする部分が核心。

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

```
Renderer::PaintFrame()
    │
    ├─ UiaEngine::StartPaint()
    │      └─ _isEnabled チェック
    │
    ├─ UiaEngine::Invalidate() / InvalidateCursor() / InvalidateSelection()
    │      └─ 変更フラグの設定
    │
    ├─ UiaEngine::NotifyNewText()
    │      └─ _newOutput にテキスト追加
    │
    ├─ UiaEngine::PaintBufferLine() (no-op)
    │
    ├─ UiaEngine::EndPaint()
    │      ├─ IUiaEventDispatcher::SignalTextBufferChanged()
    │      ├─ IUiaEventDispatcher::SignalCursorChanged()
    │      ├─ IUiaEventDispatcher::SignalSelectionChanged()
    │      └─ IUiaEventDispatcher::SignalNewOutput()
    │
    └─ UiaEngine::Present() (no-op)
```

### データフロー図

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

Renderer            ───▶ UiaEngine                 ───▶ IUiaEventDispatcher
(描画指示)                 (変更検出・フラグ管理)            (UIAイベント)
                                                           │
TextBuffer変更      ───▶ Invalidate()              ───▶ TextBufferChanged
カーソル移動        ───▶ InvalidateCursor()         ───▶ CursorChanged
選択範囲変更        ───▶ InvalidateSelection()      ───▶ SelectionChanged
新テキスト出力      ───▶ NotifyNewText()            ───▶ NewOutput
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| UiaRenderer.hpp | `src/renderer/uia/UiaRenderer.hpp` | ソース | UiaEngineクラス定義 |
| UiaRenderer.cpp | `src/renderer/uia/UiaRenderer.cpp` | ソース | UiaEngineクラス実装 |
| IUiaEventDispatcher.h | `src/types/IUiaEventDispatcher.h` | ソース | UIAイベントディスパッチャーインターフェース |
| RenderEngineBase.hpp | `src/renderer/inc/RenderEngineBase.hpp` | ソース | レンダリングエンジン基底クラス |
| IRenderEngine.hpp | `src/renderer/inc/IRenderEngine.hpp` | ソース | レンダリングエンジンインターフェース |
