# 機能設計書 118-VSliderFloat

## 概要

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

### 本機能の処理概要

VSliderFloatは、垂直方向に配置された浮動小数点数（float型）スライダーウィジェットを作成する機能である。通常のSliderFloatが水平方向であるのに対し、VSliderFloatは垂直方向にグラブ（つまみ）を移動させて値を調整する。オーディオミキサーのフェーダーやボリュームスライダーなど、縦型のインターフェースが適した場面で使用される。

**業務上の目的・背景**：オーディオ編集ソフトウェアのミキサー、エクイライザー、マルチチャンネルのボリュームコントロールなど、縦型のスライダーが標準的なUIパターンとして確立している分野がある。VSliderFloatはこれらのユースケースに対応するための専用ウィジェットを提供する。

**機能の利用シーン**：
- オーディオミキサーのチャンネルフェーダー
- イコライザーの周波数バンド調整
- 複数チャンネルのボリュームコントロール
- 縦型のゲージやインジケーターとしての使用

**主要な処理内容**：
1. ウィンドウとスタイルの取得、ウィジェットIDの生成
2. 指定されたサイズでフレーム領域を計算
3. マウスホバーとクリック検出によるアクティブ状態の制御
4. SliderBehavior関数の呼び出し（ImGuiSliderFlags_Verticalフラグを追加）
5. 垂直方向のグラブ位置計算と描画
6. 値の表示（上部に中央揃え）

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

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

## 関連画面

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

## 機能種別

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

## 入力仕様

### 入力パラメータ

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

### 入力データソース

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

## 出力仕様

### 出力データ

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

### 出力先

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

## 処理フロー

### 処理シーケンス

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

### フローチャート

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

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-118-1 | 垂直配置 | グラブは垂直方向に移動する（上=max、下=min） | 常時 |
| BR-118-2 | サイズ指定 | 幅と高さを明示的に指定する必要がある | 常時 |
| BR-118-3 | 範囲制限 | 値はv_minとv_maxの範囲内に制限される | 常時 |
| BR-118-4 | 値表示位置 | 値はスライダー上部に中央揃えで表示 | 常時 |
| BR-118-5 | ナビゲーション | Up/Downキーで値を調整（水平スライダーのLeft/Rightに相当） | キーボード操作時 |

### 計算ロジック

垂直スライダーのグラブ位置計算：

```
// 値から位置への変換（垂直スライダーでは反転）
grab_t = ScaleRatioFromValue(v, v_min, v_max, ...)
grab_t_vertical = 1.0f - grab_t  // 上がmax、下がminになるよう反転
grab_pos = slider_min + grab_t_vertical * slider_usable_sz

// グラブ矩形（X方向にパディング、Y方向にグラブサイズ）
grab_bb = ImRect(
    bb.Min.x + grab_padding,
    grab_pos - grab_sz * 0.5f,
    bb.Max.x - grab_padding,
    grab_pos + grab_sz * 0.5f
)
```

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

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

## エラー処理

### エラーケース一覧

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

### リトライ仕様

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

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

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

## パフォーマンス要件

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

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

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

## 備考

- VSliderFloatはテキスト入力モード（Ctrl+クリック）をサポートしていない
- 水平スライダーと異なり、サイズパラメータが必須である
- ナビゲーション時はUp/Downキーを使用する（Left/Rightではない）

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | imgui.h | `imgui.h` | VSliderFloat関数宣言（707行目） |
| 1-2 | imgui_widgets.cpp | `imgui_widgets.cpp` | VSliderFloat関数（3534-3537行目） |

**読解のコツ**: sizeパラメータが追加されている点に注目。これにより幅と高さを明示的に指定する。

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

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

**主要処理フロー**:
- **3484-3486行目**: フレーム領域の計算（sizeを使用）
- **3488-3490行目**: ItemSize/ItemAdd
- **3498-3506行目**: アクティブ状態制御（Up/Down方向）
- **3515行目**: SliderBehavior呼び出し（ImGuiSliderFlags_Vertical追加）
- **3520-3521行目**: 垂直グラブの描画（Y方向のサイズチェック）
- **3527行目**: 値の表示（上部に中央揃え）

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

```
VSliderFloat (imgui_widgets.cpp:3534)
    │
    └─ VSliderScalar (imgui_widgets.cpp:3474)
           │
           ├─ GetCurrentWindow()
           ├─ CalcTextSize()
           ├─ ItemSize() / ItemAdd()
           ├─ ItemHoverable()
           │
           ├─ RenderNavCursor() / RenderFrame()
           │
           └─ SliderBehavior (flags | ImGuiSliderFlags_Vertical)
                  └─ SliderBehaviorT<float>
                         └─ 垂直用のグラブ位置計算（1.0f - grab_t）
```

### データフロー図

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

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

### 関連ファイル一覧

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