# 機能設計書 12-CheckBox

## 概要

本ドキュメントは、Avalonia UIフレームワークにおけるCheckBoxコントロールの機能設計を記述する。CheckBoxはユーザーがオン・オフを切り替えることができるチェックボックスコントロールである。

### 本機能の処理概要

CheckBoxは、ユーザーがクリックやキー操作によって選択状態（チェック済み・未チェック・不定）を切り替えることができるトグルコントロールである。

**業務上の目的・背景**：フォーム入力において、ユーザーがオプションを選択/非選択できるようにする必要がある。CheckBoxは、利用規約への同意、オプション機能の有効化、複数選択肢からの複数選択など、様々なシナリオで使用される基本的な入力コントロールである。

**機能の利用シーン**：
- 設定画面でのオプション有効/無効の切り替え
- フォーム入力での同意確認
- 一覧画面での複数アイテム選択
- フィルター条件の設定

**主要な処理内容**：
1. クリックまたはスペースキーによる状態トグル
2. 2状態モード（チェック/未チェック）と3状態モード（チェック/未チェック/不定）のサポート
3. IsCheckedプロパティによる状態管理
4. ラベルテキストの表示
5. UIオートメーション対応

**関連システム・外部連携**：ToggleButtonを継承し、チェック状態のデータバインディングをサポート。MVVMパターンでのViewModelとの双方向バインディングが一般的。

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 16 | CheckBox | 主画面 | CheckBoxコントロールのデモ。3状態サポート |
| 96 | CheckBox | テスト画面 | CheckBoxのテスト |

## 機能種別

入力コントロール / 状態トグル

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| IsChecked | bool? | No | チェック状態（true=チェック済み、false=未チェック、null=不定） | - |
| IsThreeState | bool | No | 3状態モードを有効にするか | デフォルト: false |
| Content | object | No | ラベルとして表示するコンテンツ | - |
| IsEnabled | bool | No | コントロールが有効かどうか | デフォルト: true |

### 入力データソース

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

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| IsChecked | bool? | 現在のチェック状態 |

### 出力先

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

## 処理フロー

### 処理シーケンス

```
1. ユーザー操作（クリック/スペースキー）
   └─ OnClick()メソッド呼び出し
2. Toggle()メソッド実行
   └─ 現在の状態に応じて次の状態を決定
3. IsChecked更新
   └─ 新しい状態をプロパティに設定
4. 視覚的フィードバック
   └─ PseudoClassesの更新（:checked, :unchecked, :indeterminate）
5. イベント発火
   └─ IsCheckedChangedイベント
```

### フローチャート

```mermaid
flowchart TD
    A[ユーザークリック] --> B[OnClick]
    B --> C[Toggle]
    C --> D{現在の状態}
    D -->|true| E{IsThreeState?}
    D -->|false| F[IsChecked = true]
    D -->|null| G[IsChecked = false]
    E -->|true| H[IsChecked = null]
    E -->|false| I[IsChecked = false]
    F --> J[PseudoClasses更新]
    G --> J
    H --> J
    I --> J
    J --> K[IsCheckedChanged発火]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | 2状態トグル | IsThreeState=falseの場合、true→false→true | 2状態モード |
| BR-02 | 3状態トグル | IsThreeState=trueの場合、true→null→false→true | 3状態モード |
| BR-03 | 不定状態からの遷移 | nullからクリック時は常にfalseへ遷移 | 3状態モードで不定状態時 |

### 計算ロジック

Toggle()メソッドのロジック：
```
if (IsChecked.HasValue) {
    if (IsChecked.Value) {
        newValue = IsThreeState ? null : false
    } else {
        newValue = true
    }
} else {
    newValue = false
}
```

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

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

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

## エラー処理

### エラーケース一覧

特になし（シンプルなトグル動作のため）

### リトライ仕様

該当なし

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

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

## パフォーマンス要件

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

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

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

## 備考

- CheckBoxはToggleButtonを継承し、AutomationControlTypeをCheckBoxに上書きしている
- PseudoClasses（:checked, :unchecked, :indeterminate）を使用してスタイリング可能

---

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

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

### 推奨読解順序

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

CheckBoxの状態管理の基盤となるToggleButtonを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | ToggleButton.cs | `src/Avalonia.Controls/Primitives/ToggleButton.cs` | IsCheckedプロパティ、3状態トグルのロジック |

**読解のコツ**: ToggleButtonはButton→ContentControl→TemplatedControlの継承階層を持つ。IsCheckedはnull許容bool型（bool?）であり、3状態を表現できる。

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

CheckBoxクラス自体は非常にシンプル。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | CheckBox.cs | `src/Avalonia.Controls/CheckBox.cs` | ToggleButtonを継承し、オートメーション設定のみ |

**主要処理フロー**:
1. **10-16行目**: CheckBoxクラス全体（非常にシンプル）
2. **12-14行目**: 静的コンストラクタでAutomationControlTypeをCheckBoxに設定

#### Step 3: 基底クラスToggleButtonを理解する

実際のトグルロジックはToggleButtonに実装されている。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | ToggleButton.cs | `src/Avalonia.Controls/Primitives/ToggleButton.cs` | Toggle()メソッド、PseudoClasses更新 |

**主要処理フロー**:
- **19-21行目**: IsCheckedプロパティ定義（TwoWayバインディング）
- **26-27行目**: IsThreeStateプロパティ定義
- **73-77行目**: OnClick - クリック時にToggle()を呼び出し
- **82-109行目**: Toggle() - 状態遷移ロジック
- **138-143行目**: UpdatePseudoClasses - 視覚状態の更新

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

```
CheckBox
    │
    └─ ToggleButton (基底クラス)
           │
           ├─ Button (基底クラス)
           │      └─ OnClick()
           │
           ├─ IsCheckedProperty
           │      └─ 状態管理
           │
           ├─ Toggle()
           │      └─ 状態遷移ロジック
           │
           └─ UpdatePseudoClasses()
                  └─ :checked, :unchecked, :indeterminate
```

### データフロー図

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

クリック/スペース ───▶ OnClick() ───▶ Toggle()
                           │
                           ▼
                    状態遷移計算 ───▶ IsChecked更新
                           │
                           ▼
                    PseudoClasses更新 ───▶ 視覚的変化
                           │
                           ▼
                    IsCheckedChanged ───▶ イベント通知
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| CheckBox.cs | `src/Avalonia.Controls/CheckBox.cs` | ソース | CheckBoxコントロール本体 |
| ToggleButton.cs | `src/Avalonia.Controls/Primitives/ToggleButton.cs` | ソース | 基底クラス（トグル機能） |
| Button.cs | `src/Avalonia.Controls/Button.cs` | ソース | 基底クラス（クリック処理） |
| ContentControl.cs | `src/Avalonia.Controls/ContentControl.cs` | ソース | 基底クラス（コンテンツ表示） |
