# 機能設計書 42-Window

## 概要

本ドキュメントは、Avalonia UIフレームワークにおけるWindow（アプリケーションウィンドウ）機能の設計仕様を定義する。Windowはデスクトップアプリケーションのトップレベルウィンドウを表現するクラスである。

### 本機能の処理概要

Windowクラスは、タイトルバー、フレーム、コンテンツ領域を持つトップレベルのネイティブウィンドウを提供する。ウィンドウの状態管理（最大化・最小化・通常）、サイズ変更、位置制御、モーダルダイアログ表示など、デスクトップアプリケーションに必要なウィンドウ機能の全体を管理する。

**業務上の目的・背景**：デスクトップアプリケーション開発において、ネイティブウィンドウの管理はプラットフォーム固有の複雑な処理を伴う。Windowクラスはこの複雑性を抽象化し、クロスプラットフォームで一貫したウィンドウ操作APIを提供する。

**機能の利用シーン**：メインウィンドウの表示、ダイアログウィンドウの表示、子ウィンドウの管理、ウィンドウ装飾のカスタマイズ、フルスクリーン/最大化モードの制御など、アプリケーションのウィンドウ管理全般で使用される。

**主要な処理内容**：
1. ウィンドウの表示・非表示制御
2. ウィンドウ状態（Normal/Minimized/Maximized/FullScreen）の管理
3. ウィンドウサイズとコンテンツへの自動サイズ調整
4. モーダル/モードレスダイアログの表示
5. ウィンドウの閉じるイベントとキャンセル処理
6. 親子ウィンドウ関係の管理
7. システム装飾（タイトルバー・ボーダー）のカスタマイズ

**関連システム・外部連携**：IWindowImpl（プラットフォーム固有ウィンドウ実装）、Screens（マルチモニター管理）、NativeMenu（ネイティブメニュー）と連携する。

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | メインウィンドウ | 主画面 | アプリケーションのメインウィンドウを表示 |
| 3 | 装飾付きウィンドウ | 主画面 | カスタムウィンドウ装飾デモ |
| 29 | Dialogs | 参照画面 | ウィンドウダイアログ、所有ウィンドウの表示 |
| 64 | Window Customizations | 主画面 | ウィンドウカスタマイズのデモ |

## 機能種別

ウィンドウ管理 / UI表示制御 / イベント処理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| Title | string | No | ウィンドウタイトル | デフォルト: "Window" |
| Icon | WindowIcon | No | ウィンドウアイコン | - |
| WindowState | WindowState | No | ウィンドウ状態 | Normal/Minimized/Maximized/FullScreen |
| SizeToContent | SizeToContent | No | コンテンツへのサイズ調整 | Manual/Width/Height/WidthAndHeight |
| SystemDecorations | SystemDecorations | No | システム装飾設定 | None/BorderOnly/Full |
| CanResize | bool | No | リサイズ可否 | デフォルト: true |
| CanMinimize | bool | No | 最小化可否 | デフォルト: true |
| CanMaximize | bool | No | 最大化可否 | デフォルト: true |
| ShowInTaskbar | bool | No | タスクバー表示 | デフォルト: true |
| WindowStartupLocation | WindowStartupLocation | No | 起動時位置 | Manual/CenterScreen/CenterOwner |

### 入力データソース

- XAML定義: ウィンドウのプロパティ設定
- コード: 動的なウィンドウ操作
- プラットフォーム: ネイティブウィンドウイベント

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| Position | PixelPoint | ウィンドウの画面上の位置 |
| ClientSize | Size | クライアント領域のサイズ |
| FrameSize | Size? | フレームを含むウィンドウサイズ |
| WindowDecorationMargin | Thickness | ウィンドウ装飾のマージン |
| OwnedWindows | IReadOnlyList<Window> | 所有する子ウィンドウ一覧 |

### 出力先

- 画面表示: ネイティブウィンドウとして描画
- イベント: Opened/Closed/Closing/WindowStateChanged

## 処理フロー

### 処理シーケンス

```
1. ウィンドウ初期化
   └─ PlatformImplの作成とプロパティバインディング設定

2. Show() / ShowDialog() 呼び出し
   └─ ウィンドウの表示とレイアウト実行

3. レイアウトパス
   └─ MeasureOverrideでコンテンツサイズ計算
   └─ SizeToContentに応じたサイズ調整

4. ウィンドウ状態変更
   └─ WindowState変更に応じた表示更新

5. Close() / ウィンドウを閉じる
   └─ Closingイベント発火
   └─ キャンセルされなければウィンドウ破棄
```

### フローチャート

```mermaid
flowchart TD
    A[Show/ShowDialog呼び出し] --> B{既に表示中?}
    B -->|Yes| C[既存ウィンドウをアクティブ化]
    B -->|No| D[EnsureInitialized]
    D --> E[スタイル適用]
    E --> F[初期レイアウト実行]
    F --> G{SizeToContent?}
    G -->|Width| H[幅をコンテンツに合わせる]
    G -->|Height| I[高さをコンテンツに合わせる]
    G -->|WidthAndHeight| J[両方合わせる]
    G -->|Manual| K[指定サイズを使用]
    H --> L[起動位置設定]
    I --> L
    J --> L
    K --> L
    L --> M[PlatformImpl.Show]
    M --> N[OnOpened発火]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | モーダル排他 | モーダルダイアログ表示中は親ウィンドウを無効化 | ShowDialog時 |
| BR-002 | 子ウィンドウ追従 | 親ウィンドウを閉じると子ウィンドウも閉じる | 親子関係設定時 |
| BR-003 | Closing伝播 | ClosingBehaviorに応じて子ウィンドウにClosingを伝播 | ウィンドウ閉じる時 |
| BR-004 | 最大化制約 | CanResize=falseの場合、CanMaximize=falseに強制 | 常時適用 |

### 計算ロジック

**ウィンドウ起動位置の計算（CenterScreen）**：
```
Screen = ScreenFromPoint(Position) ?? Primary
Position = Screen.WorkingArea.Center - (WindowSize / 2)
```

**ウィンドウ起動位置の計算（CenterOwner）**：
```
OwnerRect = Owner.Position + Owner.Size
Position = OwnerRect.Center - (WindowSize / 2)
```

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | InvalidOperationException | 閉じたウィンドウを再表示 | 新しいWindowインスタンスを作成 |
| - | InvalidOperationException | 非表示の親ウィンドウの子として表示 | 親を先に表示 |
| - | ArgumentNullException | モーダル表示時にownerがnull | ownerを指定 |
| - | InvalidOperationException | ウィンドウが自分自身を親として設定 | 異なるウィンドウを親に設定 |

### リトライ仕様

ウィンドウ操作にリトライは適用されない。

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

トランザクション管理は不要（UI操作のため）。

## パフォーマンス要件

- ウィンドウ表示は200ms以内
- ウィンドウ状態変更は即座に反映
- リサイズ時のレイアウト更新は16ms（60FPS）以内

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

- ウィンドウハンドルへの直接アクセスは推奨されない
- 信頼されないコードからのウィンドウ操作は制限すべき

## 備考

- X11（Linux）ではSizeToContentの動作に制限あり
- macOSではフルスクリーンモードの動作がプラットフォーム固有

---

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

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

### 推奨読解順序

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

ウィンドウの状態を表す列挙型とプロパティを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | SizeToContent列挙型 | `src/Avalonia.Controls/Window.cs` | 22-44行目。コンテンツへのサイズ調整オプション |
| 1-2 | SystemDecorations列挙型 | `src/Avalonia.Controls/Window.cs` | 46-65行目。システム装飾設定 |
| 1-3 | WindowClosingBehavior列挙型 | `src/Avalonia.Controls/Window.cs` | 67-84行目。Closing動作の設定 |

**読解のコツ**: これらの列挙型がウィンドウの外観と動作を制御する重要な設定値。

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

ウィンドウ表示の開始点を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | コンストラクタ | `src/Avalonia.Controls/Window.cs` | 229-269行目。プロパティバインディングの設定 |
| 2-2 | Show メソッド | `src/Avalonia.Controls/Window.cs` | 679-682行目。ウィンドウ表示 |
| 2-3 | ShowCore | `src/Avalonia.Controls/Window.cs` | 747-874行目。表示処理の本体 |

**主要処理フロー**:
1. **749-766行目**: 状態検証（既に閉じられていないか等）
2. **772-776行目**: イベント発火とスタイル適用
3. **795行目**: 初期レイアウトパス実行
4. **797-809行目**: SizeToContentに応じたサイズ調整
5. **813行目**: 起動位置設定
6. **839行目**: PlatformImpl.Showでネイティブウィンドウ表示

#### Step 3: ウィンドウ閉じる処理を理解する

Closingイベントとウィンドウ破棄の流れ。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Close | `src/Avalonia.Controls/Window.cs` | 511-514行目。ウィンドウを閉じる |
| 3-2 | CloseCore | `src/Avalonia.Controls/Window.cs` | 532-550行目。閉じる処理の本体 |
| 3-3 | ShouldCancelClose | `src/Avalonia.Controls/Window.cs` | 582-619行目。キャンセル判定 |
| 3-4 | CloseInternal | `src/Avalonia.Controls/Window.cs` | 568-580行目。実際の破棄処理 |

**主要処理フロー**:
- **538-541行目**: Closingイベントでキャンセルチェック
- **584-618行目**: ClosingBehaviorに応じた子ウィンドウへの伝播
- **570-573行目**: 子ウィンドウの再帰的クローズ
- **575行目**: PlatformImpl.Disposeでネイティブリソース解放

#### Step 4: ダイアログ表示を理解する

モーダルダイアログの仕組み。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | ShowDialog | `src/Avalonia.Controls/Window.cs` | 886-901行目。モーダルダイアログ表示 |

**主要処理フロー**:
- **842-865行目**: TaskCompletionSourceでダイアログ結果を待機
- **856-861行目**: Closedイベントで結果をセット

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

```
Window.Show() / ShowDialog()
    │
    ├─ ShowCore
    │      ├─ EnsureStateBeforeShow
    │      ├─ EnsureParentStateBeforeShow (親ウィンドウ検証)
    │      ├─ EnsureInitialized
    │      ├─ ApplyStyling
    │      ├─ LayoutManager.ExecuteInitialLayoutPass
    │      ├─ SetWindowStartupLocation
    │      └─ PlatformImpl.Show
    │
    └─ OnOpened (イベント発火)

Window.Close()
    │
    ├─ CloseCore
    │      ├─ ShouldCancelClose
    │      │      ├─ OnClosing (Closingイベント)
    │      │      └─ 子ウィンドウのShouldCancelClose (再帰)
    │      │
    │      └─ CloseInternal
    │             ├─ 子ウィンドウのCloseInternal (再帰)
    │             ├─ PlatformImpl.Dispose
    │             └─ Owner = null
    │
    └─ HandleClosed
           └─ WindowClosedEvent発火
```

### データフロー図

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

XAMLプロパティ ────────▶ Window初期化 ──────────────────▶ プロパティ設定
                              │
Show()呼び出し ────────────▶ │
                              │
                         ShowCore
                              │
                    ┌─────────┼─────────┐
                    ▼         ▼         ▼
              スタイル適用  レイアウト  位置計算
                    │         │         │
                    └─────────┴─────────┘
                              │
                              ▼
                    PlatformImpl.Show
                              │
                              ▼
                    [ネイティブウィンドウ表示]
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Window.cs | `src/Avalonia.Controls/Window.cs` | ソース | Windowクラスの実装 |
| WindowBase.cs | `src/Avalonia.Controls/WindowBase.cs` | ソース | ウィンドウ基底クラス |
| TopLevel.cs | `src/Avalonia.Controls/TopLevel.cs` | ソース | トップレベルコンテナ基底 |
| IWindowImpl.cs | `src/Avalonia.Controls/Platform/IWindowImpl.cs` | ソース | プラットフォーム実装インターフェース |
| WindowIcon.cs | `src/Avalonia.Controls/WindowIcon.cs` | ソース | ウィンドウアイコン |
| WindowState.cs | `src/Avalonia.Controls/WindowState.cs` | ソース | ウィンドウ状態列挙型 |
