# 機能設計書 119-VSliderInt

## 概要

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

### 本機能の処理概要

VSliderIntは、垂直方向に配置された整数（int型）スライダーウィジェットを作成する機能である。VSliderFloatの整数版であり、グラブの移動は整数単位で離散的に行われる。

**業務上の目的・背景**：オーディオのステップ数設定、離散的なレベル選択、チャンネル番号の選択など、整数値を縦型のインターフェースで調整する必要がある場面で使用される。VSliderFloatとの違いは、値が整数単位で変化し、小数点以下の値を持たない点である。

**機能の利用シーン**：
- 離散的なステップ数の設定
- レベルやランクの選択
- 複数チャンネルのインデックス選択
- 縦型のスイッチやセレクターとしての使用

**主要な処理内容**：
1. VSliderScalarを呼び出し（int型を指定）
2. 垂直方向のスライダー処理
3. 整数単位でのグラブ位置計算と描画

**関連システム・外部連携**：本機能は単体で動作し、外部システムとの直接的な連携はない。

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

## 関連画面

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

## 機能種別

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

## 入力仕様

### 入力パラメータ

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

### 入力データソース

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

## 出力仕様

### 出力データ

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

### 出力先

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

## 処理フロー

### 処理シーケンス

```
1. VSliderScalarを呼び出し
   └─ data_type = ImGuiDataType_S32, size = size引数
2. VSliderScalar内部処理
   ├─ ウィンドウ取得とスキップ判定
   ├─ ID生成と領域計算
   ├─ ホバー・クリック検出とアクティブ状態制御
   ├─ フレームの描画
   ├─ SliderBehavior呼び出し（Verticalフラグ + 整数処理）
   ├─ 垂直グラブの描画
   └─ 値とラベルの表示
3. 結果を返却
```

### フローチャート

```mermaid
flowchart TD
    A[VSliderInt呼び出し] --> B[VSliderScalar呼び出し]
    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 --> J["SliderBehavior (Vertical + S32)"]
    J --> K[垂直グラブ描画]
    K --> L[値とラベル表示]
    L --> M[return value_changed]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-119-1 | 垂直配置 | グラブは垂直方向に移動する（上=max、下=min） | 常時 |
| BR-119-2 | 整数単位 | 値は整数単位でのみ変化する | 常時 |
| BR-119-3 | 範囲制限 | 値はv_minとv_maxの範囲内に制限される | 常時 |
| BR-119-4 | グラブサイズ | 整数スライダーでは、グラブのサイズが1単位を表現する | 範囲が狭い場合 |

### 計算ロジック

VSliderFloatと同様の構造だが、内部でImGuiDataType_S32を使用して整数処理を行う。グラブサイズは整数の離散性を考慮して計算される。

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | アサーション | 無効なフラグが渡された場合 | 正しいフラグ値を使用する |

### リトライ仕様

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

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

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

## パフォーマンス要件

フレームごとに呼び出されるため、軽量な処理が求められる。

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

- format文字列の検証は呼び出し側の責任

## 備考

- VSliderIntはテキスト入力モードをサポートしていない
- サイズパラメータが必須である点はVSliderFloatと同様

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | imgui.h | `imgui.h` | VSliderInt関数宣言（708行目） |
| 1-2 | imgui_widgets.cpp | `imgui_widgets.cpp` | VSliderInt関数（3539-3542行目） |

**読解のコツ**: VSliderFloatとの違いはImGuiDataType_S32を指定する点のみ。

#### Step 2: 実際の処理を理解する

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

**主要処理フロー**:
- VSliderFloatと共通のVSliderScalar関数を使用
- data_type = ImGuiDataType_S32により整数処理が適用される

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

```
VSliderInt (imgui_widgets.cpp:3539)
    │
    └─ VSliderScalar (imgui_widgets.cpp:3474)
           │
           ├─ GetCurrentWindow()
           ├─ ItemSize() / ItemAdd()
           ├─ ItemHoverable()
           │
           ├─ RenderNavCursor() / RenderFrame()
           │
           └─ SliderBehavior (flags | ImGuiSliderFlags_Vertical)
                  └─ SliderBehaviorT<ImS32>
                         └─ 整数用処理 + 垂直反転
```

### データフロー図

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

v (値へのポインタ)
v_min, v_max
size (幅×高さ)
       │
       ▼
マウスクリック ────────▶ SliderBehavior ───────▶ 更新された整数値 (*v)
マウスドラッグ               │ (Vertical + S32)
       │                     ▼
       │              整数単位で離散化 ────────▶ 垂直グラブ位置
       │
Up/Down キー ─────────▶ 整数単位で増減 ────────▶ 値更新
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| imgui.h | `imgui.h` | ヘッダー | VSliderInt関数宣言 |
| imgui_widgets.cpp | `imgui_widgets.cpp` | ソース | VSliderInt/VSliderScalarの実装 |
