# 機能設計書 41-SetNextWindowScroll

## 概要

本ドキュメントは、ImGuiライブラリにおける `SetNextWindowScroll` 関数の機能設計を記述する。この関数は、次に作成されるウィンドウのスクロール位置を事前に設定するために使用される。

### 本機能の処理概要

**業務上の目的・背景**：ImGuiでは、ウィンドウ内にコンテンツがウィンドウサイズを超える場合にスクロールが有効になる。通常、スクロール位置の設定は `SetScrollX`/`SetScrollY` を使用して `Begin()` と `End()` の間で行うが、これらの関数は次のフレームまで適用が遅延される。`SetNextWindowScroll` を使用することで、`Begin()` の前にスクロール位置を指定し、ウィンドウが開いた瞬間から指定位置にスクロールした状態で表示できる。これにより、スクロール位置変更時のちらつきや遅延を回避できる。

**機能の利用シーン**：
- チャットウィンドウで常に最新メッセージが表示されるよう、下端にスクロールする場合
- リスト表示で特定のアイテムが表示されるようスクロール位置を復元する場合
- 設定ファイルから保存されたスクロール位置を復元する場合
- 複数ウィンドウ間で同期したスクロール位置を設定する場合

**主要な処理内容**：
1. 引数で渡された `ImVec2` 型のスクロール値を `ImGuiContext` の `NextWindowData` に格納
2. フラグ `ImGuiNextWindowDataFlags_HasScroll` を設定して、スクロール設定があることを示す
3. 次の `Begin()` 呼び出し時に、このスクロール値がウィンドウに適用される
4. 負の値（< 0.0f）を指定した軸はスクロール位置の変更をスキップする

**関連システム・外部連携**：本機能はImGuiの内部システムのみで完結し、外部システムとの連携はない。

**権限による制御**：権限制御は存在しない。すべてのコンテキストで同様に動作する。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | 画面機能マッピングに該当なし |

## 機能種別

ウィンドウ操作 / 状態設定

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| scroll | const ImVec2& | Yes | スクロール位置 (x, y) | 負の値は該当軸のスクロールをスキップ |

### 入力データソース

プログラムコード内で直接指定

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| なし | void | 戻り値なし（状態設定のみ） |

### 出力先

ImGuiContext の NextWindowData.ScrollVal および NextWindowData.HasFlags に格納

## 処理フロー

### 処理シーケンス

```
1. SetNextWindowScroll(scroll) 呼び出し
   └─ ImGuiContext g の取得
2. フラグ設定
   └─ g.NextWindowData.HasFlags に ImGuiNextWindowDataFlags_HasScroll を追加
3. スクロール値の保存
   └─ g.NextWindowData.ScrollVal に scroll を格納
4. 次の Begin() 呼び出しで適用
   └─ ウィンドウ生成時に ScrollVal が参照され、スクロール位置が設定される
```

### フローチャート

```mermaid
flowchart TD
    A[SetNextWindowScroll 呼び出し] --> B[ImGuiContext 取得]
    B --> C[HasFlags に HasScroll フラグを追加]
    C --> D[NextWindowData.ScrollVal に scroll を保存]
    D --> E[関数終了]
    E --> F[後続の Begin で適用]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-41-01 | 負値スキップ | 負の値は該当軸のスクロール設定をスキップする | scroll.x < 0 または scroll.y < 0 の場合 |
| BR-41-02 | 遅延なし適用 | Begin() 前に呼び出すことで、フレーム遅延なくスクロール位置を設定 | 常時 |

### 計算ロジック

特になし

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| なし | - | 本関数はエラーを発生させない | - |

### リトライ仕様

リトライ不要

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

該当なし

## パフォーマンス要件

本関数は単純な値の設定のみを行い、O(1) の時間複雑度で完了する。

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

該当なし

## 備考

- `SetScrollX`/`SetScrollY` は `Begin()` と `End()` の間で呼び出す必要があり、変更は次のフレームで適用される
- 本関数は `Begin()` の前に呼び出し、フレーム遅延なくスクロール位置を設定する代替手段として提供されている

---

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

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

### 推奨読解順序

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

まず、スクロール設定を格納する NextWindowData 構造体を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | imgui_internal.h | `imgui_internal.h` | ImGuiNextWindowData 構造体の定義（1316-1341行目） |

**読解のコツ**: ImGuiNextWindowData 構造体の `HasFlags` フィールドはビットフラグで、どの設定が有効かを示す。`ScrollVal` フィールドに実際のスクロール位置が格納される。

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

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

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

**主要処理フロー**:
1. **8615行目**: ImGuiContext g を取得
2. **8616行目**: HasFlags に ImGuiNextWindowDataFlags_HasScroll フラグを追加
3. **8617行目**: NextWindowData.ScrollVal に引数 scroll を格納

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

公開APIとしての宣言を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | imgui.h | `imgui.h` | SetNextWindowScroll の宣言とコメント（480行目） |

**主要処理フロー**:
- **480行目**: `IMGUI_API void SetNextWindowScroll(const ImVec2& scroll);` - 負の値で軸をスキップ可能

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

```
ユーザーコード
    │
    ├─ SetNextWindowScroll(scroll)
    │      └─ g.NextWindowData.ScrollVal = scroll
    │      └─ g.NextWindowData.HasFlags |= HasScroll
    │
    └─ Begin("Window")
           └─ NextWindowData.ScrollVal を参照してスクロール位置を設定
```

### データフロー図

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

ImVec2 scroll ───▶ SetNextWindowScroll() ───▶ NextWindowData.ScrollVal
                                              NextWindowData.HasFlags

                         ▼

                   Begin() でウィンドウに適用
```

### 関連ファイル一覧

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