# 画面設計書 63-Native Embed

## 概要

本ドキュメントは、Avalonia UIフレームワークのControlCatalogサンプルアプリケーションにおけるNative Embed（ネイティブ埋め込み）デモページの画面設計書です。プラットフォーム固有のネイティブコントロールをAvalonia UIに埋め込む機能を実証するためのデモ画面を定義します。

### 本画面の処理概要

本画面は、NativeControlHostを使用してプラットフォーム固有のネイティブコントロール（Win32、macOS、Linuxなど）をAvaloniaアプリケーション内に埋め込むデモページです。グリッドスプリッターで分割された2つの領域にネイティブコントロールを配置し、ポップアップやツールチップとの共存動作を確認できます。

**業務上の目的・背景**：
クロスプラットフォームアプリケーション開発において、特定のプラットフォームでのみ利用可能なネイティブコントロール（例：Windows Media Player、macOSのWebKit、LinuxのGTKウィジェット）を統合する必要がある場合があります。本デモページは、NativeControlHostを使用してそのような統合を実現する方法を開発者に示すことを目的としています。

**画面へのアクセス方法**：
ControlCatalogアプリケーションのメインウィンドウから、HamburgerMenuナビゲーションを使用して「Native Embed」項目を選択することでアクセスします。

**主要な操作・処理内容**：
1. ネイティブコントロールの表示：2つのEmbedSampleコントロールがそれぞれネイティブコントロールを表示
2. 表示/非表示の切り替え：各ネイティブコントロールにCheckBoxが設けられ、表示状態を制御
3. グリッドスプリッターによるリサイズ：垂直・水平のGridSplitterで領域サイズを調整
4. ポップアップ表示：「Show popup」「Show popup (delay)」ボタンでコンテキストメニュー表示
5. ツールチップ表示：ツールチップ領域にホバーするとToolTip表示
6. レスポンシブ対応：画面幅によりレイアウトが横並び/縦並びに切り替わる

**画面遷移**：
- 遷移元：MainView（HamburgerMenuナビゲーション経由）
- 遷移先：なし（デモページのため他画面への遷移機能なし）

**権限による表示制御**：
なし（デモアプリケーションのため権限管理は実装されていません）

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 96 | NativePlatform | 主機能 | ネイティブコントロール埋め込みのデモ、プラットフォーム固有コントロール |

## 画面種別

デモ / 表示

## URL/ルーティング

ControlCatalogアプリケーション内のHamburgerMenuナビゲーションで「Native Embed」を選択

## 入出力項目

| 項目名 | 項目種別 | データ型 | 必須 | 説明 |
|--------|----------|----------|------|------|
| firstVisible | 入力 | bool | - | 1つ目のネイティブコントロール表示状態 |
| secondVisible | 入力 | bool | - | 2つ目のネイティブコントロール表示状態 |
| IsSecond | 設定 | bool | - | 2つ目のEmbedSampleかどうかのフラグ |

## 表示項目

| 項目名 | 表示形式 | データソース | 説明 |
|--------|----------|--------------|------|
| メニュー | Menu | 静的 | Test > SubMenu階層のテストメニュー |
| TextBox | TextBox | 静的 | "Lorem ipsum dolor sit amet"のテキスト入力 |
| Tooltip領域 | Border/TextBlock | 静的 | ホバーでツールチップ表示 |
| Show popupボタン | Button | - | 即座にポップアップ表示 |
| Show popup (delay)ボタン | Button | - | 3秒遅延後にポップアップ表示 |
| 1つ目のCheckBox | CheckBox | firstVisible | 1つ目のネイティブコントロール表示制御 |
| 1つ目のEmbedSample | EmbedSample | - | ネイティブコントロール埋め込み領域 |
| 2つ目のCheckBox | CheckBox | secondVisible | 2つ目のネイティブコントロール表示制御 |
| 2つ目のEmbedSample | EmbedSample | IsSecond=True | ネイティブコントロール埋め込み領域（2つ目） |
| GridSplitter（水平） | GridSplitter | - | 横方向の領域分割 |
| GridSplitter（垂直） | GridSplitter | - | 縦方向の領域分割 |

## イベント仕様

### 1-Show popupボタン押下

コンテキストメニューを即座に表示します。

- **トリガー**: Show popupボタンのクリック
- **処理内容**: ShowPopupメソッドの実行
- **表示内容**: "Test"メニュー項目を2つ含むContextMenu

### 2-Show popup (delay)ボタン押下

3秒の遅延後にコンテキストメニューを表示します。

- **トリガー**: Show popup (delay)ボタンのクリック
- **処理内容**: ShowPopupDelayメソッドの実行（Task.Delay(3000)後にShowPopup呼び出し）
- **表示内容**: "Test"メニュー項目を2つ含むContextMenu

### 3-表示CheckBox変更

対応するネイティブコントロールの表示/非表示を切り替えます。

- **トリガー**: CheckBoxのIsChecked変更
- **処理内容**: EmbedSampleのIsVisibleプロパティを更新
- **データ更新**: バインディング経由で即座に反映

### 4-画面サイズ変更

画面幅1200px未満で縦並びレイアウトに切り替わります。

- **トリガー**: BoundsProperty変更
- **処理内容**: OnPropertyChangedでmobileクラスを設定
- **レイアウト更新**: Styleセレクターにより Grid.RowSpan/ColumnSpanが変更

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

本画面はデータベースを使用しません。

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

該当なし

## メッセージ仕様

本画面にはメッセージ表示機能はありません。

## 例外処理

| 例外ケース | 対応処理 |
|-----------|---------|
| ネイティブコントロール未実装 | デフォルトのプラットフォームハンドルを返却 |
| Implementation未設定 | base.CreateNativeControlCore()にフォールバック |

## 備考

- EmbedSampleクラスはNativeControlHostを継承し、INativeDemoControlインターフェースを通じてプラットフォーム固有の実装を受け入れます
- 実際のネイティブコントロールはプラットフォームごとに異なる実装が必要です
- モバイルレイアウト（画面幅1200px未満）では2つのパネルが縦並びに配置されます
- GridSplitterで領域サイズを自由に調整可能です

---

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

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

### 推奨読解順序

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

NativeControlHostとプラットフォーム固有実装のインターフェースを理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | NativeEmbedPage.xaml.cs | `samples/ControlCatalog/Pages/NativeEmbedPage.xaml.cs` | INativeDemoControl インターフェース（70-76行目） |
| 1-2 | NativeEmbedPage.xaml.cs | `samples/ControlCatalog/Pages/NativeEmbedPage.xaml.cs` | EmbedSample クラス（47-68行目） |

**読解のコツ**: EmbedSampleはNativeControlHostを継承しており、CreateNativeControlCoreメソッドをオーバーライドしてプラットフォーム固有のコントロールを作成します。Implementation静的プロパティを通じて実装を注入するパターンを理解してください。

#### Step 2: UI構造を理解する

XAMLファイルでUIレイアウトとスタイルを理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | NativeEmbedPage.xaml | `samples/ControlCatalog/Pages/NativeEmbedPage.xaml` | DockPanelとGridによるレイアウト構造 |
| 2-2 | NativeEmbedPage.xaml | `samples/ControlCatalog/Pages/NativeEmbedPage.xaml` | Styleセレクターによるレスポンシブ対応（38-51行目） |

**主要処理フロー**:
1. **9-21行目**: Menu定義（Test > SubMenu階層）
2. **22-35行目**: ツールバー領域（TextBox、ボタン、ツールチップ）
3. **36-66行目**: メイングリッド（2つのパネルとGridSplitter）
4. **38-51行目**: mobileクラスによるレスポンシブスタイル

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

コードビハインドのイベントハンドラを理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | NativeEmbedPage.xaml.cs | `samples/ControlCatalog/Pages/NativeEmbedPage.xaml.cs` | ShowPopup/ShowPopupDelayメソッド（17-32行目） |
| 3-2 | NativeEmbedPage.xaml.cs | `samples/ControlCatalog/Pages/NativeEmbedPage.xaml.cs` | OnPropertyChangedメソッド（34-44行目） |

**主要処理フロー**:
- **17-21行目**: ShowPopupDelay - 3秒待機後にShowPopup呼び出し
- **23-31行目**: ShowPopup - ContextMenuを動的に生成して表示
- **34-44行目**: BoundsProperty変更時にmobileクラスを設定

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

```
NativeEmbedPage (UserControl)
    │
    ├─ NativeEmbedPage.xaml.cs
    │      ├─ ShowPopupDelay()
    │      │      └─ Task.Delay(3000)
    │      │             └─ ShowPopup()
    │      │
    │      ├─ ShowPopup()
    │      │      └─ new ContextMenu().Open()
    │      │
    │      └─ OnPropertyChanged()
    │             └─ Classes.Set("mobile", isMobile)
    │
    └─ EmbedSample (NativeControlHost)
           │
           ├─ static Implementation (INativeDemoControl)
           │
           ├─ CreateNativeControlCore()
           │      └─ Implementation?.CreateControl()
           │             └─ base.CreateNativeControlCore() [フォールバック]
           │
           └─ DestroyNativeControlCore()
                  └─ base.DestroyNativeControlCore()
```

### データフロー図

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

CheckBox.IsChecked ─────▶ {Binding #firstVisible...} ─▶ EmbedSample.IsVisible
                                                              │
Button.Click ───────────▶ ShowPopup() ────────────────▶ ContextMenu表示
                                                              │
Button.Click ───────────▶ ShowPopupDelay() ───────────▶ 3秒後 ContextMenu表示
                                                              │
Bounds変更 ─────────────▶ OnPropertyChanged() ────────▶ mobileクラス設定
     │                                                        │
     │                                                        ▼
     │                                                 Grid.RowSpan/ColumnSpan変更
     │
     └─▶ INativeDemoControl.CreateControl() ─────────▶ ネイティブコントロール表示
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| NativeEmbedPage.xaml | `samples/ControlCatalog/Pages/NativeEmbedPage.xaml` | XAML | UI定義、レイアウト |
| NativeEmbedPage.xaml.cs | `samples/ControlCatalog/Pages/NativeEmbedPage.xaml.cs` | ソース | コードビハインド、EmbedSampleクラス、INativeDemoControlインターフェース |
| NativeControlHost.cs | `src/Avalonia.Controls/NativeControlHost.cs` | ソース | ネイティブコントロールホスト基底クラス |
| IPlatformHandle.cs | `src/Avalonia.Base/Platform/IPlatformHandle.cs` | ソース | プラットフォームハンドルインターフェース |
