# 機能設計書 114-Shapes

## 概要

本ドキュメントは、Avaloniaフレームワークの図形コントロール機能について、その設計と実装を詳細に記述する機能設計書である。Rectangle、Ellipse、Line、Path、Polygon、Polyline、Arc、Sectorなどの基本的な図形描画コントロールを提供する。

### 本機能の処理概要

Shapesは、Avaloniaアプリケーションにおいて、ベクターグラフィックスを描画するためのコントロール群である。各図形は塗りつぶし（Fill）と輪郭線（Stroke）のスタイリングをサポートし、ストレッチ機能により柔軟なレイアウトが可能である。

**業務上の目的・背景**：UI設計において、装飾的な要素やカスタムグラフィックスを描画する必要がある。従来のラスター画像では解像度に依存するが、ベクター図形を使用することで、あらゆる解像度で鮮明な描画が可能となる。また、アニメーションやインタラクティブな図形変更も実現できる。

**機能の利用シーン**：アイコン、ボタンの装飾、データビジュアライゼーション（グラフ、チャート）、カスタムプログレスバー、装飾的なUI要素、図形ベースのカスタムコントロールの作成などで使用される。

**主要な処理内容**：
1. 図形のジオメトリ（Geometry）生成
2. 塗りつぶし（Fill）と輪郭線（Stroke）の描画
3. ストレッチモードに基づくサイズ計算
4. レンダリング変換の適用
5. ジオメトリ変更時の再描画

**関連システム・外部連携**：Avalonia.Media（Brush、Pen、Geometry）、レンダリングシステム

**権限による制御**：特になし

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | 図形コントロールは汎用UIコントロール |

## 機能種別

UIコントロール / 描画 / ベクターグラフィックス

## 入力仕様

### 入力パラメータ

#### Shape（基底クラス）共通プロパティ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| Fill | IBrush | No | 塗りつぶしブラシ | - |
| Stroke | IBrush | No | 輪郭線ブラシ | - |
| StrokeThickness | double | No | 輪郭線の太さ | 0以上 |
| StrokeDashArray | AvaloniaList<double> | No | 破線パターン | - |
| StrokeDashOffset | double | No | 破線オフセット | - |
| StrokeLineCap | PenLineCap | No | 線端の形状（Flat/Round/Square） | 列挙値 |
| StrokeJoin | PenLineJoin | No | 線の結合形状（Miter/Bevel/Round） | 列挙値 |
| StrokeMiterLimit | double | No | マイター制限 | 0以上 |
| Stretch | Stretch | No | ストレッチモード（None/Fill/Uniform/UniformToFill） | 列挙値 |

#### Rectangle固有プロパティ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| RadiusX | double | No | X方向の角丸半径 | 0以上 |
| RadiusY | double | No | Y方向の角丸半径 | 0以上 |

#### Line固有プロパティ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| StartPoint | Point | No | 開始点 | - |
| EndPoint | Point | No | 終了点 | - |

#### Path固有プロパティ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| Data | Geometry | No | パスデータ | - |

### 入力データソース

- XAMLまたはコードからのプロパティ設定
- データバインディング

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| DefiningGeometry | Geometry | 図形の定義ジオメトリ |
| RenderedGeometry | Geometry | レンダリング用の変換済みジオメトリ |

### 出力先

- ビジュアルツリー上の描画
- DrawingContext経由でのレンダリング

## 処理フロー

### 処理シーケンス

```
1. 図形プロパティの設定
   └─ Fill、Stroke等のプロパティを設定
2. ジオメトリの生成
   └─ CreateDefiningGeometry()でジオメトリ作成
3. レイアウト計算
   └─ MeasureOverride()でサイズ計算
   └─ ArrangeOverride()で配置計算
4. 変換行列の計算
   └─ CalculateSizeAndTransform()でストレッチ適用
5. レンダリング
   └─ Render()でDrawingContext.DrawGeometry()呼び出し
```

### フローチャート

```mermaid
flowchart TD
    A[プロパティ設定] --> B[InvalidateGeometry]
    B --> C[_definingGeometry = null]
    C --> D[InvalidateMeasure]
    D --> E[MeasureOverride]
    E --> F[DefiningGeometry取得]
    F --> G[CreateDefiningGeometry]
    G --> H[ArrangeOverride]
    H --> I[CalculateSizeAndTransform]
    I --> J[_transform更新]
    J --> K[Render]
    K --> L[RenderedGeometry取得]
    L --> M[DrawGeometry]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | ジオメトリキャッシュ | DefiningGeometryはnull化されるまでキャッシュされる | 常時 |
| BR-002 | 変換適用 | RenderedGeometryは_transformを適用した複製 | _transform != Identity時 |
| BR-003 | ストローク考慮 | RectangleとEllipseはStrokeThickness/2だけ内側にジオメトリを生成 | 常時 |
| BR-004 | Lineのデフォルト | LineのStrokeThicknessはデフォルト1 | デフォルト |
| BR-005 | ストレッチ計算 | Stretch.Uniformは縦横比を維持して最大化 | Uniform指定時 |

### 計算ロジック

ストレッチ計算：
```csharp
switch (Stretch)
{
    case Stretch.Uniform:
        sx = sy = Math.Min(sx, sy);
        break;
    case Stretch.UniformToFill:
        sx = sy = Math.Max(sx, sy);
        break;
    case Stretch.Fill:
        // sx, sy はそれぞれ独立
        break;
    default: // None
        sx = sy = 1;
        break;
}
```

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | - | ジオメトリが無効 | デフォルトサイズを返す |

### リトライ仕様

該当なし。

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

該当なし。

## パフォーマンス要件

- DefiningGeometryのキャッシングにより不要なジオメトリ生成を回避
- Pen.TryModifyOrCreateによるペンオブジェクトの再利用
- ジオメトリ変更イベントの購読解除によるメモリリーク防止

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

特になし。

## 備考

- AffectsGeometry<TShape>()により、プロパティ変更時の自動再描画を設定可能
- 複雑な図形はPathコントロールとGeometryパス文字列で描画可能

---

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

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

### 推奨読解順序

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

まず、図形描画で使用されるジオメトリクラスを理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Geometry.cs | `src/Avalonia.Base/Media/Geometry.cs` | ジオメトリ基底クラス（別モジュール） |
| 1-2 | Brush.cs | `src/Avalonia.Base/Media/Brush.cs` | ブラシ基底クラス（別モジュール） |

**読解のコツ**: AvaloniaのStyledProperty/DirectPropertyシステムを理解しておくとプロパティ定義が読みやすい。

#### Step 2: 基底クラスを理解する

処理の中核となるShape基底クラスを特定。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Shape.cs | `src/Avalonia.Controls/Shapes/Shape.cs` | 全図形の基底クラス |

**主要処理フロー**:
1. **18-67行目**: StyledPropertyの定義（Fill、Stroke、StrokeThickness等）
2. **78-127行目**: DefiningGeometryとRenderedGeometryプロパティ
3. **212-220行目**: Render()メソッドで実際の描画
4. **230-243行目**: AffectsGeometry<TShape>()による自動再描画設定
5. **249行目**: CreateDefiningGeometry()抽象メソッド
6. **266-277行目**: InvalidateGeometry()でジオメトリ無効化
7. **308-336行目**: ArrangeOverride()で変換行列計算
8. **358-431行目**: CalculateSizeAndTransform()でストレッチ計算

#### Step 3: 各図形クラスを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Rectangle.cs | `src/Avalonia.Controls/Shapes/Rectangle.cs` | 矩形描画 |
| 3-2 | Ellipse.cs | `src/Avalonia.Controls/Shapes/Ellipse.cs` | 楕円描画 |
| 3-3 | Line.cs | `src/Avalonia.Controls/Shapes/Line.cs` | 直線描画 |
| 3-4 | Path.cs | `src/Avalonia.Controls/Shapes/Path.cs` | パス描画 |
| 3-5 | Polygon.cs | `src/Avalonia.Controls/Shapes/Polygon.cs` | 多角形描画 |
| 3-6 | Polyline.cs | `src/Avalonia.Controls/Shapes/Polyline.cs` | 折れ線描画 |
| 3-7 | Arc.cs | `src/Avalonia.Controls/Shapes/Arc.cs` | 円弧描画 |
| 3-8 | Sector.cs | `src/Avalonia.Controls/Shapes/Sector.cs` | 扇形描画 |

**Rectangle主要処理フロー**:
- **13-20行目**: RadiusX、RadiusYプロパティ定義
- **22-29行目**: 静的コンストラクタでAffectsGeometry登録
- **46-51行目**: CreateDefiningGeometry()でRectangleGeometry生成

**Line主要処理フロー**:
- **7-11行目**: StartPoint、EndPointプロパティ定義
- **13-17行目**: 静的コンストラクタでデフォルト値設定とAffectsGeometry登録
- **31-34行目**: CreateDefiningGeometry()でLineGeometry生成

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

```
Shape (基底クラス)
    │
    ├─ Rectangle
    │      └─ CreateDefiningGeometry() → RectangleGeometry
    │
    ├─ Ellipse
    │      └─ CreateDefiningGeometry() → EllipseGeometry
    │
    ├─ Line
    │      └─ CreateDefiningGeometry() → LineGeometry
    │
    ├─ Path
    │      └─ CreateDefiningGeometry() → Data (Geometry)
    │
    ├─ Polygon
    │      └─ CreateDefiningGeometry() → PathGeometry
    │
    ├─ Polyline
    │      └─ CreateDefiningGeometry() → PathGeometry
    │
    ├─ Arc
    │      └─ CreateDefiningGeometry() → ArcGeometry
    │
    └─ Sector
           └─ CreateDefiningGeometry() → SectorGeometry
```

### データフロー図

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

Fill/Stroke ─────────▶ OnPropertyChanged ─────────▶ InvalidateVisual
プロパティ                     │
                              ▼
RadiusX/Points等 ────▶ AffectsGeometryInvalidate ─▶ InvalidateGeometry
ジオメトリプロパティ             │
                              ▼
                        MeasureOverride
                              │
                              ▼
                        CreateDefiningGeometry ────▶ DefiningGeometry
                              │
                              ▼
                        ArrangeOverride
                              │
                              ▼
                        CalculateSizeAndTransform ─▶ _transform
                              │
                              ▼
                        Render
                              │
                              ▼
                        DrawGeometry ─────────────▶ 画面描画
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Shape.cs | `src/Avalonia.Controls/Shapes/Shape.cs` | ソース | 図形基底クラス |
| Rectangle.cs | `src/Avalonia.Controls/Shapes/Rectangle.cs` | ソース | 矩形コントロール |
| Ellipse.cs | `src/Avalonia.Controls/Shapes/Ellipse.cs` | ソース | 楕円コントロール |
| Line.cs | `src/Avalonia.Controls/Shapes/Line.cs` | ソース | 直線コントロール |
| Path.cs | `src/Avalonia.Controls/Shapes/Path.cs` | ソース | パスコントロール |
| Polygon.cs | `src/Avalonia.Controls/Shapes/Polygon.cs` | ソース | 多角形コントロール |
| Polyline.cs | `src/Avalonia.Controls/Shapes/Polyline.cs` | ソース | 折れ線コントロール |
| Arc.cs | `src/Avalonia.Controls/Shapes/Arc.cs` | ソース | 円弧コントロール |
| Sector.cs | `src/Avalonia.Controls/Shapes/Sector.cs` | ソース | 扇形コントロール |
