# 機能設計書 109-DragInt

## 概要

本ドキュメントは、ImGuiライブラリにおける`DragInt`関数の機能設計を記載する。

### 本機能の処理概要

`DragInt`関数は、マウスドラッグによって整数値を調整できるスライダーウィジェットを作成する関数である。`DragFloat`の整数版として、ユーザーはウィジェットをドラッグして値を増減させたり、Ctrl+クリックで直接数値入力モードに切り替えたりできる。整数専用のため、小数点以下の精度は不要なケース（カウント値、インデックス、ピクセル単位の値など）に適している。

**業務上の目的・背景**：整数値の入力は多くのアプリケーションで必要とされる。例えば、配列のインデックス、繰り返し回数、ピクセル単位のサイズ指定、離散的な設定値などがある。DragIntは、これらの整数値を直感的にドラッグ操作で調整でき、必要に応じてキーボード入力も可能な柔軟なウィジェットを提供する。DragFloatと同様のインターフェースを持ち、一貫したユーザー体験を実現する。

**機能の利用シーン**：
- 配列サイズやバッファサイズの設定
- 繰り返し回数・イテレーション数の指定
- ピクセル単位のサイズ・位置指定
- レイヤー番号・優先度の設定
- 離散的なレベル・段階の選択
- シードやID値の入力

**主要な処理内容**：
1. DragScalarを整数型（ImGuiDataType_S32）で呼び出し
2. 以下はDragScalarと同様の処理:
   - ウィジェットのバウンディングボックスとIDを計算
   - マウスホバー状態を確認
   - クリック/ダブルクリック/ナビゲーション操作を判定
   - Ctrl+クリックまたはダブルクリックで一時入力モードに遷移
   - ドラッグ中は速度に基づいて値を変更
   - フレームとテキストを描画
3. 値が変更された場合trueを返す

**関連システム・外部連携**：
- DragScalar: 汎用スカラードラッグ（内部呼び出し）
- TempInputScalar: 一時的なテキスト入力モード
- スタイルシステム: FramePadding, FrameRounding

**権限による制御**：特になし（GUI描画機能のため）

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 23 | Widgets | 主機能 | 整数ドラッグスライダーのデモ |

## 機能種別

ウィジェット描画処理 / 入力処理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| label | const char* | Yes | ウィジェットのラベル | NULL不可 |
| v | int* | Yes | 編集対象の値へのポインタ | 有効なポインタ |
| v_speed | float | No | ドラッグ速度係数（デフォルト: 1.0f） | 正の値推奨 |
| v_min | int | No | 最小値（デフォルト: 0） | v_min >= v_maxで無制限 |
| v_max | int | No | 最大値（デフォルト: 0） | v_min >= v_maxで無制限 |
| format | const char* | No | 表示フォーマット（デフォルト: "%d"） | printf形式 |
| flags | ImGuiSliderFlags | No | スライダーフラグ（デフォルト: 0） | 有効なフラグ |

### 入力データソース

- ユーザー指定のパラメータ（関数引数）
- マウス入力（ドラッグ、クリック）
- キーボード入力（Ctrl、テキスト入力モード時）
- ImGuiスタイル設定

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 戻り値 | bool | 値が変更された場合true |
| v | int* | 変更後の値（変更時に更新） |

### 出力先

- vパラメータ（値の更新）
- ImDrawList（描画コマンドリスト）

## 処理フロー

### 処理シーケンス

```
1. DragScalar呼び出し
   └─ DragInt は DragScalar のラッパー
   └─ データ型: ImGuiDataType_S32
2. DragScalar内処理（DragFloatと同様）:
   2-1. ウィンドウ・ID・バウンディングボックス計算
   2-2. 一時入力許可判定
   2-3. アイテム登録（ItemSize, ItemAdd）
   2-4. フォーマット文字列設定（NULLなら"%d"）
   2-5. ホバー状態取得
   2-6. 入力モード判定
        └─ Ctrl+クリック or ダブルクリック → 一時入力モード
        └─ 通常クリック → アクティブ化
   2-7. 一時入力モードの場合
        └─ TempInputScalar呼び出し
   2-8. ドラッグモードの場合
        └─ DragBehavior で値を更新
   2-9. フレーム・値テキスト描画
3. 戻り値を返す
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[DragScalar呼び出し]
    B --> C{SkipItems?}
    C -->|Yes| D[return false]
    C -->|No| E[ID・BB計算]
    E --> F[ItemSize/ItemAdd]
    F --> G{ItemAdd成功?}
    G -->|No| D
    G -->|Yes| H[ホバー・クリック判定]
    H --> I{Ctrl+Click/DoubleClick?}
    I -->|Yes| J[TempInputScalar]
    I -->|No| K{クリック?}
    K -->|Yes| L[アクティブ化]
    K -->|No| M[DragBehavior]
    L --> M
    J --> N[フレーム・テキスト描画]
    M --> N
    N --> O[return value_changed]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-109-1 | 無制限モード | v_min >= v_maxの場合、値のクランプなし | 常時 |
| BR-109-2 | 一時入力モード | Ctrl+クリック or ダブルクリックでテキスト入力 | NoInputフラグなし |
| BR-109-3 | クランプ判定 | AlwaysClampフラグで手動入力時もクランプ | フラグ設定時 |
| BR-109-4 | フォーマットデフォルト | formatがNULLの場合"%d"を使用 | 常時 |
| BR-109-5 | 整数型処理 | ImGuiDataType_S32（符号付き32ビット整数）として処理 | 常時 |

### 計算ロジック

ドラッグ速度計算（概要）:
```cpp
// マウスドラッグ距離 * 速度係数 = 値の変化量
// 整数なので最終的に整数に丸められる
// 修飾キーで速度調整:
// - Shift: 遅い
// - Alt: さらに遅い
```

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

該当なし（GUI描画機能のためデータベース操作は行わない）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 描画スキップ | window->SkipItemsがtrue | falseを返して終了 |
| - | アサート警告 | 無効なフラグ組み合わせ | 開発時に警告表示 |

### リトライ仕様

リトライなし（フレーム単位の描画・インタラクション処理のため）

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

該当なし

## パフォーマンス要件

- 単一フレーム内で複数呼び出し可能
- ドラッグ動作はフレームごとに処理

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

- 特になし（GUI描画機能のため）

## 備考

- DragFloatと同様のインターフェースを持つ
- 速度（v_speed）はfloat型で、精密なドラッグ速度調整が可能
- 対数スケール（Logarithmic）フラグも使用可能だが、整数では効果が限定的

---

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

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

### 推奨読解順序

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

処理の起点となる関数を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | imgui.h | `imgui.h` | 682行目: DragInt関数の宣言 |
| 1-2 | imgui_widgets.cpp | `imgui_widgets.cpp` | 2879-2882行目: DragInt関数の実装 |

**主要処理フロー**:
- **2881行目**: DragScalarにImGuiDataType_S32で委譲

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

DragScalarの処理を確認する（DragFloatと共通）。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | imgui_widgets.cpp | `imgui_widgets.cpp` | 2685-2785行目: DragScalar実装 |

**読解のコツ**:
- DragIntはDragFloatとほぼ同じ処理
- 違いはデータ型（S32 vs Float）とデフォルトフォーマット（%d vs %.3f）

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

```
ImGui::DragInt()
    │
    └─ ImGui::DragScalar(data_type = ImGuiDataType_S32)
           │
           ├─ GetCurrentWindow()
           ├─ window->GetID()
           ├─ CalcItemWidth()
           ├─ ItemSize()
           ├─ ItemAdd()
           ├─ ItemHoverable()
           │
           ├─ [一時入力モード]
           │      └─ TempInputScalar()
           │
           ├─ [ドラッグモード]
           │      └─ DragBehavior()
           │
           └─ 描画処理
                  ├─ RenderNavCursor()
                  ├─ RenderFrame()
                  └─ RenderTextClipped()
```

### データフロー図

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

label       ───┐
v (int*)    ───┼──▶ DragInt()
v_speed     ───┤         │
v_min/v_max ───┤         ▼
format      ───┤    DragScalar()
flags       ───┘    (S32型)
                         │
マウスドラッグ ────────▶│
                         │
                         ▼
                    v更新 + bool戻り値 + 描画
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| imgui.h | `imgui.h` | ヘッダー | DragInt宣言 |
| imgui_widgets.cpp | `imgui_widgets.cpp` | ソース | DragInt, DragScalar実装 |
| imgui_internal.h | `imgui_internal.h` | ヘッダー | DragBehavior, TempInputScalar等 |
