# 機能設計書 13-RadioButton

## 概要

本ドキュメントは、Avalonia UIフレームワークにおけるRadioButtonコントロールの機能設計を記述する。RadioButtonはグループ内で排他的に1つのオプションを選択するためのコントロールである。

### 本機能の処理概要

RadioButtonは、同じグループ内で1つだけ選択可能なトグルコントロールである。あるRadioButtonが選択されると、同じグループ内の他のRadioButtonは自動的に選択解除される。

**業務上の目的・背景**：アンケートや設定画面において、複数の選択肢から必ず1つを選ぶ必要がある場面は多い。性別選択、支払い方法の選択、配送オプションの選択など、排他的選択が必要なユースケースでRadioButtonが使用される。

**機能の利用シーン**：
- アンケートフォームでの選択肢
- 設定画面でのオプション選択
- 支払い方法・配送方法の選択
- モードの切り替え

**主要な処理内容**：
1. グループ内での排他的選択の管理
2. GroupNameプロパティによるグループ分け
3. クリックまたはキー操作による選択
4. 選択状態の永続化（一度選択すると再クリックでは解除されない）
5. UIオートメーション対応

**関連システム・外部連携**：ToggleButtonを継承し、RadioButtonGroupManagerによってグループ管理が行われる。IRadioButtonインターフェースを実装。

**権限による制御**：特になし。IsEnabledプロパティで有効/無効を制御可能。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 47 | RadioButton | 主画面 | RadioButtonコントロールのデモ。グループ内排他的選択 |
| 106 | RadioButton | テスト画面 | RadioButtonのテスト |

## 機能種別

入力コントロール / 排他的選択

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| IsChecked | bool? | No | 選択状態 | - |
| GroupName | string | No | グループ名（同一グループ内で排他的選択） | - |
| Content | object | No | ラベルとして表示するコンテンツ | - |
| IsEnabled | bool | No | コントロールが有効かどうか | デフォルト: true |

### 入力データソース

- IsCheckedプロパティへのデータバインディング
- XAMLでのプロパティ設定
- コードビハインドでの設定

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| IsChecked | bool? | 現在の選択状態 |

### 出力先

- IsCheckedChangedイベントによる状態変更通知
- プロパティバインディングによるViewModel更新

## 処理フロー

### 処理シーケンス

```
1. ユーザー操作（クリック/スペースキー）
   └─ OnClick()メソッド呼び出し
2. Toggle()メソッド実行
   └─ 未選択の場合のみ選択状態に変更
3. グループマネージャー通知
   └─ RadioButtonGroupManager.OnCheckedChanged()
4. 同グループの他ボタンを選択解除
   └─ 他のRadioButtonのIsCheckedをfalseに設定
5. イベント発火
   └─ IsCheckedChangedイベント
```

### フローチャート

```mermaid
flowchart TD
    A[ユーザークリック] --> B[OnClick]
    B --> C[Toggle]
    C --> D{IsChecked?}
    D -->|false/null| E[IsChecked = true]
    D -->|true| F[何もしない]
    E --> G[RadioButtonGroupManager通知]
    G --> H[同グループの他ボタン解除]
    H --> I[IsCheckedChanged発火]
    F --> J[終了]
    I --> J
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | 排他的選択 | 同一GroupName内で1つのみ選択可能 | 常時 |
| BR-02 | 選択維持 | 選択済みのRadioButtonをクリックしても解除されない | 常時 |
| BR-03 | グループ管理 | GroupName未設定の場合、ビジュアルルート単位でグループ化 | GroupName未設定時 |
| BR-04 | 視覚状態 | 選択時は:checkedクラスが適用される | 選択時 |

### 計算ロジック

Toggle()メソッドのロジック（RadioButton固有）：
```
if (!IsChecked.GetValueOrDefault()) {
    SetCurrentValue(IsCheckedProperty, true);
}
// 選択済みの場合は何もしない（CheckBoxとの違い）
```

## データベース操作仕様

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

該当なし（UIコントロール）

## エラー処理

### エラーケース一覧

特になし（シンプルな選択動作のため）

### リトライ仕様

該当なし

## トランザクション仕様

該当なし（UIコントロール）

## パフォーマンス要件

特になし（軽量なコントロール）

## セキュリティ考慮事項

特になし（UIコントロールとして汎用的に使用可能）

## 備考

- RadioButtonはToggleButtonを継承するが、Toggle()の動作が異なる（解除されない）
- 同じGroupNameを持つRadioButtonは自動的に排他的選択になる
- グループ管理はRadioButtonGroupManagerクラスが担当

---

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

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

### 推奨読解順序

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

RadioButtonの基盤となるインターフェースを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | IRadioButton.cs | `src/Avalonia.Controls/IRadioButton.cs` | RadioButton用インターフェース |

**読解のコツ**: IRadioButtonインターフェースはMenuItemとも共有されており、メニュー内でのラジオ選択動作にも使用される。

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

RadioButtonクラスの実装を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | RadioButton.cs | `src/Avalonia.Controls/RadioButton.cs` | GroupName、Toggle()のオーバーライド |

**主要処理フロー**:
1. **17行目**: ToggleButtonとIRadioButtonを継承
2. **22-23行目**: GroupNameプロパティ定義
3. **44-50行目**: Toggle() - 未選択時のみtrueに設定（CheckBoxとの違い）
4. **52-65行目**: OnAttachedToVisualTree/OnDetachedFromVisualTree - グループマネージャーへの登録/解除
5. **99-106行目**: IsCheckedChanged - グループマネージャーに選択変更を通知

#### Step 3: グループ管理を理解する

RadioButtonGroupManagerによる排他的選択の実装。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | RadioButtonGroupManager.cs | `src/Avalonia.Controls/RadioButtonGroupManager.cs` | グループ管理、排他的選択の実装 |

**主要処理フロー**:
- グループ内の他のRadioButtonをfalseに設定
- ビジュアルルート単位またはGroupName単位でグループを管理

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

```
RadioButton
    │
    ├─ ToggleButton (基底クラス)
    │      └─ OnClick()
    │
    ├─ Toggle() [オーバーライド]
    │      └─ 未選択時のみtrue設定
    │
    ├─ RadioButtonGroupManager
    │      ├─ Add() - ボタン登録
    │      ├─ Remove() - ボタン解除
    │      └─ OnCheckedChanged() - 排他的選択処理
    │
    └─ IRadioButton
           └─ グループ管理インターフェース
```

### データフロー図

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

クリック ───▶ OnClick() ───▶ Toggle()
                    │
                    ▼
              IsChecked = true
                    │
                    ▼
         RadioButtonGroupManager
                    │
                    ▼
         同グループの他ボタン解除 ───▶ 視覚的変化
                    │
                    ▼
         IsCheckedChanged ───▶ イベント通知
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| RadioButton.cs | `src/Avalonia.Controls/RadioButton.cs` | ソース | RadioButtonコントロール本体 |
| RadioButtonGroupManager.cs | `src/Avalonia.Controls/RadioButtonGroupManager.cs` | ソース | グループ管理クラス |
| ToggleButton.cs | `src/Avalonia.Controls/Primitives/ToggleButton.cs` | ソース | 基底クラス（トグル機能） |
| IRadioButton.cs | `src/Avalonia.Controls/IRadioButton.cs` | ソース | インターフェース定義 |
| RadioButtonAutomationPeer.cs | `src/Avalonia.Controls/Automation/Peers/RadioButtonAutomationPeer.cs` | ソース | UIオートメーション対応 |
