# 機能設計書 64-ControlTheme

## 概要

本ドキュメントは、Avaloniaフレームワークにおける**ControlTheme**機能の設計仕様を記述する。ControlThemeは、コントロールの外観を定義するためのテンプレート集合を提供し、テーマ切り替えを実現する。

### 本機能の処理概要

ControlThemeは、特定のコントロール型に対するスタイル設定、セッター、アニメーション、および子スタイルを集約したテーマ定義である。StyleBaseを継承し、TargetTypeプロパティで適用対象の型を指定する。テーマの継承（BasedOn）もサポートしている。

**業務上の目的・背景**：UIフレームワークにおいて、コントロールの外観を一元的に管理し、アプリケーション全体で一貫したデザインを実現することは重要である。ControlThemeは、各コントロール型に対するデフォルトテーマを定義し、テーマ切り替えやカスタマイズを容易にする。これにより、FluentThemeやSimpleThemeなどの完全なテーマパッケージを構築できる。

**機能の利用シーン**：
- コントロールのデフォルト外観定義
- アプリケーションテーマの構築（Fluent、Simple等）
- カスタムコントロールのテーマ作成
- 既存テーマの拡張（BasedOnによる継承）

**主要な処理内容**：
1. TargetTypeによるコントロール型の指定
2. Setter、Animation、子Styleの管理
3. BasedOnによるテーマ継承
4. コントロールへのテーマ適用（TryAttach）

**関連システム・外部連携**：ControlThemeはAvalonia.Base.Stylingモジュール内で実装され、Style、ThemeVariant、FluentTheme、SimpleThemeと連携する。

**権限による制御**：特にアクセス権限による制御は行われない。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 57 | Theme Variants | 補助機能 | コントロールテーマの適用と切り替え |

## 機能種別

テーマ管理 / スタイリング / コントロール外観定義

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| TargetType | Type | Yes | テーマが適用されるコントロール型 | TryAttach時にnullは不可 |
| BasedOn | ControlTheme | No | 継承元のControlTheme | - |
| Setters | IList<SetterBase> | No | プロパティ設定のリスト | - |
| Animations | IList<IAnimation> | No | アニメーションのリスト | - |
| Children | IList<IStyle> | No | 子スタイルのリスト | - |
| Resources | IResourceDictionary | No | テーマ固有のリソース | - |

### 入力データソース

- XAML定義またはコードでのテーマ構築
- テーマパッケージ（FluentTheme、SimpleTheme等）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| StyleInstance | ValueFrame | 適用されたテーマのインスタンス |
| SelectorMatchResult | enum | マッチ結果（AlwaysThisType, NeverThisType） |

### 出力先

- ターゲットコントロールのValueStore

## 処理フロー

### 処理シーケンス

```
1. ControlThemeの定義
   └─ TargetType, BasedOn, Setters, Animations, Childrenの設定
2. コントロールへのアタッチ試行（TryAttach）
   └─ TargetTypeとコントロールのStyleKeyを比較
3. マッチ成功時のテーマ適用（Attach）
   └─ StyleInstanceの生成とValueStoreへの登録
4. 子スタイルの適用
   └─ 各子Styleの評価と適用
5. BasedOnチェーン処理（存在する場合）
   └─ 継承元テーマの適用
```

### フローチャート

```mermaid
flowchart TD
    A[ControlTheme定義] --> B{TargetType設定?}
    B -->|No| C[InvalidOperationException]
    B -->|Yes| D[TryAttach呼び出し]
    D --> E{Setters/Animationsあり?}
    E -->|No| F[NeverThisType返却]
    E -->|Yes| G{TargetType.IsAssignableFrom StyleKey?}
    G -->|No| F
    G -->|Yes| H[Attach呼び出し]
    H --> I[StyleInstance生成]
    I --> J[Setterインスタンス化]
    J --> K[ValueStoreに登録]
    K --> L[Animation適用]
    L --> M{BasedOnあり?}
    M -->|Yes| N[BasedOn.TryAttach]
    M -->|No| O[子Styleの適用]
    N --> O
    O --> P[AlwaysThisType返却]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-64-01 | ネスト禁止 | ControlThemeは他のスタイルにネストできない | SetParent呼び出し時 |
| BR-64-02 | TargetType必須 | TryAttach時にTargetTypeがnullの場合はエラー | TryAttach時 |
| BR-64-03 | StyleKeyによるマッチング | TargetTypeがコントロールのStyleKeyに割り当て可能かで判定 | TryAttach時 |
| BR-64-04 | FrameType制限 | ThemeまたはTemplatedParentThemeフレームタイプのみ使用可能 | TryAttach時 |

### 計算ロジック

- 型マッチング: `TargetType.IsAssignableFrom(target.StyleKey)`

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

本機能はデータベースを使用しない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | InvalidOperationException | ControlThemeをネストしようとした場合 | ControlThemeはルートレベルで定義する |
| - | InvalidOperationException | TargetTypeがnullの場合 | TargetTypeを設定する |

### リトライ仕様

リトライ処理は行わない。

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

本機能はトランザクションを使用しない。

## パフォーマンス要件

- 型チェックは効率的に実行される
- 共有可能なスタイルインスタンスはキャッシュされる

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

特段のセキュリティ要件はない。

## 備考

- ControlThemeは`<ControlTheme>`タグでXAMLに定義
- StyleKeyは通常コントロールの型だが、カスタマイズ可能

---

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

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

### 推奨読解順序

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

ControlThemeクラスの構造と継承関係を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | ControlTheme.cs | `src/Avalonia.Base/Styling/ControlTheme.cs` | TargetType, BasedOnプロパティ、TryAttachメソッドを確認 |
| 1-2 | StyleBase.cs | `src/Avalonia.Base/Styling/StyleBase.cs` | 基底クラス。共通プロパティとAttachメソッドを確認 |

**読解のコツ**: ControlThemeはStyleBaseを継承しているが、Selectorを持たず、TargetTypeで適用対象を決定する点がStyleとの主な違い。

**主要処理フロー (ControlTheme.cs)**:
1. **16行目**: デフォルトコンストラクタ
2. **22行目**: TargetType指定コンストラクタ
3. **27行目**: TargetType プロパティ - 適用対象の型
4. **32行目**: BasedOn プロパティ - 継承元テーマ
5. **34行目**: ToString - テーマの文字列表現
6. **36-39行目**: SetParent - ネスト禁止のバリデーション
7. **41-63行目**: TryAttach - テーマの適用試行

#### Step 2: テーマ適用処理を理解する

TryAttachメソッドの詳細処理を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | ControlTheme.cs | `src/Avalonia.Base/Styling/ControlTheme.cs` | TryAttachメソッドの処理フロー |

**主要処理フロー (TryAttach)**:
1. **43行目**: Debug.Assert - フレームタイプの検証
2. **45行目**: null チェック
3. **47-48行目**: TargetType null チェックと例外
4. **53行目**: `TargetType.IsAssignableFrom(target.StyleKey)` - 型マッチング
5. **55行目**: Attach呼び出し（activator=null, canShareInstance=true）
6. **58行目**: AlwaysThisType返却

#### Step 3: 基底クラスの処理を理解する

StyleBaseのAttachメソッドを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | StyleBase.cs | `src/Avalonia.Base/Styling/StyleBase.cs` | Attach メソッド |

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

```
StyledElement.ApplyControlTheme()
    │
    └─ ControlTheme.TryAttach(target, type)
           │
           ├─ TargetType.IsAssignableFrom(target.StyleKey)
           │
           └─ StyleBase.Attach(target, null, type, true)
                  │
                  ├─ new StyleInstance()
                  │
                  ├─ setter.Instance() [各Setter]
                  │
                  ├─ ValueStore.AddFrame()
                  │
                  └─ instance.ApplyAnimations()
```

### データフロー図

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

ControlTheme定義 ──────────▶ ControlTheme.TryAttach() ─────────▶ StyleInstance
    │                              │                                  │
    │ TargetType                   │ IsAssignableFrom判定             │ ValueFrame
    │ Setters                      │ Attach()                         │
    │ Animations                   │ setter.Instance()                │
    │ BasedOn                      │                                  │
    └──────────────────────────────┘                                  │
                                                                      ▼
                                                              ValueStore.AddFrame()
                                                                      │
                                                                      ▼
                                                              プロパティ値適用
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| ControlTheme.cs | `src/Avalonia.Base/Styling/ControlTheme.cs` | ソース | コントロールテーマ定義クラス |
| StyleBase.cs | `src/Avalonia.Base/Styling/StyleBase.cs` | ソース | スタイル基底クラス |
| Style.cs | `src/Avalonia.Base/Styling/Style.cs` | ソース | スタイル定義クラス |
| StyledElement.cs | `src/Avalonia.Base/StyledElement.cs` | ソース | StyleKeyプロパティ定義 |
| IStyle.cs | `src/Avalonia.Base/Styling/IStyle.cs` | ソース | スタイルインターフェース |
| FluentTheme.xaml.cs | `src/Avalonia.Themes.Fluent/FluentTheme.xaml.cs` | ソース | Fluentテーマ実装例 |
| SimpleTheme.xaml.cs | `src/Avalonia.Themes.Simple/SimpleTheme.xaml.cs` | ソース | Simpleテーマ実装例 |
