# 機能設計書 43-Application

## 概要

本ドキュメントは、Avalonia UIフレームワークにおけるApplication（アプリケーションクラス）機能の設計仕様を定義する。Applicationクラスはアプリケーション全体のライフサイクルとグローバルリソースを管理する中心的なクラスである。

### 本機能の処理概要

Applicationクラスは、Avaloniaアプリケーションの起点となるクラスであり、アプリケーション全体で共有されるスタイル、データテンプレート、リソース、テーマを管理する。また、アプリケーションのライフサイクル（起動・終了）を制御し、InputManagerやFocusManager等の必須サービスの登録を行う。

**業務上の目的・背景**：アプリケーション開発において、グローバルに共有されるリソースやスタイル、テーマの一元管理は必須である。Applicationクラスはこれらを統合的に管理し、アプリケーション全体で一貫したUIを実現するための基盤を提供する。

**機能の利用シーン**：アプリケーションの初期化、グローバルスタイルの定義、テーマ（ライト/ダーク）の切り替え、データテンプレートの登録、アプリケーション終了処理など、アプリケーションのライフサイクル全般で使用される。

**主要な処理内容**：
1. アプリケーションインスタンスの作成と初期化
2. グローバルスタイル・リソースの管理
3. データテンプレートの登録
4. テーマバリアント（ライト/ダーク）の管理
5. InputManager・ToolTipService等のサービス登録
6. アプリケーションライフタイムの管理

**関連システム・外部連携**：AppBuilder（アプリケーション構成）、IApplicationLifetime（ライフタイム管理）、IPlatformSettings（プラットフォーム設定）と連携する。

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 100 | Desktop | 主画面 | デスクトップのテスト。アプリケーションライフサイクル |

## 機能種別

ライフサイクル管理 / リソース管理 / サービス登録

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| DataContext | object | No | アプリケーションのデータコンテキスト | - |
| RequestedThemeVariant | ThemeVariant | No | 要求するテーマバリアント | Default/Light/Dark |
| Name | string | No | アプリケーション名 | デフォルト: "Avalonia Application" |

### 入力データソース

- App.axaml: アプリケーションリソース定義
- コード: Application.Initialize()での初期化処理
- プラットフォーム: システムテーマ設定

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| Current | Application | 現在のアプリケーションインスタンス |
| DataTemplates | DataTemplates | グローバルデータテンプレート |
| Styles | Styles | グローバルスタイル |
| Resources | IResourceDictionary | グローバルリソース |
| ActualThemeVariant | ThemeVariant | 実際に適用されているテーマ |
| ApplicationLifetime | IApplicationLifetime | アプリケーションライフタイム |
| PlatformSettings | IPlatformSettings | プラットフォーム設定 |

### 出力先

- イベント: ResourcesChanged、ActualThemeVariantChanged
- サービス登録: AvaloniaLocator

## 処理フロー

### 処理シーケンス

```
1. AppBuilder.Configure<App>()
   └─ Applicationファクトリの設定

2. AppBuilder.SetupWithoutStarting() または Start()
   └─ RuntimePlatformServices初期化
   └─ RenderingSubsystem初期化
   └─ WindowingSubsystem初期化

3. Application インスタンス作成
   └─ コンストラクタ実行

4. RegisterServices()
   └─ 必須サービスの登録
   └─ InputManager作成
   └─ テーマバリアント初期化

5. Initialize()
   └─ XAML読み込み・初期化

6. OnFrameworkInitializationCompleted()
   └─ アプリケーション固有の初期化
```

### フローチャート

```mermaid
flowchart TD
    A[AppBuilder.Configure] --> B[プラットフォーム設定]
    B --> C[Setup実行]
    C --> D[RuntimePlatformServices初期化]
    D --> E[RenderingSubsystem初期化]
    E --> F[WindowingSubsystem初期化]
    F --> G[Application作成]
    G --> H[AvaloniaLocatorに登録]
    H --> I[RegisterServices]
    I --> J[Initialize XAML読み込み]
    J --> K[OnFrameworkInitializationCompleted]
    K --> L[アプリケーション実行開始]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | シングルトン | Applicationインスタンスは1つのみ | Application.Currentでアクセス |
| BR-002 | ライフタイム不変 | Setup完了後はApplicationLifetimeを変更不可 | Setup完了後 |
| BR-003 | テーマ継承 | RequestedThemeVariant=DefaultでOSテーマに追従 | テーマ未指定時 |

### 計算ロジック

**ActualThemeVariantの決定**：
```
if (RequestedThemeVariant != null && RequestedThemeVariant != ThemeVariant.Default)
    ActualThemeVariant = RequestedThemeVariant
else
    ActualThemeVariant = PlatformSettings.ColorValues.ThemeVariant
```

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | InvalidOperationException | Setup後にApplicationLifetimeを変更 | Setup前に設定 |

### リトライ仕様

アプリケーション初期化にリトライは適用されない。初期化失敗時はアプリケーション終了。

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

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

## パフォーマンス要件

- アプリケーション初期化は1秒以内
- スタイル・リソース検索は高速ルックアップを使用

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

特になし。

## 備考

- Application.Currentはどこからでもアクセス可能
- グローバルスタイルはすべてのウィンドウに適用される

---

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

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

### 推奨読解順序

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

Applicationクラスが管理するデータを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | フィールド | `src/Avalonia.Controls/Application.cs` | 37-45行目。スタイル、リソース、ライフタイム等の管理 |
| 1-2 | プロパティ | `src/Avalonia.Controls/Application.cs` | 82-155行目。Current、DataTemplates、Styles等 |

**読解のコツ**: _styles、_resources、_applicationLifetimeフィールドがアプリケーション状態の核心。

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

アプリケーション初期化の流れを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | コンストラクタ | `src/Avalonia.Controls/Application.cs` | 70-73行目。Name初期化 |
| 2-2 | Initialize | `src/Avalonia.Controls/Application.cs` | 220行目。XAML初期化用仮想メソッド |
| 2-3 | RegisterServices | `src/Avalonia.Controls/Application.cs` | 248-278行目。サービス登録 |

**主要処理フロー**:
1. **250行目**: SynchronizationContextのインストール
2. **251行目**: InputManager作成
3. **253-257行目**: PlatformSettingsのイベント購読
4. **259-275行目**: 各種サービスのAvaloniaLocator登録

#### Step 3: テーマ管理を理解する

テーマバリアントの管理方法。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | RequestedThemeVariant | `src/Avalonia.Controls/Application.cs` | 88-93行目 |
| 3-2 | ActualThemeVariant | `src/Avalonia.Controls/Application.cs` | 96-98行目 |
| 3-3 | OnPropertyChanged | `src/Avalonia.Controls/Application.cs` | 327-342行目。テーマ変更処理 |
| 3-4 | OnColorValuesChanged | `src/Avalonia.Controls/Application.cs` | 344-347行目。OSテーマ変更対応 |

**主要処理フロー**:
- **331-336行目**: RequestedThemeVariant変更時のActualThemeVariant更新
- **338-341行目**: ActualThemeVariant変更時のイベント発火

#### Step 4: リソース管理を理解する

グローバルリソースの検索と管理。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | TryGetResource | `src/Avalonia.Controls/Application.cs` | 223-228行目。リソース検索 |
| 4-2 | Resources プロパティ | `src/Avalonia.Controls/Application.cs` | 134-144行目 |

**主要処理フロー**:
- **226-227行目**: リソースとスタイルの両方から検索

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

```
AppBuilder.Configure<App>()
    │
    └─ AppBuilder.Setup (またはStart)
           │
           ├─ RuntimePlatformServicesInitializer
           ├─ RenderingSubsystemInitializer
           ├─ WindowingSubsystemInitializer
           │
           ├─ Application._appFactory()
           │      └─ new App()
           │
           ├─ AvaloniaLocator.Bind(Application)
           │
           ├─ Application.RegisterServices()
           │      ├─ AvaloniaSynchronizationContext.InstallIfNeeded
           │      ├─ new InputManager()
           │      ├─ PlatformSettings.ColorValuesChanged購読
           │      └─ AvaloniaLocator各種登録
           │
           ├─ Application.Initialize()
           │      └─ (XAML読み込み - 派生クラス実装)
           │
           └─ Application.OnFrameworkInitializationCompleted()
```

### データフロー図

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

App.axaml ────────────▶ Initialize ─────────────────────▶ Styles/Resources設定
                              │
RequestedThemeVariant ───────▶ │
                              │
PlatformSettings ────────────▶ ActualThemeVariant決定
                              │
                              ▼
                    RegisterServices
                              │
                    ┌─────────┼─────────┐
                    ▼         ▼         ▼
               InputManager  ToolTip  GlobalStyles
                    │
                    ▼
              AvaloniaLocator登録
                    │
                    ▼
              [アプリケーション実行可能]
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Application.cs | `src/Avalonia.Controls/Application.cs` | ソース | Applicationクラスの実装 |
| AppBuilder.cs | `src/Avalonia.Controls/AppBuilder.cs` | ソース | アプリケーションビルダー |
| IApplicationLifetime.cs | `src/Avalonia.Controls/ApplicationLifetimes/IApplicationLifetime.cs` | ソース | ライフタイムインターフェース |
| ThemeVariant.cs | `src/Avalonia.Base/Styling/ThemeVariant.cs` | ソース | テーマバリアント |
| AvaloniaLocator.cs | `src/Avalonia.Base/AvaloniaLocator.cs` | ソース | サービスロケーター |
