# 機能設計書 208-IsItemHovered

## 概要

本ドキュメントは、ImGuiライブラリにおける `IsItemHovered` 関数の機能設計を定義する。この関数は、直前のアイテムがマウスでホバーされているかを判定するために使用される。

### 本機能の処理概要

IsItemHovered関数は、直前に追加されたアイテムがマウスカーソルの下にあり、かつ操作可能な状態であるかを判定する。ポップアップによるブロック、アクティブなアイテムによるブロック、無効化状態など、様々な条件を考慮した上でホバー状態を返す。フラグを使用することで、これらの条件を緩和してホバー判定を行うことができる。

**業務上の目的・背景**：GUIアプリケーションでは、マウスホバー状態に応じたツールチップの表示、ハイライト効果の適用、コンテキスト依存のアクションなど、多くの機能がホバー状態に依存している。IsItemHoveredは、これらの機能を実装するための基本的な判定手段を提供する。

**機能の利用シーン**：
- ツールチップの条件付き表示
- ホバー時のビジュアルフィードバック
- コンテキストメニューの表示トリガー
- ドラッグ&ドロップのビジュアルフィードバック
- インタラクティブなUIエフェクト
- デバッグ情報の表示

**主要な処理内容**：
1. ナビゲーションハイライトモードでの特別処理
2. 矩形によるホバー判定
3. ウィンドウの重なり確認
4. アクティブアイテムによるブロック確認
5. ポップアップによるブロック確認
6. 無効化状態の確認
7. 遅延判定（DelayShort, DelayNormalなど）

**関連システム・外部連携**：ウィンドウシステム、ポップアップシステム、ナビゲーションシステム、ツールチップシステムと連携する。

**権限による制御**：本機能自体に権限制御はない。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 23 | Widgets | 主画面 | ウィジェット状態クエリのデモ |
| 1 | Demo Window | 参照画面 | IsItemHoveredの各種フラグのデモ |

## 機能種別

状態判定 / クエリ関数 / インタラクション検出

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| flags | ImGuiHoveredFlags | No（デフォルト: 0） | ホバー判定の条件を制御するフラグ | 有効なフラグの組み合わせ |

### 主要なフラグ

| フラグ名 | 説明 |
|---------|------|
| ImGuiHoveredFlags_None | デフォルト動作 |
| ImGuiHoveredFlags_AllowWhenBlockedByPopup | ポップアップでブロックされていても許可 |
| ImGuiHoveredFlags_AllowWhenBlockedByActiveItem | アクティブアイテムでブロックされていても許可 |
| ImGuiHoveredFlags_AllowWhenOverlappedByItem | オーバーラップアイテムでも許可 |
| ImGuiHoveredFlags_AllowWhenOverlappedByWindow | オーバーラップウィンドウでも許可 |
| ImGuiHoveredFlags_AllowWhenDisabled | 無効化されていても許可 |
| ImGuiHoveredFlags_NoNavOverride | ナビゲーション状態を無視 |
| ImGuiHoveredFlags_ForTooltip | ツールチップ用のフラグショートカット |
| ImGuiHoveredFlags_Stationary | マウスが静止している必要あり |
| ImGuiHoveredFlags_DelayShort | 短い遅延後にtrue |
| ImGuiHoveredFlags_DelayNormal | 通常の遅延後にtrue |

### 入力データソース

- ImGuiContext内部状態（g.LastItemData）
- マウス位置
- ウィンドウ状態

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| return | bool | アイテムがホバーされていればtrue |

### 出力先

呼び出し元へのbool値返却

## 処理フロー

### 処理シーケンス

```
1. ImGuiContextの取得
   └─ グローバルコンテキスト（GImGui）を取得
2. ナビゲーションハイライトモード確認
   └─ NavHighlightItemUnderNav && NavCursorVisible の場合
   └─ IsItemFocusedで判定、無効化チェック
3. 矩形ホバー判定
   └─ LastItemData.StatusFlagsのHoveredRectを確認
4. ツールチップフラグ処理
   └─ ForTooltipフラグがある場合、スタイル設定からフラグを適用
5. ウィンドウ重なり確認
   └─ HoveredWindowとCurrentWindowの比較
6. アクティブアイテムによるブロック確認
   └─ AllowWhenBlockedByActiveItemフラグで制御
7. ポップアップによるブロック確認
   └─ IsWindowContentHoverableで確認
8. 無効化状態確認
   └─ AllowWhenDisabledフラグで制御
9. 遅延判定
   └─ DelayShort/DelayNormalの処理
```

### フローチャート

```mermaid
flowchart TD
    A[IsItemHovered呼び出し] --> B{Nav Highlight Mode?}
    B -->|Yes| C[IsItemFocused判定]
    B -->|No| D{矩形ホバー判定}
    C --> E{条件OK?}
    E -->|No| F[return false]
    E -->|Yes| G[return true/遅延処理]
    D -->|No hover| F
    D -->|Hovered| H{ウィンドウ重なりOK?}
    H -->|No| F
    H -->|Yes| I{アクティブブロック?}
    I -->|Yes| F
    I -->|No| J{ポップアップブロック?}
    J -->|Yes| F
    J -->|No| K{無効化状態?}
    K -->|Yes| F
    K -->|No| G
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-208-1 | ナビゲーション優先 | NavHighlightモード時はIsItemFocusedで判定 | NavCursorVisible時 |
| BR-208-2 | 矩形判定 | ItemAddで更新された矩形内にマウスがあるか | 常時 |
| BR-208-3 | ポップアップブロック | モーダル/ポップアップはデフォルトで他アイテムのホバーをブロック | AllowWhenBlockedByPopupなし時 |
| BR-208-4 | 無効化ブロック | 無効化アイテムはデフォルトでfalse | AllowWhenDisabledなし時 |
| BR-208-5 | ウィンドウ重なり | 別ウィンドウが上にある場合はデフォルトでfalse | AllowWhenOverlappedByWindowなし時 |

### 計算ロジック

遅延判定の計算：
```
HoverDelayShort: style.HoverDelayShort秒（デフォルト約0.15秒）
HoverDelayNormal: style.HoverDelayNormal秒（デフォルト約0.40秒）
Stationary: style.HoverStationaryDelay秒（デフォルト約0.15秒）マウスが静止
```

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

### 操作別データベース影響一覧

本機能はデータベース操作を行わない（純粋なUI状態クエリ機能）。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| IM_ASSERT | アサーション | 無効なフラグ指定時 | 有効なフラグの組み合わせを使用 |

### リトライ仕様

リトライ機能なし（即時クエリ）

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

トランザクション管理なし（状態クエリのみ）。

## パフォーマンス要件

- 軽量な処理（状態フラグとマウス位置の確認のみ）
- 毎フレーム呼び出し可能

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

- ホバー判定はUIの利便性機能であり、セキュリティ上のリスクはない

## 備考

- ツールチップにはBeginItemTooltip()やSetItemTooltip()がより便利
- Button()等の戻り値はIsItemHovered()とほぼ同等だが、厳密には異なる
- デモウィンドウの「Widgets->Querying Status」で各種関数の動作を確認可能

---

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

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

### 推奨読解順序

#### Step 1: フラグを理解する

IsItemHoveredで使用されるフラグを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | imgui.h | `imgui.h` | ImGuiHoveredFlags_の定義（1442-1477行目） |

**読解のコツ**: 各フラグは特定の条件を緩和する。デフォルトではすべての条件が厳格に適用される。

#### Step 2: API宣言を理解する

公開APIの宣言とドキュメントコメントを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | imgui.h | `imgui.h` | IsItemHovered関数の宣言（1006行目） |

**主要処理フロー**:
- **1003-1005行目**: Item/Widgets Utilities and Query Functionsセクションのコメント
- **1006行目**: IsItemHovered関数宣言

#### Step 3: 実装を理解する

IsItemHovered関数の実装詳細を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | imgui.cpp | `imgui.cpp` | IsItemHovered関数の実装（4786-4846行目以降） |

**主要処理フロー**:
- **4786行目**: 関数定義の開始
- **4790行目**: フラグのバリデーション
- **4792-4801行目**: ナビゲーションハイライトモードの処理
- **4804-4845行目**: 通常のホバー判定

#### Step 4: 使用例を理解する

デモコードでの使用パターンを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | imgui_demo.cpp | `imgui_demo.cpp` | ウィジェットクエリステータスデモ（2133-2172行目） |

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

```
ImGui::IsItemHovered(ImGuiHoveredFlags flags)
    │
    ├─ GImGui（グローバルコンテキスト取得）
    │
    ├─ IM_ASSERT_USER_ERROR（フラグバリデーション）
    │
    ├─ ナビゲーションハイライト処理
    │      ├─ IsItemFocused()
    │      └─ ApplyHoverFlagsForTooltip()
    │
    ├─ 矩形ホバー判定
    │      └─ LastItemData.StatusFlags確認
    │
    ├─ IsWindowContentHoverable()
    │
    └─ 遅延判定処理
           └─ CalcDelayFromHoveredFlags()
```

### データフロー図

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

flags(ImGuiHoveredFlags) ─▶ IsItemHovered() ───────▶ bool
                              │
g.LastItemData ───────────▶   │
                              │
g.HoveredWindow ──────────▶   │
                              │
マウス位置 ────────────────▶   │
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| imgui.h | `imgui.h` | ヘッダ | 公開API宣言、フラグ定義 |
| imgui.cpp | `imgui.cpp` | ソース | 実装コード |
| imgui_demo.cpp | `imgui_demo.cpp` | ソース | 使用例 |
