# 画面設計書 23-Cursor

## 概要

本ドキュメントは、Avalonia ControlCatalogサンプルアプリケーションにおけるCursorデモページの画面設計を定義するものです。

### 本画面の処理概要

本画面は、Cursor（マウスカーソル）コントロールの各種使用パターンをデモンストレーションするためのページです。標準カーソルの全種類とカスタムカーソルの実装方法を、開発者が学習・検証できる環境を提供します。

**業務上の目的・背景**：カーソルは、ユーザーに対してコントロールの状態や可能な操作を視覚的に伝える重要なUI要素です。例えば、リサイズ可能な領域では矢印カーソル、テキスト入力可能な領域ではIビームカーソル、リンク上ではハンドカーソルを表示することで、ユーザーは直感的に操作方法を理解できます。カスタムカーソルを使用することで、アプリケーション固有の操作を示すことも可能です。

**画面へのアクセス方法**：ControlCatalogアプリケーションのメインウィンドウから、HamburgerMenuのナビゲーションで「Cursor」を選択することでアクセスできます。

**主要な操作・処理内容**：
1. StandardCursorType列挙体の全種類をリスト表示
2. リスト項目にマウスオーバーすると、対応するカーソルに変化
3. カスタムビットマップカーソルのデモンストレーション

**画面遷移**：MainViewからHamburgerMenuナビゲーションを通じて遷移。画面内での追加遷移なし。

**権限による表示制御**：特になし（サンプルアプリケーション）

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 52 | MouseDevice | 主機能 | カーソル設定のデモ。マウスカーソルスタイル変更 |

## 画面種別

デモ / サンプル表示

## URL/ルーティング

HamburgerMenu内部ナビゲーション（直接URLルーティングなし）

## 入出力項目

本画面には入力項目はありません。表示専用のデモページです。

## 表示項目

| 項目名 | データ型 | 説明 |
|--------|----------|------|
| 説明テキスト | string | 「Defines a cursor (mouse pointer)」 |
| 標準カーソルリスト | ListBox | StandardCursorType列挙体の全値をリスト表示 |
| Custom Cursorボタン | Button | カスタムビットマップカーソルのデモ用ボタン |

## イベント仕様

### 1-標準カーソルリスト項目へのマウスオーバー

ListBoxItemにマウスポインターを移動すると、Cursor属性にバインドされたカーソルが表示される。StandardCursorTypeの各値（Arrow、Ibeam、Wait、Cross、UpArrow、SizeWestEast、SizeNorthSouth、SizeAll、No、Hand、AppStarting、Help、TopSide、BottomSide、LeftSide、RightSide、TopLeftCorner、TopRightCorner、BottomLeftCorner、BottomRightCorner、DragMove、DragCopy、DragLink、None）に対応するカーソルが適用される。

### 2-Custom Cursorボタンへのマウスオーバー

ボタンにマウスポインターを移動すると、ViewModelで生成されたカスタムビットマップカーソル（avalonia-32.pngを使用）が表示される。ホットスポットは(16, 16)に設定。

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

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

本画面はUIコントロールのデモであり、データベース操作は行いません。

## メッセージ仕様

本画面にはメッセージ表示機能はありません。

## 例外処理

- カスタムカーソル画像のロード失敗時は例外がスローされる可能性あり

## 備考

- StandardCursorTypeはEnum.GetValuesで動的に取得される
- カスタムカーソルはBitmapとPixelPointのホットスポットで生成される
- プラットフォームによってカーソルの見た目が異なる場合がある

---

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

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

### 推奨読解順序

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

まず、カーソル情報を表現するViewModelの構造を理解することが重要です。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | CursorPageViewModel.cs | `samples/ControlCatalog/ViewModels/CursorPageViewModel.cs` | StandardCursorsコレクション、CustomCursorプロパティの定義（行12-28） |
| 1-2 | StandardCursorModel.cs | `samples/ControlCatalog/ViewModels/CursorPageViewModel.cs` | StandardCursorModelクラス（行31-42）、TypeとCursorプロパティ |

**読解のコツ**: StandardCursorTypeはAvalonia.Inputネームスペースに定義されている列挙体で、プラットフォーム共通のカーソル種類を表します。

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

処理の起点となるUserControlとXAMLレイアウトを特定します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | CursorPage.xaml | `samples/ControlCatalog/Pages/CursorPage.xaml` | Grid構造、ListBoxのItemsSourceバインディング、Cursorプロパティのバインディング |

**主要処理フロー**:
1. **行6**: 2列のGridレイアウト定義
2. **行11-22**: 標準カーソルリストのListBox定義
3. **行13-16**: ListBoxItem.Cursorへのバインディングスタイル
4. **行17-21**: ItemTemplate定義（カーソルタイプ名の表示）
5. **行24-28**: カスタムカーソルボタン定義

#### Step 3: コードビハインドを理解する

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | CursorPage.xaml.cs | `samples/ControlCatalog/Pages/CursorPage.xaml.cs` | コンストラクタでのDataContext設定 |

**主要処理フロー**:
- **行8-12**: コンストラクタでCursorPageViewModelをDataContextに設定

#### Step 4: ViewModelの実装を理解する

カーソル生成ロジックを確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | CursorPageViewModel.cs | `samples/ControlCatalog/ViewModels/CursorPageViewModel.cs` | Enum.GetValuesによる標準カーソル列挙、Bitmapからのカスタムカーソル生成 |

**主要処理フロー**:
- **行14-19**: コンストラクタでStandardCursorType全値をStandardCursorModelリストに変換
- **行21-23**: avalonia-32.pngからBitmapを読み込み、ホットスポット(16,16)でCursorを生成
- **行33-37**: StandardCursorModelコンストラクタでStandardCursorTypeからCursorを生成

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

```
CursorPage (UserControl)
    │
    ├─ コンストラクタ
    │      └─ CursorPageViewModel生成 → DataContext設定
    │
    └─ CursorPageViewModel
           │
           ├─ StandardCursors (コレクション)
           │      └─ Enum.GetValues(StandardCursorType)
           │             └─ StandardCursorModel生成
           │                    └─ new Cursor(StandardCursorType)
           │
           └─ CustomCursor
                  ├─ AssetLoader.Open() → Bitmap読み込み
                  └─ new Cursor(Bitmap, PixelPoint)
```

### データフロー図

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

列挙体定義 ──────────▶ Enum.GetValues ─────────────▶ StandardCursorModel群
                              │
                              └─ new Cursor(type)

画像ファイル ─────────▶ AssetLoader.Open ──────────▶ Bitmap
                              │
                              └─ new Cursor(bitmap, hotspot) ──▶ CustomCursor

マウス移動 ────────────▶ Cursorプロパティ参照 ────────▶ カーソル表示変更
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| CursorPage.xaml | `samples/ControlCatalog/Pages/CursorPage.xaml` | XAML | 画面レイアウト定義 |
| CursorPage.xaml.cs | `samples/ControlCatalog/Pages/CursorPage.xaml.cs` | ソース | コードビハインド |
| CursorPageViewModel.cs | `samples/ControlCatalog/ViewModels/CursorPageViewModel.cs` | ソース | カーソルデータとロジック |
| avalonia-32.png | `samples/ControlCatalog/Assets/avalonia-32.png` | アセット | カスタムカーソル画像 |
