# 機能設計書 68-SetCursorScreenPos

## 概要

本ドキュメントは、Dear ImGuiライブラリにおける`SetCursorScreenPos`関数の機能設計を定義する。この関数は、現在のカーソル位置を画面絶対座標（スクリーン座標）で設定する。

### 本機能の処理概要

SetCursorScreenPos関数は、次にウィジェットが描画される位置を、画面全体での絶対座標で直接指定する。GetCursorScreenPosと対になる関数であり、ImGuiの公式ドキュメントで「YOUR BEST FRIEND」と呼ばれる最も推奨される位置設定関数である。

**業務上の目的・背景**：GUIアプリケーションでは、ウィジェットの描画位置を自由に制御したい場面がある。特にカスタムレイアウトやオーバーレイ表示、複雑なウィジェット配置において、画面絶対座標での位置指定が必要となる。SetCursorScreenPosはウィンドウのスクロールや位置に関係なく、画面上の任意の位置にカーソルを設定できる。

**機能の利用シーン**：
- カスタムレイアウトの実装
- ウィジェットを特定の画面位置に配置
- ImDrawListと組み合わせたカスタム描画
- 既存のレイアウトを上書きする特殊な配置

**主要な処理内容**：
1. 現在のウィンドウを取得
2. DC.CursorPosを指定された絶対座標に設定
3. IsSetPosフラグをtrueに設定

**関連システム・外部連携**：GetCursorScreenPosと対になる関数。内部レイアウトシステムと連携。

**権限による制御**：特になし。任意のウィンドウコンテキスト内で使用可能。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | 特定の画面に紐づかない汎用機能 |

## 機能種別

位置設定 / レイアウト制御

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| pos | const ImVec2& | Yes | カーソル位置（画面絶対座標、ピクセル単位） | 特になし |

### 入力データソース

- 呼び出し元からの直接パラメータ指定

## 出力仕様

### 出力データ

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

### 出力先

- ImGuiWindow::DC.CursorPos（カーソル位置、更新）
- ImGuiWindow::DC.IsSetPos（位置設定フラグ、trueに設定）

## 処理フロー

### 処理シーケンス

```
1. 現在のウィンドウを取得
   └─ ImGuiWindow* window = GetCurrentWindow()

2. カーソル位置を設定
   └─ window->DC.CursorPos = pos

3. 位置設定フラグを設定
   └─ window->DC.IsSetPos = true
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[GetCurrentWindow]
    B --> C[DC.CursorPos = pos]
    C --> D[DC.IsSetPos = true]
    D --> E[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-68-01 | 絶対座標 | 指定する座標は画面全体での絶対位置 | 常時 |
| BR-68-02 | 即時反映 | 設定した位置は次のウィジェット描画から即時に適用される | 常時 |
| BR-68-03 | IsSetPosフラグ | 位置が明示的に設定されたことを示すフラグが設定される | 常時 |

### 計算ロジック

特になし（直接代入のみ）

関連する座標変換：
```cpp
// ローカル座標から画面座標への変換
screen_pos = local_pos + window->Pos - window->Scroll
```

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | - | 特になし | - |

### リトライ仕様

該当なし

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

該当なし

## パフォーマンス要件

- O(1)の定数時間操作
- 単純な値の設定のみで非常に軽量

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

特になし

## 備考

- ImGuiコメントで「THIS IS YOUR BEST FRIEND」と記載されており、最も推奨される位置設定方法
- SetCursorPos()はウィンドウローカル座標を使用するが、こちらは画面絶対座標を使用する
- CursorMaxPosの更新はコメントアウトされている（将来の変更の可能性あり）

---

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

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

### 推奨読解順序

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

まず、カーソル位置に関連するデータ構造を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | imgui_internal.h | `imgui_internal.h` | ImGuiWindowTempData構造体内のCursorPos、IsSetPos定義（2590、2600行目） |

**読解のコツ**: CursorPosは「現在の出力位置（絶対座標）」を表す。IsSetPosは位置が明示的に設定されたかどうかを示すフラグ。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | imgui.h | `imgui.h` | SetCursorScreenPosの関数宣言（566行目）とコメント |

**主要処理フロー**:
1. **566行目**: 関数宣言と「THIS IS YOUR BEST FRIEND」というコメント

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | imgui.cpp | `imgui.cpp` | SetCursorScreenPos関数の実装（11386-11392行目） |

**主要処理フロー**:
- **11388行目**: GetCurrentWindow()で現在のウィンドウを取得
- **11389行目**: DC.CursorPosに座標を設定
- **11390行目**: コメントアウトされたCursorMaxPosの更新（将来の変更の可能性）
- **11391行目**: IsSetPosフラグをtrueに設定

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

```
SetCursorScreenPos(const ImVec2& pos)
    │
    └─ GetCurrentWindow()
           └─ 現在のウィンドウポインタを取得
                  │
                  ├─ window->DC.CursorPos = pos
                  │
                  └─ window->DC.IsSetPos = true
```

### データフロー図

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

ImVec2 pos ────────▶ SetCursorScreenPos() ────▶ DC.CursorPos（更新）
                           │
                           └──▶ DC.IsSetPos（true）
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| imgui.h | `imgui.h` | ヘッダ | 公開API宣言 |
| imgui.cpp | `imgui.cpp` | ソース | 関数実装 |
| imgui_internal.h | `imgui_internal.h` | ヘッダ | 内部データ構造定義 |
