# 機能設計書 159-SetTooltip

## 概要

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

### 本機能の処理概要

SetTooltipは、テキストのみのツールチップを簡単に設定するためのヘルパー関数である。BeginTooltip + Text + EndTooltipの組み合わせを1行で実現する。以前に設定されたツールチップを上書きする動作をする。

**業務上の目的・背景**：ツールチップは最も一般的なユーザー情報表示手段であり、多くの場合は単純なテキストメッセージで十分である。SetTooltipは、このような一般的なケースを簡潔に記述できるようにするヘルパー関数である。IsItemHovered() + SetTooltip()のパターンで、アイテムホバー時のツールチップを簡単に実装できる。

**機能の利用シーン**：アイテムがホバーされた際にヘルプテキストを表示する場合、ボタンや入力フィールドの説明を表示する場合などに使用される。

**主要な処理内容**：
1. BeginTooltipEx()をOverridePreviousフラグ付きで呼び出す
2. TextV()でフォーマット済みテキストを表示する
3. EndTooltip()でツールチップを終了する

**関連システム・外部連携**：IsItemHovered()と組み合わせて使用することが多い。

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

## 関連画面

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

## 機能種別

ヘルパー関数 / ユーザー情報表示

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| fmt | const char* | Yes | printf形式のフォーマット文字列 | NULL終端文字列 |
| ... | 可変引数 | No | フォーマット引数 | フォーマット文字列に対応 |

### 入力データソース

- 呼び出し元から渡されるフォーマット文字列と引数

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| (なし) | void | 戻り値なし |

### 出力先

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

## 処理フロー

### 処理シーケンス

```
1. 可変引数の処理
   └─ va_start/va_endで引数リストを取得
   └─ SetTooltipVを呼び出し

2. ツールチップの開始
   └─ BeginTooltipEx(OverridePrevious, None)を呼び出し
   └─ falseを返した場合は終了

3. テキストの表示
   └─ TextV()でフォーマット済みテキストを表示

4. ツールチップの終了
   └─ EndTooltip()を呼び出し
```

### フローチャート

```mermaid
flowchart TD
    A[開始: SetTooltip] --> B[va_start]
    B --> C[SetTooltipV呼び出し]
    C --> D[va_end]
    D --> E[SetTooltipV]
    E --> F[BeginTooltipEx<br/>OverridePrevious]
    F --> G{成功?}
    G -->|No| H[終了]
    G -->|Yes| I[TextV]
    I --> J[EndTooltip]
    J --> H
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-159-01 | 上書き動作 | 同一フレーム内で複数回呼ばれた場合、以前のツールチップを上書き | 常時 |
| BR-159-02 | printf形式 | フォーマット文字列はprintf形式に従う | 常時 |
| BR-159-03 | 単独呼び出し | Begin/Endを別途呼ぶ必要がない | 常時 |

### 計算ロジック

特になし

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 早期リターン | BeginTooltipExがfalseを返す | 何もせず終了 |

### リトライ仕様

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

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

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

## パフォーマンス要件

- 単一フレーム内で複数回呼び出し可能（上書き動作）
- 軽量なテキスト表示処理

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

- フォーマット文字列攻撃に注意（ユーザー入力を直接渡さない）

## 備考

- SetTooltipVは可変引数リスト版
- SetItemTooltipは「IsItemHovered(ForTooltip) + SetTooltip」のショートカット
- リッチなコンテンツが必要な場合はBeginTooltip/EndTooltipを使用する

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | imgui.h | `imgui.h` | 824行目: SetTooltip API宣言を確認 |
| 1-2 | imgui.h | `imgui.h` | 825行目: SetTooltipV API宣言を確認 |
| 1-3 | imgui.h | `imgui.h` | IM_FMTARGS、IM_FMTLISTマクロを確認 |

**読解のコツ**: SetTooltipはSetTooltipVの薄いラッパーで、可変引数を処理している。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | imgui.cpp | `imgui.cpp` | 12017-12023行目: SetTooltip関数 |
| 2-2 | imgui.cpp | `imgui.cpp` | 12025-12031行目: SetTooltipV関数 |

**主要処理フロー**:
1. **12019-12021行目**: va_start/va_endで可変引数を処理
2. **12027-12028行目**: BeginTooltipEx呼び出し（OverridePrevious）
3. **12029行目**: TextVでテキスト表示
4. **12030行目**: EndTooltip呼び出し

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

```
ImGui::SetTooltip(fmt, ...)
    │
    ├─ va_start(args, fmt)
    │
    ├─ SetTooltipV(fmt, args)
    │      │
    │      ├─ BeginTooltipEx(OverridePrevious, None)
    │      │      └─ ツールチップウィンドウを開始
    │      │
    │      ├─ TextV(fmt, args)
    │      │      └─ フォーマット済みテキストを表示
    │      │
    │      └─ EndTooltip()
    │             └─ ツールチップウィンドウを終了
    │
    └─ va_end(args)
```

### データフロー図

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

fmt ──────────────────────> va_start
... (可変引数)                  │
                                ▼
                           SetTooltipV
                                │
                                ├──> BeginTooltipEx ──────> ツールチップウィンドウ
                                │
                                ├──> TextV ─────────────────> テキスト描画
                                │
                                └──> EndTooltip ───────────> ウィンドウ終了
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| imgui.h | `imgui.h` | ヘッダー | SetTooltip/SetTooltipV APIの宣言 |
| imgui.cpp | `imgui.cpp` | ソース | SetTooltip実装（12017-12023行目）、SetTooltipV実装（12025-12031行目） |
