# 機能設計書 45-TopLevel

## 概要

本ドキュメントは、Avalonia UIフレームワークにおけるTopLevel（トップレベルコンテナ基底）機能の設計仕様を定義する。TopLevelはWindow、Popup、EmbeddableControlHostなど、ネイティブプラットフォームウィンドウを持つすべてのコントロールの基底クラスである。

### 本機能の処理概要

TopLevelクラスは、ネイティブウィンドウハンドルを持つすべてのトップレベルコンテナの基底クラスである。レンダリング、入力処理、フォーカス管理、レイアウトマネージャー、スタイルシステムなど、トップレベルコンテナに共通する機能を提供する。

**業務上の目的・背景**：Window、Popup、OverlayPopupHostなど、様々なトップレベルコンテナが共通の基盤機能を必要とする。TopLevelはこれらの共通機能を抽象化し、コードの再利用性と一貫性を確保する。

**機能の利用シーン**：Window、Popup、OverlayPopupHost等のトップレベルコンテナの基底として使用される。直接インスタンス化されることは稀で、派生クラスを通じて機能が利用される。

**主要な処理内容**：
1. PlatformImplの管理（ネイティブウィンドウ実装）
2. レイアウトマネージャーの提供
3. フォーカスマネージャーの提供
4. RendererおよびRendererDiagnosticsの管理
5. ClientSize、FrameSize等のサイズ管理
6. スタイルおよびテーマの適用
7. 入力イベントの処理

**関連システム・外部連携**：ITopLevelImpl（プラットフォーム実装）、LayoutManager、FocusManager、Renderer、Stylerと連携する。

**権限による制御**：本機能に権限による制御はない。すべてのアプリケーションで使用可能である。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | メインウィンドウ | 継承 | WindowがTopLevelを継承 |
| 30 | Popup | 継承 | PopupがTopLevelを継承して使用 |

## 機能種別

基底クラス / レイアウト管理 / 入力処理 / レンダリング

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| TransparencyLevelHint | WindowTransparencyLevel | No | 透明度レベルのヒント | None/Transparent/Blur/AcrylicBlur/Mica |
| TransparencyBackgroundFallback | IBrush | No | 透明度非対応時のフォールバック背景 | - |
| RenderTransform | Transform | No | レンダリング変換 | - |
| FrameMargins | Thickness | No | フレームマージン | - |

### 入力データソース

- PlatformImpl: ネイティブウィンドウからのイベント
- コード: プロパティ設定

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ClientSize | Size | クライアント領域のサイズ |
| FrameSize | Size? | フレームを含むサイズ |
| PlatformImpl | ITopLevelImpl | プラットフォーム実装 |
| Renderer | IRenderer | レンダラー |
| FocusManager | IFocusManager | フォーカスマネージャー |
| InsetsManager | IInsetsManager | インセット（ノッチ等）マネージャー |
| Screens | Screens | 画面情報 |
| ActualTransparencyLevel | WindowTransparencyLevel | 実際の透明度レベル |

### 出力先

- イベント: Opened、Closed、ScalingChanged、BackRequestedなど

## 処理フロー

### 処理シーケンス

```
1. コンストラクタ（ITopLevelImpl受取）
   └─ PlatformImplの設定
   └─ LayoutManager作成
   └─ FocusManager作成
   └─ Styler接続

2. HandleOpened
   └─ Rendererの初期化
   └─ Openedイベント発火

3. レイアウトパス
   └─ LayoutManager.ExecuteLayoutPass

4. HandleResized
   └─ ClientSizeの更新
   └─ 再レイアウト

5. HandleClosed
   └─ リソース解放
   └─ Closedイベント発火
```

### フローチャート

```mermaid
flowchart TD
    A[TopLevel作成] --> B[PlatformImpl設定]
    B --> C[LayoutManager作成]
    C --> D[FocusManager作成]
    D --> E[スタイル適用]
    E --> F{Opened?}
    F -->|Yes| G[Renderer初期化]
    G --> H[Openedイベント]
    H --> I[レイアウトパス]
    I --> J{Closed?}
    J -->|No| K[入力イベント処理]
    K --> I
    J -->|Yes| L[リソース解放]
    L --> M[Closedイベント]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | スケーリング伝播 | RenderScalingはTopLevel単位で管理 | 常時適用 |
| BR-002 | 透明度フォールバック | 要求した透明度が使用できない場合はフォールバック背景を使用 | 透明度非対応時 |
| BR-003 | フォーカススコープ | TopLevelは独立したフォーカススコープ | 常時適用 |

### 計算ロジック

**DPI変換**：
```
PixelPoint = Point * RenderScaling
Point = PixelPoint / RenderScaling
```

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

本機能はデータベース操作を行わない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | ObjectDisposedException | PlatformImplがnull | TopLevelが既に破棄されている |

### リトライ仕様

リトライは適用されない。

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

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

## パフォーマンス要件

- レイアウトパスは16ms以内（60FPS）
- 入力イベント処理は即座に完了

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

- PlatformImplへの直接アクセスは推奨されない

## 備考

- TopLevelは抽象クラスに近い設計だが、直接インスタンス化も可能
- GetTopLevel()静的メソッドでVisualからTopLevelを取得可能

---

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

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

### 推奨読解順序

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

TopLevelクラスが管理するフィールドとプロパティを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | フィールド | `src/Avalonia.Controls/TopLevel.cs` | 56-81行目。LayoutManager、Renderer、FocusManager等 |
| 1-2 | プロパティ | `src/Avalonia.Controls/TopLevel.cs` | 130-220行目。ClientSize、FrameSize、TransparencyLevel等 |

**読解のコツ**: _layoutManager、_focusManager、_renderがTopLevelの核心機能を提供。

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

コンストラクタとPlatformImpl設定を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | コンストラクタ | `src/Avalonia.Controls/TopLevel.cs` | 250-290行目。PlatformImplからの初期化 |
| 2-2 | HandlePlatformImpl | `src/Avalonia.Controls/TopLevel.cs` | 内部でPlatformImplイベントをバインド |

**主要処理フロー**:
1. **270-273行目**: LayoutManager作成
2. **274-275行目**: FocusManager作成
3. **PlatformImpl各種イベントの購読**

#### Step 3: ライフサイクル処理を理解する

Open/Closeの処理フロー。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | HandleOpened | `src/Avalonia.Controls/TopLevel.cs` | Openedイベント処理 |
| 3-2 | HandleClosed | `src/Avalonia.Controls/TopLevel.cs` | Closedイベント処理、リソース解放 |

**主要処理フロー**:
- Opened時にRendererを開始
- Closed時にRendererを停止、リソース解放

#### Step 4: レイアウトとレンダリングを理解する

レイアウトパスとレンダリングの流れ。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | HandleResized | `src/Avalonia.Controls/TopLevel.cs` | サイズ変更処理 |
| 4-2 | HandlePaint | `src/Avalonia.Controls/TopLevel.cs` | 描画要求処理 |
| 4-3 | LayoutManager | `src/Avalonia.Controls/LayoutManager.cs` | レイアウトマネージャーの実装 |

**主要処理フロー**:
- ClientSizeの更新
- InvalidateMeasure/Arrangeでレイアウト再計算をスケジュール
- LayoutManager.ExecuteLayoutPassで実際のレイアウト実行

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

```
TopLevel コンストラクタ
    │
    ├─ new LayoutManager(this)
    ├─ new FocusManager()
    ├─ PlatformImpl イベント購読
    │      ├─ Resized → HandleResized
    │      ├─ Paint → HandlePaint
    │      ├─ Opened → HandleOpened
    │      ├─ Closed → HandleClosed
    │      └─ Input → InputManager
    │
    └─ Styler.ApplyStyles

HandleOpened
    │
    ├─ Renderer.Start()
    └─ OnOpened (イベント発火)

HandleResized
    │
    ├─ ClientSize更新
    ├─ InvalidateMeasure
    └─ LayoutManager.ExecuteLayoutPass

HandleClosed
    │
    ├─ Renderer.Stop()
    ├─ PlatformImpl.Dispose()
    └─ OnClosed (イベント発火)
```

### データフロー図

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

PlatformImpl ────────────▶ TopLevel初期化 ──────────────▶ LayoutManager
                                │                          FocusManager
                                │
Resized イベント ──────────────▶ HandleResized
                                │
                                ▼
                          ClientSize更新
                                │
                                ▼
                          InvalidateMeasure
                                │
                                ▼
                    LayoutManager.ExecuteLayoutPass
                                │
                                ▼
                    [子コントロールのMeasure/Arrange]
                                │
                                ▼
                          Renderer.Render
                                │
                                ▼
                          [画面描画]
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| TopLevel.cs | `src/Avalonia.Controls/TopLevel.cs` | ソース | TopLevelクラスの実装 |
| ITopLevelImpl.cs | `src/Avalonia.Controls/Platform/ITopLevelImpl.cs` | ソース | プラットフォーム実装インターフェース |
| LayoutManager.cs | `src/Avalonia.Controls/LayoutManager.cs` | ソース | レイアウトマネージャー |
| FocusManager.cs | `src/Avalonia.Base/Input/FocusManager.cs` | ソース | フォーカスマネージャー |
| IRenderer.cs | `src/Avalonia.Base/Rendering/IRenderer.cs` | ソース | レンダラーインターフェース |
| WindowTransparencyLevel.cs | `src/Avalonia.Controls/Platform/WindowTransparencyLevel.cs` | ソース | 透明度レベル |
