# 画面設計書 55-TextBox

## 概要

本ドキュメントは、AvaloniaフレームワークのControlCatalogサンプルアプリケーションにおけるTextBoxデモページの画面設計書です。TextBoxコントロールの各種機能と設定オプションを網羅的にデモンストレーションします。

### 本画面の処理概要

本画面は、Avaloniaフレームワークが提供するTextBoxコントロールの多彩な機能を実演するデモページです。テキスト入力、プレースホルダー、バリデーション、フォントカスタマイズ、マルチライン対応など、TextBoxの主要な機能を確認できます。

**業務上の目的・背景**：TextBoxはフォーム入力の基本コンポーネントであり、ユーザー名、パスワード、検索クエリ、コメントなど、あらゆるテキスト入力に使用されます。本デモページは、開発者がTextBoxの多様なプロパティ設定（ReadOnly、PlaceholderText、PasswordChar、TextWrapping、MaskedTextBox等）を理解し、適切なUXを実装するための参考資料として機能します。特にフローティングプレースホルダー、カスタム選択ブラシ、IME設定など、高度なカスタマイズオプションを学ぶことができます。

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

**主要な操作・処理内容**：
1. 基本的なテキスト入力とカスタムフォント表示（Comic Sans MS、青文字）
2. ReadOnlyプロパティによる読み取り専用TextBoxの確認
3. NumericコンテンツタイプによるNumeric入力モードの体験
4. フローティングプレースホルダー（UseFloatingPlaceholder）の動作確認
5. カスタムプレースホルダー色（PlaceholderForeground）の設定
6. MaskedTextBoxによる入力形式制御（電話番号形式）
7. バリデーションエラー表示の確認
8. パスワード入力モード（PasswordChar、Classes="revealPasswordButton"）
9. テキスト配置（Left/Center/Right）の確認
10. カスタム選択ブラシとキャレット色の設定
11. マルチラインTextBoxとTextWrappingの動作確認
12. カスタムフォント（Source Sans Pro）の各スタイル表示
13. IME設定（InputMethod.IsInputMethodEnabled）の確認
14. 中国語テキストの入力と表示

**画面遷移**：HamburgerMenuから他のデモページへ遷移可能。本ページからの特別な遷移先はありません。

**権限による表示制御**：本デモページでは権限による表示制御は実装されていません。すべての機能がすべてのユーザーに公開されます。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 7 | TextBox | 主機能 | TextBoxコントロールのデモ。テキスト入力、マルチライン、マスク付き |
| 29 | MaskedTextBox | 補助機能 | マスク付きテキストボックスの入力形式制御 |

## 画面種別

デモ / 機能確認

## URL/ルーティング

ControlCatalogアプリケーション内のHamburgerMenuナビゲーションによるページ遷移（直接URLなし）

## 入出力項目

| 項目名 | 項目種別 | 入力/出力 | データ型 | 説明 |
|--------|----------|-----------|----------|------|
| Text | プロパティ | 入出力 | string | テキストボックスのテキスト内容 |
| PlaceholderText | プロパティ | 入力 | string | プレースホルダーテキスト |
| IsReadOnly | プロパティ | 入力 | bool | 読み取り専用フラグ |
| UseFloatingPlaceholder | プロパティ | 入力 | bool | フローティングプレースホルダー有効化 |
| PasswordChar | プロパティ | 入力 | char | パスワード文字 |
| AcceptsReturn | プロパティ | 入力 | bool | マルチライン許可 |
| TextWrapping | プロパティ | 入力 | TextWrapping | テキスト折り返し |
| TextAlignment | プロパティ | 入力 | TextAlignment | テキスト配置 |
| Mask | プロパティ | 入力 | string | MaskedTextBoxのマスクパターン |

## 表示項目

| 表示項目 | 説明 |
|----------|------|
| ページ説明ラベル | "A control into which the user can input text" |
| 基本TextBox（カスタムフォント） | Comic Sans MS、青文字、カスタムContextFlyout |
| ReadOnly TextBox | 読み取り専用テキストボックス |
| Numeric TextBox | 数値入力モード |
| フローティングプレースホルダーTextBox | UseFloatingPlaceholder=True |
| カスタムプレースホルダー色TextBox | PlaceholderForeground=Red/Purple |
| MaskedTextBox | 電話番号形式マスク "(LLL) 999-0000" |
| バリデーションエラーTextBox | DataValidationErrors.Error表示 |
| パスワードTextBox | revealPasswordButtonクラス、PasswordChar="*" |
| 配置サンプルTextBox | Left/Center/Right配置 |
| カスタム選択ブラシTextBox | SelectionBrush=Green |
| カスタムキャレットTextBox | CaretBrush=DarkOrange |
| マルチラインTextBox | AcceptsReturn=True、TextWrapping有無 |
| ClearButtonTextBox | Classes="clearButton" |
| IMEサンプルTextBox | small/large font、IME無効 |
| LineHeight設定TextBox | LineHeight=32 |
| Source Sans Proフォント（res_m） | カスタムフォント各スタイル |
| Source Sans Proフォント（res） | カスタムフォント各スタイル |
| 中国語TextBox | WenQuanYi Micro Heiフォント |

## イベント仕様

### 1-テキスト入力

ユーザーがテキストを入力すると、Textプロパティが更新されます。IMEが有効な場合は、変換候補が表示されます。

### 2-ContextFlyout表示

最初のTextBox（Comic Sans MS）では、右クリックでカスタムContextFlyout（"Custom context flyout"テキスト）が表示されます。

### 3-ClearButton押下

Classes="clearButton"のTextBoxでは、クリアボタンが表示され、クリックでテキストがクリアされます。

### 4-RevealPasswordButton押下

Classes="revealPasswordButton"のパスワードTextBoxでは、パスワード表示/非表示の切り替えボタンが表示されます。

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

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

本画面はUIデモのため、データベース操作は発生しません。

## メッセージ仕様

| メッセージ種別 | メッセージ内容 | 表示条件 |
|----------------|----------------|----------|
| バリデーションエラー | （視覚的エラー表示） | DataValidationErrors.Error設定時 |
| ContextFlyout | "Custom context flyout" | 最初のTextBoxで右クリック時 |

## 例外処理

本画面はデモ用途のため、特別な例外処理は実装されていません。DataValidationErrors.Errorは固定的に設定されたUIデモです。

## 備考

- MaskedTextBoxのマスク形式："L"は必須英字、"9"は任意数字、"0"は必須数字を表します
- avares://およびresm:スキームでカスタムフォントを読み込めます
- TextInputOptions.ContentTypeでIMEの入力モードを制御できます（Number、Password等）
- ClearSelectionOnLostFocus="False"でフォーカス喪失時も選択を保持できます

---

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

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

### 推奨読解順序

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

TextBoxPageはシンプルな構成で、ViewModelを使用せず、すべてのプロパティがXAMLで直接設定されています。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | TextBox.cs | `src/Avalonia.Controls/TextBox.cs` | TextBoxの主要プロパティを確認 |
| 1-2 | MaskedTextBox.cs | `src/Avalonia.Controls/MaskedTextBox.cs` | マスク機能の理解 |

**読解のコツ**: TextBoxは多くのプロパティを持つため、まずXAMLで使用されているプロパティに注目して読み進めてください。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | TextBoxPage.xaml | `samples/ControlCatalog/Pages/TextBoxPage.xaml` | 各種TextBoxの設定を確認 |
| 2-2 | TextBoxPage.xaml.cs | `samples/ControlCatalog/Pages/TextBoxPage.xaml.cs` | InitializeComponent()のみの最小実装 |

**主要処理フロー**:
1. **行6**: ページ説明ラベル
2. **行11-19**: カスタムフォント・色・ContextFlyout付きTextBox
3. **行20**: ReadOnly TextBox
4. **行21**: Numeric入力モードTextBox
5. **行22-32**: フローティングプレースホルダー・カスタムプレースホルダー色
6. **行33**: MaskedTextBox（電話番号形式）
7. **行35-39**: バリデーションエラーTextBox
8. **行41-47**: パスワードTextBox（revealPasswordButton）
9. **行49-55**: 配置サンプル・カスタム選択ブラシ・キャレット色
10. **行59-62**: マルチラインTextBox
11. **行64-76**: ClearButton・IMEサンプル
12. **行84-98**: カスタムフォント（res_m/res）
13. **行100-102**: 中国語TextBox

#### Step 3: スタイルとテンプレートを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | TextBox.xaml（Fluent） | `src/Avalonia.Themes.Fluent/Controls/TextBox.xaml` | ClearButtonとRevealPasswordButtonのスタイル定義 |

**主要処理フロー**:
- Classes="clearButton": TextBoxにクリアボタンを追加
- Classes="revealPasswordButton": パスワード表示/非表示ボタンを追加

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

```
MainView (HamburgerMenu)
    │
    └─ TextBoxPage (UserControl)
           │
           ├─ StackPanel (メインレイアウト)
           │      │
           │      ├─ Label (ページ説明)
           │      │
           │      └─ WrapPanel (TextBoxグリッド)
           │             │
           │             ├─ StackPanel (列1: 基本機能)
           │             │      ├─ TextBox (カスタムフォント)
           │             │      ├─ TextBox (ReadOnly)
           │             │      ├─ TextBox (Numeric)
           │             │      ├─ TextBox (フローティングPH)
           │             │      ├─ MaskedTextBox
           │             │      ├─ TextBox (Validation)
           │             │      ├─ TextBox (Password)
           │             │      └─ TextBox (配置/選択)
           │             │
           │             ├─ StackPanel (列2: マルチライン/IME)
           │             │
           │             ├─ StackPanel (列3: res_mフォント)
           │             │
           │             └─ StackPanel (列4: resフォント)
           │
           └─ TextBox (中国語・全幅)
```

### データフロー図

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

キーボード入力 ───▶ TextBox.OnKeyDown ───▶ Text更新
                         │
                         └──▶ IME処理 ───▶ 変換候補表示

MaskedTextBox入力 ───▶ Mask適用 ───▶ フォーマット済みText
                         │
                         └──▶ 不正入力拒否

PasswordChar設定 ───▶ TextPresenter ───▶ マスク文字表示
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| TextBoxPage.xaml | `samples/ControlCatalog/Pages/TextBoxPage.xaml` | ソース | ページのXAML定義 |
| TextBoxPage.xaml.cs | `samples/ControlCatalog/Pages/TextBoxPage.xaml.cs` | ソース | コードビハインド |
| TextBox.cs | `src/Avalonia.Controls/TextBox.cs` | フレームワーク | TextBoxコントロール本体 |
| MaskedTextBox.cs | `src/Avalonia.Controls/MaskedTextBox.cs` | フレームワーク | MaskedTextBoxコントロール |
| SourceSansPro-*.ttf | `samples/ControlCatalog/Assets/Fonts/` | リソース | カスタムフォントファイル |
| WenQuanYi*.ttf | `samples/ControlCatalog/Assets/Fonts/` | リソース | 中国語フォントファイル |
