# 機能設計書 144-SetNextItemSelectionUserData

## 概要

本ドキュメントは、Dear ImGuiライブラリにおけるSetNextItemSelectionUserData関数の機能設計を記述する。SetNextItemSelectionUserDataは次に追加されるアイテムに選択識別用のユーザーデータを設定する関数である。

### 本機能の処理概要

SetNextItemSelectionUserData関数は、BeginMultiSelect/EndMultiSelectスコープ内で使用され、次に追加されるSelectable、TreeNode、Checkbox等のアイテムにアプリケーション定義の識別子を関連付ける。この識別子は選択リクエスト（ImGuiSelectionRequest）で参照される。

**業務上の目的・背景**：マルチセレクション機能では、どのアイテムが選択・選択解除されたかをアプリケーションに伝える必要がある。ImGuiはアプリケーションのデータ構造を知らないため、アプリケーション側が識別子を提供する仕組みが必要である。SetNextItemSelectionUserDataにより、インデックス、ポインタ、その他の識別子を各アイテムに関連付けることができる。

**機能の利用シーン**：
- リストビューでのインデックスベースの選択管理
- オブジェクトポインタを使用した直接参照
- カスタムID体系による選択追跡
- クリッパー使用時の効率的な選択状態管理

**主要な処理内容**：
1. NextItemData構造体へのユーザーデータ設定
2. FocusScopeIdの設定
3. アイテムフラグ（HasSelectionUserData、IsMultiSelect）の設定
4. マルチセレクト時のRangeSrcPassedBy更新

**関連システム・外部連携**：
- BeginMultiSelect/EndMultiSelectスコープ内で使用
- Selectable、TreeNode、Checkboxなどの選択可能ウィジェットと連携
- ImGuiListClipperと組み合わせて仮想スクロールをサポート

**権限による制御**：特になし。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 22 | Assets Browser | 主機能 | アセットアイテムの識別 |
| 23 | Widgets | 主機能 | マルチセレクトデモでのアイテム識別 |

## 機能種別

設定関数 / アイテム識別 / マルチセレクト補助

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| selection_user_data | ImGuiSelectionUserData | Yes | アプリケーション定義の識別子（インデックス、ポインタ等） | 任意の値（-1は内部で無効値として扱われる） |

### 入力データソース

- 呼び出し元からの直接パラメータ指定
- グローバルコンテキスト（g.CurrentMultiSelect）の状態

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| （戻り値なし） | void | - |
| g.NextItemData.SelectionUserData | ImGuiSelectionUserData | 次のアイテムに関連付けるユーザーデータ |
| g.NextItemData.ItemFlags | ImGuiItemFlags | HasSelectionUserData/IsMultiSelectフラグ |

### 出力先

- グローバルコンテキストのNextItemData構造体

## 処理フロー

### 処理シーケンス

```
1. NextItemDataへのユーザーデータ設定
   └─ g.NextItemData.SelectionUserData = selection_user_data

2. FocusScopeIdの設定
   └─ g.NextItemData.FocusScopeId = g.CurrentFocusScopeId

3. マルチセレクトコンテキストの確認
   └─ g.CurrentMultiSelectが存在するか判定

4. アイテムフラグの設定
   └─ マルチセレクト内: HasSelectionUserData | IsMultiSelect
   └─ マルチセレクト外: HasSelectionUserData のみ

5. RangeSrcPassedByの更新（マルチセレクト時）
   └─ IO.RangeSrcItemと一致する場合、フラグをtrue
```

### フローチャート

```mermaid
flowchart TD
    A[SetNextItemSelectionUserData開始] --> B[SelectionUserData設定]
    B --> C[FocusScopeId設定]
    C --> D{CurrentMultiSelect存在?}
    D -->|Yes| E[ItemFlags = HasSelectionUserData OR IsMultiSelect]
    D -->|No| F[ItemFlags = HasSelectionUserData]
    E --> G{RangeSrcItem == selection_user_data?}
    G -->|Yes| H[RangeSrcPassedBy = true]
    G -->|No| I[終了]
    H --> I
    F --> I
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-144-01 | アイテム直前呼び出し | Selectable等の直前に呼び出す必要がある | BeginMultiSelect内で常時 |
| BR-144-02 | 一意性推奨 | 各アイテムには一意の識別子を推奨 | 正確な選択管理が必要な場合 |
| BR-144-03 | -1は無効値 | -1（ImGuiSelectionUserData_Invalid）は無効値 | 内部処理 |
| BR-144-04 | クリッパー連携 | RangeSrcItemはクリッパーでIncludeが必要 | クリッパー使用時 |

### 計算ロジック

ImGuiSelectionUserData型:
- ImS64（64ビット符号付き整数）として定義
- インデックス、ポインタのreinterpret_cast、その他の識別子を格納可能
- -1がImGuiSelectionUserData_Invalidとして予約

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

該当なし（ImGuiはインメモリUIライブラリ）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | アサーション | BeginMultiSelect内でSetNextItemSelectionUserData未呼び出し | Selectable等の前に必ず呼び出す |

### リトライ仕様

該当なし

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

設定は次のアイテム追加時（ItemAdd）でクリアされる。

## パフォーマンス要件

- 非常に軽量な操作（数個の代入のみ）
- 大量アイテムでもオーバーヘッドは最小

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

ポインタを格納する場合、有効なメモリを指していることを確認すること。

## 備考

- マルチセレクト外でも呼び出し可能（ナビゲーション用途等）
- NULL/0も有効な値として使用可能
- 詳細はimgui.h内のImGuiSelectionUserDataコメントを参照

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | imgui.h | `imgui.h` | ImGuiSelectionUserData型定義（280-281行目）を確認 |
| 1-2 | imgui_internal.h | `imgui_internal.h` | NextItemData構造体でSelectionUserDataフィールドを確認 |

**読解のコツ**: ImGuiSelectionUserDataはtypedef ImS64であり、64ビット整数として定義されている。インデックスやポインタを格納できる。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | imgui.h | `imgui.h` | SetNextItemSelectionUserData関数宣言（775行目） |
| 2-2 | imgui_widgets.cpp | `imgui_widgets.cpp` | 実装（8092-8111行目） |

**主要処理フロー**:
1. **8097行目**: SelectionUserDataの設定
2. **8098行目**: FocusScopeIdの設定
3. **8100-8106行目**: マルチセレクト時の追加処理
4. **8103行目**: ItemFlagsにHasSelectionUserData | IsMultiSelectを設定
5. **8104-8105行目**: RangeSrcPassedByの更新

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | imgui_widgets.cpp | `imgui_widgets.cpp` | MultiSelectItemHeader（8117行目〜）でユーザーデータの参照を確認 |

**主要処理フロー**:
- **8126行目**: g.NextItemData.SelectionUserDataの読み取り
- **8127行目**: FocusScopeId一致のアサーション

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

```
SetNextItemSelectionUserData(selection_user_data)
    │
    ├─ g.NextItemData.SelectionUserData = selection_user_data
    │
    ├─ g.NextItemData.FocusScopeId = g.CurrentFocusScopeId
    │
    └─ [if g.CurrentMultiSelect]
          │
          ├─ g.NextItemData.ItemFlags |= HasSelectionUserData | IsMultiSelect
          │
          └─ [if ms->IO.RangeSrcItem == selection_user_data]
                └─ ms->RangeSrcPassedBy = true
```

### データフロー図

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

selection_user_data ─────────▶ SetNextItemSelectionUserData()
                                        │
                                        ├──▶ g.NextItemData.SelectionUserData
                                        │
g.CurrentFocusScopeId ─────────────────▶├──▶ g.NextItemData.FocusScopeId
                                        │
g.CurrentMultiSelect ──────────────────▶├──▶ g.NextItemData.ItemFlags
                                        │
                                        └──▶ ms->RangeSrcPassedBy
                                             (マルチセレクト時)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| imgui.h | `imgui.h` | ヘッダー | 公開API宣言、型定義 |
| imgui_widgets.cpp | `imgui_widgets.cpp` | ソース | SetNextItemSelectionUserData実装 |
| imgui_internal.h | `imgui_internal.h` | ヘッダー | NextItemData構造体定義 |
