# 機能設計書 91-SeparatorText

## 概要

本ドキュメントはImGuiのSeparatorText機能について、その処理内容、入出力仕様、実装詳細を記述した機能設計書である。

### 本機能の処理概要

SeparatorTextは、水平線（セパレータ）とテキストを組み合わせて表示するウィジェット機能である。通常のセパレータ（Separator）に加えて、テキストラベルを中央付近に配置し、視覚的なセクション区切りを提供する。

**業務上の目的・背景**：GUIアプリケーションにおいて、フォームやプロパティエディタなどのコンテンツを論理的なセクションに分割し、ユーザーが情報を把握しやすくする必要がある。単なる空白やセパレータ線だけでは、セクションの意味が伝わりにくいため、テキスト付きのセパレータが求められる。本機能は、CollapsingHeaderほど目立たないが、明確にセクションを区切りたい場合に最適なUIコンポーネントである。

**機能の利用シーン**：プロパティエディタでカテゴリごとに設定項目を分ける場合、設定画面で「一般設定」「詳細設定」などのセクションを区切る場合、ツールウィンドウ内でグループ化されたコントロールを視覚的に分離する場合などに使用される。

**主要な処理内容**：
1. ラベルテキストのサイズを計算する
2. セパレータ全体の領域（バウンディングボックス）を確定する
3. テキストの左右に水平線を描画する
4. テキストをスタイルに従った位置に描画する
5. ログ出力が有効な場合は「---」形式でログにも出力する

**関連システム・外部連携**：ImGuiのDrawList描画システムと連携し、描画コマンドを発行する。スタイル設定（SeparatorTextPadding、SeparatorTextBorderSize、SeparatorTextAlign）により外観をカスタマイズ可能。

**権限による制御**：特になし。ウィンドウのSkipItems状態によって描画がスキップされる場合がある。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | SeparatorTextは画面機能マッピングに直接関連付けられていないが、Demo Window内のウィジェットセクション等で使用例が確認できる |

## 機能種別

描画処理 / UIウィジェット

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| label | const char* | Yes | 表示するテキストラベル | NULL終端文字列 |

### 入力データソース

- 呼び出し元からの直接指定（文字列リテラルまたは動的生成文字列）
- ImGuiStyleからのスタイル設定値

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| (なし) | void | 戻り値なし |

### 出力先

- ImDrawList（現在のウィンドウの描画リスト）
- ログバッファ（LogEnabled時）

## 処理フロー

### 処理シーケンス

```
1. ウィンドウの取得と状態チェック
   └─ GetCurrentWindow()で現在のウィンドウを取得
   └─ SkipItemsがtrueの場合は即座にreturn

2. SeparatorTextExの呼び出し
   └─ ID=0（インタラクティブでないため）
   └─ label終端位置を検出（FindRenderedTextEnd）
   └─ 追加幅=0.0f

3. テキストサイズの計算
   └─ CalcTextSize()でラベルの描画サイズを取得

4. 領域の確保
   └─ min_sizeを計算（ラベル幅+パディング、ラベル高さ+パディング）
   └─ ItemSize()で領域を確保
   └─ ItemAdd()で描画リストに追加

5. セパレータ線の描画
   └─ ラベルがある場合：左右に分割して2本の水平線を描画
   └─ ラベルがない場合：1本の水平線を描画

6. テキストの描画
   └─ RenderTextEllipsisでテキストを描画（省略対応）

7. ログ出力
   └─ LogEnabled時は「---」をログに出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始: SeparatorText] --> B{ウィンドウ取得}
    B --> C{SkipItems?}
    C -->|Yes| D[終了]
    C -->|No| E[SeparatorTextExを呼び出し]
    E --> F[テキストサイズ計算]
    F --> G[領域確保 ItemSize/ItemAdd]
    G --> H{ItemAdd成功?}
    H -->|No| D
    H -->|Yes| I{ラベルあり?}
    I -->|Yes| J[左側の水平線を描画]
    J --> K[右側の水平線を描画]
    K --> L[テキストを描画]
    I -->|No| M[1本の水平線を描画]
    L --> N{LogEnabled?}
    M --> N
    N -->|Yes| O[ログ出力 ---]
    N -->|No| D
    O --> D
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-91-01 | 線の太さ | SeparatorTextBorderSize（スタイル設定）に従う | 常時 |
| BR-91-02 | テキスト位置 | SeparatorTextAlignに従って水平・垂直位置を決定 | 常時 |
| BR-91-03 | 空ラベル処理 | ラベルが空の場合は線のみを描画 | label_size.x == 0 |

### 計算ロジック

- セパレータY座標: `(bb.Min.y + bb.Max.y) * 0.5f`（中央に配置）
- 左側線の終点X: `label_pos.x - style.ItemSpacing.x`
- 右側線の始点X: `label_pos.x + label_size.x + extra_w + style.ItemSpacing.x`

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

データベース操作なし（UI描画のみ）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 早期リターン | window->SkipItems == true | 描画をスキップ |
| - | 早期リターン | ItemAdd失敗 | 描画をスキップ |

### リトライ仕様

リトライ不要（フレームごとに再描画）

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

トランザクション管理なし（即時描画）

## パフォーマンス要件

- 単一フレーム内で複数回呼び出し可能
- テキストサイズの計算とDrawListへのコマンド追加のみのため軽量

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

- ラベル文字列の長さに制限なし（ただしRenderTextEllipsisで省略処理あり）

## 備考

- SeparatorTextExは内部関数として公開されており、IDとextra_widthを指定可能
- 将来的にドラッグ可能なセパレータテキストの実装が検討されている（コメント参照）

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | imgui.h | `imgui.h` | 627行目: SeparatorText関数のAPI宣言を確認 |
| 1-2 | imgui.h | `imgui.h` | ImGuiStyleのSeparatorTextPadding、SeparatorTextBorderSize、SeparatorTextAlignを確認 |

**読解のコツ**: ImGuiStyleの各メンバーは、ウィジェットの見た目を決定する重要なパラメータ。Separator系のスタイル設定を把握することで、描画ロジックの理解が深まる。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | imgui_widgets.cpp | `imgui_widgets.cpp` | 1755-1768行目: SeparatorText関数の実装 |

**主要処理フロー**:
1. **1757行目**: GetCurrentWindow()で現在のウィンドウを取得
2. **1758-1759行目**: SkipItemsチェック
3. **1767行目**: SeparatorTextExを呼び出し（実際の描画処理を委譲）

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | imgui_widgets.cpp | `imgui_widgets.cpp` | 1705-1753行目: SeparatorTextEx関数の実装 |

**主要処理フロー**:
- **1711行目**: CalcTextSizeでラベルサイズを計算
- **1715行目**: セパレータの太さを取得
- **1716-1717行目**: バウンディングボックスを計算
- **1719-1721行目**: ItemSize/ItemAddで領域を確保
- **1723-1725行目**: セパレータ線のY座標を計算
- **1734-1745行目**: ラベルありの場合の描画（2本の線+テキスト）
- **1746-1752行目**: ラベルなしの場合の描画（1本の線のみ）

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

```
ImGui::SeparatorText(label)
    │
    ├─ GetCurrentWindow()
    │      └─ 現在のウィンドウコンテキストを取得
    │
    ├─ FindRenderedTextEnd(label)
    │      └─ テキスト終端位置を検出
    │
    └─ SeparatorTextEx(0, label, label_end, 0.0f)
           │
           ├─ CalcTextSize()
           │      └─ ラベルのピクセルサイズを計算
           │
           ├─ ItemSize()
           │      └─ レイアウトで領域を確保
           │
           ├─ ItemAdd()
           │      └─ アイテムを描画リストに登録
           │
           ├─ GetColorU32(ImGuiCol_Separator)
           │      └─ セパレータ色を取得
           │
           ├─ DrawList->AddLine()
           │      └─ 水平線を描画
           │
           └─ RenderTextEllipsis()
                  └─ テキストを描画（必要に応じて省略）
```

### データフロー図

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

label (文字列) ─────────────> CalcTextSize ─────────────────> label_size
                                  │
ImGuiStyle ─────────────────> スタイル適用 ─────────────────> 描画パラメータ
 - SeparatorTextPadding           │
 - SeparatorTextBorderSize        │
 - SeparatorTextAlign             │
                                  │
                            領域計算・確保
                                  │
                            AddLine(左) ─────────────────────> DrawList
                            AddLine(右) ─────────────────────> DrawList
                            RenderTextEllipsis ──────────────> DrawList
                                  │
                            LogText (条件付き) ──────────────> LogBuffer
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| imgui.h | `imgui.h` | ヘッダー | SeparatorText APIの宣言、ImGuiStyle定義 |
| imgui_internal.h | `imgui_internal.h` | ヘッダー | SeparatorTextEx内部API宣言 |
| imgui_widgets.cpp | `imgui_widgets.cpp` | ソース | SeparatorText/SeparatorTextExの実装 |
| imgui.cpp | `imgui.cpp` | ソース | ItemSize、ItemAdd等のコア関数 |
