# 機能設計書 94-Win32Platform

## 概要

本ドキュメントは、Avaloniaフレームワークにおける Windows Win32プラットフォーム（Win32Platform）機能の設計仕様を記述します。Win32Platformは、Windows OS上でAvaloniaアプリケーションを実行するための基盤を提供し、Win32 APIを通じてウィンドウ管理、入力処理、レンダリングなどのネイティブ機能を統合します。

### 本機能の処理概要

Win32Platformは、AvaloniaフレームワークがWindows OS上で動作するために必要なプラットフォーム抽象化レイヤーを実装します。IWindowingPlatformインターフェースを実装し、ウィンドウ作成、クリップボード、カーソル、入力デバイス、画面情報などの各種プラットフォームサービスを提供します。

**業務上の目的・背景**：Avaloniaはクロスプラットフォームフレームワークとして設計されており、各OSのネイティブAPIを抽象化する必要があります。Win32Platformは、Windows固有のWin32 APIを使用してこの抽象化を実現し、開発者がプラットフォーム固有のコードを書くことなくWindows上で動作するアプリケーションを構築できるようにします。DPI対応、Direct Composition、WinRT統合などのWindows固有機能もサポートします。

**機能の利用シーン**：
- WindowsデスクトップアプリケーションのAvalonia実行基盤
- ウィンドウの作成・管理
- システムクリップボードとの連携
- キーボード・マウス入力の処理
- マルチモニター環境でのスクリーン情報取得
- システムトレイアイコンの表示
- ドラッグ＆ドロップ操作

**主要な処理内容**：
1. Win32プラットフォームの初期化とサービス登録
2. メッセージウィンドウの作成とWndProc処理
3. DPI認識の設定
4. グラフィックスサブシステムの初期化（ANGLE/WGL/Direct3D）
5. Compositorの初期化
6. 各種プラットフォームサービスの提供

**関連システム・外部連携**：
- Win32 API（user32.dll, shcore.dll）
- OLE/COM（ドラッグ＆ドロップ、クリップボード）
- Direct Composition / WinRT Composition
- OpenGL（ANGLE/WGL）
- Vulkan

**権限による制御**：管理者権限は不要ですが、一部の機能（システムトレイ等）はWindowsセキュリティポリシーの影響を受けます。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | メインウィンドウ | 主機能 | アプリケーションのメインウィンドウ表示 |
| 3 | 装飾付きウィンドウ | 主機能 | カスタムウィンドウ装飾 |
| 64 | Window Customizations | 主機能 | ウィンドウカスタマイズデモ |

## 機能種別

プラットフォーム基盤 / ウィンドウ管理 / ネイティブ統合

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| Win32PlatformOptions | Win32PlatformOptions | No | プラットフォームオプション | - |
| DpiAwareness | Win32DpiAwareness | No | DPI認識設定 | デフォルト:PerMonitorDpiAware |
| CompositionMode | Win32CompositionMode[] | No | コンポジションモード | - |
| OverlayPopups | bool | No | オーバーレイポップアップ使用 | デフォルト:false |
| ShouldRenderOnUIThread | bool | No | UIスレッドレンダリング | デフォルト:false |

### 入力データソース

- アプリケーション設定（AvaloniaLocator経由）
- Windows OS API

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| IWindowImpl | WindowImpl | ウィンドウ実装 |
| ITrayIconImpl | TrayIconImpl | トレイアイコン実装 |
| ITopLevelImpl | EmbeddedWindowImpl | 埋め込みトップレベル |

### 出力先

- AvaloniaLocator経由でのサービス登録
- Win32ウィンドウシステム

## 処理フロー

### 処理シーケンス

```
1. UseWin32()拡張メソッド呼び出し
   └─ AppBuilderの設定
2. Win32Platform.Initialize()
   └─ Win32PlatformOptionsの取得
3. DPI認識設定
   └─ SetProcessDpiAwarenessContext/SetProcessDpiAwareness
4. メッセージウィンドウ作成
   └─ CreateMessageWindow() - 非表示のメッセージ処理用ウィンドウ
5. ディスパッチャ初期化
   └─ Win32DispatcherImpl
6. サービス登録
   └─ AvaloniaLocatorへの各種サービスバインド
7. グラフィックス初期化
   └─ Win32GlManager.Initialize()
8. Compositor作成
   └─ new Compositor(platformGraphics)
```

### フローチャート

```mermaid
flowchart TD
    A[UseWin32呼び出し] --> B[Initialize]
    B --> C[DPI認識設定]
    C --> D{DPI API選択}
    D -->|Win10+| E[SetProcessDpiAwarenessContext]
    D -->|Win8.1| F[SetProcessDpiAwareness]
    D -->|旧OS| G[SetProcessDPIAware]
    E --> H[メッセージウィンドウ作成]
    F --> H
    G --> H
    H --> I[ディスパッチャ初期化]
    I --> J[サービス登録]
    J --> K{CustomPlatformGraphics?}
    K -->|Yes| L[カスタムグラフィックス使用]
    K -->|No| M[Win32GlManager.Initialize]
    L --> N[Compositor作成]
    M --> N
    N --> O[OLE初期化確認]
    O --> P{OLE利用可?}
    P -->|Yes| Q[DragSource登録]
    P -->|No| R[スキップ]
    Q --> S[初期化完了]
    R --> S
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-94-01 | DPI認識優先順位 | PerMonitorDpiAware V2 → V1 → System → Unawareの順で試行 | 初期化時 |
| BR-94-02 | グラフィックスフォールバック | ANGLE → WGL → Softwareの順でフォールバック | グラフィックス初期化時 |
| BR-94-03 | メッセージ処理 | WM_DISPATCH_WORK_ITEMでディスパッチャ処理 | メッセージ受信時 |
| BR-94-04 | シャットダウン処理 | WM_QUERYENDSESSIONでShutdownRequestedイベント | セッション終了時 |
| BR-94-05 | テーマ変更検知 | WM_SETTINGCHANGEでテーマ変更を検知 | 設定変更時 |

### 計算ロジック

WindowsVersionはRtlGetVersion APIを使用して実際のOS バージョンを取得します（互換性シムの影響を受けない）。

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

### 操作別データベース影響一覧

本機能はデータベース操作を伴いません。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| Win32Exception | Win32Exception | RegisterClassEx失敗 | プロセス終了 |
| Win32Exception | Win32Exception | CreateWindowEx失敗 | プロセス終了 |
| InvalidOperationException | InvalidOperationException | CustomPlatformGraphics設定不整合 | 設定修正 |

### リトライ仕様

DPI認識設定は優先度順に複数のAPIを試行します。

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

本機能はUI基盤のため、トランザクション管理は不要です。

## パフォーマンス要件

- メッセージループは効率的なWin32メッセージポンプを使用
- タイマー処理はTIMERID_DISPATCHERで管理
- レンダリングはGPUアクセラレーションを優先

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

- OLEコンテキストの適切な初期化
- ウィンドウメッセージフィルタリング（トレイアイコン）

## 備考

Win32Platformはシングルトンパターンで実装され、s_instanceでインスタンスを保持します。

---

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

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

### 推奨読解順序

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

まず、プラットフォームオプションとインターフェースを理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Win32PlatformOptions.cs | `src/Windows/Avalonia.Win32/Win32PlatformOptions.cs` | プラットフォーム設定オプション |
| 1-2 | IWindowingPlatform.cs | `src/Avalonia.Controls/Platform/IWindowingPlatform.cs` | プラットフォームインターフェース |

**読解のコツ**: Win32PlatformOptionsの各プロパティがInitializeでどのように使用されるかを追跡してください。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Win32Platform.cs | `src/Windows/Avalonia.Win32/Win32Platform.cs` | メインプラットフォームクラス |

**主要処理フロー**:
1. **27-35行目**: UseWin32拡張メソッド - AppBuilder設定
2. **77-79行目**: Initialize() - デフォルトオプションでの初期化
3. **82-138行目**: Initialize(options) - 詳細初期化処理
4. **86行目**: SetDpiAwareness() - DPI設定
5. **92-114行目**: サービス登録
6. **136行目**: Compositor作成
7. **198-226行目**: CreateMessageWindow() - メッセージウィンドウ作成
8. **143-196行目**: WndProc - メッセージ処理

#### Step 3: ウィンドウ実装を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | WindowImpl.cs | `src/Windows/Avalonia.Win32/WindowImpl.cs` | ウィンドウ実装 |
| 3-2 | WindowImpl.WndProc.cs | `src/Windows/Avalonia.Win32/WindowImpl.WndProc.cs` | メッセージ処理 |

#### Step 4: 入力処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | WindowsKeyboardDevice.cs | `src/Windows/Avalonia.Win32/Input/WindowsKeyboardDevice.cs` | キーボード入力 |
| 4-2 | WindowsMouseDevice.cs | `src/Windows/Avalonia.Win32/Input/WindowsMouseDevice.cs` | マウス入力 |

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

```
Win32Platform (シングルトン)
    │
    ├─ Initialize()
    │      ├─ SetDpiAwareness()
    │      ├─ CreateMessageWindow()
    │      ├─ Win32DispatcherImpl
    │      ├─ Win32GlManager.Initialize()
    │      └─ new Compositor()
    │
    ├─ CreateWindow()
    │      └─ new WindowImpl()
    │
    ├─ CreateTrayIcon()
    │      └─ new TrayIconImpl()
    │
    └─ WndProc()
           ├─ WM_DISPATCH_WORK_ITEM → DispatchWorkItem()
           ├─ WM_QUERYENDSESSION → ShutdownRequested
           ├─ WM_SETTINGCHANGE → OnColorValuesChanged()
           └─ WM_TIMER → FireTimer()
```

### データフロー図

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

Win32PlatformOptions ─▶ Win32Platform.Initialize() ─▶ サービス登録
         │                      │
         │                      ├─ IClipboard
         │                      ├─ ICursorFactory
         │                      ├─ IKeyboardDevice
         │                      ├─ IScreenImpl
         │                      ├─ IDispatcherImpl
         │                      ├─ IRenderTimer
         │                      └─ Compositor

Win32メッセージ ─────▶ WndProc() ─────────────────▶ イベント発火
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Win32Platform.cs | `src/Windows/Avalonia.Win32/Win32Platform.cs` | ソース | メインプラットフォームクラス |
| Win32PlatformOptions.cs | `src/Windows/Avalonia.Win32/Win32PlatformOptions.cs` | ソース | プラットフォームオプション |
| WindowImpl.cs | `src/Windows/Avalonia.Win32/WindowImpl.cs` | ソース | ウィンドウ実装 |
| WindowImpl.WndProc.cs | `src/Windows/Avalonia.Win32/WindowImpl.WndProc.cs` | ソース | WndProc処理 |
| Win32DispatcherImpl.cs | `src/Windows/Avalonia.Win32/Win32DispatcherImpl.cs` | ソース | ディスパッチャ実装 |
| ClipboardImpl.cs | `src/Windows/Avalonia.Win32/ClipboardImpl.cs` | ソース | クリップボード実装 |
| CursorFactory.cs | `src/Windows/Avalonia.Win32/CursorFactory.cs` | ソース | カーソル生成 |
| ScreenImpl.cs | `src/Windows/Avalonia.Win32/ScreenImpl.cs` | ソース | スクリーン情報 |
| TrayIconImpl.cs | `src/Windows/Avalonia.Win32/TrayIconImpl.cs` | ソース | システムトレイ |
| Win32GlManager.cs | `src/Windows/Avalonia.Win32/Win32GlManager.cs` | ソース | OpenGL管理 |
| Win32PlatformSettings.cs | `src/Windows/Avalonia.Win32/Win32PlatformSettings.cs` | ソース | プラットフォーム設定 |
| WindowsKeyboardDevice.cs | `src/Windows/Avalonia.Win32/Input/WindowsKeyboardDevice.cs` | ソース | キーボードデバイス |
| WindowsMouseDevice.cs | `src/Windows/Avalonia.Win32/Input/WindowsMouseDevice.cs` | ソース | マウスデバイス |
| UnmanagedMethods.cs | `src/Windows/Avalonia.Win32/Interop/UnmanagedMethods.cs` | ソース | Win32 API P/Invoke |
| PopupImpl.cs | `src/Windows/Avalonia.Win32/PopupImpl.cs` | ソース | ポップアップ実装 |
| DragSource.cs | `src/Windows/Avalonia.Win32/DragSource.cs` | ソース | ドラッグソース |
| OleDropTarget.cs | `src/Windows/Avalonia.Win32/OleDropTarget.cs` | ソース | OLEドロップターゲット |
