# 機能設計書 115-SliderInt

## 概要

本ドキュメントは、Dear ImGuiライブラリにおける整数スライダー機能「SliderInt」の設計を詳細に記述したものである。

### 本機能の処理概要

SliderIntは、32ビット符号付き整数（int型）の値を視覚的なスライダーインターフェースで調整するウィジェットを作成する機能である。マウスでスライダーのグラブ（つまみ）をドラッグするか、スライダー上の任意の位置をクリックすることで値を設定できる。

**業務上の目的・背景**：ゲーム開発やツール開発において、インデックス、カウント、ピクセル単位の値など、整数パラメータを調整する場面は非常に多い。SliderIntは直感的で精密な整数値の調整インターフェースを提供する。SliderFloatとの違いは、グラブの移動が整数単位で離散的に行われ、小数点以下の値を持たない点である。

**機能の利用シーン**：
- 配列のインデックスを選択するとき
- アイテムの数量やカウントを設定するとき
- ピクセル単位のサイズや位置を調整するとき
- レベルや段階的なパラメータを設定するとき

**主要な処理内容**：
1. ウィンドウとスタイルの取得、ウィジェットIDの生成
2. フレーム領域とラベル領域の計算
3. マウスホバーとクリック検出によるアクティブ状態の制御
4. Ctrl+クリックでテキスト入力モードへ切り替え
5. SliderScalar関数の呼び出し（int型を指定）
6. グラブ（つまみ）の位置計算と描画

**関連システム・外部連携**：本機能は単体で動作し、外部システムとの直接的な連携はない。内部的にSliderScalarを呼び出し、SliderScalarはさらにSliderBehaviorを使用する。

**権限による制御**：ImGuiItemFlags_ReadOnlyフラグまたはImGuiSliderFlags_ReadOnlyフラグにより読み取り専用モードを設定可能。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 23 | Widgets | 主機能 | スライダーウィジェットのデモ表示 |

## 機能種別

インタラクティブウィジェット / ユーザー入力処理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| label | const char* | Yes | ウィジェットのラベル（ID生成にも使用） | NULL不可 |
| v | int* | Yes | 編集対象の値へのポインタ | NULL不可 |
| v_min | int | Yes | スライダーの最小値 | v_max未満を推奨 |
| v_max | int | Yes | スライダーの最大値 | v_min超を推奨 |
| format | const char* | No | 表示フォーマット文字列（デフォルト: "%d"） | printf形式 |
| flags | ImGuiSliderFlags | No | 動作制御フラグ（デフォルト: 0） | 有効なフラグの組み合わせ |

### 入力データソース

ユーザーからのマウス操作（クリック・ドラッグ）およびキーボード入力（テキスト入力モード時、矢印キーによる微調整）。

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 戻り値 | bool | 値が変更された場合true |
| *v | int | 更新されたスライダー値 |

### 出力先

呼び出し元への戻り値、およびvが指すメモリ領域への値の書き込み。

## 処理フロー

### 処理シーケンス

```
1. SliderScalarを呼び出し
   └─ data_type = ImGuiDataType_S32, p_min = &v_min, p_max = &v_max
2. SliderScalar内部処理
   ├─ ウィンドウ取得とスキップ判定
   ├─ ID生成と領域計算
   ├─ ItemSizeとItemAddの呼び出し
   ├─ ホバー・クリック検出とアクティブ状態制御
   ├─ テキスト入力モードの判定と処理
   ├─ フレームの描画
   ├─ SliderBehaviorの呼び出し（グラブ位置計算と値更新）
   ├─ グラブの描画
   └─ 値とラベルの表示
3. 結果を返却
```

### フローチャート

```mermaid
flowchart TD
    A[SliderInt呼び出し] --> B[SliderScalar呼び出し]
    B --> C{window->SkipItems?}
    C -->|Yes| D[return false]
    C -->|No| E[ID生成と領域計算]
    E --> F[ItemSize/ItemAdd]
    F --> G{ItemAdd成功?}
    G -->|No| D
    G -->|Yes| H[ホバー・クリック検出]
    H --> I{テキスト入力モード?}
    I -->|Yes| J[TempInputScalar]
    J --> K[return 結果]
    I -->|No| L[フレーム描画]
    L --> M[SliderBehavior]
    M --> N[グラブ描画]
    N --> O[値とラベル表示]
    O --> P[return value_changed]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-115-1 | 範囲制限 | 値は常にv_minとv_maxの範囲内に制限される | 常時 |
| BR-115-2 | 整数単位 | 値は整数単位でのみ変化する（小数点以下は存在しない） | 常時 |
| BR-115-3 | グラブサイズ | 整数スライダーでは、グラブのサイズが1単位を表現する | 範囲が狭い場合 |
| BR-115-4 | デフォルト表示 | デフォルトで整数を10進数で表示 | format未指定時 |

### 計算ロジック

整数スライダーのグラブサイズ計算：

```
v_range = v_max - v_min + 1  // +1は整数の離散性を考慮
grab_sz = max(slider_sz / v_range, style.GrabMinSize)
grab_sz = min(grab_sz, slider_sz)
```

マウス位置から値への変換（整数の場合）：

```
t = (mouse_pos - slider_min) / slider_usable_sz  // 0.0〜1.0の比率
v_new_off = (v_max - v_min) * t
result = v_min + round(v_new_off)  // 四捨五入で整数化
```

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | アサーション | 無効なImGuiSliderFlagsが渡された場合 | 正しいフラグ値を使用する |
| - | アサーション | WrapAroundフラグが設定された場合 | SliderではWrapAroundは非対応 |
| - | アサーション | v_min/v_maxがS32_MAX/2を超える場合 | 適切な範囲を設定する |

### リトライ仕様

本機能はユーザー入力ウィジェットであり、リトライは適用されない。

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

本機能はトランザクション処理を行わない。

## パフォーマンス要件

フレームごとに呼び出されるため、軽量な処理が求められる。SliderScalarは単純なラッパーであり、オーバーヘッドは最小限。

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

- format文字列の検証は呼び出し側の責任
- 値の範囲外入力はAlwaysClampフラグで防止可能

## 備考

- SliderInt2/3/4は複数コンポーネント版で、内部でSliderScalarNを呼び出す
- 垂直スライダーが必要な場合はVSliderIntを使用する
- 16ビットや64ビット整数が必要な場合はSliderScalarを直接使用する

---

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

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

### 推奨読解順序

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

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

**読解のコツ**: デフォルトフォーマット"%d"に注目。整数表示であることが明示されている。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | imgui_widgets.cpp | `imgui_widgets.cpp` | SliderInt関数（3454-3457行目） |

**主要処理フロー**:
1. **3454-3457行目**: SliderScalarへの単純なラッパー呼び出し（ImGuiDataType_S32を指定）

#### Step 3: 整数特有の処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | imgui_widgets.cpp | `imgui_widgets.cpp` | SliderBehaviorT（3095-3097行目）のグラブサイズ計算 |
| 3-2 | imgui_widgets.cpp | `imgui_widgets.cpp` | ScaleValueFromRatioT（3060-3073行目）の整数処理 |

**主要処理フロー**:
- **3095-3096行目**: 整数スライダーのグラブサイズ計算（1単位を表現）
- **3065-3072行目**: 整数の場合の値計算（四捨五入処理）

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

```
SliderInt (imgui_widgets.cpp:3454)
    │
    └─ SliderScalar (imgui_widgets.cpp:3295)
           │
           ├─ GetCurrentWindow()
           ├─ CalcTextSize()
           ├─ ItemSize() / ItemAdd()
           ├─ ItemHoverable()
           │
           ├─ TempInputScalar() [テキスト入力モード時]
           │
           ├─ RenderNavCursor() / RenderFrame()
           │
           └─ SliderBehavior (imgui_widgets.cpp:3257)
                  └─ SliderBehaviorT<ImS32> (imgui_widgets.cpp:3080)
                         ├─ ScaleRatioFromValueT()
                         └─ ScaleValueFromRatioT()
```

### データフロー図

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

v (値へのポインタ)
v_min, v_max
       │
       ▼
マウスクリック ────────▶ SliderBehavior ───────▶ 更新された値 (*v)
マウスドラッグ                │
       │                     ▼
       │              整数に丸め処理 ─────────▶ 整数値
       │
format ──────────────▶ 値のフォーマット ────▶ "%d"形式で表示
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| imgui.h | `imgui.h` | ヘッダー | SliderInt関数宣言 |
| imgui_internal.h | `imgui_internal.h` | ヘッダー | 内部関数宣言 |
| imgui_widgets.cpp | `imgui_widgets.cpp` | ソース | SliderInt/SliderScalar/SliderBehaviorの実装 |
