# 機能設計書 32-Grid

## 概要

本ドキュメントは、Avalonia UIフレームワークにおけるGrid（グリッドレイアウトパネル）の機能設計を定義するものである。Gridは行と列で構成される柔軟なレイアウト領域を提供し、複雑なUIレイアウトを実現するための基本コンポーネントである。

### 本機能の処理概要

Gridは、RowDefinitionsとColumnDefinitionsで定義された行・列に子要素を配置するレイアウトパネルを提供する。各行・列はAuto（内容に合わせる）、Pixel（固定サイズ）、Star（残りスペースの比率配分）の3種類のサイズ指定が可能である。

**業務上の目的・背景**：アプリケーションのUI設計において、要素を行・列の格子状に配置するニーズは非常に多い。Gridは、フォームレイアウト、データ表示、複雑なダッシュボードなど、様々なUI要件に対応できる汎用的なレイアウトコンテナを提供する。

**機能の利用シーン**：
- フォームのラベルと入力フィールドの配置
- ダッシュボードのタイル配置
- マスター・ディテール形式のレイアウト
- ヘッダー・コンテンツ・フッター構成

**主要な処理内容**：
1. RowDefinitions/ColumnDefinitionsによる行・列構造の定義
2. 添付プロパティ（Row, Column, RowSpan, ColumnSpan）による子要素配置
3. Auto/Pixel/Starサイズ計算アルゴリズムによるレイアウト処理
4. SharedSizeScopeによる複数Grid間でのサイズ共有

**関連システム・外部連携**：Panel基底クラスを継承し、Avalonia UIのレイアウトシステムと統合。

**権限による制御**：特になし。UIコンポーネントとしてアプリケーション側で必要に応じて実装。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | Gridは基本レイアウトパネルとして多くの画面で使用される |

## 機能種別

レイアウト制御 / UIコンテナ

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| RowDefinitions | RowDefinitions | No | 行定義のコレクション | - |
| ColumnDefinitions | ColumnDefinitions | No | 列定義のコレクション | - |
| ShowGridLines | bool | No | グリッド線を表示するかどうか（デフォルト: false） | - |
| RowSpacing | double | No | 行間のスペース（デフォルト: 0） | 0以上 |
| ColumnSpacing | double | No | 列間のスペース（デフォルト: 0） | 0以上 |

### 添付プロパティ

| プロパティ名 | 型 | 説明 | デフォルト値 |
|-------------|-----|------|-------------|
| Grid.Row | int | 子要素を配置する行インデックス | 0 |
| Grid.Column | int | 子要素を配置する列インデックス | 0 |
| Grid.RowSpan | int | 子要素がまたがる行数 | 1 |
| Grid.ColumnSpan | int | 子要素がまたがる列数 | 1 |
| Grid.IsSharedSizeScope | bool | 共有サイズスコープを有効にするか | false |

### GridLength単位タイプ

| タイプ | 説明 | 例 |
|--------|------|-----|
| Auto | 内容に合わせてサイズを自動決定 | `Height="Auto"` |
| Pixel | 固定ピクセルサイズ | `Width="100"` |
| Star | 残りスペースの比率配分 | `Width="2*"` |

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| DesiredSize | Size | 計測フェーズで計算された希望サイズ |
| 子要素の最終位置 | Rect | 配置フェーズで決定された各子要素の位置とサイズ |

## 処理フロー

### 処理シーケンス

```
1. 定義の検証
   └─ RowDefinitions/ColumnDefinitions構造の検証
2. セルグループ分類
   └─ Px/Auto/Starの組み合わせで4グループに分類
3. Measureフェーズ
   ├─ グループ1: Px/Auto行列のセル
   ├─ グループ2: Auto行×Star列のセル
   ├─ グループ3: Star行×Auto列のセル
   └─ グループ4: Star行×Star列のセル
4. 解決フェーズ
   ├─ Starサイズ解決（行）
   └─ Starサイズ解決（列）
5. Arrangeフェーズ
   └─ 各子要素を計算された位置に配置
```

### フローチャート

```mermaid
flowchart TD
    A[MeasureOverride開始] --> B{定義あり?}
    B -->|Yes| C[定義構造検証]
    B -->|No| D[単純計測]
    C --> E[セルグループ分類]
    E --> F[グループ1計測]
    F --> G{StarsV解決可?}
    G -->|Yes| H[StarsV解決]
    G -->|No| I{StarsU解決可?}
    H --> J[グループ2計測]
    J --> K[StarsU解決]
    K --> L[グループ3計測]
    I -->|Yes| M[StarsU解決]
    I -->|No| N[グループ2'計測]
    N --> O[StarsU解決]
    M --> P[グループ3計測]
    P --> Q[StarsV解決]
    O --> R[StarsV解決]
    L --> S[グループ4計測]
    Q --> S
    R --> S
    S --> T[DesiredSize計算]
    D --> T
    T --> U[MeasureOverride終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-32-01 | 定義不在時のデフォルト | RowDefinitions/ColumnDefinitionsが未定義の場合、1行1列として扱う | 定義なし時 |
| BR-32-02 | 範囲外インデックス | Row/Column値が定義範囲外の場合、最後の行/列に配置 | インデックス範囲外時 |
| BR-32-03 | Starサイズ解決 | Star列/行は残りスペースを比率に応じて配分 | Starサイズ指定時 |
| BR-32-04 | SharedSizeGroup | 同一SharedSizeScope内のSharedSizeGroupは同じサイズになる | SharedSizeGroup指定時 |

### 計算ロジック

**Starサイズ計算**:
```
各Star要素のサイズ = (残りスペース / 全Star値の合計) × 該当要素のStar値
```

**グリッドサイズ計算**:
```
GridWidth = Σ(ColumnWidths) + (ColumnCount - 1) × ColumnSpacing
GridHeight = Σ(RowHeights) + (RowCount - 1) × RowSpacing
```

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

該当なし（UIコンポーネントのためDB操作は行わない）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| ArgumentNullException | パラメータエラー | null要素への添付プロパティ設定 | 例外スロー |
| ArgumentException | 範囲エラー | GridLength値が負数/NaN/Infinity | 例外スロー |

## パフォーマンス要件

- レイアウト計算の最適化（キャッシュ活用、不要な再計算回避）
- UseLayoutRounding有効時の丸め誤差補正

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

特になし

## 備考

- WPFのGridからの移植実装
- 複雑なレイアウト要件には他のパネル（StackPanel, DockPanel等）との組み合わせを推奨

---

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

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

### 推奨読解順序

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

行・列定義の構造体とサイズ指定方法を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | GridLength.cs | `src/Avalonia.Controls/GridLength.cs` | GridLengthとGridUnitType（Auto/Pixel/Star）の定義 |
| 1-2 | DefinitionBase.cs | `src/Avalonia.Controls/DefinitionBase.cs` | 行・列定義の基底クラス |
| 1-3 | RowDefinition.cs | `src/Avalonia.Controls/RowDefinition.cs` | 行定義クラス |
| 1-4 | ColumnDefinition.cs | `src/Avalonia.Controls/ColumnDefinition.cs` | 列定義クラス |

**読解のコツ**: GridLengthのParse()メソッド（192-211行目）で文字列から`Auto`/`100`/`2*`形式をパースする方法を理解する。

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

Gridクラスの基本構造と添付プロパティを把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Grid.cs | `src/Avalonia.Controls/Grid.cs` | メインクラス（Panelを継承） |

**主要処理フロー**:
- **23行目**: `Grid`クラス定義。`Panel`を継承
- **25-39行目**: 静的コンストラクタ - プロパティ変更ハンドラ登録
- **53-134行目**: 添付プロパティ（Column/Row/ColumnSpan/RowSpan）のGetter/Setter
- **136-156行目**: IsSharedSizeScopeプロパティ
- **189-227行目**: ColumnDefinitions/RowDefinitionsプロパティ

#### Step 3: MeasureOverride - 計測処理

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Grid.cs | `src/Avalonia.Controls/Grid.cs` | MeasureOverrideメソッド（234行目〜） |

**主要処理フロー**:
- **234-256行目**: 定義なし時のシンプル計測
- **259-292行目**: 定義構造の検証とSizeToContent判定
- **294-399行目**: セルグループ分類アルゴリズムのコメント説明
- グループ1〜4の計測順序と依存関係の解決

**読解のコツ**: 298-315行目のコメントで、Px/Auto/Starの組み合わせによる4グループ分類を説明。循環依存の解決方法も記載。

#### Step 4: ArrangeOverride - 配置処理

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Grid.cs | `src/Avalonia.Controls/Grid.cs` | ArrangeOverrideメソッド |

**主要処理フロー**:
- 行・列の最終サイズに基づく子要素配置
- RowSpan/ColumnSpanの考慮
- Spacingの適用

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

```
Grid (レイアウトパネル)
    │
    ├─ MeasureOverride() - 計測処理
    │      ├─ ValidateDefinitionsUStructure() - 列定義構造検証
    │      ├─ ValidateDefinitionsVStructure() - 行定義構造検証
    │      ├─ ValidateCells() - セル情報検証
    │      ├─ MeasureCellsGroup() - グループ別計測
    │      │      └─ MeasureCell() - 個別セル計測
    │      ├─ ResolveStar() - Starサイズ解決
    │      └─ CalculateDesiredSize() - 希望サイズ計算
    │
    └─ ArrangeOverride() - 配置処理
           ├─ SetFinalSize() - 最終サイズ設定
           └─ ArrangeChild() - 子要素配置
                  └─ GetFinalSizeForRange() - 範囲サイズ取得
```

### データフロー図

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

RowDefinitions ─────────▶ ValidateDefinitionsVStructure()
                              │
ColumnDefinitions ───────▶ ValidateDefinitionsUStructure()
                              │
子要素コレクション ────────▶ ValidateCells() ─────────────────▶ セルグループ分類
                              │
利用可能サイズ ─────────────▶ ↓
                              │
                    ┌─────────┴─────────┐
                    ▼                   ▼
            グループ1-4計測      Starサイズ解決
                    │                   │
                    └─────────┬─────────┘
                              ▼
                     DesiredSize計算
                              │
                              ▼
                     ArrangeOverride()
                              │
                              ▼
                    子要素の最終位置設定
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Grid.cs | `src/Avalonia.Controls/Grid.cs` | ソース | メインクラス |
| GridLength.cs | `src/Avalonia.Controls/GridLength.cs` | ソース | サイズ指定構造体 |
| DefinitionBase.cs | `src/Avalonia.Controls/DefinitionBase.cs` | ソース | 定義基底クラス |
| RowDefinition.cs | `src/Avalonia.Controls/RowDefinition.cs` | ソース | 行定義クラス |
| ColumnDefinition.cs | `src/Avalonia.Controls/ColumnDefinition.cs` | ソース | 列定義クラス |
| RowDefinitions.cs | `src/Avalonia.Controls/RowDefinitions.cs` | ソース | 行定義コレクション |
| ColumnDefinitions.cs | `src/Avalonia.Controls/ColumnDefinitions.cs` | ソース | 列定義コレクション |
| Panel.cs | `src/Avalonia.Controls/Panel.cs` | ソース | 基底クラス |
