# 機能設計書 100-iOSPlatform

## 概要

本ドキュメントは、Avaloniaフレームワークにおける iOSプラットフォーム（iOSPlatform）機能の設計仕様を記述します。iOSPlatformは、iOS/tvOS/macCatalyst上でAvaloniaアプリケーションを実行するための基盤を提供し、UIKitとの統合を実現します。

### 本機能の処理概要

iOSプラットフォームは、AvaloniaをiOSアプリケーションとして動作させるためのプラットフォーム抽象化レイヤーを提供します。AvaloniaViewをUIViewとして実装し、タッチ入力、ソフトキーボード、Metal/OpenGL ESレンダリングなどのiOS固有機能との統合を行います。

**業務上の目的・背景**：iOSはモバイルアプリケーション市場において重要なプラットフォームです。AvaloniaをiOSで動作させることで、デスクトップ、Android、iOSでコードベースを共有し、真のクロスプラットフォーム開発を実現できます。iOSPlatformは、AvaloniaのUIシステムをUIKitのライフサイクルとViewシステムに適合させ、ネイティブiOSアプリと同等のユーザー体験を提供します。

**機能の利用シーン**：
- iPhone/iPad向けアプリケーション
- Apple TV向けアプリケーション（tvOS）
- macCatalyst対応アプリケーション
- デスクトップとモバイルのクロスプラットフォーム開発

**主要な処理内容**：
1. iOSプラットフォームの初期化とサービス登録
2. AvaloniaViewによるUI表示
3. タッチジェスチャー入力の処理
4. ソフトキーボード（IME）統合
5. Metal/EaGLによるレンダリング
6. Safe Area Insets対応

**関連システム・外部連携**：
- UIKit / AppKit（macCatalyst）
- Metal
- EaGL（OpenGL ES、非macCatalyst）
- iOS Storage API

**権限による制御**：カメラ、写真ライブラリ、位置情報等はInfo.plistでの権限宣言とランタイム権限要求が必要です。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | シングルビュー | 主機能 | iOSシングルビューアプリケーション |

## 機能種別

プラットフォーム基盤 / モバイル / iOS統合

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| iOSPlatformOptions | iOSPlatformOptions | No | プラットフォームオプション | - |
| RenderingMode | iOSRenderingMode[] | No | レンダリングモード | OpenGl/Metal |
| IAvaloniaAppDelegate | IAvaloniaAppDelegate | No | AppDelegate | - |

### 入力データソース

- iOS UIApplication
- UIViewController

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| AvaloniaView | UIView | UIViewとしてのAvalonia UI |

### 出力先

- AvaloniaLocator経由でのサービス登録
- iOS View階層

## 処理フロー

### 処理シーケンス

```
1. UseiOS()拡張メソッド呼び出し
   └─ AppBuilderの設定
2. Platform.Register()
   └─ オプション取得とサービス登録
3. グラフィックス初期化
   └─ Metal/EaGL（OpenGL ES）の選択
4. Compositor作成
   └─ new Compositor(graphics)
5. UIApplicationMain起動
   └─ AppDelegateの初期化
6. ViewController/AvaloniaView配置
   └─ UIへのView追加
```

### フローチャート

```mermaid
flowchart TD
    A[UseiOS呼び出し] --> B[UseStandardRuntimePlatformSubsystem]
    B --> C[UseWindowingSubsystem]
    C --> D[Platform.Register]
    D --> E[サービス登録]
    E --> F{RenderingMode走査}
    F -->|Metal| G[MetalPlatformGraphics.TryCreate]
    F -->|OpenGl| H{macCatalyst?}
    H -->|No| I[EaglPlatformGraphics.TryCreate]
    H -->|Yes| J[スキップ]
    G --> K[Compositor作成]
    I --> K
    J --> G
    K --> L[初期化完了]
    L --> M[AppDelegate起動]
    M --> N[ViewController/AvaloniaView作成]
    N --> O[UI表示開始]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-100-01 | レンダリング優先順位 | Metal → OpenGl（非macCatalyst）の順でフォールバック | 初期化時 |
| BR-100-02 | macCatalyst制限 | macCatalystではEaGL（OpenGL ES）は非対応 | macCatalyst環境時 |
| BR-100-03 | DisplayLink同期 | DisplayLinkTimerでフレーム同期 | レンダリング時 |
| BR-100-04 | Safe Area対応 | InsetsManagerでSafe Area Insets処理 | 画面表示時 |
| BR-100-05 | キージェスチャ記号 | macOS記号（⌘⇧⌃⌥）を使用 | キー表示時 |

### 計算ロジック

画面スケールはUIScreen.MainScreen.Scaleから取得し、Avaloniaのスケーリングに適用されます。

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

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

本機能はデータベース操作を伴いません（SQLiteはiOSのAPI経由で別途使用可能）。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| InvalidOp-01 | InvalidOperationException | RenderingMode空配列 | 少なくとも1つのモード指定 |
| InvalidOp-02 | InvalidOperationException | 全RenderingModeが失敗 | 別のレンダリングモードを試行 |

### リトライ仕様

レンダリングモードは優先度順にフォールバックします。

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

本機能はUI基盤のため、トランザクション管理は不要です。

## パフォーマンス要件

- DisplayLinkTimerによるVSync同期
- Metalを優先してGPUアクセラレーション

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

- iOSパーミッションモデル（Info.plist）への準拠
- App Sandbox環境での動作

## 備考

iOSPlatformはPlatform静的クラスとして実装され、Register()メソッドで初期化されます。

---

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

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

### 推奨読解順序

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

まず、iOSプラットフォームオプションと基本構造を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Platform.cs | `src/iOS/Avalonia.iOS/Platform.cs` | オプションとプラットフォームクラス |

**読解のコツ**: iOSRenderingMode列挙型とiOSPlatformOptionsの各プロパティを確認してください。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Platform.cs | `src/iOS/Avalonia.iOS/Platform.cs` | Register()実装 |

**主要処理フロー**:
1. **48-60行目**: UseiOS拡張メソッド
2. **72-107行目**: Register() - プラットフォーム初期化
3. **80-97行目**: サービス登録
4. **105-106行目**: Compositor作成
5. **109-137行目**: InitializeGraphics - レンダリングモード選択

#### Step 3: ビュー実装を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | AvaloniaView.cs | `src/iOS/Avalonia.iOS/AvaloniaView.cs` | メインビュー実装 |
| 3-2 | AvaloniaView.Text.cs | `src/iOS/Avalonia.iOS/AvaloniaView.Text.cs` | テキスト入力 |
| 3-3 | InputHandler.cs | `src/iOS/Avalonia.iOS/InputHandler.cs` | 入力処理 |

#### Step 4: AppDelegate統合を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | AvaloniaAppDelegate.cs | `src/iOS/Avalonia.iOS/AvaloniaAppDelegate.cs` | AppDelegate |
| 4-2 | ViewController.cs | `src/iOS/Avalonia.iOS/ViewController.cs` | ViewController |
| 4-3 | SingleViewLifetime.cs | `src/iOS/Avalonia.iOS/SingleViewLifetime.cs` | ライフサイクル |

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

```
IOSApplicationExtensions
    │
    └─ UseiOS()
           ├─ UseStandardRuntimePlatformSubsystem()
           ├─ UseWindowingSubsystem()
           │      └─ Platform.Register()
           │             ├─ サービス登録
           │             ├─ InitializeGraphics()
           │             └─ Compositor作成
           │
           ├─ UseHarfBuzz()
           └─ UseSkia()

AvaloniaAppDelegate
    │
    ├─ FinishedLaunching()
    │      └─ ViewController作成
    │
    └─ ViewController
           └─ AvaloniaView配置
```

### データフロー図

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

iOSPlatformOptions ────▶ Platform.Register() ────────▶ サービス登録
         │                      │
         │                      ├─ InitializeGraphics()
         │                      │      ├─ MetalPlatformGraphics
         │                      │      └─ EaglPlatformGraphics
         │                      │
         │                      └─ Compositor

AppDelegate起動 ───────▶ ViewController ──────────────▶ UI表示
         │                      │
         │                      └─ AvaloniaView
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Platform.cs | `src/iOS/Avalonia.iOS/Platform.cs` | ソース | メインプラットフォーム |
| AvaloniaView.cs | `src/iOS/Avalonia.iOS/AvaloniaView.cs` | ソース | メインビュー |
| AvaloniaView.Text.cs | `src/iOS/Avalonia.iOS/AvaloniaView.Text.cs` | ソース | テキスト入力 |
| InputHandler.cs | `src/iOS/Avalonia.iOS/InputHandler.cs` | ソース | 入力処理 |
| AvaloniaAppDelegate.cs | `src/iOS/Avalonia.iOS/AvaloniaAppDelegate.cs` | ソース | AppDelegate |
| AvaloniaSceneDelegate.cs | `src/iOS/Avalonia.iOS/AvaloniaSceneDelegate.cs` | ソース | SceneDelegate |
| ViewController.cs | `src/iOS/Avalonia.iOS/ViewController.cs` | ソース | ViewController |
| SingleViewLifetime.cs | `src/iOS/Avalonia.iOS/SingleViewLifetime.cs` | ソース | ライフサイクル |
| ActivatableLifetime.cs | `src/iOS/Avalonia.iOS/ActivatableLifetime.cs` | ソース | アクティベーション |
| DispatcherImpl.cs | `src/iOS/Avalonia.iOS/DispatcherImpl.cs` | ソース | ディスパッチャ |
| DisplayLinkTimer.cs | `src/iOS/Avalonia.iOS/DisplayLinkTimer.cs` | ソース | フレーム同期 |
| iOSScreens.cs | `src/iOS/Avalonia.iOS/iOSScreens.cs` | ソース | 画面情報 |
| InsetsManager.cs | `src/iOS/Avalonia.iOS/InsetsManager.cs` | ソース | Safe Area |
| PlatformSettings.cs | `src/iOS/Avalonia.iOS/PlatformSettings.cs` | ソース | 設定 |
| TextInputResponder.cs | `src/iOS/Avalonia.iOS/TextInputResponder.cs` | ソース | テキスト入力 |
| ClipboardImpl.cs | `src/iOS/Avalonia.iOS/Clipboard/ClipboardImpl.cs` | ソース | クリップボード |
| IOSStorageProvider.cs | `src/iOS/Avalonia.iOS/Storage/IOSStorageProvider.cs` | ソース | ストレージ |
| MetalPlatformGraphics.cs | `src/iOS/Avalonia.iOS/Metal/MetalPlatformGraphics.cs` | ソース | Metal |
| EaglDisplay.cs | `src/iOS/Avalonia.iOS/Eagl/EaglDisplay.cs` | ソース | OpenGL ES |
