# 画面設計書 41-NumericUpDown

## 概要

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

### 本画面の処理概要

NumericUpDownページは、数値入力コントロールであるNumericUpDownの機能と使用方法をデモンストレーションする画面です。ユーザーはスピンボタン、キーボードの上下矢印キー、またはマウスホイールを使用して数値を増減できます。

**業務上の目的・背景**：NumericUpDownコントロールは、数値入力が必要なフォームやデータ入力画面で広く使用されます。本画面は、開発者がNumericUpDownコントロールの様々な機能（フォーマット文字列、カルチャ対応、バリデーション、16進数モードなど）を理解し、自身のアプリケーションに組み込む際の参考とするために提供されています。通貨入力、数量指定、設定値調整など、多様な業務シナリオに対応するコントロールの柔軟性を示しています。

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

**主要な操作・処理内容**：
1. スピンボタンによる数値の増減操作
2. テキスト入力による直接数値入力
3. フォーマット文字列（通貨、パーセント、固定小数点など）の選択と適用
4. カルチャ（言語・地域）による数値フォーマットの切り替え
5. 最小値・最大値・増分値の動的変更
6. 読み取り専用モードの切り替え
7. スピンボタンの表示/非表示切り替え
8. 16進数モードでの数値入力
9. バリデーションエラーの表示確認

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

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

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 27 | NumericUpDown | 主機能 | スピンボタンによる数値入力の増減制御 |

## 画面種別

デモ / 入力コントロール

## URL/ルーティング

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

## 入出力項目

| 項目名 | 項目種別 | データ型 | 必須 | 説明 |
|--------|----------|----------|------|------|
| ShowButtonSpinner | 入力 | bool | - | スピンボタンの表示/非表示を制御 |
| IsReadOnly | 入力 | bool | - | 読み取り専用モードの設定 |
| AllowSpin | 入力 | bool | - | スピン操作の許可/禁止 |
| ClipValueToMinMax | 入力 | bool | - | 値を最小・最大範囲にクリップするかどうか |
| FormatString | 入力 | string | - | 数値表示フォーマット（C2、F2、G、N、P等） |
| ButtonSpinnerLocation | 入力 | Location | - | スピンボタンの位置（Left/Right） |
| CultureInfo | 入力 | CultureInfo | - | 数値フォーマットに使用するカルチャ |
| PlaceholderText | 入力 | string | - | プレースホルダーテキスト |
| Minimum | 入力 | decimal | - | 最小値（デフォルト: 0） |
| Maximum | 入力 | decimal | - | 最大値（デフォルト: 10） |
| Increment | 入力 | decimal | - | 増減量（デフォルト: 0.5） |
| Value | 入出力 | decimal/double | - | 現在の数値 |
| Text | 入出力 | string | - | テキスト表示値 |

## 表示項目

| 項目名 | 表示位置 | 説明 |
|--------|----------|------|
| 機能説明テキスト | 上部 | NumericUpDownコントロールの説明 |
| Features設定エリア | 上部グリッド | 各種オプション設定用のチェックボックス・コンボボックス |
| decimal NumericUpDown | 中央左 | decimal型NumericUpDownのデモ |
| double NumericUpDown | 中央中 | double型NumericUpDownのデモ |
| Validation NumericUpDown | 中央右 | バリデーションエラー表示のデモ |
| HEX NumericUpDown | 右端 | 16進数モードのデモ |
| プレースホルダー付きNumericUpDown | 下部 | カスタムプレースホルダー色のデモ |
| InnerContent付きNumericUpDown | 最下部 | 内部コンテンツ（単位表示等）のデモ |

## イベント仕様

### 1-Value変更イベント

スピンボタンクリック、キーボード上下矢印、マウスホイール、またはテキスト入力によりValueプロパティが変更される。ViewModelのDecimalValue/DoubleValueプロパティとバインディングされており、INotifyPropertyChangedを通じて変更が通知される。

### 2-FormatString変更イベント

FormatStringコンボボックスで選択変更時、NumericUpDownのFormatStringプロパティがバインディングにより更新され、表示フォーマットが変更される。

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

CultureSelectorコンボボックスで選択変更時、CultureConverterを通じてNumberFormatプロパティが更新され、数値フォーマットが選択されたカルチャに従って変更される。

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

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

## メッセージ仕様

| メッセージ種別 | 表示条件 | メッセージ内容 |
|---------------|----------|---------------|
| バリデーションエラー | ValidationUpDownに対して | DataValidationErrors.Errorに設定されたExceptionによるエラー表示 |

## 例外処理

- 数値として解釈できない文字列が入力された場合、NumericUpDownコントロールの内部処理により値が拒否される
- ClipValueToMinMaxが有効な場合、範囲外の値は自動的に最小値または最大値にクリップされる
- HexConverterで16進数として解釈できない文字列が入力された場合、UnsetValueが返される

## 備考

- Decimal型とDouble型の両方のNumericUpDownをサポート
- カスタムTextConverter（HexConverter）を使用して16進数入力モードを実現
- InnerLeftContent/InnerRightContentにより、NumericUpDown内部に単位表示やボタン等のカスタムコンテンツを配置可能

---

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

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

### 推奨読解順序

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

まず、ViewModelで管理されるデータ構造と、NumericUpDownで使用されるフォーマットオブジェクトを理解することが重要です。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | NumericUpDownPage.xaml.cs | `samples/ControlCatalog/Pages/NumericUpDownPage.xaml.cs` | NumbersPageViewModelクラス（25-93行）でDecimalValue、DoubleValue、Formats、Culturesプロパティを確認 |
| 1-2 | NumericUpDownPage.xaml.cs | `samples/ControlCatalog/Pages/NumericUpDownPage.xaml.cs` | FormatObjectクラス（95-99行）でフォーマット名と値のマッピングを確認 |

**読解のコツ**: MiniMvvmフレームワークのViewModelBaseとRaiseAndSetIfChangedパターンに注目。INotifyPropertyChanged実装のシンプルな例として参考になる。

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

処理の起点となるUserControlの初期化処理を確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | NumericUpDownPage.xaml.cs | `samples/ControlCatalog/Pages/NumericUpDownPage.xaml.cs` | コンストラクタ（14-19行）でViewModelのインスタンス化とDataContext設定 |

**主要処理フロー**:
1. **14-16行**: InitializeComponentでXAMLをロード
2. **17行**: NumbersPageViewModelをインスタンス化
3. **18行**: DataContextにViewModelを設定

#### Step 3: XAMLレイアウト構造を理解する

NumericUpDownコントロールの配置とバインディング設定を確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | NumericUpDownPage.xaml | `samples/ControlCatalog/Pages/NumericUpDownPage.xaml` | StackPanel構造とWrapPanelによるレイアウト |
| 3-2 | NumericUpDownPage.xaml | `samples/ControlCatalog/Pages/NumericUpDownPage.xaml` | 14-27行で機能設定用CheckBoxのバインディング（#upDown参照） |
| 3-3 | NumericUpDownPage.xaml | `samples/ControlCatalog/Pages/NumericUpDownPage.xaml` | 81-84行でメインNumericUpDownの設定とバインディング |

**主要処理フロー**:
- **81-84行**: upDown（メインのNumericUpDown）定義
- **82行**: NumberFormatプロパティへのCultureConverter適用
- **84行**: FormatStringプロパティへのバインディング

#### Step 4: コンバーターを理解する

カルチャ変換と16進数変換のロジックを確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | NumericUpDownPage.xaml.cs | `samples/ControlCatalog/Pages/NumericUpDownPage.xaml.cs` | CultureConverter（21-22行）でCultureInfoからNumberFormatInfoへの変換 |
| 4-2 | HexConverter.cs | `samples/ControlCatalog/Converter/HexConverter.cs` | 16進数文字列とdecimal間の双方向変換（10-33行） |

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

```
NumericUpDownPage (UserControl)
    │
    ├─ InitializeComponent()
    │      └─ XAMLパーサー → NumericUpDownPage.xaml読み込み
    │
    ├─ NumbersPageViewModel
    │      ├─ DecimalValue (Property)
    │      ├─ DoubleValue (Property)
    │      ├─ Formats (IList<FormatObject>)
    │      ├─ SpinnerLocations (IList<Location>)
    │      ├─ Cultures (IList<CultureInfo>)
    │      └─ SelectedFormat (Property)
    │
    ├─ CultureConverter (Static)
    │      └─ FuncValueConverter → NumberFormatInfo
    │
    └─ NumericUpDown (Controls)
           ├─ upDown (decimal型)
           ├─ DoubleUpDown (double型)
           ├─ ValidationUpDown (エラー表示)
           ├─ HexUpDown (16進数)
           │      └─ HexConverter
           ├─ PlaceholderForegroundUpDown
           └─ InnerContent
```

### データフロー図

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

ユーザー操作 ─────────▶ NumericUpDown ──────────────▶ 数値表示
(スピンボタン/           ├─ Value検証                  (フォーマット適用)
 キーボード/             ├─ Min/Max制約
 マウスホイール/         └─ Increment適用
 テキスト入力)                  │
                              ▼
                       ViewModel
                       (DecimalValue/DoubleValue)
                              │
                              ▼
                       バインディング更新
                       (INotifyPropertyChanged)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| NumericUpDownPage.xaml | `samples/ControlCatalog/Pages/NumericUpDownPage.xaml` | XAML | 画面レイアウト定義 |
| NumericUpDownPage.xaml.cs | `samples/ControlCatalog/Pages/NumericUpDownPage.xaml.cs` | ソース | コードビハインド・ViewModel |
| HexConverter.cs | `samples/ControlCatalog/Converter/HexConverter.cs` | ソース | 16進数変換コンバーター |
| ViewModelBase.cs | `samples/ControlCatalog/ViewModels/ViewModelBase.cs` | ソース | MVVMベースクラス（MiniMvvm） |
