# 機能設計書 30-IsWindowFocused

## 概要

本ドキュメントは、Dear ImGuiライブラリにおけるIsWindowFocused機能の設計仕様を記述する。この機能は、現在のウィンドウまたは関連するウィンドウがフォーカスされているかどうかを判定するための関数である。フラグによってルートウィンドウや子ウィンドウを含むかどうかを制御できる。

### 本機能の処理概要

**業務上の目的・背景**：ウィンドウのフォーカス状態を検出することで、フォーカスされているウィンドウに対してのみ特定の処理を行うことができる。例えば、フォーカスされているウィンドウでのみショートカットキーを有効にしたり、フォーカス状態に応じた視覚的フィードバックを提供したりする際に使用される。複数のオプションフラグにより、ルートウィンドウ、子ウィンドウ、任意のウィンドウなど、様々な条件でのフォーカス判定が可能である。

**機能の利用シーン**：
- 現在のウィンドウがフォーカスされているか確認する場合
- ルートウィンドウがフォーカスされているか確認する場合
- 子ウィンドウを含めたフォーカス判定を行う場合
- 任意のウィンドウがフォーカスされているか確認する場合
- フォーカス状態に応じたキーボード入力処理を行う場合

**主要な処理内容**：
1. ナビゲーションウィンドウ（g.NavWindow）を取得する
2. フラグに応じて判定対象のウィンドウを決定する
3. 現在のウィンドウまたはルートウィンドウとの比較を行う
4. 子ウィンドウを含む場合はIsWindowChildOf()で判定する

**関連システム・外部連携**：ImGuiのウィンドウ管理システム、ナビゲーションシステムと連携する。

**権限による制御**：特になし。すべてのユーザーが任意のタイミングで呼び出し可能。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | 全てのウィンドウ | 参照機能 | ウィンドウのフォーカス状態取得 |

## 機能種別

状態取得 / ウィンドウユーティリティ

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| flags | ImGuiFocusedFlags | No | フォーカス判定のオプションフラグ | ImGuiFocusedFlags_の組み合わせ |

### 入力データソース

- グローバルコンテキストのナビゲーションウィンドウ（g.NavWindow）
- グローバルコンテキストの現在のウィンドウ（g.CurrentWindow）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 戻り値 | bool | 指定条件でウィンドウがフォーカスされている場合はtrue、そうでない場合はfalse |

### 出力先

なし（戻り値として返す）

## 処理フロー

### 処理シーケンス

```
1. ナビゲーションウィンドウを取得
   └─ g.NavWindowを取得
2. NULLチェック
   └─ NavWindowがNULLの場合はfalseを返す
3. AnyWindowフラグのチェック
   └─ ImGuiFocusedFlags_AnyWindowの場合はtrueを返す
4. 現在のウィンドウを取得
   └─ g.CurrentWindowを取得
5. RootWindowフラグの処理
   └─ フラグが指定されている場合はルートウィンドウを取得
6. フォーカス判定
   └─ ChildWindowsフラグに応じてIsWindowChildOf()または直接比較
```

### フローチャート

```mermaid
flowchart TD
    A[IsWindowFocused開始] --> B[g.NavWindow取得]
    B --> C{NavWindow == NULL?}
    C -->|Yes| D[return false]
    C -->|No| E{AnyWindowフラグ?}
    E -->|Yes| F[return true]
    E -->|No| G[g.CurrentWindow取得]
    G --> H{RootWindowフラグ?}
    H -->|Yes| I[GetCombinedRootWindow]
    H -->|No| J{ChildWindowsフラグ?}
    I --> J
    J -->|Yes| K[IsWindowChildOf判定]
    J -->|No| L[NavWindow == CurrentWindow?]
    K --> M[return 結果]
    L --> M
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | フラグなし | フラグなしの場合は現在のウィンドウが直接フォーカスされているかを判定 | デフォルト |
| BR-002 | AnyWindow | ImGuiFocusedFlags_AnyWindowの場合、任意のウィンドウがフォーカスされていればtrue | AnyWindowフラグ指定時 |
| BR-003 | RootWindow | ImGuiFocusedFlags_RootWindowの場合、ルートウィンドウを基準に判定 | RootWindowフラグ指定時 |
| BR-004 | ChildWindows | ImGuiFocusedFlags_ChildWindowsの場合、子ウィンドウを含めて判定 | ChildWindowsフラグ指定時 |
| BR-005 | NoPopupHierarchy | ImGuiFocusedFlags_NoPopupHierarchyの場合、ポップアップ階層を考慮しない | NoPopupHierarchyフラグ指定時 |

### 計算ロジック

- RootWindowフラグが指定されている場合: GetCombinedRootWindow()でルートウィンドウを取得
- ChildWindowsフラグが指定されている場合: IsWindowChildOf()で子ウィンドウ関係を判定
- 両方指定されている場合（RootAndChildWindows）: ルートウィンドウを基準に子ウィンドウを含めて判定

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

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

なし（本機能はメモリ内のデータ構造の読み取りのみを行う）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | アサーション警告 | Begin/End外で呼び出した場合 | Begin/End内で呼び出す |

### リトライ仕様

なし

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

なし

## パフォーマンス要件

- 処理時間: 軽量（フラグによっては若干の追加処理あり）
- メモリ使用: なし

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

なし

## 備考

- io.WantCaptureMouse/WantCaptureKeyboardを使用する方がマウス/キーボードディスパッチの判断には適切な場合がある（FAQを参照）
- v1.53でIsRootWindowFocused()とIsRootWindowOrAnyChildFocused()が本関数に統合された
- v1.60でIsAnyWindowFocused()が本関数に統合された

---

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

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

### 推奨読解順序

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

ImGuiFocusedFlags列挙型を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | imgui.h | `imgui.h` | ImGuiFocusedFlags_列挙型（1428-1436行目） |

**読解のコツ**:
- ImGuiFocusedFlags_ChildWindows: 子ウィンドウのいずれかがフォーカスされていればtrue
- ImGuiFocusedFlags_RootWindow: ルートウィンドウを基準に判定
- ImGuiFocusedFlags_AnyWindow: 任意のウィンドウがフォーカスされていればtrue
- ImGuiFocusedFlags_NoPopupHierarchy: ポップアップ階層を考慮しない
- ImGuiFocusedFlags_RootAndChildWindows: RootWindow | ChildWindows

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | imgui.h | `imgui.h` | IsWindowFocused関数宣言（464行目） |
| 2-2 | imgui.cpp | `imgui.cpp` | IsWindowFocused関数実装（12726-12746行目） |

**主要処理フロー**:
1. **12726-12730行目**: 関数開始、NavWindowとCurrentWindowの取得
2. **12732-12733行目**: NavWindowがNULLの場合はfalseを返す
3. **12734-12735行目**: AnyWindowフラグの処理
4. **12738-12740行目**: RootWindowフラグの処理
5. **12742-12745行目**: ChildWindowsフラグの処理または直接比較

#### Step 3: 関連する内部関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | imgui.cpp | `imgui.cpp` | GetCombinedRootWindow関数 |
| 3-2 | imgui.cpp | `imgui.cpp` | IsWindowChildOf関数 |

**主要処理フロー**:
- GetCombinedRootWindow: ポップアップ階層を考慮したルートウィンドウの取得
- IsWindowChildOf: ウィンドウの親子関係の判定

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

```
IsWindowFocused(flags)
    │
    ├─ g.NavWindow [ナビゲーションウィンドウの取得]
    │
    ├─ g.CurrentWindow [現在のウィンドウの取得]
    │
    ├─ GetCombinedRootWindow() [RootWindowフラグの場合]
    │
    └─ IsWindowChildOf() [ChildWindowsフラグの場合]
```

### データフロー図

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

flags ─────────────────────▶
g.NavWindow ───────────────▶ IsWindowFocused()       ──▶ bool (フォーカス状態)
g.CurrentWindow ───────────▶     │
                                 ▼
                          フラグに応じた判定
                          ・AnyWindow: 任意のウィンドウ
                          ・RootWindow: ルートウィンドウ
                          ・ChildWindows: 子ウィンドウ含む
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| imgui.h | `imgui.h` | ヘッダ | API宣言、ImGuiFocusedFlags_列挙型定義 |
| imgui.cpp | `imgui.cpp` | ソース | IsWindowFocused関数の実装 |
| imgui_internal.h | `imgui_internal.h` | ヘッダ | 内部関数定義 |
