# 機能設計書 117-SliderScalar

## 概要

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

### 本機能の処理概要

SliderScalarは、任意のデータ型（8/16/32/64ビットの整数・符号なし整数、単精度・倍精度浮動小数点数）に対応した汎用スライダーウィジェットを作成する機能である。SliderFloat/SliderIntなどの型固有のスライダーは全てこの関数を内部で呼び出している、スライダーウィジェットのコア実装である。

**業務上の目的・背景**：SliderScalarは、データ型に依存しない汎用的なスライダーインターフェースを提供する。開発者がカスタムデータ型（8ビット整数、64ビット整数など）でスライダーを使用する場合や、型情報に基づいて動的にウィジェットを生成するプロパティエディタを実装する場合に不可欠な機能である。

**機能の利用シーン**：
- 8ビットや16ビットの整数値を調整するとき
- 64ビット整数や倍精度浮動小数点数を調整するとき
- 汎用的なプロパティエディタを実装するとき
- データ型に基づいて動的にウィジェットを生成するとき

**主要な処理内容**：
1. ウィンドウとスタイルの取得、ウィジェットIDの生成
2. フレーム領域とラベル領域の計算
3. マウスホバーとクリック検出によるアクティブ状態の制御
4. Ctrl+クリックでテキスト入力モードへ切り替え
5. SliderBehavior関数によるスライダー操作の処理
6. グラブの位置計算と描画、値の表示

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

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

## 関連画面

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

## 機能種別

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

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| label | const char* | Yes | ウィジェットのラベル（ID生成にも使用） | NULL不可 |
| data_type | ImGuiDataType | Yes | データ型の指定 | 有効な列挙値 |
| p_data | void* | Yes | 編集対象の値へのポインタ | NULL不可 |
| p_min | const void* | Yes | 最小値へのポインタ | data_typeに対応した型 |
| p_max | const void* | Yes | 最大値へのポインタ | data_typeに対応した型 |
| format | const char* | No | 表示フォーマット文字列（NULL時はデータ型のデフォルト） | printf形式 |
| flags | ImGuiSliderFlags | No | 動作制御フラグ（デフォルト: 0） | 有効なフラグの組み合わせ |

### 入力データソース

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

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 戻り値 | bool | 値が変更された場合true |
| *p_data | void* | 更新されたスカラー値（p_dataが指す領域） |

### 出力先

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

## 処理フロー

### 処理シーケンス

```
1. ウィンドウ取得とスキップ判定
   └─ window->SkipItemsがtrueの場合は即座にfalseを返却
2. コンテキストとスタイルの取得
3. IDの生成と領域計算
4. ItemSizeとItemAddの呼び出し
5. デフォルトフォーマット文字列の設定
   └─ formatがNULLの場合、データ型に応じたデフォルトフォーマットを使用
6. ホバー・クリック検出とアクティブ状態制御
7. テキスト入力モードの判定と処理
   └─ Ctrl+クリックでTempInputScalarを呼び出し
8. フレームの描画
9. SliderBehaviorの呼び出し
   └─ グラブ位置計算と値の更新処理
10. グラブの描画
11. 値とラベルの表示
12. 結果を返却
```

### フローチャート

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

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-117-1 | 型安全 | p_data、p_min、p_maxはdata_typeで指定した型のポインタである必要がある | 常時 |
| BR-117-2 | 必須範囲 | スライダーではp_min、p_maxは必須（DragScalarとは異なる） | 常時 |
| BR-117-3 | 範囲制限 | 32ビット以上の型では、範囲は型の最大値の半分以内に制限 | 32/64ビット型使用時 |
| BR-117-4 | 対数スケール | Logarithmicフラグ設定時、対数スケールでグラブ位置を計算 | Logarithmicフラグ設定時 |

### 計算ロジック

SliderBehaviorTテンプレート関数で型ごとに最適化された処理を実行。

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

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

## エラー処理

### エラーケース一覧

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

### リトライ仕様

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

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

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

## パフォーマンス要件

フレームごとに呼び出されるため、軽量な処理が求められる。テンプレート関数を使用して型ごとに最適化されている。

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

- format文字列の検証は呼び出し側の責任
- 型とポインタの整合性は呼び出し側の責任

## 備考

- SliderFloat、SliderInt等の高レベルAPIは内部でSliderScalarを呼び出している
- SliderScalarNは複数コンポーネント版

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | imgui.h | `imgui.h` | ImGuiDataType列挙型、SliderScalar関数宣言（705行目） |
| 1-2 | imgui_internal.h | `imgui_internal.h` | ImGuiDataTypeInfo構造体とGDataTypeInfo配列 |

**読解のコツ**: DragScalarと異なり、p_minとp_maxが必須パラメータであることに注目。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | imgui_widgets.cpp | `imgui_widgets.cpp` | SliderScalar関数（3295-3383行目） |
| 2-2 | imgui_widgets.cpp | `imgui_widgets.cpp` | SliderBehavior関数（3257-3291行目） |
| 2-3 | imgui_widgets.cpp | `imgui_widgets.cpp` | SliderBehaviorTテンプレート（3080-3252行目） |

**主要処理フロー**:
- **3297-3299行目**: ウィンドウ取得とスキップ判定
- **3316-3318行目**: デフォルトフォーマット設定
- **3320-3344行目**: ホバー・クリック検出
- **3361-3365行目**: SliderBehavior呼び出し
- **3367-3369行目**: グラブ描画
- **3371-3376行目**: 値表示

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

```
SliderScalar (imgui_widgets.cpp:3295)
    │
    ├─ GetCurrentWindow()
    ├─ CalcTextSize()
    ├─ ItemSize() / ItemAdd()
    ├─ ItemHoverable()
    │
    ├─ TempInputScalar() [テキスト入力モード時]
    │
    ├─ RenderNavCursor() / RenderFrame() / RenderFrameBorder()
    │
    └─ SliderBehavior (imgui_widgets.cpp:3257)
           │
           └─ SliderBehaviorT<TYPE> (imgui_widgets.cpp:3080)
                  │ [型に応じて適切なテンプレートインスタンス]
                  │ - SliderBehaviorT<ImS8>
                  │ - SliderBehaviorT<ImU8>
                  │ - SliderBehaviorT<ImS16>
                  │ - SliderBehaviorT<ImU16>
                  │ - SliderBehaviorT<ImS32>
                  │ - SliderBehaviorT<ImU32>
                  │ - SliderBehaviorT<ImS64>
                  │ - SliderBehaviorT<ImU64>
                  │ - SliderBehaviorT<float>
                  │ - SliderBehaviorT<double>
                  │
                  ├─ ScaleRatioFromValueT()
                  └─ ScaleValueFromRatioT()
```

### データフロー図

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

p_data (値へのポインタ)
data_type
p_min, p_max
       │
       ▼
マウスクリック ────────▶ SliderBehavior ───────▶ 更新された値 (*p_data)
マウスドラッグ                │
       │                     ▼
       │              型に応じた処理 ─────────▶ 適切な型での値更新
       │                (テンプレート)
       │
format ──────────────▶ DataTypeFormatString ──▶ 値の表示
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| imgui.h | `imgui.h` | ヘッダー | SliderScalar関数宣言、ImGuiDataType定義 |
| imgui_internal.h | `imgui_internal.h` | ヘッダー | ImGuiDataTypeInfo、GDataTypeInfo |
| imgui_widgets.cpp | `imgui_widgets.cpp` | ソース | SliderScalar/SliderBehavior/SliderBehaviorTの実装 |
