# 機能設計書 205-SetItemDefaultFocus

## 概要

本ドキュメントは、ImGuiライブラリにおける `SetItemDefaultFocus` 関数の機能設計を定義する。この関数は、新しく表示されるウィンドウで直前のアイテムをデフォルトフォーカスアイテムとして設定するために使用される。

### 本機能の処理概要

SetItemDefaultFocus関数は、ウィンドウが新しく表示される際（Appearing状態）に、直前に追加されたアイテムをナビゲーションシステムのデフォルトフォーカスアイテムとして設定する。これにより、コンボボックスやリストボックスを開いた時に選択済みアイテムに自動的にフォーカスが移動する。

**業務上の目的・背景**：キーボードやゲームパッドでのナビゲーションにおいて、ポップアップやリストが開かれた時に適切な初期フォーカス位置を設定することは、ユーザーエクスペリエンスの向上に重要である。特に、既に選択されているアイテムにフォーカスを当てることで、ユーザーは現在の選択状態を即座に認識でき、そこから操作を開始できる。

**機能の利用シーン**：
- コンボボックスを開いた時に選択済みアイテムにフォーカス
- リストボックスで現在選択中のアイテムを強調
- ポップアップメニューでデフォルト項目にフォーカス
- ツリービューで展開時に特定ノードにフォーカス
- 初期表示時のフォーム項目のデフォルト選択

**主要な処理内容**：
1. ウィンドウがAppearing状態かどうかを確認
2. ナビゲーション初期化リクエストが有効な条件を確認
3. NavInitResultに直前のアイテム情報を適用
4. 必要に応じてスクロール調整を実行

**関連システム・外部連携**：ナビゲーションシステム、スクロールシステム、ウィンドウ表示状態管理と連携する。

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 23 | Widgets | 参照画面 | コンボボックス・リストボックスでのフォーカス設定 |
| 1 | Demo Window | 参照画面 | 各種セレクタブルアイテムでのデフォルトフォーカス |

## 機能種別

フォーカス制御 / ナビゲーション制御 / UI初期化

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| なし | - | - | パラメータなし | - |

### 入力データソース

- ImGuiContext内部状態（g.LastItemData）
- ウィンドウのAppearing状態
- ナビゲーションシステムの初期化リクエスト状態

## 出力仕様

### 出力データ

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

### 出力先

- ImGuiContext::NavInitRequest（フラグ更新）
- ImGuiContext::NavInitResult（アイテム情報設定）
- ウィンドウのスクロール位置（必要に応じて）

## 処理フロー

### 処理シーケンス

```
1. ImGuiContextの取得
   └─ グローバルコンテキスト（GImGui）を取得
2. ウィンドウのAppearing状態確認
   └─ window->Appearingがfalseなら早期リターン
3. ナビゲーション初期化条件の確認
   └─ NavWindow、NavInitRequest、NavLayer等の条件確認
   └─ 条件を満たさない場合は早期リターン
4. NavInitResultの更新
   └─ NavInitRequestをfalseに設定
   └─ NavApplyItemToResultで直前のアイテム情報を適用
   └─ NavUpdateAnyRequestFlagを呼び出し
5. スクロール調整
   └─ アイテムがClipRect外の場合、スクロール調整
```

### フローチャート

```mermaid
flowchart TD
    A[SetItemDefaultFocus呼び出し] --> B{window->Appearing?}
    B -->|No| C[早期リターン]
    B -->|Yes| D{Nav初期化条件OK?}
    D -->|No| C
    D -->|Yes| E[NavInitRequest = false]
    E --> F[NavApplyItemToResult]
    F --> G[NavUpdateAnyRequestFlag]
    G --> H{アイテムがClipRect内?}
    H -->|Yes| I[終了]
    H -->|No| J[ScrollToRectEx]
    J --> I
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-205-1 | Appearing時のみ有効 | ウィンドウがAppearing状態の時のみ効果がある | 常時 |
| BR-205-2 | 直前アイテム対象 | 直前に追加されたアイテムがフォーカス対象となる | 常時 |
| BR-205-3 | スクロール連動 | アイテムが見えない場合は自動スクロール | ClipRect外の場合 |
| BR-205-4 | 単一呼び出し | 同一フレームで複数回呼び出しても最後のアイテムが有効 | 常時 |

### 計算ロジック

スクロール調整判定：
```
if (!window->ClipRect.Contains(g.LastItemData.Rect)):
    ScrollToRectEx(window, g.LastItemData.Rect, ImGuiScrollFlags_None)
```

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

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

本機能はデータベース操作を行わない（純粋なUI制御機能）。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| なし | 無効操作 | ウィンドウがAppearing状態でない時 | 警告なしで無視される |
| なし | 無効操作 | ナビゲーション初期化条件を満たさない時 | 警告なしで無視される |

### リトライ仕様

リトライ機能なし（即時処理）

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

トランザクション管理なし（UI状態の更新）。

## パフォーマンス要件

- 軽量な処理（条件チェックと状態更新のみ）
- オーバーヘッドは最小限

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

- フォーカス制御はUIの利便性機能であり、セキュリティ上のリスクはない

## 備考

- コンボボックスやリストボックスのヘルパー関数内で自動的に呼び出される
- 手動で呼び出す場合は、選択されているアイテムの直後に呼び出す
- SetKeyboardFocusHereとは異なり、ナビゲーション初期化時のみ有効

---

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

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

### 推奨読解順序

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

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

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

**主要処理フロー**:
- **993-994行目**: Focus, Activationセクションのコメントと関数宣言

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

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

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

**主要処理フロー**:
- **8790行目**: 関数定義の開始
- **8793-8794行目**: Appearing状態チェック（早期リターン）
- **8795-8797行目**: ナビゲーション初期化条件チェック
- **8799行目**: NavInitRequest = false
- **8800行目**: NavApplyItemToResult呼び出し
- **8801行目**: NavUpdateAnyRequestFlag呼び出し
- **8804-8805行目**: スクロール調整

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

ウィジェット内での使用パターンを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | imgui_widgets.cpp | `imgui_widgets.cpp` | Combo関数内での使用（2173行目） |
| 3-2 | imgui_widgets.cpp | `imgui_widgets.cpp` | ListBox関数内での使用（8724行目） |
| 3-3 | imgui_demo.cpp | `imgui_demo.cpp` | デモでの使用例（1338行目） |

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

```
ImGui::SetItemDefaultFocus()
    │
    ├─ GImGui（グローバルコンテキスト取得）
    │
    ├─ window->Appearing確認
    │
    ├─ Nav初期化条件確認
    │      ├─ g.NavWindow
    │      ├─ g.NavInitRequest
    │      └─ g.NavLayer
    │
    ├─ NavApplyItemToResult(&g.NavInitResult)
    │
    ├─ NavUpdateAnyRequestFlag()
    │
    └─ ScrollToRectEx()（条件付き）
```

### データフロー図

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

g.LastItemData ───────▶ SetItemDefaultFocus() ─▶ NavInitRequest更新
                              │
window->Appearing ────▶       │ ───────────────▶ NavInitResult更新
                              │
Nav初期化状態 ────────▶       └─────────────────▶ スクロール位置
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| imgui.h | `imgui.h` | ヘッダ | 公開API宣言 |
| imgui.cpp | `imgui.cpp` | ソース | 実装コード |
| imgui_widgets.cpp | `imgui_widgets.cpp` | ソース | Combo/ListBox内での使用 |
| imgui_demo.cpp | `imgui_demo.cpp` | ソース | 使用例 |
