# 機能設計書 47-TrayIcon

## 概要

本ドキュメントは、Avalonia UIフレームワークにおけるTrayIcon（システムトレイアイコン）機能の設計仕様を定義する。TrayIconはシステムトレイ（通知領域）にアイコンを表示し、コンテキストメニューやクリックイベントを提供する。

### 本機能の処理概要

TrayIconクラスは、Windowsのシステムトレイ、LinuxのシステムトレイやAppIndicator、macOSのメニューバーステータスアイテムなど、各プラットフォームの通知領域にアイコンを表示する機能を提供する。アイコン、ツールチップ、コンテキストメニューの設定が可能。

**業務上の目的・背景**：バックグラウンドで動作するアプリケーションやメインウィンドウを閉じても動作を継続するアプリケーションでは、システムトレイアイコンが必要となる。TrayIconはクロスプラットフォームで一貫したシステムトレイ機能を提供する。

**機能の利用シーン**：バックグラウンドサービス、常駐アプリケーション、ウィンドウ最小化時のトレイ格納、クイックアクセスメニューの提供など。

**主要な処理内容**：
1. システムトレイへのアイコン表示
2. ツールチップテキストの設定
3. コンテキストメニュー（NativeMenu）の表示
4. クリックイベントの処理
5. コマンドパターンでのアクション実行
6. 表示/非表示の制御

**関連システム・外部連携**：ITrayIconImpl（プラットフォーム実装）、NativeMenu、WindowIconと連携する。

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | ウィンドウ外（システムトレイ）に表示 |

## 機能種別

システム連携 / イベント処理 / メニュー表示

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| Icon | WindowIcon | No | トレイに表示するアイコン | - |
| ToolTipText | string | No | ツールチップテキスト | - |
| Menu | NativeMenu | No | コンテキストメニュー | - |
| Command | ICommand | No | クリック時に実行するコマンド | - |
| CommandParameter | object | No | コマンドパラメータ | - |
| IsVisible | bool | No | 表示/非表示 | デフォルト: true |

### 入力データソース

- XAML: App.axamlでのTrayIcon.Icons設定
- コード: 動的なプロパティ設定

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| NativeMenuExporter | INativeMenuExporter | ネイティブメニューエクスポーター |

### 出力先

- システムトレイ: ネイティブアイコン表示
- イベント: Clicked

## 処理フロー

### 処理シーケンス

```
1. TrayIcon インスタンス作成
   └─ PlatformManager.CreateTrayIcon()

2. プロパティ設定
   └─ Icon、ToolTipText、Menu等

3. Application.Icons に追加
   └─ TrayIcons コレクションへの追加

4. ユーザー操作
   └─ クリック: Clickedイベント発火
   └─ 右クリック: NativeMenu表示

5. アプリケーション終了
   └─ UIThread.ShutdownStarted で自動Dispose
```

### フローチャート

```mermaid
flowchart TD
    A[TrayIcon作成] --> B[PlatformManager.CreateTrayIcon]
    B --> C[プロパティ設定]
    C --> D[TrayIcons.Add]
    D --> E{ユーザー操作}
    E -->|左クリック| F[Clickedイベント発火]
    E -->|右クリック| G[NativeMenu表示]
    F --> H{Commandあり?}
    H -->|Yes| I[Command.Execute]
    H -->|No| E
    G --> E
    E -->|アプリ終了| J[Dispose]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | Icons所有者制限 | TrayIcon.IconsはApplicationにのみ設定可能 | 常時適用 |
| BR-002 | 自動クリーンアップ | UIThreadシャットダウン時に自動Dispose | 常時適用 |
| BR-003 | macOSクリック制限 | macOSではClickedイベントが発火しない | macOS |

### 計算ロジック

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

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | InvalidOperationException | Application以外にTrayIcon.Iconsを設定 | Applicationに設定 |

### リトライ仕様

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

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

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

## パフォーマンス要件

- アイコン表示は即座に反映
- クリックイベントは即座に処理

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

特になし。

## 備考

- Win32とLinuxの一部デスクトップ環境でClickedイベントをサポート
- macOSではステータスアイテムとして表示されるが、クリックイベントは非サポート
- プラットフォームがトレイアイコンをサポートしない場合、Implがnullになる

---

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

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

### 推奨読解順序

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | TrayIcons クラス | `src/Avalonia.Controls/TrayIcon.cs` | 14-16行目。TrayIconのコレクション |
| 1-2 | TrayIcon クラス | `src/Avalonia.Controls/TrayIcon.cs` | 18行目。AvaloniaObject継承 |
| 1-3 | プロパティ定義 | `src/Avalonia.Controls/TrayIcon.cs` | 81-118行目。StyledProperty各種 |

**読解のコツ**: _implフィールドがプラットフォーム実装へのブリッジ。

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

TrayIcon作成とイベント設定。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | プライベートコンストラクタ | `src/Avalonia.Controls/TrayIcon.cs` | 22-40行目。ITrayIconImpl受け取り |
| 2-2 | パブリックコンストラクタ | `src/Avalonia.Controls/TrayIcon.cs` | 42-44行目。PlatformManager経由作成 |
| 2-3 | 静的コンストラクタ | `src/Avalonia.Controls/TrayIcon.cs` | 46-69行目。IconsProperty購読、シャットダウン処理 |

**主要処理フロー**:
1. **28行目**: IsVisible初期設定
2. **30-37行目**: Clickedイベントハンドラ設定、Command実行
3. **48-66行目**: Icons変更時のコレクション管理
4. **68行目**: シャットダウン時のクリーンアップ登録

#### Step 3: プロパティ変更処理を理解する

プロパティ変更時のプラットフォーム連携。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | OnPropertyChanged | `src/Avalonia.Controls/TrayIcon.cs` | 209-229行目。プロパティ変更ハンドラ |

**主要処理フロー**:
- **213-216行目**: Iconプロパティ変更時
- **217-220行目**: IsVisibleプロパティ変更時
- **221-224行目**: ToolTipTextプロパティ変更時
- **225-228行目**: Menuプロパティ変更時

#### Step 4: ライフサイクル処理を理解する

TrayIconのクリーンアップ処理。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | ShutdownStarted | `src/Avalonia.Controls/TrayIcon.cs` | 183-192行目。シャットダウン時処理 |
| 4-2 | Icons_CollectionChanged | `src/Avalonia.Controls/TrayIcon.cs` | 194-198行目。コレクション変更時処理 |
| 4-3 | RemoveIcons | `src/Avalonia.Controls/TrayIcon.cs` | 200-206行目。アイコン削除 |
| 4-4 | Dispose | `src/Avalonia.Controls/TrayIcon.cs` | 234行目。リソース解放 |

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

```
TrayIcon()
    │
    └─ TrayIcon(ITrayIconImpl?)
           │
           ├─ _impl.SetIsVisible(IsVisible)
           └─ _impl.OnClicked = () => ...
                  ├─ Clicked?.Invoke
                  └─ Command?.Execute

Application.SetIcons(trayIcons)
    │
    └─ IconsProperty.Changed.Subscribe
           └─ CollectionChanged購読

Dispatcher.UIThread.ShutdownStarted
    │
    └─ ShutdownStarted
           └─ RemoveIcons → Dispose

OnPropertyChanged
    │
    ├─ IconProperty → _impl.SetIcon
    ├─ IsVisibleProperty → _impl.SetIsVisible
    ├─ ToolTipTextProperty → _impl.SetToolTipText
    └─ MenuProperty → _impl.MenuExporter.SetNativeMenu
```

### データフロー図

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

App.axaml設定 ─────────▶ TrayIcon作成 ──────────────────▶ _impl初期化
                              │
プロパティ設定 ────────────▶ OnPropertyChanged
                              │
                              ▼
                         _impl.SetXxx
                              │
                              ▼
                    [システムトレイに反映]

ユーザークリック ────────▶ _impl.OnClicked
                              │
                              ▼
                    ┌─────────┴─────────┐
                    ▼                   ▼
              Clickedイベント      Command.Execute
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| TrayIcon.cs | `src/Avalonia.Controls/TrayIcon.cs` | ソース | TrayIconクラスの実装 |
| ITrayIconImpl.cs | `src/Avalonia.Controls/Platform/ITrayIconImpl.cs` | ソース | プラットフォームインターフェース |
| NativeMenu.cs | `src/Avalonia.Controls/NativeMenu.cs` | ソース | ネイティブメニュー |
| WindowIcon.cs | `src/Avalonia.Controls/WindowIcon.cs` | ソース | ウィンドウアイコン |
| PlatformManager.cs | `src/Avalonia.Controls/Platform/PlatformManager.cs` | ソース | プラットフォームマネージャー |
