# 画面設計書 18-ColorPicker

## 概要

本ドキュメントは、ControlCatalogアプリケーションにおけるColorPickerページ（カラーピッカーコントロールのデモページ）の画面設計を記述したものである。

### 本画面の処理概要

ColorPickerページはAvaloniaフレームワークのカラー関連コントロール（ColorView、ColorPicker、ColorSpectrum、ColorSlider、ColorPreviewer）の機能をデモンストレーションするための画面である。HLS/RGB/HSV形式での色指定、カラースペクトラムによる視覚的な色選択、スライダーによる各成分の調整などを確認できる。

**業務上の目的・背景**：グラフィックエディター、テーマカスタマイズ、デザインツールなど、ユーザーが色を選択する必要があるアプリケーションを開発する開発者に対して、各種カラーピッカーコントロールの使用方法とカスタマイズ方法を示す。

**画面へのアクセス方法**：MainWindow起動後、左側のHamburgerMenuから「ColorPicker」を選択してアクセスする。

**主要な操作・処理内容**：
1. ColorViewによるリング型カラースペクトラムでの色選択
2. ColorPickerのポップアップによる色選択
3. ColorSpectrumによる2次元カラースペースでの色選択
4. ColorSliderによるHSVA各成分の調整
5. ColorPreviewerによる選択色のプレビュー表示

**画面遷移**：MainViewのHamburgerMenuから遷移してくる。本画面から他画面への直接遷移はない。

**権限による表示制御**：本画面はデモ用途であり、権限による表示制御は実装されていない。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 31 | ColorPicker | 主機能 | カラーピッカーコントロールのデモ。HLS/RGB/HSV形式での色指定 |

## 画面種別

デモ・サンプル画面（カラーピッカーコントロールの機能展示）

## URL/ルーティング

ControlCatalogアプリケーション内のHamburgerMenuによるナビゲーション。URIベースのルーティングは使用していない。

## 入出力項目

| 項目名 | 種別 | データ型 | 必須 | 説明 |
|--------|------|----------|------|------|
| HsvColor | 入出力 | HsvColor | - | HSV形式の色値 |
| Color | 出力 | Color | - | RGB形式の色値 |

## 表示項目

| 要素 | コントロール | 説明 |
|------|--------------|------|
| ColorView (リング型) | ColorView | ColorSpectrumShape="Ring"のカラービュー |
| ColorPicker (Palette付き) | ColorPicker | FlatHalfColorPaletteを使用 |
| ColorPicker (小) | ColorPicker | Width=150の小型バージョン |
| ColorPicker (カスタムContent) | ColorPicker | Contentに選択色のテキスト表示 |
| ColorPicker (コード追加) | ColorPicker | コードビハインドで追加、MaterialHalfColorPalette使用 |
| ColorSpectrum | ColorSpectrum | 2次元カラースペース（256x256） |
| ColorSlider (Hue) | ColorSlider | Component1（色相）スライダー |
| ColorSlider (Saturation) | ColorSlider | Component2（彩度）スライダー |
| ColorSlider (Value) | ColorSlider | Component3（明度）スライダー |
| ColorSlider (Alpha) | ColorSlider | Alpha（透明度）スライダー |
| ColorPreviewer | ColorPreviewer | 選択色のプレビュー表示 |

## イベント仕様

### 1-ColorSpectrum 色選択

ColorSpectrumで色を選択すると、バインドされたColorSliderとColorPreviewerが更新される。

**処理フロー**:
1. ユーザーがColorSpectrumをクリック/ドラッグ
2. HsvColorプロパティが更新される
3. ElementName=ColorSpectrum1でバインドされた各ColorSliderのHsvColorが更新
4. 各スライダーの表示が更新
5. ColorPreviewerのプレビュー色が更新

**関連XAML** (ColorPickerPage.xaml:91-95):
```xml
<ColorSlider Grid.Row="1"
             Margin="0,10,0,0"
             ColorComponent="Component1"
             ColorModel="Hsva"
             HsvColor="{Binding HsvColor, ElementName=ColorSpectrum1}" />
```

### 2-ColorSlider 値変更

ColorSliderを操作すると、バインドされた他のコントロールが更新される。

**処理フロー**:
1. ユーザーがスライダーをドラッグ
2. HsvColorの該当成分が更新
3. 双方向バインディングによりColorSpectrumとColorPreviewerが更新

### 3-ColorPicker カスタムContent

ColorPickerのContentに選択色のテキストを表示するデモ。

**処理フロー**:
1. ColorPickerで色を選択
2. Colorプロパティが更新
3. バインディング`{Binding $parent[ColorPicker].Color}`でTextBlockが更新
4. ColorToBrushConverterでForegroundも選択色に更新

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

本画面はUIデモ用途であり、データベース操作は行わない。

## メッセージ仕様

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

## 例外処理

本画面では特別な例外処理は実装されていない。

## 備考

- ColorViewはColorSpectrumShape="Ring"でリング型の色選択UI
- ColorSliderのColorModelはHsva（HSV+Alpha）を使用
- ColorToBrushConverterでColorをBrushに変換して使用
- コードビハインドでMaterialHalfColorPaletteを使用したColorPickerを追加
- Thumbのカスタムテーマ（ColorSliderThumbTheme）を定義

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | ColorPickerPage.xaml | `samples/ControlCatalog/Pages/ColorPickerPage.xaml` | HsvColor型とバインディング構造 |

**読解のコツ**: HsvColorはHue（色相）、Saturation（彩度）、Value（明度）、Alpha（透明度）を持つ構造体。hsv(120, 1, 1)のような初期値指定が可能。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | ColorPickerPage.xaml.cs | `samples/ControlCatalog/Pages/ColorPickerPage.xaml.cs` | コードからのColorPicker追加 |

**主要処理フロー**:
1. **行12-13**: InitializeComponent()
2. **行15-21**: コードからColorPickerを作成
   - Color = Colors.Blue
   - Palette = new MaterialHalfColorPalette()
3. **行22-23**: Grid.SetColumn/Row
4. **行25**: LayoutRoot.Children.Add()

#### Step 3: XAML構造を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | ColorPickerPage.xaml | `samples/ControlCatalog/Pages/ColorPickerPage.xaml` | Grid構造とコントロール配置 |

**主要処理フロー**:
- **行12-14**: リソース定義（ColorToBrushConverter）
- **行16-18**: Grid定義（2列構成）
- **行19-21**: ColorView（リング型）
- **行22-44**: StackPanelに3つのColorPicker
- **行46-126**: 右側グリッド（ColorSpectrum、ColorSlider、ColorPreviewer）
- **行49-82**: ColorSliderのカスタムThumb定義（ColorSliderThumbTheme）
- **行84-89**: ColorSpectrum
- **行90-107**: 4つのColorSlider（H, S, V, Alpha）
- **行122-125**: ColorPreviewer

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

```
ColorPickerPage
    │
    ├─ InitializeComponent()
    │      └─ XAML解析・コントロール初期化
    │
    └─ コンストラクタ内処理
           ├─ new ColorPicker()
           │      ├─ Color = Colors.Blue
           │      ├─ Palette = MaterialHalfColorPalette
           │      └─ HorizontalAlignment.Center
           │
           ├─ Grid.SetColumn(colorPicker, 2)
           ├─ Grid.SetRow(colorPicker, 1)
           └─ LayoutRoot.Children.Add(colorPicker)
```

### データフロー図

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

ColorSpectrum.Click ───▶ HsvColor更新 ───▶ ColorSlider.HsvColor
                                     ───▶ ColorPreviewer.HsvColor

ColorSlider.Drag ───▶ HsvColor成分更新 ───▶ ColorSpectrum.HsvColor
                                       ───▶ ColorPreviewer.HsvColor

ColorPicker選択 ───▶ Color更新 ───▶ TextBlock.Text（ColorToBrushConverter経由）
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| ColorPickerPage.xaml | `samples/ControlCatalog/Pages/ColorPickerPage.xaml` | XAML | 画面レイアウト・カラーコントロール定義 |
| ColorPickerPage.xaml.cs | `samples/ControlCatalog/Pages/ColorPickerPage.xaml.cs` | ソース | コードビハインド・追加ColorPicker作成 |
| MainView.xaml | `samples/ControlCatalog/MainView.xaml` | XAML | ナビゲーション元のメインビュー |
