# 機能設計書 160-BeginItemTooltip

## 概要

本ドキュメントはImGuiのBeginItemTooltip機能について、その処理内容、入出力仕様、実装詳細を記述した機能設計書である。

### 本機能の処理概要

BeginItemTooltipは、直前のアイテムがホバーされている場合にツールチップウィンドウを開始するためのショートカット関数である。「IsItemHovered(ImGuiHoveredFlags_ForTooltip) && BeginTooltip()」というイディオムを1関数で実現する。

**業務上の目的・背景**：ツールチップの最も一般的な使用パターンは「直前のアイテムがホバーされた場合にツールチップを表示する」というものである。BeginItemTooltipは、このパターンを簡潔に記述できるようにするヘルパー関数である。ImGuiHoveredFlags_ForTooltipフラグを自動的に適用するため、適切な遅延やホバー判定が行われる。

**機能の利用シーン**：ボタン、入力フィールド、リストアイテムなど、任意のウィジェットにリッチなツールチップ（テキスト以外のコンテンツを含む）を付ける場合に使用される。

**主要な処理内容**：
1. IsItemHovered(ImGuiHoveredFlags_ForTooltip)で直前のアイテムがホバーされているか確認する
2. ホバーされていない場合はfalseを返す
3. ホバーされている場合はBeginTooltipEx()を呼び出してツールチップを開始する

**関連システム・外部連携**：IsItemHovered、BeginTooltipExと連携。ImGuiIO::HoverFlagsForTooltipMouse/Navの設定を使用。

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | BeginItemTooltipは特定の画面に紐づかず、汎用的に使用される |

## 機能種別

ヘルパー関数 / ウィンドウ生成

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| (なし) | void | - | パラメータなし | - |

### 入力データソース

- 直前のアイテムのホバー状態（g.LastItemData）
- ImGuiIO（HoverFlagsForTooltipMouse/HoverFlagsForTooltipNav）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 戻り値 | bool | 直前のアイテムがホバーされており、ツールチップが開始された場合true |

### 出力先

- ツールチップウィンドウ（trueを返した場合）

## 処理フロー

### 処理シーケンス

```
1. ホバー状態の確認
   └─ IsItemHovered(ImGuiHoveredFlags_ForTooltip)を呼び出し
   └─ falseの場合はfalseを返す

2. ツールチップの開始
   └─ BeginTooltipEx(None, None)を呼び出し
   └─ 結果を返す
```

### フローチャート

```mermaid
flowchart TD
    A[開始: BeginItemTooltip] --> B[IsItemHovered<br/>ForTooltip]
    B --> C{ホバー中?}
    C -->|No| D[return false]
    C -->|Yes| E[BeginTooltipEx]
    E --> F[return true]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-160-01 | ペア呼び出し | 戻り値がtrueの場合はEndTooltipを呼び出す | 常時 |
| BR-160-02 | ForTooltipフラグ | 自動的にImGuiHoveredFlags_ForTooltipを適用 | 常時 |
| BR-160-03 | 直前アイテム | 直前に配置されたアイテムのホバー状態を確認 | 常時 |

### 計算ロジック

- ImGuiHoveredFlags_ForTooltipは、マウス使用時はHoverFlagsForTooltipMouse、キーボード/ゲームパッド使用時はHoverFlagsForTooltipNavの設定を使用する
- デフォルトでは、マウス使用時にImGuiHoveredFlags_Stationary | ImGuiHoveredFlags_DelayShortが適用される

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

データベース操作なし（UI描画のみ）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | falseリターン | 直前のアイテムがホバーされていない | 何もしない |

### リトライ仕様

リトライ不要（フレームごとに再実行）

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

トランザクション管理なし（即時描画）

## パフォーマンス要件

- 単一フレーム内で複数回呼び出し可能
- ホバー判定とウィンドウ作成のみのため軽量

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

- 特になし

## 備考

- SetItemTooltipは「IsItemHovered(ForTooltip) + SetTooltip」のショートカット（テキストのみ）
- BeginItemTooltipは「IsItemHovered(ForTooltip) + BeginTooltip」のショートカット（リッチコンテンツ対応）
- ForTooltipフラグにより適切な遅延（DelayShort）とホバー判定（Stationary）が適用される

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | imgui.h | `imgui.h` | 831行目: BeginItemTooltip API宣言を確認 |
| 1-2 | imgui.h | `imgui.h` | ImGuiHoveredFlags_ForTooltipの定義を確認 |
| 1-3 | imgui.h | `imgui.h` | ImGuiIO::HoverFlagsForTooltipMouse/Navを確認 |

**読解のコツ**: BeginItemTooltipは非常にシンプルな関数。ForTooltipフラグの動作を理解することが重要。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | imgui.cpp | `imgui.cpp` | 11957-11962行目: BeginItemTooltip関数の実装 |

**主要処理フロー**:
1. **11959行目**: IsItemHovered(ImGuiHoveredFlags_ForTooltip)を呼び出し
2. **11960行目**: falseの場合はfalseを返す
3. **11961行目**: BeginTooltipExを呼び出して結果を返す

#### Step 3: ForTooltipフラグの動作を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | imgui.h | `imgui.h` | ImGuiHoveredFlags_ForTooltipの定義とコメント |
| 3-2 | imgui.h | `imgui.h` | ImGuiIO::HoverFlagsForTooltipMouse/Navのデフォルト値 |

**主要処理フロー**:
- ForTooltipは入力方式（マウス/キーボード）に応じて適切なホバーフラグを適用
- マウス使用時: Stationary + DelayShortがデフォルト

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

```
ImGui::BeginItemTooltip()
    │
    ├─ IsItemHovered(ImGuiHoveredFlags_ForTooltip)
    │      │
    │      └─ 直前のアイテムがホバーされているか確認
    │         （ForTooltipフラグにより適切な遅延を適用）
    │
    └─ BeginTooltipEx(None, None) [ホバー中の場合]
           └─ ツールチップウィンドウを開始
```

### データフロー図

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

g.LastItemData ───────────> IsItemHovered
g.IO.HoverFlagsForTooltipMouse/Nav  │
                                  │
                                  ├─ [ホバーなし] ───────────> return false
                                  │
                                  └─ [ホバーあり]
                                        │
                                        ▼
                                  BeginTooltipEx
                                        │
                                        └──────────────────────> ツールチップウィンドウ
                                                                 return true
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| imgui.h | `imgui.h` | ヘッダー | BeginItemTooltip APIの宣言、ImGuiHoveredFlags_ForTooltipの定義 |
| imgui.cpp | `imgui.cpp` | ソース | BeginItemTooltip実装（11957-11962行目） |
