# 機能設計書 20-ToolTip

## 概要

本ドキュメントは、Avalonia UIフレームワークにおけるToolTipコントロールの機能設計を記述する。ToolTipはコントロール上にマウスホバー時にヒントを表示するコントロールである。

### 本機能の処理概要

ToolTipは、ユーザーがコントロール上にマウスをホバーさせた際に、そのコントロールに関する補足情報や説明を表示するポップアップコントロールである。添付プロパティとして使用され、任意のコントロールにツールチップ機能を追加できる。

**業務上の目的・背景**：ユーザーインターフェースにおいて、ボタンやアイコンの機能説明、入力フィールドの入力ガイド、エラーメッセージの詳細など、補足情報を提供することはUX上重要である。ToolTipはこの目的を達成するための標準的なUIパターンを提供する。

**機能の利用シーン**：
- ボタンやアイコンの機能説明
- フォームフィールドの入力ヒント
- 省略されたテキストの全文表示
- 状態やエラーの詳細説明

**主要な処理内容**：
1. ホバー検出と表示遅延管理
2. Popup内でのコンテンツ表示
3. 配置位置の自動調整
4. 表示/非表示のタイミング制御（ShowDelay、BetweenShowDelay）
5. 無効化されたコントロールでの表示オプション

**関連システム・外部連携**：ContentControlを継承し、添付プロパティパターンで使用。ToolTipServiceと連携して表示タイミングを管理。

**権限による制御**：特になし。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 60 | ToolTip | 主画面 | ToolTipコントロールのデモ |

## 機能種別

表示コントロール / 補助情報表示

## 入力仕様

### 入力パラメータ（添付プロパティ）

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| ToolTip.Tip | object | No | ツールチップの内容 | - |
| ToolTip.IsOpen | bool | No | ツールチップの表示状態 | - |
| ToolTip.Placement | PlacementMode | No | 配置モード | デフォルト: Pointer |
| ToolTip.HorizontalOffset | double | No | 水平オフセット | デフォルト: 0 |
| ToolTip.VerticalOffset | double | No | 垂直オフセット | デフォルト: 20 |
| ToolTip.ShowDelay | int | No | 表示までの遅延（ミリ秒） | デフォルト: 400 |
| ToolTip.BetweenShowDelay | int | No | 連続表示時の遅延（ミリ秒） | デフォルト: 100 |
| ToolTip.ShowOnDisabled | bool | No | 無効化されたコントロールでも表示 | デフォルト: false |
| ToolTip.ServiceEnabled | bool | No | 自動表示サービスの有効化 | デフォルト: true |
| ToolTip.CustomPopupPlacementCallback | CustomPopupPlacementCallback | No | カスタム配置コールバック | - |

### 入力データソース

- ToolTip.Tipプロパティへのデータバインディング
- XAMLでの直接設定

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ToolTip.IsOpen | bool | ツールチップの表示状態 |

### 出力先

- ToolTipOpeningイベント：ツールチップ表示前（キャンセル可能）
- ToolTipClosingイベント：ツールチップ非表示時

## 処理フロー

### 処理シーケンス

```
1. ホバー検出
   └─ ToolTipServiceがマウス移動を監視
2. 遅延タイマー開始
   └─ ShowDelayまたはBetweenShowDelay経過待ち
3. ToolTipOpening イベント確認
   └─ キャンセルされなければ続行
4. IsOpen = true
   └─ Popup作成・表示
5. コンテンツ表示
   └─ Tip内容またはToolTipコントロールを表示
6. マウス離脱検出
   └─ ToolTipClosingイベント発火
7. IsOpen = false
   └─ Popup非表示
```

### フローチャート

```mermaid
flowchart TD
    A[マウスホバー] --> B{ServiceEnabled?}
    B -->|No| C[終了]
    B -->|Yes| D{Tipあり?}
    D -->|No| C
    D -->|Yes| E{ShowOnDisabled or Enabled?}
    E -->|No| C
    E -->|Yes| F[遅延タイマー開始]
    F --> G{前回表示から BetweenShowDelay内?}
    G -->|Yes| H[即時表示]
    G -->|No| I[ShowDelay待機]
    H --> J[ToolTipOpening]
    I --> J
    J --> K{キャンセル?}
    K -->|Yes| C
    K -->|No| L[IsOpen = true]
    L --> M[Popup表示]
    M --> N[マウス離脱待ち]
    N --> O[ToolTipClosing]
    O --> P[IsOpen = false]
    P --> Q[Popup非表示]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | 表示遅延 | ShowDelay（デフォルト400ms）経過後に表示 | 通常時 |
| BR-02 | 連続表示遅延 | 前回表示からBetweenShowDelay内なら即時表示 | 連続ホバー時 |
| BR-03 | 無効コントロール | ShowOnDisabled=trueの場合のみ無効コントロールで表示 | コントロール無効時 |
| BR-04 | Tip変更時の再生成 | Tip内容変更時はToolTipインスタンスを再生成 | Tip変更時 |
| BR-05 | 配置デフォルト | PlacementMode.Pointerがデフォルト | Placement未設定時 |

### 計算ロジック

VerticalOffsetのデフォルトは20ピクセルで、マウスカーソル下に表示される。

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

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

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

## エラー処理

### エラーケース一覧

特になし（表示専用コントロールのため）

### リトライ仕様

該当なし

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

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

## パフォーマンス要件

- ToolTipインスタンスは遅延生成
- Popupは再利用される

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

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

## 備考

- ToolTipは直接配置するとContentControlとして動作する
- 添付プロパティとして使用するのが一般的
- PseudoClass: :open
- TakesFocusFromNativeControl=false（フォーカスを奪わない）

---

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

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

### 推奨読解順序

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

ToolTipの添付プロパティを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | ToolTip.cs | `src/Avalonia.Controls/ToolTip.cs` | 添付プロパティ定義 |

**読解のコツ**: ToolTipは添付プロパティパターンで使用される。Tip、IsOpen、Placement等すべてが添付プロパティとして定義されている。

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

ToolTipクラス本体を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | ToolTip.cs | `src/Avalonia.Controls/ToolTip.cs` | ContentControl継承、添付プロパティ、Open/Close |

**主要処理フロー**:
1. **23行目**: ContentControl継承、IPopupHostProvider実装
2. **28-87行目**: 添付プロパティ定義（Tip, IsOpen, Placement, ShowDelay等）
3. **98-109行目**: ルーティドイベント定義（ToolTipOpening, ToolTipClosing）
4. **118-121行目**: 静的コンストラクタでIsOpenChanged購読
5. **351-390行目**: IsOpenChanged - 表示/非表示の処理
6. **403-430行目**: Open() - Popup作成・表示
7. **432-449行目**: Close() - Popup非表示

#### Step 3: サービス層を理解する

ToolTipServiceでのホバー検出と遅延管理。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | ToolTipService.cs | `src/Avalonia.Controls/ToolTipService.cs` | ホバー検出、遅延タイマー |

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

```
ToolTip（添付プロパティ）
    │
    ├─ ToolTip.TipProperty
    │      └─ ツールチップ内容
    │
    ├─ ToolTip.IsOpenProperty
    │      └─ 表示状態管理
    │
    ├─ ToolTipService
    │      ├─ ホバー検出
    │      ├─ ShowDelayタイマー
    │      └─ BetweenShowDelayタイマー
    │
    ├─ ToolTip（インスタンス）
    │      ├─ ContentControl
    │      └─ AdornedControl
    │
    └─ Popup (_popup)
           └─ ツールチップ表示
```

### データフロー図

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

マウスホバー ───▶ ToolTipService ───▶ 遅延タイマー
                        │
                        ▼
                    IsOpen = true
                        │
                        ▼
              ToolTipOpeningイベント
                        │
                        ▼
                    Open() ───▶ Popup表示
                        │
マウス離脱 ───▶ ToolTipClosingイベント
                        │
                        ▼
                    Close() ───▶ Popup非表示
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| ToolTip.cs | `src/Avalonia.Controls/ToolTip.cs` | ソース | ToolTipコントロール本体 |
| ToolTipService.cs | `src/Avalonia.Controls/ToolTipService.cs` | ソース | ホバー検出・遅延管理 |
| Popup.cs | `src/Avalonia.Controls/Primitives/Popup.cs` | ソース | ポップアップ表示 |
| ContentControl.cs | `src/Avalonia.Controls/ContentControl.cs` | ソース | 基底クラス |
