# 画面設計書 33-Focus

## 概要

本ドキュメントは、ControlCatalogサンプルアプリケーションのFocusページに関する画面設計書です。XYフォーカスナビゲーション機能のデモンストレーションを行うページです。

### 本画面の処理概要

Focusページは、Avaloniaフレームワークにおける空間的なフォーカスナビゲーション（XYフォーカス）の動作を確認するためのデモ画面です。ゲームコントローラーやリモコンなどの方向キーを使用したナビゲーション、およびキーボードの矢印キーによるフォーカス移動を学習・検証できます。

**業務上の目的・背景**：テレビやゲームコンソール向けアプリケーション、アクセシビリティ対応が必要なアプリケーションでは、マウスやタッチに頼らない方向キーベースのナビゲーションが重要です。XYフォーカスナビゲーションは、上下左右の方向入力に基づいて、最も適切な次のフォーカス対象を自動的に決定します。本画面は開発者がXYフォーカスの動作と設定オプションを確認するために提供されています。

**画面へのアクセス方法**：ControlCatalogアプリケーションのMainViewから、HamburgerMenuナビゲーションを使用して「Focus」を選択することでアクセスできます。

**主要な操作・処理内容**：
1. XYフォーカスナビゲーションモードの切り替え（Enabled/Disabled）
2. ナビゲーション戦略の選択（Projection/NavigationDirectionDistance/RectilinearDistance）
3. キーボード矢印キーによるボタン間のフォーカス移動の確認
4. Canvas上に配置されたボタン間での空間的なフォーカス遷移の確認

**画面遷移**：
- 遷移元：MainView（HamburgerMenuによるナビゲーション）
- 遷移先：なし（デモページのため他画面への遷移機能はなし）

**権限による表示制御**：特になし。すべてのユーザーが全機能を利用可能。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 50 | FocusManager | 主機能 | フォーカス管理のデモ。フォーカス移動とスコープ制御 |
| 56 | KeyboardNavigation | 補助機能 | Tabキーによるフォーカス移動制御 |

## 画面種別

デモ/サンプル画面

## URL/ルーティング

HamburgerMenuナビゲーション経由でアクセス（Avalonia UIフレームワークのページベースナビゲーション）

## 入出力項目

| 項目名 | 入力/出力 | 型 | 説明 |
|--------|----------|------|------|
| Navigation | 入力 | XYFocusNavigationModes | フォーカスナビゲーションモード（Enabled/Disabled） |
| NavigationStrategy | 入力 | XYFocusNavigationStrategy | ナビゲーション戦略の選択 |

## 表示項目

| 項目名 | 型 | 説明 |
|--------|------|------|
| Navigation ComboBox | ComboBox | XYFocusNavigationModesの選択（Enabled/Disabled） |
| NavigationStrategy ComboBox | ComboBox | ナビゲーション戦略の選択 |
| Button A | Button | Canvas上に配置されたボタン（Top=0, Left=50, 150x150） |
| Button B | Button | Canvas上に配置されたボタン（Top=200, Left=0, 50x50） |
| Button C | Button | Canvas上に配置されたボタン（Top=150, Left=400, 50x50） |
| Button D | Button | Canvas上に配置されたボタン（Top=300, Left=100, 50x50） |

## イベント仕様

### 1-XYフォーカスナビゲーション

矢印キーが押されると、XYフォーカスマネージャーが現在フォーカスされている要素から、指定された方向にある最も適切な次のフォーカス対象を決定します。ナビゲーション戦略によって、次のフォーカス対象の決定アルゴリズムが変わります。

### 2-ナビゲーションモード変更

KeyboardNavigation ComboBoxの選択が変更されると、TabRoot StackPanelのXYFocus.NavigationModesプロパティがバインディングにより更新され、XYフォーカスの有効/無効が切り替わります。

### 3-ナビゲーション戦略変更

NavigationStrategy ComboBoxの選択が変更されると、各ButtonのXYFocus.UpNavigationStrategy、XYFocus.DownNavigationStrategy、XYFocus.LeftNavigationStrategy、XYFocus.RightNavigationStrategyがスタイル経由で更新されます。

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

本画面はデモ画面のため、データベース操作は行いません。

## メッセージ仕様

本画面には固有のメッセージ表示はありません。

## 例外処理

本画面はデモ画面のため、特別な例外処理は実装されていません。

## 備考

- XYFocusNavigationModes: Enabled（有効）、Disabled（無効）
- XYFocusNavigationStrategy:
  - Projection: 投影ベースのアルゴリズム（方向の延長線上にある要素を優先）
  - NavigationDirectionDistance: 方向性と距離を考慮したアルゴリズム
  - RectilinearDistance: マンハッタン距離ベースのアルゴリズム
- Canvas上のボタン配置は、異なるナビゲーション戦略の違いを確認できるように意図的に配置されています

---

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

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

### 推奨読解順序

#### Step 1: UI定義を理解する

FocusPageはViewModelを持たないシンプルな構造で、XAMLでXYフォーカスナビゲーションの設定を行っています。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | FocusPage.xaml | `samples/ControlCatalog/Pages/FocusPage.xaml` | XYFocus関連の設定、Canvas上のボタン配置を理解 |

**読解のコツ**: XYFocus.NavigationModes、XYFocus.UpNavigationStrategy等の添付プロパティの使用方法を確認してください。スタイル（Style Selector="Button"）を使用して、全ボタンに対して一括でナビゲーション戦略を設定しています。

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

最小限のコードビハインドでXAMLの読み込みのみを行います。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | FocusPage.xaml.cs | `samples/ControlCatalog/Pages/FocusPage.xaml.cs` | AvaloniaXamlLoader.Loadによる初期化 |

**主要処理フロー**:
1. **行11**: AvaloniaXamlLoader.Load(this)でXAMLを読み込み

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

```
FocusPage (UserControl)
    |
    +-- FocusPage.xaml.cs (Code-behind)
    |       |
    |       +-- AvaloniaXamlLoader.Load(this)
    |
    +-- FocusPage.xaml (UI定義)
            |
            +-- TabControl
            |       +-- TabItem "XY Focus"
            |               +-- StackPanel (TabRoot)
            |                       +-- XYFocus.NavigationModes バインディング
            |                       +-- ComboBox (KeyboardNavigation)
            |                       +-- ComboBox (NavigationStrategy)
            |                       +-- Canvas (500x幅)
            |                               +-- Button A (150x150, Top=0, Left=50)
            |                               +-- Button B (50x50, Top=200, Left=0)
            |                               +-- Button C (50x50, Top=150, Left=400)
            |                               +-- Button D (50x50, Top=300, Left=100)
            |
            +-- Styles (Canvas.Styles)
                    +-- Style Selector="Button"
                            +-- XYFocus.UpNavigationStrategy
                            +-- XYFocus.DownNavigationStrategy
                            +-- XYFocus.LeftNavigationStrategy
                            +-- XYFocus.RightNavigationStrategy
```

### データフロー図

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

ComboBox選択変更 ─────> XYFocus.NavigationModes ─────> フォーカス動作変更
(Enabled/Disabled)              |
                                v
                        XYフォーカス有効/無効

ComboBox選択変更 ─────> XYFocus.*NavigationStrategy ─> ナビゲーション
(Strategy)                      |                       アルゴリズム変更
                                v
                        Projection/
                        NavigationDirectionDistance/
                        RectilinearDistance

矢印キー入力 ──────────> XYFocusManager ─────────────> 次のフォーカス
                                |                       対象を決定
                                v
                        ナビゲーション戦略に基づく
                        最適な要素を選択
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| FocusPage.xaml | `samples/ControlCatalog/Pages/FocusPage.xaml` | XAML | UI定義、XYフォーカス設定 |
| FocusPage.xaml.cs | `samples/ControlCatalog/Pages/FocusPage.xaml.cs` | ソース | コードビハインド（最小限） |
