# 画面設計書 46-ProgressBar

## 概要

本ドキュメントは、Avalonia UIフレームワークのControlCatalogサンプルアプリケーションにおける「ProgressBar」デモページの画面設計書です。

### 本画面の処理概要

ProgressBarページは、進捗表示コントロールであるProgressBarの機能と使用方法をデモンストレーションする画面です。水平・垂直方向のプログレスバー、不確定モード、進捗テキスト表示など、様々な表示パターンを示しています。

**業務上の目的・背景**：ファイルダウンロード、データ処理、インストール進捗など、時間のかかる操作の進捗状況をユーザーに視覚的にフィードバックすることは、UX向上に不可欠です。本画面は、ProgressBarコントロールの基本的な使用方法から、カスタマイズされた表示フォーマット、不確定モード（処理時間が不明な場合）の表示まで、様々なシナリオでの実装方法を示しています。

**画面へのアクセス方法**：MainWindowからMainViewのHamburgerMenuを開き、「ProgressBar」メニュー項目を選択することでアクセスできます。

**主要な操作・処理内容**：
1. Sliderを使用した進捗値の動的変更
2. Maximum/Minimum値の設定変更
3. 進捗テキストフォーマットのカスタマイズ
4. 進捗テキスト表示の切り替え
5. 不確定モード（Indeterminate）の切り替え
6. 水平・垂直方向のProgressBar表示

**画面遷移**：本画面は単独のデモページであり、MainViewのHamburgerMenuから遷移します。他画面への直接遷移機能は持ちません。

**権限による表示制御**：本デモ画面では権限による表示制御は実装されていません。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 15 | ProgressBar | 主機能 | 進捗表示コントロール |

## 画面種別

デモ / 進捗表示

## URL/ルーティング

ControlCatalog内のHamburgerMenuナビゲーションによるページ切り替え（URL/ルーティング定義なし）

## 入出力項目

| 項目名 | 項目種別 | データ型 | 必須 | 説明 |
|--------|----------|----------|------|------|
| Maximum | 入力 | double | - | 最大値（デフォルト: 100） |
| Minimum | 入力 | double | - | 最小値（デフォルト: 0） |
| Progress Text Format | 入力 | string | - | 進捗テキストフォーマット（デフォルト: "{0:0}%"） |
| Show Progress Text | 入力 | bool | - | 進捗テキスト表示フラグ |
| Toggle Indeterminate | 入力 | bool | - | 不確定モードフラグ |
| hprogress | 入力 | double | - | 水平ProgressBar用スライダー値 |
| vprogress | 入力 | double | - | 垂直ProgressBar用スライダー値 |

## 表示項目

| 項目名 | 表示位置 | 説明 |
|--------|----------|------|
| 説明テキスト | 上部 | "A progress bar control" |
| Maximum NumericUpDown | 設定エリア | 最大値設定（デフォルト: 100） |
| Minimum NumericUpDown | 設定エリア | 最小値設定（デフォルト: 0） |
| Progress Text Format TextBox | 設定エリア | フォーマット文字列設定 |
| Show Progress Text CheckBox | 設定エリア | 進捗テキスト表示切り替え |
| Toggle Indeterminate CheckBox | 設定エリア | 不確定モード切り替え |
| 水平ProgressBar | 中央左 | 水平方向の進捗表示 |
| 垂直ProgressBar | 中央右 | 垂直方向の進捗表示 |
| 水平Slider | 下部 | 水平ProgressBarの値制御 |
| 垂直Slider | 下部 | 垂直ProgressBarの値制御 |
| 固定値ProgressBar x 3 | 最下部 | 様々な範囲設定のProgressBar |

## イベント仕様

### 1-Slider値変更イベント

hprogressまたはvprogressスライダーの値が変更されると、バインディングを通じてProgressBarのValueプロパティが更新される。ProgressBarは自動的に進捗表示を更新する。

### 2-Maximum/Minimum変更イベント

NumericUpDownでMaximumまたはMinimumが変更されると、バインディングを通じてProgressBarとSliderの範囲が更新される。

### 3-ShowProgressText変更イベント

CheckBoxのIsCheckedが変更されると、ProgressBarのShowProgressTextプロパティが更新され、進捗テキストの表示/非表示が切り替わる。

### 4-IsIndeterminate変更イベント

CheckBoxのIsCheckedが変更されると、ProgressBarのIsIndeterminateプロパティが更新され、確定/不確定モードが切り替わる。不確定モードでは進捗値に関係なくアニメーションが表示される。

## データベース更新仕様

本画面はUIコントロールのデモ画面であり、データベースへのアクセス・更新は行いません。

## メッセージ仕様

本画面では特定のメッセージ表示は実装されていません。

## 例外処理

- Maximum < Minimum の場合の動作はAvaloniaコントロールの標準動作に依存
- 不正なフォーマット文字列が指定された場合はデフォルト表示にフォールバック

## 備考

- ProgressTextFormatはString.Format形式で指定（{0}が進捗率）
- Orientationプロパティで水平（Horizontal）/垂直（Vertical）を切り替え
- 不確定モード（IsIndeterminate=True）では進捗値に関係なくアニメーション表示
- 固定値の例として、Value=5/Maximum=10、Value=50/Maximum=100、Minimum=25/Maximum=75のProgressBarを表示

---

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

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

### 推奨読解順序

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

ProgressBarコントロールのプロパティと設定項目を理解することが重要です。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | ProgressBarPage.xaml | `samples/ControlCatalog/Pages/ProgressBarPage.xaml` | NumericUpDownによるMaximum/Minimum設定（7-12行） |
| 1-2 | ProgressBarPage.xaml | `samples/ControlCatalog/Pages/ProgressBarPage.xaml` | TextBoxによるフォーマット文字列設定（14-15行） |

**読解のコツ**: ProgressBarのMinimum/Maximum/Valueの関係と、ProgressTextFormatの書式を理解しておくと良い。

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

UserControlの初期化処理を確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | ProgressBarPage.xaml.cs | `samples/ControlCatalog/Pages/ProgressBarPage.xaml.cs` | コンストラクタ（7-10行）でInitializeComponent |

**主要処理フロー**:
1. **8行**: InitializeComponentでXAMLをロード
2. 以降はXAMLバインディングによる制御

#### Step 3: バインディング構造を理解する

コントロール間のバインディング関係を確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | ProgressBarPage.xaml | `samples/ControlCatalog/Pages/ProgressBarPage.xaml` | ProgressBarへのバインディング（21-22行） |
| 3-2 | ProgressBarPage.xaml | `samples/ControlCatalog/Pages/ProgressBarPage.xaml` | Sliderからの値バインディング（28-29行） |

**主要処理フロー**:
- **21行**: IsIndeterminate → #isIndeterminate.IsChecked
- **21行**: ShowProgressText → #showProgress.IsChecked
- **21行**: Value → #hprogress.Value
- **22行**: Minimum/Maximum → #minimum.Value/#maximum.Value

#### Step 4: 固定値ProgressBarを理解する

様々な設定パターンのProgressBarを確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | ProgressBarPage.xaml | `samples/ControlCatalog/Pages/ProgressBarPage.xaml` | 固定値ProgressBar（32-36行） |

**主要処理フロー**:
- **33行**: Value=5, Maximum=10（50%表示）
- **34行**: Value=50（デフォルトMax=100なので50%表示）
- **35行**: Value=50, Minimum=25, Maximum=75（範囲内で50%表示）

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

```
ProgressBarPage (UserControl)
    │
    ├─ InitializeComponent()
    │      └─ XAMLパーサー → ProgressBarPage.xaml読み込み
    │
    └─ XAML バインディング構造
           │
           ├─ NumericUpDown (maximum)
           │      └─ Value ──▶ ProgressBar.Maximum
           │                   └─ Slider.Maximum
           │
           ├─ NumericUpDown (minimum)
           │      └─ Value ──▶ ProgressBar.Minimum
           │                   └─ Slider.Minimum
           │
           ├─ TextBox (stringFormat)
           │      └─ Text ──▶ ProgressBar.ProgressTextFormat
           │
           ├─ CheckBox (showProgress)
           │      └─ IsChecked ──▶ ProgressBar.ShowProgressText
           │
           ├─ CheckBox (isIndeterminate)
           │      └─ IsChecked ──▶ ProgressBar.IsIndeterminate
           │
           ├─ Slider (hprogress)
           │      └─ Value ──▶ 水平ProgressBar.Value
           │
           └─ Slider (vprogress)
                  └─ Value ──▶ 垂直ProgressBar.Value
```

### データフロー図

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

NumericUpDown ──────────▶ Binding ──────────────────▶ ProgressBar
(Maximum/Minimum)          │                           .Maximum/.Minimum
                           │                                │
                           ▼                                ▼
                      Slider範囲更新              進捗バー範囲更新

Slider ─────────────────▶ Binding ──────────────────▶ ProgressBar.Value
(hprogress/vprogress)      │                                │
                           │                                ▼
                           │                          進捗表示更新

TextBox ────────────────▶ Binding ──────────────────▶ ProgressTextFormat
(stringFormat)                                              │
                                                            ▼
                                                      進捗テキスト更新
                                                      (例: "40%")

CheckBox ───────────────▶ Binding ──────────────────▶ IsIndeterminate
(isIndeterminate)                                           │
                                                            ▼
                                                      不確定モードアニメーション
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| ProgressBarPage.xaml | `samples/ControlCatalog/Pages/ProgressBarPage.xaml` | XAML | 画面レイアウト・バインディング定義 |
| ProgressBarPage.xaml.cs | `samples/ControlCatalog/Pages/ProgressBarPage.xaml.cs` | ソース | コードビハインド（InitializeComponentのみ） |
