# 画面設計書 59-ToolTip

## 概要

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

### 本画面の処理概要

本画面は、Avaloniaフレームワークが提供するToolTip機能を実演するデモページです。ToolTipは、コントロール上にマウスをホバーした際に表示されるヒント情報で、様々な配置オプション、カスタムコンテンツ、動的オフセット、無効化コントロールへの表示などの機能を確認できます。

**業務上の目的・背景**：ToolTipは、ユーザーインターフェースの使いやすさを向上させる重要な要素です。ボタン、アイコン、フォーム入力などに対して、操作のヒントや追加情報を提供できます。本デモページは、開発者がToolTipの配置（Placement）、表示制御（ServiceEnabled、IsOpen、ShowOnDisabled）、カスタムコンテンツ、動的オフセットアニメーション、カスタム配置コールバック、ネストされたToolTip、動的ToolTip変更などの高度な機能を理解し、適切に実装するための参考資料として機能します。

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

**主要な操作・処理内容**：
1. ToolTipサービスの有効/無効切り替え（ToggleSwitch）
2. ToolTipの強制表示/非表示切り替え（ToggleSwitch）
3. 基本ToolTip（テキスト）の表示確認
4. Bottom配置のToolTip（リッチコンテンツ）の表示確認
5. カスタム配置のToolTip（ランダムな配置）の表示確認
6. 動的オフセットアニメーションToolTipの表示確認
7. 無効化コントロール上のToolTip表示確認
8. ネストされたToolTip（外側/内側）の表示確認
9. ToolTipOpening イベントでの動的ToolTip変更の確認

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

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

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 20 | ToolTip | 主機能 | ToolTipのデモ。ホバー時の情報表示 |

## 画面種別

デモ / 機能確認

## URL/ルーティング

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

## 入出力項目

| 項目名 | 項目種別 | 入力/出力 | データ型 | 説明 |
|--------|----------|-----------|----------|------|
| ToolTip.ServiceEnabled | 添付プロパティ | 入出力 | bool | ToolTipサービスの有効/無効 |
| ToolTip.IsOpen | 添付プロパティ | 入出力 | bool | ToolTipの強制表示/非表示 |
| ToolTip.Tip | 添付プロパティ | 入力 | object | ToolTipコンテンツ |
| ToolTip.Placement | 添付プロパティ | 入力 | PlacementMode | ToolTip配置位置 |
| ToolTip.ShowOnDisabled | 添付プロパティ | 入力 | bool | 無効コントロールでの表示 |
| ToolTip.HorizontalOffset | 添付プロパティ | 入力 | double | 水平オフセット |
| ToolTip.VerticalOffset | 添付プロパティ | 入力 | double | 垂直オフセット |

## 表示項目

| 表示項目 | 説明 |
|----------|------|
| ページ説明 | "A control which pops up a hint when a control is hovered" |
| "Enable ToolTip service" ToggleSwitch | ToolTipサービスの有効/無効トグル |
| "ToolTip Open" ToggleSwitch | ToolTipの強制開閉トグル |
| 基本ToolTipエリア | "Hover Here"、ToolTip="This is a ToolTip" |
| Bottom配置ToolTipエリア | リッチコンテンツ（h1、h2テキスト） |
| カスタム配置ToolTipエリア | ランダムな位置に表示 |
| 動的オフセットToolTipエリア | アニメーションで位置が変化 |
| 無効ボタンToolTip | ShowOnDisabled=True |
| ネストToolTipエリア | 外側"Outer tooltip"、内側"Inner tooltip" |
| 動的変更ToolTipエリア | ToolTipOpening で変更 |

## イベント仕様

### 1-ToolTipサービス有効/無効

ServiceEnabled添付プロパティへのバインディングにより、ToggleSwitchの状態変更でToolTip機能全体の有効/無効が切り替わります。

### 2-ToolTip強制表示

IsOpen添付プロパティへのバインディングにより、ToggleSwitchの状態変更でBottom配置ToolTipの表示/非表示が強制的に制御されます。

### 3-CustomPlacementCallback

カスタム配置ToolTipでは、CustomPopupPlacementCallbackメソッドが呼び出され、ランダムなAnchor、Gravity、Offsetを設定します。

### 4-動的オフセットアニメーション

Style.Animationsを使用して、HorizontalOffsetとVerticalOffsetを0〜100の範囲で2秒間アニメーションさせます。

### 5-ToolTipOpening

動的変更ToolTipエリアでは、ToolTipOpeningイベントでToolTip.Tipプロパティを"New tip set from ToolTipOpening."に変更します。

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

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

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

## メッセージ仕様

| メッセージ種別 | メッセージ内容 | 表示条件 |
|----------------|----------------|----------|
| ToolTip | "This is a ToolTip" | 基本エリアホバー時 |
| ToolTip | "ToolTip" + "A control which pops up..." | Bottom配置エリアホバー時 |
| ToolTip | "Custom positioned tooltip" | カスタム配置エリアホバー時 |
| ToolTip | "Hello" | 動的オフセットエリアホバー時 |
| ToolTip | "This control is disabled" | 無効ボタンホバー時 |
| ToolTip | "Outer tooltip" / "Inner tooltip" | ネストエリアホバー時 |
| ToolTip | "New tip set from ToolTipOpening." | 動的変更エリアホバー時 |

## 例外処理

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

## 備考

- ToolTipはPopup内に表示されるため、ウィンドウ境界を超えて表示される場合があります
- ServiceEnabledをfalseにすると、ページ内のすべてのToolTipが無効になります
- ShowOnDisabled=Trueを設定すると、無効化されたコントロール上でもToolTipが表示されます
- ネストされたToolTipでは、最も具体的な（内側の）ToolTipが優先されます

---

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

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

### 推奨読解順序

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

ToolTipPageはコードビハインドでイベントハンドラとカスタム配置コールバックを実装しています。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | ToolTipPage.xaml.cs | `samples/ControlCatalog/Pages/ToolTipPage.xaml.cs` | ToolTipOpening、CustomPlacementCallbackメソッドを確認 |

**読解のコツ**: CustomPopupPlacementはPopupAnchorとPopupGravityを組み合わせて配置を決定します。ランダム値による動的配置のパターンを理解してください。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | ToolTipPage.xaml | `samples/ControlCatalog/Pages/ToolTipPage.xaml` | 各種ToolTip設定を確認 |
| 2-2 | ToolTipPage.xaml.cs | `samples/ControlCatalog/Pages/ToolTipPage.xaml.cs` | イベントハンドラを確認 |

**主要処理フロー**:
1. **行6**: ページ説明TextBlock
2. **行11-14**: ServiceEnabled ToggleSwitch - UserControlのToolTip.ServiceEnabledにバインド
3. **行15-18**: IsOpen ToggleSwitch - BorderのToolTip.IsOpenにバインド
4. **行19-24**: 基本ToolTip - ToolTip.Tip="This is a ToolTip"
5. **行25-37**: Bottom配置ToolTip - リッチコンテンツ（StackPanel内にh1、h2テキスト）
6. **行38-45**: カスタム配置ToolTip - Placement="Custom"、CustomPopupPlacementCallback
7. **行46-68**: 動的オフセットToolTip - Style.Animationsで位置アニメーション
8. **行70-76**: 無効ボタンToolTip - ShowOnDisabled="True"
9. **行78-83**: ネストToolTip - 外側Borderと内側TextBlock
10. **行85-91**: 動的変更ToolTip - ToolTipOpeningイベント

#### Step 3: コードビハインドのロジックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | ToolTipPage.xaml.cs | `samples/ControlCatalog/Pages/ToolTipPage.xaml.cs` | CustomPlacementCallbackの実装 |

**主要処理フロー**:
- **行16-18**: ToolTipOpening - ToolTip.TipProperty を動的に変更
- **行21-39**: CustomPlacementCallback - ランダムなAnchor、Gravity、Offsetを設定
  - **行23-31**: ランダム値でAnchorとGravityを選択（Top/Left/Right/Bottom）
  - **行39**: Offsetにランダム値を設定

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

```
MainView (HamburgerMenu)
    │
    └─ ToolTipPage (UserControl)
           │
           ├─ StackPanel (メインレイアウト)
           │      │
           │      ├─ TextBlock (ページ説明)
           │      │
           │      └─ UniformGrid (Columns=2)
           │             │
           │             ├─ ToggleSwitch (ServiceEnabled)
           │             │      └─ Binding ───▶ UserControl.ToolTip.ServiceEnabled
           │             │
           │             ├─ ToggleSwitch (IsOpen)
           │             │      └─ Binding ───▶ Border.ToolTip.IsOpen
           │             │
           │             ├─ Border (基本ToolTip)
           │             │      └─ ToolTip.Tip = "This is a ToolTip"
           │             │
           │             ├─ Border (Bottom配置)
           │             │      └─ ToolTip.Tip = StackPanel (h1, h2)
           │             │
           │             ├─ Border (カスタム配置)
           │             │      └─ CustomPopupPlacementCallback
           │             │
           │             ├─ Border (動的オフセット)
           │             │      └─ Style.Animations
           │             │
           │             ├─ Button (無効、ShowOnDisabled)
           │             │
           │             ├─ Border (ネストToolTip)
           │             │      ├─ Outer: "Outer tooltip"
           │             │      └─ Inner: "Inner tooltip"
           │             │
           │             └─ Border (動的変更)
           │                    └─ ToolTipOpening ───▶ ToolTipOpening()
           │
           └─ コードビハインド
                  ├─ ToolTipOpening()
                  └─ CustomPlacementCallback()
```

### データフロー図

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

マウスホバー ───▶ ToolTip.ServiceEnabled確認 ───▶ ToolTip表示
                        │
                        └──▶ Placement設定 ───▶ 配置計算

CustomPlacementCallback ───▶ Random.Next() ───▶ Anchor/Gravity/Offset決定
                                    │
                                    └──▶ ToolTip表示位置

ToolTipOpening ───▶ SetValue(ToolTip.TipProperty) ───▶ 新しいToolTip表示
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| ToolTipPage.xaml | `samples/ControlCatalog/Pages/ToolTipPage.xaml` | ソース | ページのXAML定義 |
| ToolTipPage.xaml.cs | `samples/ControlCatalog/Pages/ToolTipPage.xaml.cs` | ソース | コードビハインド、イベントハンドラ |
| ToolTip.cs | `src/Avalonia.Controls/ToolTip.cs` | フレームワーク | ToolTip添付プロパティ定義 |
| PopupPositioning.cs | `src/Avalonia.Controls/Primitives/PopupPositioning` | フレームワーク | Popup配置ロジック |
