# 機能設計書 3-StyledElement

## 概要

本ドキュメントは、Avaloniaフレームワークにおけるスタイリングとロジカルツリーの基盤クラスである`StyledElement`の機能設計を記述する。`Animatable`を継承し、DataContext継承、ロジカルツリー構築、スタイル適用、リソース管理などの機能を提供する。

### 本機能の処理概要

`StyledElement`は、UIコントロールにおいて以下の機能を提供する中核クラスである：
- **DataContext継承**：親要素からデータコンテキストを継承し、データバインディングの基盤を提供
- **ロジカルツリー**：`ILogical`インターフェースを実装し、論理的な親子関係を構築
- **スタイリング**：CSS風のスタイリングシステムとの連携
- **リソース管理**：リソースディクショナリの管理とリソース検索
- **初期化制御**：`ISupportInitialize`による初期化フェーズの制御

**業務上の目的・背景**：MVVMパターンにおいて、ViewとViewModelを疎結合にするためにはDataContextの継承機構が不可欠である。また、スタイルシステムにより、一貫したUIの外観を宣言的に定義できる。

**機能の利用シーン**：
- XAMLでのデータバインディング設定時（DataContext継承）
- スタイルリソースの定義と適用
- テーマ切り替え
- コントロールの初期化タイミング制御

**主要な処理内容**：
1. `DataContext`プロパティによるデータ継承
2. `Classes`コレクションによるCSSクラス管理
3. `LogicalChildren`コレクションによる子要素管理
4. `Styles`/`Resources`コレクションによるリソース管理
5. `ApplyStyling`によるスタイル適用処理
6. `BeginInit`/`EndInit`による初期化制御
7. `AttachedToLogicalTree`/`DetachedFromLogicalTree`イベント

**関連システム・外部連携**：
- `AvaloniaObject`：依存関係プロパティシステム
- `Animatable`：アニメーション基盤
- `ILogical`/`ILogicalRoot`：ロジカルツリー
- `IStyleHost`/`IResourceHost`：スタイルとリソース管理
- `ValueStore`：スタイル適用の値管理

**権限による制御**：特になし（フレームワーク基盤クラス）

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | 本機能は全画面の基盤となるクラスであり、特定の画面に紐づかない |

## 機能種別

フレームワーク基盤 / スタイリングシステム / ロジカルツリー管理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| DataContext | object? | No | データバインディングのデフォルトソース | - |
| Name | string? | No | 要素の識別名 | スタイル適用後は変更不可 |
| Classes | Classes | No | CSSクラスのコレクション | - |
| Theme | ControlTheme? | No | 適用するコントロールテーマ | - |
| Parent | ILogical | No | 論理的な親要素（内部設定） | 二重設定不可 |

### 入力データソース

- XAMLパーサーからのプロパティ設定
- コードからの直接設定
- 親要素からの継承（DataContext）
- スタイルシステムからの値適用

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| AttachedToLogicalTree | event | ロジカルツリーにアタッチされた時のイベント |
| DetachedFromLogicalTree | event | ロジカルツリーからデタッチされた時のイベント |
| DataContextChanged | event | DataContext変更時のイベント |
| Initialized | event | 初期化完了時のイベント |
| ResourcesChanged | event | リソース変更時のイベント |

### 出力先

- イベントリスナー（上記イベント）
- 子要素への継承プロパティ伝播
- スタイルシステムへの登録

## 処理フロー

### 処理シーケンス

```
1. コンストラクタ
   └─ 自身がILogicalRootならlogicalRootを設定

2. SetParent(親要素の設定)
   └─ 二重設定チェック
   └─ InheritanceParentの設定
   └─ 以前のルートからデタッチ
   └─ 新しいルートにアタッチ

3. OnAttachedToLogicalTreeCore
   └─ _logicalRootの設定
   └─ ReevaluateImplicitTheme（暗黙テーマの再評価）
   └─ ApplyStyling（スタイル適用）
   └─ NotifyResourcesChanged
   └─ 子要素への伝播

4. ApplyStyling
   └─ BeginStyling（ValueStore）
   └─ ApplyControlTheme（コントロールテーマ適用）
   └─ ApplyTemplatedParentControlTheme
   └─ ApplyStyles（スタイル適用）
   └─ EndStyling
```

### フローチャート

```mermaid
flowchart TD
    A[StyledElement作成] --> B[BeginInit/EndInit]
    B --> C{ロジカルツリーに追加?}
    C -->|Yes| D[SetParent呼び出し]
    D --> E[OnAttachedToLogicalTreeCore]
    E --> F[ReevaluateImplicitTheme]
    F --> G[ApplyStyling]
    G --> H[InitializeIfNeeded]
    H --> I[Initializedイベント]
    C -->|No| J[待機]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | Name変更制約 | スタイル適用後はNameプロパティを変更できない | _stylesApplied == true |
| BR-02 | 二重親設定禁止 | 既に親を持つ要素に別の親を設定できない | SetParent時 |
| BR-03 | DataContext継承 | DataContextは親から子へ継承される | inherits: true |
| BR-04 | 初期化順序 | EndInitはBeginInitの後でなければならない | ISupportInitialize |
| BR-05 | LogicalChildren null禁止 | LogicalChildrenにnullを追加できない | Validator |

### 計算ロジック

**効果的なテーマ取得（GetEffectiveTheme）**：
1. Theme プロパティが設定されていればそれを返す
2. 暗黙テーマがキャッシュされていればそれを返す
3. StyleKeyをキーにリソースからControlThemeを検索
4. 見つかればキャッシュして返す、なければs_invalidThemeをキャッシュ

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

該当なし（メモリ内データ構造のみ）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | InvalidOperationException | スタイル適用後のName変更 | 初期化前にNameを設定 |
| - | InvalidOperationException | 二重親設定 | 先に親をnullに設定 |
| - | InvalidOperationException | BeginInit未呼び出しのEndInit | BeginInitを先に呼び出す |
| - | ArgumentException | LogicalChildrenにnull追加 | nullチェックを追加 |
| - | ArgumentNullException | Resourcesにnull設定 | 有効なリソース辞書を設定 |

### リトライ仕様

該当なし

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

該当なし（メモリ内操作のみ）

## パフォーマンス要件

- 暗黙テーマはキャッシュされ、再計算を避ける
- スタイル適用はValueStoreのバッチ処理で最適化
- リソース変更通知は重複を避けるための_lastResourcesChangedEventArgsチェック

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

- 特別なセキュリティ考慮事項なし（フレームワーク内部クラス）

## 備考

- WPFの`FrameworkElement`に相当する機能の一部を担当
- `Visual`クラスと共に、コントロール基盤の二本柱を形成

---

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

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

### 推奨読解順序

#### Step 1: クラス定義と主要プロパティを理解する

クラスの位置づけと主要なプロパティを把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | StyledElement.cs | `src/Avalonia.Base/StyledElement.cs` | 20-38行目：クラス定義と実装インターフェース |
| 1-2 | StyledElement.cs | `src/Avalonia.Base/StyledElement.cs` | 39-78行目：プロパティ定義（DataContext, Name, Theme等） |

**読解のコツ**:
- `DataContextProperty`は`inherits: true`で定義されており、親から子に継承されることを確認
- 実装している多数のインターフェース（ILogical, IStyleHost, IResourceHost等）が役割を表している

#### Step 2: ロジカルツリー管理を理解する

親子関係の設定とイベント通知を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | StyledElement.cs | `src/Avalonia.Base/StyledElement.cs` | 444-490行目：SetParent実装 |
| 2-2 | StyledElement.cs | `src/Avalonia.Base/StyledElement.cs` | 845-881行目：OnAttachedToLogicalTreeCore |
| 2-3 | StyledElement.cs | `src/Avalonia.Base/StyledElement.cs` | 883-913行目：OnDetachedFromLogicalTreeCore |

**主要処理フロー**:
- **444-490行目**: 親設定時に継承親の設定、ツリーのアタッチ/デタッチ処理
- **845-881行目**: ロジカルツリーアタッチ時にスタイル適用、リソース通知、子要素への伝播
- **883-913行目**: デタッチ時のスタイル無効化と子要素への伝播

#### Step 3: スタイリングシステムを理解する

スタイル適用の流れを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | StyledElement.cs | `src/Avalonia.Base/StyledElement.cs` | 367-400行目：ApplyStyling |
| 3-2 | StyledElement.cs | `src/Avalonia.Base/StyledElement.cs` | 759-790行目：ApplyControlTheme |
| 3-3 | StyledElement.cs | `src/Avalonia.Base/StyledElement.cs` | 792-806行目：ApplyStyles |

**主要処理フロー**:
- **367-400行目**: スタイル適用のメインメソッド。テーマ、親テーマ、スタイルの順に適用
- **759-790行目**: コントロールテーマの適用（BasedOnチェーン対応）
- **792-806行目**: スタイルホストの階層を辿ってスタイルを適用

#### Step 4: 初期化制御を理解する

ISupportInitializeの実装を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | StyledElement.cs | `src/Avalonia.Base/StyledElement.cs` | 336-354行目：BeginInit/EndInit |
| 4-2 | StyledElement.cs | `src/Avalonia.Base/StyledElement.cs` | 402-410行目：InitializeIfNeeded |

**主要処理フロー**:
- **336-354行目**: 初期化カウンタによる入れ子対応。EndInitでスタイル適用と初期化完了
- **402-410行目**: 初期化完了時にOnInitializedとInitializedイベント発火

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

```
StyledElement
    │
    ├─ Animatable（アニメーション基盤）
    │      └─ AvaloniaObject（プロパティシステム）
    │
    ├─ ILogical（ロジカルツリー）
    │      ├─ LogicalChildren
    │      └─ LogicalParent
    │
    ├─ IStyleHost（スタイルホスト）
    │      ├─ Styles コレクション
    │      └─ StylingParent
    │
    ├─ IResourceHost（リソースホスト）
    │      └─ Resources ディクショナリ
    │
    └─ IDataContextProvider
           └─ DataContext
```

### データフロー図

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

SetParent(newParent)
        │
        ▼
   二重親チェック ────▶ InvalidOperationException
        │
        ▼
   InheritanceParent設定 ─▶ 継承プロパティの再評価
        │
        ▼
   FindLogicalRoot ───────▶ ルート検索
        │
        ▼
   OnAttachedToLogicalTreeCore
        │
        ├──▶ ReevaluateImplicitTheme ─▶ テーマ変更検出
        │
        ├──▶ ApplyStyling ────────────▶ スタイル適用
        │
        ├──▶ NotifyResourcesChanged ──▶ リソース変更通知
        │
        └──▶ 子要素への伝播 ──────────▶ 子要素のAttached
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| StyledElement.cs | `src/Avalonia.Base/StyledElement.cs` | ソース | スタイリング基盤クラス |
| Animatable.cs | `src/Avalonia.Base/Animatable.cs` | ソース | アニメーション対応基底 |
| AvaloniaObject.cs | `src/Avalonia.Base/AvaloniaObject.cs` | ソース | プロパティシステム基底 |
| Classes.cs | `src/Avalonia.Base/Styling/Classes.cs` | ソース | CSSクラスコレクション |
| ControlTheme.cs | `src/Avalonia.Base/Styling/ControlTheme.cs` | ソース | コントロールテーマ定義 |
| Style.cs | `src/Avalonia.Base/Styling/Style.cs` | ソース | スタイル定義 |
| ILogical.cs | `src/Avalonia.Base/LogicalTree/ILogical.cs` | ソース | ロジカルツリーインターフェース |
| IStyleHost.cs | `src/Avalonia.Base/Styling/IStyleHost.cs` | ソース | スタイルホストインターフェース |
| ResourceDictionary.cs | `src/Avalonia.Base/Styling/ResourceDictionary.cs` | ソース | リソース辞書 |
