# 画面設計書 91-WindowDecorations

## 概要

本ドキュメントは、IntegrationTestAppアプリケーションにおけるWindowDecorationsPageの画面設計書です。ウィンドウ装飾（Window Decorations）のカスタマイズ機能をテストするためのページとして設計されています。

### 本画面の処理概要

**業務上の目的・背景**：本画面は、Avaloniaフレームワークにおけるウィンドウ装飾機能の統合テストを目的としています。クロスプラットフォームアプリケーション開発において、ウィンドウのタイトルバー、境界線、システムクロームなどの装飾をカスタマイズする必要があるケースがあり、これらの機能が正しく動作することを検証するためのテストUIを提供します。特にmacOS固有のThick SystemChromeや、クライアント領域の拡張機能など、プラットフォーム依存の振る舞いを検証できます。

**画面へのアクセス方法**：IntegrationTestAppのメインウィンドウ左側のListBoxナビゲーションから「Window Decorations」項目を選択することでアクセスします。

**主要な操作・処理内容**：
1. クライアント領域をウィンドウ装飾まで拡張するオプションの設定（ExtendClientAreaToDecorationsHint）
2. システムクロームの強制使用設定（Force SystemChrome）
3. システムクロームの優先使用設定（Prefer SystemChrome）
4. macOS特有の太いタイトルバー設定（Mac Thick SystemChrome）
5. タイトルエリアコントロールの表示設定
6. タイトルバーの高さヒント値の入力（DIP単位）
7. 現在のウィンドウに装飾設定を適用
8. 新しいウィンドウを開いて装飾設定を適用

**画面遷移**：この画面はIntegrationTestAppのメインウィンドウ内のページとして表示されます。「Show new Window with decorations」ボタン押下時にShowWindowTestウィンドウが新規に開きます。

**権限による表示制御**：特になし。すべてのユーザーが全機能を利用可能です。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 42 | Window | 主機能 | ウィンドウ装飾の設定・テスト。ExtendClientAreaToDecorationsHint、ExtendClientAreaChromeHintsなどのプロパティを操作 |

## 画面種別

設定・テスト画面

## URL/ルーティング

デスクトップアプリケーションのため、URLルーティングはなし。MainWindowのListBoxナビゲーションから「Window Decorations」を選択。

## 入出力項目

| 項目名 | 入出力 | 型 | 必須 | 説明 |
|--------|--------|-----|------|------|
| WindowExtendClientAreaToDecorationsHint | 入力 | CheckBox (bool) | - | クライアント領域を装飾まで拡張するか |
| WindowForceSystemChrome | 入力 | CheckBox (bool) | - | システムクロームを強制するか |
| WindowPreferSystemChrome | 入力 | CheckBox (bool) | - | システムクロームを優先するか |
| WindowMacThickSystemChrome | 入力 | CheckBox (bool) | - | macOS太いタイトルバーを使用するか |
| WindowShowTitleAreaControl | 入力 | CheckBox (bool) | - | タイトルエリアコントロールを表示するか |
| WindowTitleBarHeightHint | 入力 | TextBox (string) | - | タイトルバーの高さヒント（DIP単位、デフォルト: -1） |
| WindowDecorationProperties | 出力 | TextBox (string) | - | 適用結果の表示（OffScreenMargin、WindowDecorationMargin、IsExtendedIntoWindowDecorations） |

## 表示項目

| 項目名 | 説明 |
|--------|------|
| WindowDecorationProperties | ウィンドウ装飾プロパティの現在値を表示（OffScreenMargin.Top、WindowDecorationMargin.Top、IsExtendedIntoWindowDecorations） |

## イベント仕様

### 1-ApplyWindowDecorations_Click

**トリガー**: 「Apply decorations on this Window」ボタン押下

**処理内容**:
1. 現在のウィンドウ（TopLevel.GetTopLevel）を取得
2. SetWindowDecorationsメソッドを呼び出し
3. チェックボックスの状態に基づいてExtendClientAreaToDecorationsHintを設定
4. タイトルバー高さヒントをパースしてExtendClientAreaTitleBarHeightHintを設定
5. ExtendClientAreaChromeHintsをNoChrome + 各チェックボックス状態の組み合わせで設定
6. ウィンドウの背景を透明に設定
7. PropertyChangedイベントハンドラを登録してオフセットの自動調整を有効化

### 2-ShowNewWindowDecorations_Click

**トリガー**: 「Show new Window with decorations」ボタン押下

**処理内容**:
1. ShowWindowTestインスタンスを新規作成
2. SetWindowDecorationsメソッドで装飾設定を適用
3. WindowShowTitleAreaControlがチェックされている場合、ShowTitleAreaControlを呼び出し
4. ウィンドウをShow()で表示

## データベース更新仕様

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

本画面はUIコントロールのテスト用であり、データベース操作は行いません。

## メッセージ仕様

| 種別 | メッセージ | 表示条件 |
|------|----------|----------|
| 例外 | "WindowDecorationsPage is not attached to a Window." | ApplyWindowDecorations_Click時にウィンドウが取得できない場合 |

## 例外処理

| 例外 | 発生条件 | 処理 |
|------|----------|------|
| AvaloniaInternalException | TopLevel.GetTopLevelがnullを返した場合 | 例外をスロー |

## 備考

- タイトルバー高さヒント値の入力はDIP（Device Independent Pixels）単位
- ExtendClientAreaChromeHintsは複数のフラグの組み合わせ（NoChrome、SystemChrome、PreferSystemChrome、OSXThickTitleBar）
- macOS固有の機能（OSXThickTitleBar）はmacOSでのみ有効

---

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

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

### 推奨読解順序

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

まず、ウィンドウ装飾に関連するプロパティと列挙型を理解することが重要です。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Window.cs | `src/Avalonia.Controls/Window.cs` | ExtendClientAreaToDecorationsHint、ExtendClientAreaTitleBarHeightHint、ExtendClientAreaChromeHintsプロパティの定義 |
| 1-2 | ExtendClientAreaChromeHints.cs | `src/Avalonia.Controls/ExtendClientAreaChromeHints.cs` | NoChrome、SystemChrome、PreferSystemChrome、OSXThickTitleBarの列挙型定義 |

**読解のコツ**: ExtendClientAreaChromeHintsは[Flags]属性を持つ列挙型で、ビット演算による組み合わせが可能です。

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

処理の起点となるページファイルを確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | WindowDecorationsPage.axaml | `samples/IntegrationTestApp/Pages/WindowDecorationsPage.axaml` | UI構造とコントロール名の定義 |
| 2-2 | WindowDecorationsPage.axaml.cs | `samples/IntegrationTestApp/Pages/WindowDecorationsPage.axaml.cs` | イベントハンドラとSetWindowDecorationsメソッドの実装 |

**主要処理フロー**:
1. **行14-19**: ApplyWindowDecorations_Clickでボタンイベントを処理
2. **行56-61**: TopLevel.GetTopLevelで現在のウィンドウを取得
3. **行15-54**: SetWindowDecorationsで装飾プロパティを設定

#### Step 3: 新規ウィンドウ表示を理解する

ShowWindowTestウィンドウの構造と動作を確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | ShowWindowTest.axaml | `samples/IntegrationTestApp/ShowWindowTest.axaml` | テスト用ウィンドウのUI構造、TitleAreaControlの定義 |
| 3-2 | ShowWindowTest.axaml.cs | `samples/IntegrationTestApp/ShowWindowTest.axaml.cs` | ShowTitleAreaControlメソッドの実装 |

**主要処理フロー**:
- **行142-151**: ShowTitleAreaControlでタイトルエリアコントロールを表示・配置

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

```
WindowDecorationsPage
    │
    ├─ ApplyWindowDecorations_Click
    │      ├─ TopLevel.GetTopLevel(this)
    │      └─ SetWindowDecorations(window)
    │             ├─ Window.ExtendClientAreaToDecorationsHint設定
    │             ├─ Window.ExtendClientAreaTitleBarHeightHint設定
    │             ├─ Window.ExtendClientAreaChromeHints設定
    │             ├─ Window.Background設定
    │             └─ Window.PropertyChanged += AdjustOffsets
    │
    └─ ShowNewWindowDecorations_Click
           ├─ new ShowWindowTest()
           ├─ SetWindowDecorations(window)
           ├─ ShowWindowTest.ShowTitleAreaControl()
           └─ Window.Show()
```

### データフロー図

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

CheckBox群        ───▶  SetWindowDecorations()  ───▶  Window装飾プロパティ更新
(各装飾オプション)       │
                        ├─ ExtendClientAreaChromeHints    ───▶  タイトルバー外観変更
TextBox                 │   (NoChrome | SystemChrome等)
(TitleBarHeightHint) ───┤
                        ├─ ExtendClientAreaTitleBarHeightHint ─▶  タイトルバー高さ変更
                        │
                        └─ PropertyChanged監視            ───▶  WindowDecorationProperties
                                                               (結果表示)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| WindowDecorationsPage.axaml | `samples/IntegrationTestApp/Pages/WindowDecorationsPage.axaml` | ソース | ページのUI定義 |
| WindowDecorationsPage.axaml.cs | `samples/IntegrationTestApp/Pages/WindowDecorationsPage.axaml.cs` | ソース | ページのコードビハインド |
| ShowWindowTest.axaml | `samples/IntegrationTestApp/ShowWindowTest.axaml` | ソース | テスト用ウィンドウのUI定義 |
| ShowWindowTest.axaml.cs | `samples/IntegrationTestApp/ShowWindowTest.axaml.cs` | ソース | テスト用ウィンドウのコードビハインド |
| MainWindow.axaml | `samples/IntegrationTestApp/MainWindow.axaml` | ソース | メインウィンドウとナビゲーション |
| MainWindow.axaml.cs | `samples/IntegrationTestApp/MainWindow.axaml.cs` | ソース | ページ生成ファクトリ |
