# 機能設計書 31-IsWindowHovered

## 概要

本ドキュメントは、Dear ImGuiライブラリにおける `IsWindowHovered` 関数の機能設計書である。この関数は、現在のウィンドウがマウスホバー状態にあるかどうかを判定するためのAPIを提供する。

### 本機能の処理概要

**業務上の目的・背景**：GUIアプリケーションにおいて、ユーザーのマウス操作に応じたインタラクティブな動作を実現するために、ウィンドウのホバー状態を検出する必要がある。IsWindowHovered関数は、現在処理中のウィンドウ（Begin/End ブロック内）がマウスカーソルの下にあるかどうかを判定し、ツールチップ表示やハイライト効果、コンテキストメニューの表示制御などに活用される。

**機能の利用シーン**：
- ウィンドウにマウスが乗った際にツールチップや追加情報を表示する場合
- ウィンドウのホバー状態に応じて視覚的なフィードバックを提供する場合
- 子ウィンドウを含むウィンドウ階層全体のホバー状態を確認する場合
- ポップアップやモーダルがある状態でのホバー判定をカスタマイズする場合

**主要な処理内容**：
1. 現在ホバーされているウィンドウ（g.HoveredWindow）を取得
2. フラグに応じてルートウィンドウや子ウィンドウを考慮した判定を実行
3. ポップアップ階層の考慮有無をフラグで制御
4. アクティブアイテムによるブロック状態を考慮
5. Stationary（静止）フラグによる遅延判定を適用

**関連システム・外部連携**：ImGuiコンテキスト（GImGui）の HoveredWindow、CurrentWindow、ActiveId などの状態を参照する。

**権限による制御**：特になし。すべてのウィンドウで利用可能。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | 本機能は直接的に画面に関連付けられていないが、すべてのウィンドウで使用可能 |

## 機能種別

状態判定API

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| flags | ImGuiHoveredFlags | No | ホバー判定の動作を制御するフラグ（デフォルト: 0） | AllowedMaskForIsWindowHovered マスクで検証 |

### 利用可能なフラグ

| フラグ名 | 説明 |
|---------|------|
| ImGuiHoveredFlags_None | デフォルト動作（直接ホバーのみ） |
| ImGuiHoveredFlags_ChildWindows | 子ウィンドウがホバーされている場合もtrueを返す |
| ImGuiHoveredFlags_RootWindow | ルートウィンドウから判定を開始 |
| ImGuiHoveredFlags_AnyWindow | いずれかのウィンドウがホバーされていればtrueを返す |
| ImGuiHoveredFlags_NoPopupHierarchy | ポップアップ階層を無視 |
| ImGuiHoveredFlags_AllowWhenBlockedByPopup | ポップアップによりブロックされていてもtrueを返す |
| ImGuiHoveredFlags_AllowWhenBlockedByActiveItem | アクティブアイテムによりブロックされていてもtrueを返す |
| ImGuiHoveredFlags_ForTooltip | ツールチップ用の標準フラグを適用 |
| ImGuiHoveredFlags_Stationary | マウスが一定時間静止している場合のみtrueを返す |

### 入力データソース

ImGuiコンテキスト（GImGui）から以下の状態を参照：
- g.HoveredWindow: 現在ホバーされているウィンドウ
- g.CurrentWindow: 現在処理中のウィンドウ
- g.ActiveId: 現在アクティブなアイテムのID

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 戻り値 | bool | ウィンドウがホバー状態であればtrue、そうでなければfalse |

### 出力先

呼び出し元に直接返却。

## 処理フロー

### 処理シーケンス

```
1. フラグのバリデーション
   └─ 無効なフラグが指定されていないかアサートで検証

2. ホバーウィンドウの確認
   └─ g.HoveredWindow が NULL の場合は false を返す

3. AnyWindow フラグの処理
   └─ AnyWindow が指定されている場合は即座に true を返す

4. ウィンドウの一致判定
   ├─ RootWindow フラグの場合はルートウィンドウを取得
   ├─ ChildWindows フラグの場合は子孫関係を確認
   └─ それ以外は直接一致を確認

5. ホバー可能性の確認
   └─ IsWindowContentHoverable で確認

6. アクティブアイテムによるブロック確認
   └─ AllowWhenBlockedByActiveItem でない場合はブロック判定

7. Stationary フラグの処理
   └─ マウスが静止しているか確認

8. 結果を返す
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{フラグ検証}
    B -->|無効| Z[アサート失敗]
    B -->|有効| C{HoveredWindow存在?}
    C -->|No| R1[return false]
    C -->|Yes| D{AnyWindowフラグ?}
    D -->|Yes| R2[return true]
    D -->|No| E{RootWindowフラグ?}
    E -->|Yes| F[ルートウィンドウ取得]
    E -->|No| G{ChildWindowsフラグ?}
    F --> G
    G -->|Yes| H[子孫関係確認]
    G -->|No| I[直接一致確認]
    H --> J{一致?}
    I --> J
    J -->|No| R1
    J -->|Yes| K{ContentHoverable?}
    K -->|No| R1
    K -->|Yes| L{ActiveItemブロック?}
    L -->|Yes| R1
    L -->|No| M{Stationaryフラグ?}
    M -->|Yes| N{静止中?}
    M -->|No| R2
    N -->|No| R1
    N -->|Yes| R2
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | Begin/End必須 | この関数はBegin/End ブロック内で呼び出す必要がある | AnyWindowフラグが指定されていない場合 |
| BR-02 | ポップアップブロック | デフォルトではポップアップがホバーをブロックする | AllowWhenBlockedByPopup未指定時 |
| BR-03 | アクティブアイテムブロック | デフォルトではアクティブアイテムがホバーをブロックする | AllowWhenBlockedByActiveItem未指定時 |
| BR-04 | NoInputsウィンドウ | ImGuiWindowFlags_NoInputs フラグを持つウィンドウは無視される | 常時 |

### 計算ロジック

特になし。

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

本機能はデータベース操作を行わない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| ASSERT | アサーション | 無効なフラグが指定された | AllowedMaskForIsWindowHovered に含まれるフラグのみを使用 |

### リトライ仕様

リトライは不要。

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

該当なし。

## パフォーマンス要件

- 毎フレーム複数回呼び出される可能性があるため、軽量な実装が求められる
- O(1) の計算量で判定を行う（子孫関係の確認を除く）

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

特になし。

## 備考

- io.WantCaptureMouse を使用して、マウス入力をDear ImGuiとアプリケーションのどちらに送るかを判定することを推奨
- IsItemHovered() と異なり、ウィンドウ全体のホバー状態を判定する

---

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

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

### 推奨読解順序

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

ImGuiHoveredFlags の各フラグ値と、ウィンドウのホバー状態管理に関するデータ構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | imgui.h | `imgui.h` | ImGuiHoveredFlags_ 列挙型の定義（1442-1477行） |
| 1-2 | imgui_internal.h | `imgui_internal.h` | AllowedMaskForIsWindowHovered の定義（1017行） |

**読解のコツ**: ImGuiHoveredFlags は IsItemHovered と IsWindowHovered の両方で使用されるが、一部のフラグは IsWindowHovered 専用である（ChildWindows、RootWindow、AnyWindow、NoPopupHierarchy）。

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

IsWindowHovered 関数の実装を確認する。

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

**主要処理フロー**:
1. **8381行目**: フラグのバリデーション（AllowedMaskForIsWindowHovered でマスク）
2. **8383-8386行目**: HoveredWindow と CurrentWindow の取得、NULL チェック
3. **8388-8401行目**: AnyWindow、RootWindow、ChildWindows フラグによる判定分岐
4. **8404行目**: IsWindowContentHoverable による追加チェック
5. **8406-8408行目**: ActiveItem によるブロック判定
6. **8415-8418行目**: ForTooltip と Stationary フラグの処理

#### Step 3: 補助関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | imgui.cpp | `imgui.cpp` | GetCombinedRootWindow 関数（RootWindowフラグ処理用） |
| 3-2 | imgui.cpp | `imgui.cpp` | IsWindowChildOf 関数（ChildWindowsフラグ処理用） |
| 3-3 | imgui.cpp | `imgui.cpp` | IsWindowContentHoverable 関数（ホバー可能性判定） |

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

```
IsWindowHovered(flags)
    │
    ├─ IM_ASSERT_USER_ERROR (フラグ検証)
    │
    ├─ GetCombinedRootWindow (RootWindowフラグ時)
    │      └─ ウィンドウ階層を遡ってルートを取得
    │
    ├─ IsWindowChildOf (ChildWindowsフラグ時)
    │      └─ 子孫関係の確認
    │
    ├─ IsWindowContentHoverable
    │      └─ ウィンドウのホバー可能性を確認
    │
    └─ ApplyHoverFlagsForTooltip (ForTooltipフラグ時)
           └─ ツールチップ用フラグを適用
```

### データフロー図

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

flags (ImGuiHoveredFlags)
        │
        ├─────────────────▶ フラグ検証
        │
g.HoveredWindow ──────────▶ ウィンドウ比較判定 ─────────────▶ bool (true/false)
        │                        │
g.CurrentWindow ─────────────────┘
        │
g.ActiveId ───────────────▶ ブロック判定
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| imgui.h | `imgui.h` | ヘッダー | IsWindowHovered 関数の宣言、ImGuiHoveredFlags の定義 |
| imgui.cpp | `imgui.cpp` | ソース | IsWindowHovered 関数の実装 |
| imgui_internal.h | `imgui_internal.h` | ヘッダー | AllowedMaskForIsWindowHovered の定義 |
| imgui_demo.cpp | `imgui_demo.cpp` | デモ | IsWindowHovered の使用例（2232-2257行） |
