# 機能設計書 161-SetItemTooltip

## 概要

本ドキュメントは、Dear ImGuiライブラリにおける `SetItemTooltip` 関数の機能設計書である。この関数は、直前に描画されたアイテムがホバーされている場合にテキストのみのツールチップを表示するためのヘルパー関数である。

### 本機能の処理概要

`SetItemTooltip`は、ImGuiウィジェットにツールチップを簡単に追加するための便利な関数である。直前のアイテムがマウスでホバーされているかを自動的に判定し、ホバー状態であればフォーマット文字列を使用してツールチップテキストを表示する。

**業務上の目的・背景**：GUIアプリケーションにおいて、ユーザーにウィジェットの追加情報や操作説明を提供することは、使いやすさ（ユーザビリティ）の向上に不可欠である。ツールチップは、画面スペースを占有せずに補足情報を表示できる効果的な手段であり、特にボタンやアイコン、略語などに対して詳細な説明を提供する場面で重宝される。`SetItemTooltip`は、この一般的なパターンを1行で実装できるようにすることで、開発者の生産性を向上させる。

**機能の利用シーン**：
- ボタンやメニューアイテムに対する操作説明の表示
- 設定項目の詳細な説明の提供
- 略称や専門用語の補足説明
- 入力フィールドの入力規則や形式の案内
- デバッグ情報やステータス情報の表示

**主要な処理内容**：
1. 直前のアイテムがホバー状態かどうかを`IsItemHovered(ImGuiHoveredFlags_ForTooltip)`で判定
2. ホバー状態であれば、`SetTooltipV`を呼び出してフォーマット済みテキストのツールチップを表示
3. フォーマット文字列はprintf形式の書式指定子をサポート

**関連システム・外部連携**：この関数は内部的に以下の関数と連携する。
- `IsItemHovered()`: アイテムのホバー状態判定
- `SetTooltip()` / `SetTooltipV()`: 実際のツールチップ表示処理

**権限による制御**：なし。すべてのコンテキストで使用可能。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | 全画面共通 | 補助機能 | 任意のウィジェット後にツールチップを追加 |

## 機能種別

UI表示補助機能（ツールチップ表示）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| fmt | const char* | Yes | ツールチップに表示するフォーマット文字列 | NULLポインタ禁止 |
| ... | 可変引数 | No | フォーマット文字列に対応する引数 | フォーマット指定子と型の一致が必要 |

### 入力データソース

- 呼び出し元コードから直接提供されるフォーマット文字列と引数
- 内部的に`g.LastItemData`（直前のアイテム情報）を参照

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| (戻り値なし) | void | この関数は戻り値を持たない |

### 出力先

- 画面上にツールチップウィンドウとして表示
- 描画データはImDrawListに追加される

## 処理フロー

### 処理シーケンス

```
1. 可変引数リストの初期化
   └─ va_start(args, fmt)でva_listを初期化
2. ホバー状態の判定
   └─ IsItemHovered(ImGuiHoveredFlags_ForTooltip)を呼び出し
   └─ ForTooltipフラグによりstyle.HoverFlagsForTooltipMouse/Navが適用される
3. ツールチップ表示（条件付き）
   └─ ホバー状態の場合、SetTooltipV(fmt, args)を呼び出し
4. 可変引数リストの終了処理
   └─ va_end(args)でクリーンアップ
```

### フローチャート

```mermaid
flowchart TD
    A[SetItemTooltip開始] --> B[va_listを初期化]
    B --> C{IsItemHovered?}
    C -->|Yes| D[SetTooltipV呼び出し]
    C -->|No| E[何もしない]
    D --> F[va_listを終了]
    E --> F
    F --> G[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-161-01 | ホバー遅延 | マウス使用時、デフォルトでDelayShortが適用され、即座にツールチップは表示されない | マウス入力使用時 |
| BR-161-02 | ナビゲーション遅延 | キーボード/ゲームパッド使用時、DelayNormalが適用される | ナビゲーション入力使用時 |
| BR-161-03 | 上書き動作 | 同一フレーム内で複数回呼び出された場合、最後の呼び出しが有効となる | 複数回呼び出し時 |

### 計算ロジック

特になし。

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

該当なし（データベース操作は行わない）。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 未定義動作 | フォーマット文字列がNULL | 呼び出し側でNULLチェックを行う |
| - | 未定義動作 | フォーマット指定子と引数の不一致 | 呼び出し側で正しい引数を渡す |

### リトライ仕様

リトライ不要（即時処理完了）。

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

該当なし。

## パフォーマンス要件

- 処理時間: 即時（1ms未満）
- ホバー判定は内部キャッシュされた`g.LastItemData`を参照するため軽量

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

- フォーマット文字列脆弱性に注意（ユーザー入力を直接fmtに渡さない）
- 機密情報をツールチップに表示する場合は画面キャプチャに注意

## 備考

- `BeginItemTooltip()`との違い: `SetItemTooltip`はテキストのみ、`BeginItemTooltip`は任意のウィジェットを含むツールチップを作成可能
- `ImGuiHoveredFlags_ForTooltip`は`style.HoverFlagsForTooltipMouse`または`style.HoverFlagsForTooltipNav`にマッピングされる
- デフォルトのマウス用フラグ: `ImGuiHoveredFlags_Stationary | ImGuiHoveredFlags_DelayShort | ImGuiHoveredFlags_AllowWhenDisabled`

---

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

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

### 推奨読解順序

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

まず、ツールチップ表示に関連するスタイル設定を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | imgui.h | `imgui.h` | ImGuiStyle構造体のHoverFlagsForTooltipMouse/Nav設定 |

**読解のコツ**: `ImGuiHoveredFlags_ForTooltip`がスタイル設定にマッピングされる仕組みを理解する。

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

`SetItemTooltip`関数の実装を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | imgui.cpp | `imgui.cpp` | SetItemTooltip関数の実装（12035-12042行目） |

**主要処理フロー**:
1. **12035-12036行目**: 関数シグネチャと可変引数の定義
2. **12037-12038行目**: va_listの初期化
3. **12039-12040行目**: IsItemHoveredによる条件判定とSetTooltipV呼び出し
4. **12041行目**: va_listの終了処理

#### Step 3: 依存関数を理解する

ツールチップの実際の表示処理を追跡する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | imgui.cpp | `imgui.cpp` | SetTooltipV関数の実装 |
| 3-2 | imgui.cpp | `imgui.cpp` | IsItemHovered関数のForTooltipフラグ処理 |

**主要処理フロー**:
- IsItemHoveredでImGuiHoveredFlags_ForTooltipが指定されると、入力タイプに応じてHoverFlagsForTooltipMouse/Navが適用される

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

```
SetItemTooltip(fmt, ...)
    │
    ├─ va_start(args, fmt)
    │
    ├─ IsItemHovered(ImGuiHoveredFlags_ForTooltip)
    │      └─ スタイル設定からホバーフラグを解決
    │
    ├─ SetTooltipV(fmt, args)  [条件付き]
    │      ├─ BeginTooltipEx()
    │      │      └─ ツールチップウィンドウを開始
    │      ├─ TextV(fmt, args)
    │      │      └─ フォーマット済みテキストを表示
    │      └─ EndTooltip()
    │             └─ ツールチップウィンドウを終了
    │
    └─ va_end(args)
```

### データフロー図

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

fmt (文字列)   ───▶ SetItemTooltip()   ───▶ ツールチップウィンドウ
... (可変引数)       │                        （画面上に描画）
                     ├─ ホバー判定
                     │   └─ g.LastItemData参照
                     │
                     └─ SetTooltipV()
                         └─ ImDrawListに描画コマンド追加
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| imgui.h | `imgui.h` | ヘッダ | 関数宣言、ImGuiHoveredFlags定義 |
| imgui.cpp | `imgui.cpp` | ソース | SetItemTooltip/SetItemTooltipV実装 |
| imgui_internal.h | `imgui_internal.h` | 内部ヘッダ | 内部データ構造定義 |
| imgui_demo.cpp | `imgui_demo.cpp` | デモ | 使用例（891行目、3970行目等） |
