# 機能設計書 157-BeginTooltip

## 概要

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

### 本機能の処理概要

BeginTooltipは、ツールチップウィンドウを開始・追加するための関数である。マウスカーソル付近にフローティングウィンドウを表示し、ユーザーに補足情報を提供する。通常はIsItemHovered()等と組み合わせて使用する。

**業務上の目的・背景**：GUIアプリケーションにおいて、ユーザーが要素にホバーした際に追加情報を表示する「ツールチップ」は広く使われるUIパターンである。BeginTooltipは、テキストだけでなく任意のウィジェットを含むリッチなツールチップを作成できる。Begin/End構文により、ツールチップ内に画像やボタンなど複雑なコンテンツを配置可能。

**機能の利用シーン**：アイテムがホバーされた際にヘルプテキストを表示する場合、ドラッグ&ドロップ操作中にプレビューを表示する場合、複雑な情報を持つ要素の詳細を表示する場合などに使用される。Popups画面などで使用される。

**主要な処理内容**：
1. BeginTooltipEx()を呼び出してツールチップを開始する
2. ドラッグ&ドロップ中は特別な位置設定と背景透明度を適用する
3. 以前のツールチップを上書きする場合は非表示にする
4. ツールチップウィンドウをBegin()で作成する

**関連システム・外部連携**：ImGuiのドラッグ&ドロップシステムと連携し、ドラッグ中のツールチップ表示をサポート。

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 25 | Popups | 補助機能 | ツールチップの開始 |

## 機能種別

ウィンドウ生成 / ユーザー情報表示

## 入力仕様

### 入力パラメータ

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

### 入力データソース

- ImGuiContext（グローバルコンテキスト）
- マウス位置（g.IO.MousePos）
- ドラッグ&ドロップ状態（g.DragDropWithinSource等）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 戻り値 | bool | 常にtrueを返す（将来の互換性のため） |

### 出力先

- ツールチップウィンドウ

## 処理フロー

### 処理シーケンス

```
1. BeginTooltipExへの委譲
   └─ BeginTooltipEx(ImGuiTooltipFlags_None, ImGuiWindowFlags_None)を呼び出し

2. ドラッグ&ドロップツールチップの検出
   └─ DragDropWithinSource または DragDropWithinTarget を確認
   └─ ドラッグ中の場合は特別処理

3. ドラッグ&ドロップ時の位置設定
   └─ タッチスクリーンとマウスで異なるオフセットを使用
   └─ SetNextWindowPosで位置を設定
   └─ 背景の透明度を60%に設定
   └─ OverridePreviousフラグを設定

4. 以前のツールチップの上書き
   └─ TooltipPreviousWindowが存在し、アクティブな場合
   └─ SetWindowHiddenAndSkipItemsForCurrentFrameで非表示に
   └─ TooltipOverrideCountをインクリメント

5. ウィンドウ名の生成
   └─ "##Tooltip_%02d" または "##Tooltip_DragDrop_%02d" 形式

6. ツールチップウィンドウの作成
   └─ Tooltip、NoInputs、NoTitleBar等のフラグを設定
   └─ Begin()で作成
   └─ 常にtrueを返す
```

### フローチャート

```mermaid
flowchart TD
    A[開始: BeginTooltip] --> B[BeginTooltipEx呼び出し]
    B --> C{ドラッグ&ドロップ中?}
    C -->|Yes| D[タッチ/マウス判定]
    D --> E[位置・ピボット設定]
    E --> F[背景透明度60%に設定]
    F --> G[OverridePreviousフラグ設定]
    C -->|No| H{OverridePrevious<br/>フラグあり?}
    G --> H
    H -->|Yes| I{TooltipPreviousWindow<br/>がアクティブ?}
    I -->|Yes| J[前のツールチップを非表示]
    J --> K[TooltipOverrideCount++]
    I -->|No| L[ウィンドウ名生成]
    H -->|No| L
    K --> L
    L --> M[ウィンドウフラグ設定]
    M --> N[Begin]
    N --> O[return true]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-157-01 | ペア呼び出し | BeginTooltipがtrueを返した場合はEndTooltipを呼び出す | 常時 |
| BR-157-02 | ドラッグオフセット | ドラッグ中は特別なオフセット位置を使用 | DragDrop中 |
| BR-157-03 | 上書き動作 | 同一フレーム内の複数ツールチップは上書き可能 | 常時 |
| BR-157-04 | 常にtrue | 現在の実装では常にtrueを返す | 常時 |

### 計算ロジック

- マウス用オフセット: `TOOLTIP_DEFAULT_OFFSET_MOUSE * g.Style.MouseCursorScale`
- タッチ用オフセット: `TOOLTIP_DEFAULT_OFFSET_TOUCH * g.Style.MouseCursorScale`
- ドラッグ時背景透明度: `g.Style.Colors[ImGuiCol_PopupBg].w * 0.60f`

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | - | - | 現在の実装ではエラーケースなし |

### リトライ仕様

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

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

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

## パフォーマンス要件

- 単一フレーム内で複数回呼び出し可能
- 軽量なウィンドウ作成処理

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

- 特になし

## 備考

- SetTooltipはBeginTooltip + Text + EndTooltipの省略形
- ツールチップウィンドウは自動リサイズされる
- ドラッグ&ドロップ中のツールチップは通常のツールチップと別管理される

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | imgui.h | `imgui.h` | 822行目: BeginTooltip API宣言を確認 |
| 1-2 | imgui.h | `imgui.h` | ImGuiWindowFlags_Tooltipを確認 |
| 1-3 | imgui_internal.h | `imgui_internal.h` | ImGuiTooltipFlagsの定義を確認 |

**読解のコツ**: BeginTooltipは内部でBeginTooltipExを呼び出す薄いラッパー。実際のロジックはBeginTooltipExにある。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | imgui.cpp | `imgui.cpp` | 11952-11955行目: BeginTooltip関数 |
| 2-2 | imgui.cpp | `imgui.cpp` | 11964-12009行目: BeginTooltipEx関数の実装 |

**主要処理フロー**:
1. **11968-11988行目**: ドラッグ&ドロップツールチップの処理
2. **11990-11996行目**: 以前のツールチップの上書き処理
3. **11998-12002行目**: ウィンドウ名生成とBegin呼び出し
4. **12008行目**: 常にtrueを返す

#### Step 3: ドラッグ&ドロップ連携を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | imgui.cpp | `imgui.cpp` | 11968-11988行目: ドラッグ中の特別処理 |

**主要処理フロー**:
- **11977行目**: タッチスクリーンかマウスかの判定
- **11980-11982行目**: 位置とピボットの設定
- **11985行目**: 背景透明度の設定

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

```
ImGui::BeginTooltip()
    │
    └─ BeginTooltipEx(ImGuiTooltipFlags_None, ImGuiWindowFlags_None)
           │
           ├─ [ドラッグ&ドロップ中の処理]
           │      ├─ SetNextWindowPos()
           │      └─ SetNextWindowBgAlpha()
           │
           ├─ [OverridePrevious処理]
           │      └─ SetWindowHiddenAndSkipItemsForCurrentFrame()
           │
           ├─ ImFormatString()
           │      └─ ウィンドウ名を生成
           │
           └─ Begin()
                  └─ ツールチップウィンドウを作成
```

### データフロー図

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

g.DragDropWithinSource ───> ドラッグ判定 ─────────────────> is_dragdrop_tooltip
g.DragDropWithinTarget
                                  │
g.IO.MousePos ────────────────> 位置計算 ─────────────────> SetNextWindowPos
g.IO.MouseSource                  │
                                  │
g.Style.Colors[PopupBg] ──────> 透明度設定 ────────────────> SetNextWindowBgAlpha
                                  │
g.TooltipOverrideCount ───────> ウィンドウ名生成 ───────────> "##Tooltip_XX"
                                  │
                                  └──────────────────────────> Begin() ─> ツールチップウィンドウ
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| imgui.h | `imgui.h` | ヘッダー | BeginTooltip APIの宣言 |
| imgui_internal.h | `imgui_internal.h` | ヘッダー | ImGuiTooltipFlags等の内部定義 |
| imgui.cpp | `imgui.cpp` | ソース | BeginTooltip実装（11952-11955行目）、BeginTooltipEx実装（11964-12009行目） |
