# 画面設計書 85-Playground

## 概要

本ドキュメントは、VirtualizationDemoアプリケーションにおけるPlayground（プレイグラウンド）ページの画面設計について記載します。

### 本画面の処理概要

このページは、Avaloniaフレームワークの仮想化ListBox機能を包括的にテストするためのプレイグラウンドです。1000件のアイテムを持つリストに対して、選択モード（Multiple/Toggle/AlwaysSelected）の切り替え、アイテムへのスクロール、新規アイテムの追加・削除など、様々な操作を試すことができます。また、リアルタイムで仮想化コンテナの実現数を表示し、仮想化の効果を可視化します。

**業務上の目的・背景**：
開発者がAvaloniaのListBox仮想化機能の動作を理解し、大量データを扱うアプリケーションのパフォーマンス最適化を学ぶことを目的としています。SelectionModeの各種設定、アイテム操作、スクロール制御など、実際のアプリケーション開発で必要となる機能を網羅的に試すことができます。

**画面へのアクセス方法**：
VirtualizationDemoアプリケーションを起動後、メインウィンドウのHamburgerMenuから「Playground」タブを選択することでアクセスできます。

**主要な操作・処理内容**：
1. ListBoxで1000件のアイテムを仮想化表示
2. SelectionドロップダウンでMultiple/Toggle/AlwaysSelected/AutoScrollToSelectedItem/WrapSelectionを切り替え
3. ScrollToIndexテキストボックスでインデックス指定のスクロール
4. ランダム化ボタンでランダムなインデックスを設定
5. 新規アイテムの追加（選択位置に挿入）
6. 選択アイテムの削除
7. 500ms間隔で実現コンテナ数を表示更新

**画面遷移**：
- 遷移元：VirtualizationDemo MainWindow（HamburgerMenuナビゲーション）
- 遷移先：なし（同一ウィンドウ内の他タブへはHamburgerMenu経由）

**権限による表示制御**：
特に権限による表示制御はありません。デモ用途のため全ての機能が常に利用可能です。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 41 | VirtualizingStackPanel | 主機能 | 1000件アイテムの仮想化表示、実現コンテナ数の監視 |
| 9 | ListBox | 補助機能 | アイテム選択、SelectionMode切り替え |

## 画面種別

デモ / インタラクティブ

## URL/ルーティング

HamburgerMenuナビゲーション: "Playground"タブ

## 入出力項目

| 項目名 | 入出力 | 型 | 初期値 | 説明 |
|--------|--------|-----|--------|------|
| Multiple | 入力 | bool | true | 複数選択を許可 |
| Toggle | 入力 | bool | false | トグル選択を有効化 |
| AlwaysSelected | 入力 | bool | false | 常に1つ以上選択 |
| AutoScrollToSelectedItem | 入力 | bool | - | 選択時に自動スクロール |
| WrapSelection | 入力 | bool | - | 選択のラップを有効化 |
| ScrollToIndex | 入力 | int | 500 | スクロール先インデックス |
| NewItemHeader | 入力 | string | "New Item 1" | 追加アイテムのヘッダー |
| 実現コンテナ数 | 出力 | string | - | "Realized X of Y"形式で表示 |

## 表示項目

| 項目名 | データ型 | 説明 |
|--------|----------|------|
| ListBox | ListBox | 仮想化された1000件のアイテムリスト |
| SelectionドロップダウンFlyout | Flyout | 選択モード設定用のチェックボックス群 |
| Select Itemラベル | Label | スクロール先インデックス入力フィールドのラベル |
| ScrollToIndexテキストボックス | TextBox | スクロール先インデックスの入力 |
| ランダム化ボタン | Button | ScrollToIndexをランダム値に設定 |
| 実行ボタン | Button | 指定インデックスへスクロール |
| New Itemラベル | Label | 新規アイテムヘッダー入力フィールドのラベル |
| NewItemHeaderテキストボックス | TextBox | 追加アイテムのヘッダー入力 |
| 追加ボタン | Button | 選択位置にアイテムを追加 |
| Delete Selectedボタン | Button | 選択アイテムを削除 |
| itemCountテキストブロック | TextBlock | 実現コンテナ数を表示 |

## イベント仕様

### 1-コンストラクタ

ページ初期化時に発生するイベントです。

- **トリガー**：ページのコンストラクタ呼び出し時
- **処理内容**：
  1. InitializeComponent()でXAMLリソースを読み込み
  2. DispatcherTimerを500ms間隔で設定

### 2-OnAttachedToVisualTree

ページがビジュアルツリーにアタッチされた際のイベントです。

- **トリガー**：ページがビジュアルツリーに追加されたとき
- **処理内容**：
  1. _timer.Start()でタイマーを開始
  2. 500ms間隔でTimerTickが実行される

### 3-OnDetachedFromVisualTree

ページがビジュアルツリーからデタッチされた際のイベントです。

- **トリガー**：ページがビジュアルツリーから削除されたとき
- **処理内容**：
  1. _timer.Stop()でタイマーを停止

### 4-TimerTick

タイマーイベントで実現コンテナ数を更新します。

- **トリガー**：500msごと
- **処理内容**：
  1. list.GetRealizedContainers().Count()で実現コンテナ数を取得
  2. list.ItemsPanelRoot?.Children.Countで全子要素数を取得
  3. "Realized X of Y"形式でitemCount.Textを更新

### 5-ExecuteScrollToIndex

指定インデックスへスクロールするコマンドです。

- **トリガー**：実行ボタン押下
- **処理内容**：
  1. Selection.Select(ScrollToIndex)で指定インデックスを選択
  2. AutoScrollToSelectedItemが有効なら自動スクロール

### 6-RandomizeScrollToIndex

ランダムインデックスを設定するコマンドです。

- **トリガー**：ランダム化ボタン押下
- **処理内容**：
  1. Random.Next(Items.Count)でランダムな値を生成
  2. ScrollToIndexプロパティを更新

### 7-AddAtSelectedIndex

選択位置にアイテムを追加するコマンドです。

- **トリガー**：追加ボタン押下
- **処理内容**：
  1. Selection.SelectedIndexが-1でないことを確認
  2. Items.Insert(Selection.SelectedIndex, new(NewItemHeader))で挿入

### 8-DeleteSelectedItem

選択アイテムを削除するコマンドです。

- **トリガー**：Delete Selectedボタン押下
- **処理内容**：
  1. Selection.Countで選択数を取得
  2. 降順でItems.RemoveAt(Selection.SelectedIndexes[i])を実行

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

本画面はデータベースを使用しません。

## メッセージ仕様

| メッセージ種別 | 表示内容 | 表示タイミング |
|--------------|----------|---------------|
| 情報 | "Realized X of Y" | 500ms間隔で更新 |

## 例外処理

| 例外状況 | 処理内容 |
|----------|----------|
| 選択なしでAddAtSelectedIndex | 早期リターン（何もしない） |

## 備考

- SelectionModel<T>を使用した高度な選択管理
- ObservableCollectionによるリアクティブなコレクション操作
- VirtualizingStackPanelの効果を実現コンテナ数で可視化

---

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

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

### 推奨読解順序

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

ViewModelとItemViewModelの構造を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | PlaygroundPageViewModel.cs | `samples/VirtualizationDemo/ViewModels/PlaygroundPageViewModel.cs` | 行1-95で全体構造を確認 |
| 1-2 | PlaygroundItemViewModel.cs | `samples/VirtualizationDemo/ViewModels/PlaygroundItemViewModel.cs` | 行1-17でアイテムモデルを確認 |

**読解のコツ**: SelectionModel<PlaygroundItemViewModel>は複雑な選択ロジックをカプセル化しています。

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

コードビハインドでのタイマー処理を確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | PlaygroundPageView.axaml.cs | `samples/VirtualizationDemo/Views/PlaygroundPageView.axaml.cs` | 行1-44で全体を確認 |

**主要処理フロー**:
- **行15-17**: コンストラクタでInitializeComponentとDispatcherTimer設定
- **行19-25**: DispatcherTimerを500msで設定
- **行27-31**: OnAttachedToVisualTreeでタイマー開始
- **行39-43**: TimerTickで実現コンテナ数を取得・表示

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

ListBoxとコントロールパネルの構造を確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | PlaygroundPageView.axaml | `samples/VirtualizationDemo/Views/PlaygroundPageView.axaml` | 行1-66で全体を確認 |

**主要処理フロー**:
- **行9-23**: Selectionドロップダウン（5つのCheckBox）
- **行25-43**: ScrollToIndex入力と実行ボタン
- **行45-51**: NewItemHeader入力と追加ボタン
- **行60-64**: ListBox（Items、Selection、SelectionModeバインディング）

#### Step 4: ViewModelのコマンドを理解する

各操作のビジネスロジックを確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | PlaygroundPageViewModel.cs | `samples/VirtualizationDemo/ViewModels/PlaygroundPageViewModel.cs` | 行63-94でコマンドを確認 |

**主要処理フロー**:
- **行63-66**: ExecuteScrollToIndex（Selection.Selectを呼び出し）
- **行68-72**: RandomizeScrollToIndex（Randomで値生成）
- **行74-79**: AddAtSelectedIndex（Insert処理）
- **行81-86**: DeleteSelectedItem（降順でRemoveAt）

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

```
PlaygroundPageView (UserControl)
    │
    ├─ コンストラクタ
    │      ├─ InitializeComponent()
    │      └─ DispatcherTimer設定 (500ms)
    │
    ├─ OnAttachedToVisualTree
    │      └─ _timer.Start()
    │
    ├─ OnDetachedFromVisualTree
    │      └─ _timer.Stop()
    │
    ├─ TimerTick
    │      └─ itemCount.Text = "Realized X of Y"
    │
    └─ PlaygroundPageViewModel (DataContext)
           │
           ├─ Items (ObservableCollection<PlaygroundItemViewModel>)
           │      └─ 初期化: 0-999の1000件
           │
           ├─ Selection (SelectionModel<PlaygroundItemViewModel>)
           │
           ├─ SelectionMode (SelectionMode)
           │      └─ Multiple/Toggle/AlwaysSelected
           │
           ├─ ExecuteScrollToIndex()
           │      └─ Selection.Select(ScrollToIndex)
           │
           ├─ RandomizeScrollToIndex()
           │      └─ ScrollToIndex = Random.Next(Items.Count)
           │
           ├─ AddAtSelectedIndex()
           │      └─ Items.Insert(Selection.SelectedIndex, ...)
           │
           └─ DeleteSelectedItem()
                  └─ Items.RemoveAt(Selection.SelectedIndexes[i])
```

### データフロー図

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

ユーザー操作     ─▶ ViewModel更新            ─▶ ListBox表示更新
                        │
                        ▼
                   ObservableCollection
                        │
                        ├─▶ Insert/RemoveAt     ─▶ アイテム変更
                        │
                        └─▶ Selection.Select   ─▶ 選択変更
                        │
                        ▼
タイマーTick     ─▶ GetRealizedContainers()  ─▶ 実現数表示
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| PlaygroundPageView.axaml | `samples/VirtualizationDemo/Views/PlaygroundPageView.axaml` | テンプレート | プレイグラウンドページのUIレイアウト |
| PlaygroundPageView.axaml.cs | `samples/VirtualizationDemo/Views/PlaygroundPageView.axaml.cs` | ソース | タイマー処理、実現コンテナ数表示 |
| PlaygroundPageViewModel.cs | `samples/VirtualizationDemo/ViewModels/PlaygroundPageViewModel.cs` | ソース | ListBoxのデータと操作ロジック |
| PlaygroundItemViewModel.cs | `samples/VirtualizationDemo/ViewModels/PlaygroundItemViewModel.cs` | ソース | リストアイテムのViewModel |
| MainWindow.axaml | `samples/VirtualizationDemo/MainWindow.axaml` | テンプレート | HamburgerMenuナビゲーションを提供 |
