# 機能設計書 18-MenuItem

## 概要

本ドキュメントは、Avalonia UIフレームワークにおけるMenuItemコントロールの機能設計を記述する。MenuItemはメニュー内の個々の項目を表すコントロールである。

### 本機能の処理概要

MenuItemは、メニュー内の個々の選択可能項目を表すコントロールである。コマンドの実行、サブメニューの表示、チェックボックス/ラジオボタン的なトグル動作、アイコン表示、ホットキーの設定などの機能を提供する。

**業務上の目的・背景**：メニューシステムにおいて、各機能へのアクセスポイントとなるMenuItemは最も基本的な要素である。ファイル保存、コピー&ペースト、表示モードの切り替えなど、様々なアクションをMenuItemとして提供することで、ユーザーが直感的に機能を利用できる。

**機能の利用シーン**：
- コマンド実行（保存、開く、コピー等）
- サブメニューの親項目
- チェック可能なオプション項目
- ラジオボタン的な排他選択項目
- セパレーター（区切り線）

**主要な処理内容**：
1. Clickイベントによるコマンド実行
2. ICommand/CommandParameterによるMVVMパターン対応
3. サブメニュー（Popup）の開閉管理
4. ToggleType（None/CheckBox/Radio）によるトグル動作
5. HotKeyによるショートカットキー登録
6. Iconプロパティによるアイコン表示

**関連システム・外部連携**：HeaderedSelectingItemsControlを継承し、IMenuItem、ISelectable、ICommandSource、IClickableControl、IRadioButtonインターフェースを実装。

**権限による制御**：特になし。IsEnabledはCommandのCanExecuteと連動。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 37 | Menu | 関連画面 | Menuコントロール内でMenuItemを使用 |
| 19 | ContextMenu | 関連画面 | ContextMenu内でMenuItemを使用 |
| 134 | MenuInteractionTests | テスト画面 | メニューインタラクションテスト |

## 機能種別

ナビゲーションコントロール / コマンド実行

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| Header | object | No | メニュー項目のヘッダー（"-"でセパレーター） | - |
| Command | ICommand | No | 実行するコマンド | - |
| CommandParameter | object | No | コマンドパラメータ | - |
| HotKey | KeyGesture | No | ホットキー（グローバルショートカット） | - |
| InputGesture | KeyGesture | No | 表示用ジェスチャー（実行はしない） | - |
| Icon | object | No | アイコン | - |
| IsSubMenuOpen | bool | No | サブメニューが開いているか | - |
| StaysOpenOnClick | bool | No | クリックしてもメニューを閉じない | デフォルト: false |
| ToggleType | MenuItemToggleType | No | トグル種別（None/CheckBox/Radio） | - |
| IsChecked | bool | No | チェック状態（ToggleType有効時） | - |
| GroupName | string | No | ラジオグループ名（ToggleType=Radio時） | - |

### 入力データソース

- ItemsSourceプロパティへのデータバインディング（サブメニュー項目）
- XAMLでのプロパティ設定

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| IsSubMenuOpen | bool | サブメニューの開閉状態 |
| IsChecked | bool | チェック状態 |
| IsSelected | bool | 選択状態 |

### 出力先

- Clickイベント：項目クリック時
- SubmenuOpenedイベント：サブメニュー展開時

## 処理フロー

### 処理シーケンス

```
1. ユーザー操作（クリック/Enter/ホットキー）
2. OnClick処理
   ├─ サブメニューがある場合：Open()
   ├─ ToggleType有効時：IsChecked切り替え
   └─ Commandがある場合：Command.Execute()
3. Clickイベント発火
4. StaysOpenOnClick=falseの場合、メニュー閉じ
```

### フローチャート

```mermaid
flowchart TD
    A[ユーザー操作] --> B{サブメニューあり?}
    B -->|Yes| C[サブメニュー展開]
    B -->|No| D{ToggleType?}
    D -->|CheckBox| E[IsChecked切り替え]
    D -->|Radio| F[IsChecked=true、グループ他解除]
    D -->|None| G[Clickイベント]
    E --> G
    F --> G
    G --> H{Command有効?}
    H -->|Yes| I[Command.Execute]
    H -->|No| J[終了]
    I --> K{StaysOpenOnClick?}
    K -->|false| L[メニュー閉じ]
    K -->|true| J
    C --> M[SubmenuOpenedイベント]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | セパレーター判定 | Header="-"の場合、:separatorクラスが適用されFocusable=false | Header="-"時 |
| BR-02 | コマンド有効性 | サブメニューがない場合、IsEnabledはCommand.CanExecuteに依存 | サブメニューなし時 |
| BR-03 | ラジオグループ | ToggleType=Radio時、同一GroupName内で排他的選択 | ToggleType=Radio時 |
| BR-04 | ホットキー管理 | LogicalTree接続/切断時にHotKeyの登録/解除 | HotKey設定時 |

### 計算ロジック

特になし

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

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

該当なし（UIコントロール）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | コマンド無効 | CommandのCanExecute=false | IsEnabledがfalseになる |
| - | バインディングエラー | Commandプロパティのバインディング失敗 | _commandBindingErrorフラグで管理 |

### リトライ仕様

該当なし

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

該当なし（UIコントロール）

## パフォーマンス要件

- サブメニューIsOpen時のみCanExecuteを評価（パフォーマンス最適化）

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

特になし（UIコントロールとして汎用的に使用可能）

## 備考

- PseudoClasses: :separator, :radio, :toggle, :checked, :icon, :open, :pressed, :selected
- PART_Popupがテンプレートパーツ
- MenuItemAccessKeyHandlerを使用してサブメニュー内のアクセスキーを処理

---

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

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

### 推奨読解順序

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

MenuItem関連のインターフェースを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | IMenuItem.cs | `src/Avalonia.Controls/IMenuItem.cs` | メニュー項目インターフェース |
| 1-2 | ICommandSource.cs | `src/Avalonia.Base/Input/ICommandSource.cs` | コマンドソースインターフェース |
| 1-3 | MenuItemToggleType.cs | `src/Avalonia.Controls/MenuItemToggleType.cs` | トグル種別の列挙型 |

**読解のコツ**: IMenuItemはサブメニュー管理、選択状態、トグル状態などを定義する。ICommandSourceはCommand/CommandParameterパターンを定義。

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

MenuItemクラスを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | MenuItem.cs | `src/Avalonia.Controls/MenuItem.cs` | プロパティ、OnClick、トグル処理 |

**主要処理フロー**:
1. **25行目**: HeaderedSelectingItemsControlを継承、多数のインターフェース実装
2. **33-88行目**: プロパティ定義（Command, HotKey, Icon, ToggleType等）
3. **93-127行目**: イベント定義（Click, SubmenuOpened等）
4. **137-147行目**: 静的コンストラクタでミキシン適用、イベントハンドラ登録
5. **398-406行目**: Open/Close - サブメニュー開閉
6. **498-506行目**: OnClick - コマンド実行
7. **703-752行目**: OnPropertyChanged - 各プロパティ変更時の処理
8. **766-773行目**: ToggleTypeChanged - PseudoClasses更新
9. **779-788行目**: IsCheckedChanged - チェック状態変更処理

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

```
MenuItem
    │
    ├─ HeaderedSelectingItemsControl (基底クラス)
    │      └─ Header, ItemsSource
    │
    ├─ ICommandSource
    │      ├─ Command
    │      └─ CommandParameter
    │
    ├─ IRadioButton
    │      ├─ IsChecked
    │      └─ GroupName
    │
    ├─ PART_Popup (サブメニュー)
    │      └─ IsSubMenuOpen
    │
    ├─ HotKeyManager
    │      └─ HotKey登録
    │
    └─ DefaultMenuInteractionHandler
           └─ インタラクション管理
```

### データフロー図

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

クリック ───▶ OnClick() ───▶ Command.Execute()
                  │
                  ▼
         ToggleType処理 ───▶ IsChecked変更
                  │
                  ▼
         Clickイベント ───▶ イベント通知
                  │
HotKey ───▶ HotKeyManager ───▶ RaiseClick()
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| MenuItem.cs | `src/Avalonia.Controls/MenuItem.cs` | ソース | MenuItemコントロール本体 |
| MenuItemToggleType.cs | `src/Avalonia.Controls/MenuItemToggleType.cs` | ソース | トグル種別列挙型 |
| IMenuItem.cs | `src/Avalonia.Controls/IMenuItem.cs` | ソース | インターフェース |
| HeaderedSelectingItemsControl.cs | `src/Avalonia.Controls/Primitives/HeaderedSelectingItemsControl.cs` | ソース | 基底クラス |
| MenuItemAutomationPeer.cs | `src/Avalonia.Controls/Automation/Peers/MenuItemAutomationPeer.cs` | ソース | UIオートメーション対応 |
| MenuItemAccessKeyHandler.cs | `src/Avalonia.Controls/MenuItemAccessKeyHandler.cs` | ソース | アクセスキー処理 |
