# 通知設計書 30-ImGuiHoveredFlags_ForTooltip

## 概要

本ドキュメントは、ImGuiライブラリにおける`ImGuiHoveredFlags_ForTooltip`フラグの仕様と動作を定義する設計書である。このフラグは、`IsItemHovered()`関数で使用され、ツールチップ表示に最適化された標準的なホバー条件を適用するショートカットとして機能する。

### 本通知の処理概要

`ImGuiHoveredFlags_ForTooltip`は、ツールチップ表示のための標準的なホバーフラグをまとめたショートカットフラグである。このフラグを使用することで、アプリケーション全体で一貫したツールチップ表示動作を実現でき、`style.HoverFlagsForTooltipMouse`または`style.HoverFlagsForTooltipNav`から設定を自動的に取得する。

**業務上の目的・背景**：ツールチップの表示タイミングはUXにおいて重要である。表示が早すぎると邪魔になり、遅すぎると役に立たない。このフラグは、マウス操作時とキーボード/ゲームパッドナビゲーション時でそれぞれ最適化されたホバー条件（停止時間、遅延時間など）をスタイル設定から取得し、アプリケーション全体で統一されたツールチップ体験を提供する。開発者は個々の場所で複雑なフラグ組み合わせを指定する必要がなくなる。

**通知の送信タイミング**：`IsItemHovered(ImGuiHoveredFlags_ForTooltip)`関数の呼び出し時に、このフラグが評価される。入力モード（マウス/ナビゲーション）に応じて`HoverFlagsForTooltipMouse`または`HoverFlagsForTooltipNav`からフラグが読み込まれる。

**通知の受信者**：ImGuiのホバー判定システムが受信者である。`IsItemHovered()`関数内でこのフラグを展開し、適切なホバー条件を適用する。

**通知内容の概要**：ツールチップ用の標準ホバー条件を使用することを示すビットフラグ情報を伝達する。値は`1 << 12`。

**期待されるアクション**：開発者はこのフラグを使用して、ツールチップ表示に最適化されたホバー判定を行い、`SetTooltip()`や`BeginTooltip()`と組み合わせて使用する。

## 通知種別

ホバーフラグ（ビットフラグ）

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期 |
| 優先度 | 中 |
| リトライ | 無 |

### 送信先決定ロジック

フラグは`IsItemHovered()`の引数として渡され、内部で入力モードに応じた設定に展開される。

## 通知テンプレート

### フラグ定義

| 項目 | 内容 |
|-----|------|
| フラグ名 | ImGuiHoveredFlags_ForTooltip |
| 値 | 1 << 12 (4096) |
| 定義場所 | imgui.h:1467 |

### デフォルトで含まれるフラグ

| 入力モード | デフォルト設定 |
|-----------|--------------|
| マウス | `ImGuiHoveredFlags_Stationary \| ImGuiHoveredFlags_DelayShort \| ImGuiHoveredFlags_AllowWhenDisabled` |
| ナビゲーション | `ImGuiHoveredFlags_DelayNormal \| ImGuiHoveredFlags_NoSharedDelay` |

### 使用例

```cpp
// ツールチップ表示の標準パターン
if (ImGui::IsItemHovered(ImGuiHoveredFlags_ForTooltip))
{
    ImGui::SetTooltip("This is a standardized tooltip");
}

// BeginItemTooltip() は内部でこのパターンを使用
if (ImGui::BeginItemTooltip())
{
    ImGui::Text("Rich tooltip content");
    ImGui::EndTooltip();
}

// スタイルでカスタマイズ可能
ImGuiStyle& style = ImGui::GetStyle();
style.HoverFlagsForTooltipMouse = ImGuiHoveredFlags_Stationary | ImGuiHoveredFlags_DelayNormal;
```

### 添付ファイル

該当なし

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| flags | ホバーフラグ | 呼び出し元引数 | No |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| API呼び出し | IsItemHovered() | フラグ指定時 | ツールチップ用ホバー条件適用 |
| API呼び出し | BeginItemTooltip() | 常時 | 内部で使用 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| なし | フラグは常に有効 |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[IsItemHovered呼び出し] --> B{ForTooltipフラグ?}
    B -->|No| C[通常のホバー判定]
    B -->|Yes| D{入力モード判定}
    D -->|マウス| E[HoverFlagsForTooltipMouseを取得]
    D -->|ナビゲーション| F[HoverFlagsForTooltipNavを取得]
    E --> G[フラグ展開]
    F --> G
    G --> H[遅延・停止条件チェック]
    H --> I{条件満たす?}
    I -->|Yes| J[true を返す]
    I -->|No| K[false を返す]
```

## データベース参照・更新仕様

### 参照テーブル一覧

該当なし（ImGuiはメモリベースの即時モードGUI）

### 更新テーブル一覧

該当なし

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| 無効なフラグ組み合わせ | なし | フラグは安全に組み合わせ可能 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | 0 |
| リトライ間隔 | 該当なし |
| リトライ対象エラー | なし |

## 配信設定

### レート制限

| 項目 | 内容 |
|-----|------|
| 1分あたり上限 | 無制限 |
| 1日あたり上限 | 無制限 |

### 配信時間帯

制限なし（フレームごとに評価）

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

特になし。UIフラグはユーザー入力の検知のみに使用される。

## 備考

- ツールチップ表示に最適化されたショートカットフラグ
- `style.HoverFlagsForTooltipMouse`と`style.HoverFlagsForTooltipNav`から設定を取得
- デフォルトでは`Stationary + DelayShort + AllowWhenDisabled`（マウス）
- 頻繁に操作されるアイテムには遅延付きが推奨
- 主目的がホバーであるアイテム（情報アイコンなど）には遅延なしも可
- `BeginItemTooltip()`の内部で使用されている

---

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

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

### 推奨読解順序

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

フラグの定義位置を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | imgui.h | `imgui.h` | ImGuiHoveredFlags_ForTooltip定義（1467行目） |
| 1-2 | imgui.h | `imgui.h` | 遅延関連フラグ（1472-1476行目） |

**読解のコツ**: コメントで「Shortcut for standard flags when using IsItemHovered() + SetTooltip() sequence」と説明されている。

#### Step 2: スタイル設定を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | imgui.h | `imgui.h` | ImGuiStyle::HoverFlagsForTooltipMouse |
| 2-2 | imgui.h | `imgui.h` | ImGuiStyle::HoverFlagsForTooltipNav |

**主要処理フロー**:
1. スタイルに2種類のフラグセットが定義されている
2. 入力モードに応じて適切なセットが選択される

#### Step 3: フラグが使用される箇所を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | imgui.cpp | `imgui.cpp` | IsItemHovered関数内でのForTooltip評価 |
| 3-2 | imgui_demo.cpp | `imgui_demo.cpp` | 使用例（2137行目、4003行目） |

**主要処理フロー**:
- **2137行目**: `IsItemHovered(ImGuiHoveredFlags_ForTooltip)`の使用
- フラグが設定されている場合、スタイルから適切なフラグセットを取得

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

```
IsItemHovered(ImGuiHoveredFlags_ForTooltip)
    |
    +-- フラグ評価
    |      |
    |      +-- if (flags & ImGuiHoveredFlags_ForTooltip)
    |             |
    |             +-- 入力モード判定 (Nav active?)
    |             |
    |             +-- flags |= style.HoverFlagsForTooltipMouse
    |             |       or style.HoverFlagsForTooltipNav
    |
    +-- 展開されたフラグで判定
           |
           +-- Stationary判定 (マウス停止チェック)
           |
           +-- Delay判定 (遅延時間チェック)
           |
           +-- AllowWhenDisabled判定
```

### データフロー図

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

ImGuiHoveredFlags_ForTooltip ───> IsItemHovered() ───> bool (ホバー状態)
                                       |
                                       v
                              入力モード判定
                                       |
                                       v
                              HoverFlagsForTooltipMouse
                              または
                              HoverFlagsForTooltipNav
                                       |
                                       v
                              遅延・停止条件評価
                                       |
                                       v
                              ホバー判定結果
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| imgui.h | `imgui.h` | ヘッダ | ImGuiHoveredFlags_ForTooltip定義（1467行目） |
| imgui.h | `imgui.h` | ヘッダ | 遅延フラグ定義（1472-1476行目） |
| imgui.cpp | `imgui.cpp` | ソース | IsItemHovered実装 |
| imgui_demo.cpp | `imgui_demo.cpp` | デモ | 使用例（2137行目、4003行目） |
