# 機能設計書 48-NativeMenu

## 概要

本ドキュメントは、Avalonia UIフレームワークにおけるNativeMenu（ネイティブメニュー）機能の設計仕様を定義する。NativeMenuは各プラットフォームのネイティブメニューシステムを使用したメニューを作成・管理する。

### 本機能の処理概要

NativeMenuクラスは、macOSのアプリケーションメニュー、Windowsのシステムメニュー、TrayIconのコンテキストメニューなど、各プラットフォームのネイティブメニュー機能を抽象化する。メニュー項目の追加・削除、イベント処理、サブメニュー管理などを提供する。

**業務上の目的・背景**：macOSアプリケーションではネイティブのメニューバーが標準であり、その他のプラットフォームでもコンテキストメニューやシステムトレイメニューにネイティブメニューが使用される。NativeMenuはこれらのネイティブメニューを統一的なAPIで提供する。

**機能の利用シーン**：macOSメニューバー、TrayIconのコンテキストメニュー、ネイティブコンテキストメニューの表示など。

**主要な処理内容**：
1. メニュー項目（NativeMenuItem）の管理
2. サブメニューの階層構造
3. メニュー表示前の更新通知（NeedsUpdate）
4. メニューの開閉イベント通知
5. 親子関係の管理

**関連システム・外部連携**：INativeMenuExporter（プラットフォームエクスポーター）、TrayIcon、Windowと連携する。

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | ネイティブメニューとして表示（画面外） |

## 機能種別

メニュー管理 / ネイティブ連携 / イベント処理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| Items | IList<NativeMenuItemBase> | No | メニュー項目のリスト | 自動初期化 |

### 入力データソース

- XAML: NativeMenuの宣言的定義
- コード: 動的なメニュー項目追加

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| Items | IList<NativeMenuItemBase> | メニュー項目のリスト |
| Parent | NativeMenuItem? | 親メニュー項目 |

### 出力先

- イベント: NeedsUpdate、Opening、Closed

## 処理フロー

### 処理シーケンス

```
1. NativeMenu 作成
   └─ AvaloniaList<NativeMenuItemBase> 初期化

2. Items 設定
   └─ CollectionChangedでParent管理

3. プラットフォームエクスポーターに設定
   └─ Window.NativeMenuまたはTrayIcon.Menu

4. メニュー表示要求
   └─ NeedsUpdateイベント発火
   └─ Openingイベント発火
   └─ ネイティブメニュー表示

5. メニュークローズ
   └─ Closedイベント発火
```

### フローチャート

```mermaid
flowchart TD
    A[NativeMenu作成] --> B[Items初期化]
    B --> C[Items.Add で項目追加]
    C --> D[Parentプロパティ設定]
    D --> E[エクスポーターに設定]
    E --> F{メニュー表示要求}
    F -->|Yes| G[NeedsUpdateイベント]
    G --> H[Openingイベント]
    H --> I[ネイティブメニュー表示]
    I --> J{メニュー選択/クローズ}
    J -->|選択| K[NativeMenuItem.Click]
    J -->|クローズ| L[Closedイベント]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | 単一親 | メニュー項目は同時に1つのメニューにのみ所属可能 | 常時適用 |
| BR-002 | 親チェック | 既にParentを持つ項目の追加はInvalidOperationException | 項目追加時 |
| BR-003 | NeedsUpdate優先 | メニュー更新はNeedsUpdateイベントで行う（Opening/Closedでは不可） | メニュー更新時 |

### 計算ロジック

特記すべき計算ロジックなし。

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | InvalidOperationException | 既にParentを持つ項目を追加 | 先に元のメニューから削除 |

### リトライ仕様

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

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

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

## パフォーマンス要件

- メニュー表示は即座に完了
- NeedsUpdateイベントは高頻度で呼ばれる可能性あり

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

特になし。

## 備考

- macOSではアプリケーションメニューバーとして統合
- Windows/LinuxではTrayIconのコンテキストメニュー等で使用
- メニュー項目の動的更新はNeedsUpdateイベント内で行う

---

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

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

### 推奨読解順序

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

NativeMenuクラスの構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | フィールド | `src/Avalonia.Controls/NativeMenu.cs` | 15-17行目。_itemsと_parent |
| 1-2 | Content属性 | `src/Avalonia.Controls/NativeMenu.cs` | 19行目。XAMLでのコンテンツプロパティ指定 |
| 1-3 | Itemsプロパティ | `src/Avalonia.Controls/NativeMenu.cs` | 20行目。メニュー項目リスト |

**読解のコツ**: _itemsがAvaloniaListで、ResetBehavior.Removeにより削除時に通知される。

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

メニューライフサイクルイベント。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | NeedsUpdateイベント | `src/Avalonia.Controls/NativeMenu.cs` | 22-29行目。更新通知 |
| 2-2 | Openingイベント | `src/Avalonia.Controls/NativeMenu.cs` | 31-37行目。開く前通知 |
| 2-3 | Closedイベント | `src/Avalonia.Controls/NativeMenu.cs` | 39-45行目。閉じた後通知 |

**読解のコツ**: NeedsUpdateでメニュー更新、Opening/Closedでは更新しない。

#### Step 3: コレクション管理を理解する

メニュー項目のコレクション管理。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | コンストラクタ | `src/Avalonia.Controls/NativeMenu.cs` | 47-51行目。Validatorとイベント設定 |
| 3-2 | Validate | `src/Avalonia.Controls/NativeMenu.cs` | 68-76行目。親チェックバリデーション |
| 3-3 | ItemsChanged | `src/Avalonia.Controls/NativeMenu.cs` | 78-86行目。Parent管理 |

**主要処理フロー**:
- **70-75行目**: 既に親を持つ項目の追加をブロック
- **80-82行目**: 削除された項目のParentをnullに
- **83-85行目**: 追加された項目のParentを設定

#### Step 4: イベントブリッジを理解する

プラットフォーム実装からのイベント伝播。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | INativeMenuExporterEventsImplBridge | `src/Avalonia.Controls/NativeMenu.cs` | 53-66行目。内部イベント発火 |
| 4-2 | Parentプロパティ | `src/Avalonia.Controls/NativeMenu.cs` | 88-95行目。親の取得・設定 |

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

```
NativeMenu()
    │
    ├─ _items = new AvaloniaList (ResetBehavior.Remove)
    ├─ _items.Validator = this
    └─ _items.CollectionChanged += ItemsChanged

Items.Add(item)
    │
    ├─ IAvaloniaListItemValidator.Validate(item)
    │      └─ 既存Parentチェック → InvalidOperationException
    │
    └─ ItemsChanged (CollectionChanged)
           └─ item.Parent = this

INativeMenuExporterEventsImplBridge (内部)
    │
    ├─ RaiseNeedsUpdate → NeedsUpdate?.Invoke
    ├─ RaiseOpening → Opening?.Invoke
    └─ RaiseClosed → Closed?.Invoke
```

### データフロー図

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

XAML/コード ────────────▶ NativeMenu作成 ───────────────▶ _items初期化
                              │
Items.Add ─────────────────▶ Validate
                              │
                              ▼
                         ItemsChanged
                              │
                              ▼
                         Parent設定
                              │
                              ▼
                    エクスポーター登録
                              │
                              ▼
プラットフォーム ────────▶ RaiseNeedsUpdate ───────────▶ NeedsUpdateイベント
                    ────────▶ RaiseOpening ────────────▶ Openingイベント
                    ────────▶ RaiseClosed ─────────────▶ Closedイベント
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| NativeMenu.cs | `src/Avalonia.Controls/NativeMenu.cs` | ソース | NativeMenuクラスの実装 |
| NativeMenuItemBase.cs | `src/Avalonia.Controls/NativeMenuItemBase.cs` | ソース | メニュー項目基底クラス |
| NativeMenuItem.cs | `src/Avalonia.Controls/NativeMenuItem.cs` | ソース | メニュー項目 |
| NativeMenuItemSeparator.cs | `src/Avalonia.Controls/NativeMenuItemSeparator.cs` | ソース | セパレーター |
| INativeMenuExporter.cs | `src/Avalonia.Controls/Platform/INativeMenuExporter.cs` | ソース | エクスポーターインターフェース |
