# 機能設計書 15-ProgressBar

## 概要

本ドキュメントは、Avalonia UIフレームワークにおけるProgressBarコントロールの機能設計を記述する。ProgressBarは処理の進捗状況を視覚的に表示するためのコントロールである。

### 本機能の処理概要

ProgressBarは、タスクの進捗状況をバー形式で視覚的に表示するコントロールである。確定モード（進捗率が明確）と不確定モード（進捗率不明）の2つの動作モードをサポートする。

**業務上の目的・背景**：ファイルダウンロード、データ処理、インストールなど、時間のかかる処理においてユーザーに進捗を示すことは、UX上非常に重要である。ProgressBarは、処理の完了までどの程度かかるかをユーザーに視覚的にフィードバックし、待ち時間のストレスを軽減する。

**機能の利用シーン**：
- ファイルダウンロード/アップロードの進捗表示
- データ処理・計算の進捗表示
- インストール処理の進捗表示
- ローディング状態の表示（不確定モード）

**主要な処理内容**：
1. 確定モードでの進捗率表示（0〜100%）
2. 不確定モードでのアニメーション表示
3. 進捗テキストの表示オプション
4. 水平・垂直の向き切り替え
5. Fluentテーマ/Simpleテーマ向けのアニメーション設定

**関連システム・外部連携**：RangeBaseを継承し、Minimum/Maximum/Valueプロパティを使用。アニメーション表示のためProgressBarTemplateSettingsを使用。

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 46 | ProgressBar | 主画面 | ProgressBarコントロールのデモ。進捗表示 |

## 機能種別

表示コントロール / 進捗表示

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| Minimum | double | No | 最小値 | デフォルト: 0 |
| Maximum | double | No | 最大値 | デフォルト: 100 |
| Value | double | No | 現在の値 | デフォルト: 0、OneWayバインディング |
| IsIndeterminate | bool | No | 不確定モード | デフォルト: false |
| ShowProgressText | bool | No | 進捗テキスト表示 | デフォルト: false |
| ProgressTextFormat | string | No | 進捗テキストフォーマット | デフォルト: "{1:0}%" |
| Orientation | Orientation | No | 向き | デフォルト: Horizontal |

### 入力データソース

- Valueプロパティへのデータバインディング
- IsIndeterminateプロパティによるモード切替

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| Percentage | double | 進捗率（0〜100） |

### 出力先

- 視覚的な進捗バー表示
- 進捗テキスト表示（ShowProgressText=true時）

## 処理フロー

### 処理シーケンス

```
1. プロパティ変更の検出
   └─ Value/Minimum/Maximum/IsIndeterminateの変更
2. UpdateIndicator()呼び出し
   └─ インジケーターのサイズ計算
3. モード判定
   ├─ 確定モード: インジケーター幅を進捗率に応じて設定
   └─ 不確定モード: アニメーション設定値の計算
4. Percentage更新
   └─ 進捗率を計算してプロパティ更新
```

### フローチャート

```mermaid
flowchart TD
    A[Value/IsIndeterminate変更] --> B[UpdateIndicator]
    B --> C{IsIndeterminate?}
    C -->|Yes| D[不確定モード設定]
    C -->|No| E[確定モード設定]
    D --> F[アニメーション開始位置計算]
    D --> G[アニメーション終了位置計算]
    D --> H[コンテナ幅計算]
    E --> I[進捗率計算]
    I --> J[インジケーター幅/高さ設定]
    J --> K[Percentage更新]
    F --> L[TemplateSettings更新]
    G --> L
    H --> L
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | 進捗率計算 | Percentage = (Value - Minimum) / (Maximum - Minimum) * 100 | 確定モード時 |
| BR-02 | ゼロ除算回避 | Maximum = Minimumの場合、進捗率は100%とする | 確定モード時 |
| BR-03 | 不確定アニメーション | Fluentテーマでは2つのインジケーターがアニメーション | 不確定モード時 |

### 計算ロジック

UpdateIndicator()のロジック（確定モード）：
```csharp
var percent = Math.Abs(Maximum - Minimum) < double.Epsilon ?
    1.0 :
    (Value - Minimum) / (Maximum - Minimum);

if (Orientation == Orientation.Horizontal)
{
    var width = (barSize.Width - margin) * percent;
    _indicator.Width = width > 0 ? width : 0;
}
else
{
    var height = (barSize.Height - margin) * percent;
    _indicator.Height = height > 0 ? height : 0;
}

Percentage = percent * 100;
```

不確定モードのアニメーション設定：
```csharp
var dim = barSize.Width;  // or Height for vertical
var barIndicatorWidth = dim * 0.4;  // 40%幅
var barIndicatorWidth2 = dim * 0.6; // 60%幅

ContainerAnimationStartPosition = barIndicatorWidth * -1.8;
ContainerAnimationEndPosition = barIndicatorWidth * 3.0;
Container2AnimationStartPosition = barIndicatorWidth2 * -1.5;
Container2AnimationEndPosition = barIndicatorWidth2 * 1.66;
```

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

### 操作別データベース影響一覧

該当なし（UIコントロール）

## エラー処理

### エラーケース一覧

特になし（表示専用コントロールのため）

### リトライ仕様

該当なし

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

該当なし（UIコントロール）

## パフォーマンス要件

- 不確定モードのアニメーションはGPUアクセラレーションを使用
- ValueのOneWayバインディングで高頻度更新に対応

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

特になし（UIコントロールとして汎用的に使用可能）

## 備考

- ValueプロパティのデフォルトバインディングモードはOneWay（RangeBaseのTwoWayをオーバーライド）
- PseudoClasses: :horizontal, :vertical, :indeterminate
- PART_Indicatorはテンプレート必須パーツ

---

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

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

### 推奨読解順序

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

ProgressBarTemplateSettingsを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | ProgressBar.cs (ProgressBarTemplateSettings) | `src/Avalonia.Controls/ProgressBar.cs` (26-186行目) | 不確定モードのアニメーション設定値 |

**読解のコツ**: ProgressBarTemplateSettingsは内部クラスとしてProgressBar.cs内に定義されている。これはテーマ側でアニメーションに使用する計算値を保持する。

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

ProgressBarクラス本体を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | ProgressBar.cs | `src/Avalonia.Controls/ProgressBar.cs` | プロパティ、UpdateIndicator()、PseudoClasses |

**主要処理フロー**:
1. **18行目**: RangeBaseを継承
2. **193-235行目**: プロパティ定義（IsIndeterminate, ShowProgressText, Orientation等）
3. **237-240行目**: 静的コンストラクタでValueのバインディングモードをOneWayに設定
4. **293-298行目**: ArrangeOverride - レイアウト後にUpdateIndicator呼び出し
5. **325-337行目**: OnApplyTemplate - PART_Indicatorの取得
6. **345-394行目**: UpdateIndicator - インジケーターサイズの計算

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

RangeBaseでの値管理を確認。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | RangeBase.cs | `src/Avalonia.Controls/Primitives/RangeBase.cs` | Minimum/Maximum/Value、ValueChangedイベント |

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

```
ProgressBar
    │
    ├─ RangeBase (基底クラス)
    │      └─ Minimum/Maximum/Value
    │
    ├─ ProgressBarTemplateSettings
    │      ├─ ContainerWidth/Container2Width
    │      ├─ ContainerAnimationStartPosition
    │      ├─ ContainerAnimationEndPosition
    │      ├─ Container2AnimationStartPosition
    │      ├─ Container2AnimationEndPosition
    │      └─ IndeterminateStartingOffset/EndingOffset
    │
    ├─ UpdateIndicator()
    │      ├─ 確定モード処理
    │      └─ 不確定モード処理
    │
    └─ PART_Indicator (Border)
           └─ 視覚的な進捗表示
```

### データフロー図

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

Value変更 ───▶ OnPropertyChanged ───▶ UpdateIndicator()
                        │
                        ▼
              IsIndeterminate判定
                   ├─────────┐
                   ▼         ▼
              確定モード  不確定モード
                   │         │
                   ▼         ▼
            インジケーター幅  TemplateSettings
                   │         │
                   ▼         ▼
              Percentage  アニメーション
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| ProgressBar.cs | `src/Avalonia.Controls/ProgressBar.cs` | ソース | ProgressBarコントロール本体 |
| RangeBase.cs | `src/Avalonia.Controls/Primitives/RangeBase.cs` | ソース | 基底クラス（範囲値管理） |
| ProgressBarAutomationPeer.cs | `src/Avalonia.Controls/Automation/Peers/ProgressBarAutomationPeer.cs` | ソース | UIオートメーション対応 |
