# 機能設計書 34-DockPanel

## 概要

本ドキュメントは、Avalonia UIフレームワークにおけるDockPanel（ドックレイアウトパネル）の機能設計を定義するものである。DockPanelは子要素をパネルの上下左右または中央に配置するレイアウトパネルを提供する。

### 本機能の処理概要

DockPanelは、Dock添付プロパティで指定された位置（Left/Right/Top/Bottom）に子要素を順次配置し、最後の子要素で残りスペースを埋めるレイアウトパネルを提供する。典型的なアプリケーションのヘッダー・サイドバー・コンテンツ・フッター構成を簡単に実現できる。

**業務上の目的・背景**：アプリケーションのメインレイアウトにおいて、ヘッダー、ナビゲーション、コンテンツ、ステータスバーなどの配置パターンは非常に一般的である。DockPanelは、このような「ドッキング」パターンを宣言的に実現できるレイアウトコンテナを提供する。

**機能の利用シーン**：
- アプリケーションのメインレイアウト構成
- ヘッダー・フッター付きのページレイアウト
- サイドバー付きのエディタレイアウト
- ツールバー領域の配置

**主要な処理内容**：
1. Dock添付プロパティによる配置位置指定（Left/Right/Top/Bottom）
2. LastChildFillオプションによる最後の子要素の残りスペース充填
3. HorizontalSpacing/VerticalSpacingによる要素間の間隔設定
4. 順次ドッキングによる残りスペースの縮小計算

**関連システム・外部連携**：Panel基底クラスを継承。

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

## 関連画面

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

## 機能種別

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

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| LastChildFill | bool | No | 最後の子要素が残りスペースを埋めるか（デフォルト: true） | - |
| HorizontalSpacing | double | No | 左右ドック間の水平間隔（デフォルト: 0） | 0以上 |
| VerticalSpacing | double | No | 上下ドック間の垂直間隔（デフォルト: 0） | 0以上 |

### 添付プロパティ

| プロパティ名 | 型 | 説明 | デフォルト値 |
|-------------|-----|------|-------------|
| DockPanel.Dock | Dock | 子要素のドック位置 | Left (0) |

### Dock列挙型

| 値 | 説明 |
|-----|------|
| Left | 左端にドック |
| Right | 右端にドック |
| Top | 上端にドック |
| Bottom | 下端にドック |

## 出力仕様

### 出力データ

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

## 処理フロー

### 処理シーケンス

```
1. MeasureOverrideフェーズ
   ├─ 各子要素を順次計測
   ├─ Left/Right: 幅を累積、高さを最大化
   ├─ Top/Bottom: 高さを累積、幅を最大化
   └─ 最後の子要素（LastChildFill時）: 残りスペースで計測
2. ArrangeOverrideフェーズ
   ├─ currentBoundsを初期化（全体サイズ）
   ├─ 各子要素を順次配置
   ├─ ドック後にcurrentBoundsを縮小
   └─ 最後の子要素: 残りのcurrentBoundsに配置
```

### フローチャート

```mermaid
flowchart TD
    A[MeasureOverride開始] --> B[accumulatedWidth/Height初期化]
    B --> C[子要素ループ]
    C --> D{Dock値?}
    D -->|Left/Right| E[accumulatedWidth += 子幅 + Spacing]
    D -->|Top/Bottom| F[accumulatedHeight += 子高 + Spacing]
    E --> G[parentHeight = Max]
    F --> H[parentWidth = Max]
    G --> I{次の子?}
    H --> I
    I -->|Yes| C
    I -->|No| J{LastChildFill?}
    J -->|Yes| K[最後の子要素計測]
    J -->|No| L[Spacing調整]
    K --> M[DesiredSize返却]
    L --> M
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-34-01 | ドック順序 | 子要素は追加順にドックされ、先にドックした要素が優先される | 常時 |
| BR-34-02 | スペース消費 | Left/Rightは垂直方向全体、Top/Bottomは水平方向全体を使用 | 常時 |
| BR-34-03 | LastChildFill | true時は最後の子要素が残りスペースを埋める | LastChildFill=true時 |
| BR-34-04 | 非可視要素スキップ | IsVisible=falseの子要素はSpacing計算と配置から除外 | 子要素が非可視時 |

### 計算ロジック

**ドック領域の計算**:
```
Left ドック後: remainingWidth = currentWidth - childWidth - HorizontalSpacing
Top ドック後: remainingHeight = currentHeight - childHeight - VerticalSpacing
```

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

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

## エラー処理

特になし（基本的にエラーは発生しない設計）

## パフォーマンス要件

- 軽量なレイアウト計算（O(n)）
- 可視性チェックによる不要計算のスキップ

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

特になし

## 備考

- WPFのDockPanelからの移植実装
- HorizontalSpacing/VerticalSpacingはAvaloniaの拡張機能

---

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

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

### 推奨読解順序

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

Dock列挙型の定義を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | DockPanel.cs | `src/Avalonia.Controls/DockPanel.cs` | Dock列挙型定義（13-19行目） |

**読解のコツ**: Dock列挙型はLeft=0, Bottom=1, Right=2, Top=3の順序で定義されている。

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | DockPanel.cs | `src/Avalonia.Controls/DockPanel.cs` | メインクラス |

**主要処理フロー**:
- **24行目**: `DockPanel`クラス定義。`Panel`を継承
- **29-30行目**: Dock添付プロパティ定義
- **35-38行目**: LastChildFillプロパティ（デフォルトtrue）
- **44-54行目**: HorizontalSpacing/VerticalSpacingプロパティ
- **59-63行目**: 静的コンストラクタ - AffectsMeasure登録

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

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

**主要処理フロー**:
- **127-130行目**: 累積サイズ変数初期化
- **134行目**: LastChildFill時は最後の子を別処理
- **136-180行目**: 子要素ループ - Dock値による分岐処理
- **156-167行目**: Left/Right処理 - 幅累積、高さ最大化
- **169-178行目**: Top/Bottom処理 - 高さ累積、幅最大化
- **182-195行目**: LastChildFill時の最後の子要素計測

**読解のコツ**: 117-122行目のコメントで、Left/Rightは全垂直スペース、Top/Bottomは全水平スペースを使用する動作を説明。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | DockPanel.cs | `src/Avalonia.Controls/DockPanel.cs` | ArrangeOverrideメソッド（215-275行目） |

**主要処理フロー**:
- **220行目**: currentBoundsを全体サイズで初期化
- **223-266行目**: 子要素ループ - Dock値による配置
- **233-240行目**: Left配置とcurrentBounds縮小
- **241-248行目**: Top配置とcurrentBounds縮小
- **249-256行目**: Right配置とcurrentBounds縮小
- **257-264行目**: Bottom配置とcurrentBounds縮小
- **268-272行目**: 最後の子要素を残りスペースに配置

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

```
DockPanel (レイアウトパネル)
    │
    ├─ MeasureOverride()
    │      ├─ 子要素ループ
    │      │      ├─ Dock値取得
    │      │      ├─ child.Measure()
    │      │      └─ 累積サイズ更新
    │      └─ LastChildFill処理
    │
    └─ ArrangeOverride()
           ├─ 子要素ループ
           │      ├─ Dock値取得
           │      ├─ child.Arrange()
           │      └─ currentBounds縮小
           └─ LastChildFill配置
```

### データフロー図

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

LastChildFill ───────────▶ MeasureOverride()
                              │
Spacing設定 ─────────────▶ │
                              │
子要素コレクション ────────▶ 子要素ループ
                              │
Dock添付プロパティ ────────▶ │
                              │
                    ┌─────────┴─────────┐
                    ▼                   ▼
         Left/Right累積      Top/Bottom累積
         (Width + Spacing)   (Height + Spacing)
                    │                   │
                    └─────────┬─────────┘
                              ▼
                     DesiredSize
                              │
                              ▼
                     ArrangeOverride()
                              │
                    ┌─────────┴─────────┐
                    ▼                   ▼
         各要素配置          currentBounds縮小
                    │                   │
                    └─────────┬─────────┘
                              ▼
                    最後の子要素を残りに配置
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| DockPanel.cs | `src/Avalonia.Controls/DockPanel.cs` | ソース | メインクラス、Dock列挙型 |
| Panel.cs | `src/Avalonia.Controls/Panel.cs` | ソース | 基底クラス |
