# 機能設計書 90-BulletText

## 概要

本ドキュメントは、Dear ImGuiライブラリにおけるBulletText関数の機能設計を定義する。BulletTextは、小さな円形のビュレット（箇条書き記号）付きでフォーマットテキストを表示する機能である。

### 本機能の処理概要

BulletText関数は、テキストの前に小さな円形のビュレット記号を描画し、ツリーノードと同じインデント位置にテキストを配置する機能を提供する。リストや箇条書きの作成に使用される。

**業務上の目的・背景**：GUIアプリケーションにおいて、情報をリスト形式で整理して表示することは読みやすさを向上させる重要な手法である。BulletTextを使用することで、ヘルプテキスト、機能リスト、注意事項などを箇条書き形式で表示でき、ユーザーが情報を素早く把握できるようになる。TreeNodeと同じインデントを使用するため、階層構造と組み合わせても視覚的な一貫性が保たれる。

**機能の利用シーン**：
- ヘルプテキストやユーザーガイドを箇条書きで表示する場合
- 機能リストや特徴一覧を表示する場合
- 注意事項や警告を箇条書きで表示する場合
- Aboutウィンドウでのバージョン情報や機能リスト表示
- ドキュメントやチュートリアルの説明文

**主要な処理内容**：
1. 現在のウィンドウとスタイルを取得
2. フォーマット文字列から表示テキストを生成
3. テキストサイズを計算
4. ビュレットとテキストを含む領域を計算
5. ItemSize/ItemAddでアイテム領域を確保
6. ビュレットを描画（RenderBullet）
7. テキストを描画（RenderText）

**関連システム・外部連携**：ImGuiContext、ImGuiStyle、ImDrawList

**権限による制御**：なし。すべてのImGuiユーザーが利用可能。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 5 | About Window | 補助機能 | 機能リストのビュレット表示 |
| 7 | User Guide | 主機能 | 操作説明のビュレット表示 |

## 機能種別

表示機能 / テキストウィジェット

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| fmt | const char* | Yes | printf形式のフォーマット文字列 | NULLチェックなし |
| ... | 可変長引数 | No | フォーマット引数 | フォーマット文字列に対応 |

### 入力データソース

- 呼び出し元コードからの直接入力
- 現在のフォントサイズ（g.FontSize）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| (なし) | void | 戻り値なし。描画コマンドが生成される |

### 出力先

ImDrawList（ウィンドウの描画リスト）

## 処理フロー

### 処理シーケンス

```
1. 可変長引数の初期化
   └─ va_start(args, fmt)
2. BulletTextV関数の呼び出し
   └─ 実際の処理をBulletTextVに委譲
3. 可変長引数の終了
   └─ va_end(args)

BulletTextV内部処理:
4. ウィンドウとスタイルの取得
   └─ GetCurrentWindow()、g.Style
5. テキストのフォーマット
   └─ ImFormatStringToTempBufferV
6. テキストサイズの計算
   └─ CalcTextSize
7. 全体サイズの計算
   └─ g.FontSize + (label_size.x > 0 ? style.FramePadding.x * 2 : 0)
8. カーソル位置の調整
   └─ CurrLineTextBaseOffset考慮
9. ItemSize/ItemAdd
   └─ アイテム領域の確保と登録
10. ビュレットの描画
    └─ RenderBullet（円形）
11. テキストの描画
    └─ RenderText
```

### フローチャート

```mermaid
flowchart TD
    A[BulletText開始] --> B[va_start]
    B --> C[BulletTextV呼び出し]
    C --> D[GetCurrentWindow]
    D --> E{SkipItems?}
    E -->|Yes| F[リターン]
    E -->|No| G[フォーマット処理]
    G --> H[CalcTextSize]
    H --> I[全体サイズ計算]
    I --> J[カーソル位置調整]
    J --> K[ItemSize/ItemAdd]
    K --> L{ItemAdd成功?}
    L -->|No| M[リターン]
    L -->|Yes| N[RenderBullet]
    N --> O[RenderText]
    O --> P[va_end]
    P --> Q[終了]
    F --> Q
    M --> Q
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | ビュレット位置 | ビュレットはフォントサイズの半分の位置に中心を配置 | 常時 |
| BR-02 | テキスト位置 | テキストはTreeNodeと同じインデント位置に配置 | 常時 |
| BR-03 | 空テキスト | テキストが空の場合はパディングなし | label_size.x == 0 |
| BR-04 | ビュレット色 | ImGuiCol_Textの色でビュレットを描画 | 常時 |

### 計算ロジック

- **ビュレット中心X**: bb.Min.x + style.FramePadding.x + g.FontSize * 0.5f
- **ビュレット中心Y**: bb.Min.y + g.FontSize * 0.5f
- **テキスト開始X**: bb.Min.x + g.FontSize + style.FramePadding.x * 2
- **全体幅**: g.FontSize + (テキストがある場合: label_size.x + style.FramePadding.x * 2)

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

該当なし（メモリ内操作のみ）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | - | 通常エラーは発生しない | - |

### リトライ仕様

該当なし

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

該当なし

## パフォーマンス要件

- フォーマット処理のオーバーヘッドあり
- ビュレット描画（円形）のオーバーヘッドあり（微小）
- 1フレーム内で多数回呼び出し可能

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

- Text関数と同様、ユーザー入力をフォーマット文字列として直接使用しないこと

## 備考

- Bullet() + Text() のショートカットとして動作
- BulletTextVはva_list版
- IM_FMTARGS(1)マクロによりコンパイラのフォーマット文字列チェックが有効
- TreeNodeと同じインデントを使用するため、ツリー構造内で使用すると自然な見た目になる

---

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

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

### 推奨読解順序

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

描画関連の構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | imgui.h | `imgui.h` | ImGuiStyle構造体（FramePadding） |
| 1-2 | imgui_internal.h | `imgui_internal.h` | RenderBullet関数の役割 |

**読解のコツ**: ビュレットはImDrawList::AddCircleFilledで描画される円形のマーカーである。

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

BulletText関数の実装を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | imgui.h | `imgui.h` | BulletText/BulletTextV関数宣言（625-626行目） |
| 2-2 | imgui_widgets.cpp | `imgui_widgets.cpp` | BulletText/BulletTextV関数実装（419-452行目） |

**主要処理フロー**:
1. **419-425行目**: BulletText関数 - va_startで可変長引数を初期化し、BulletTextVを呼び出し、va_endで終了
2. **428-452行目**: BulletTextV関数
   - **430-432行目**: GetCurrentWindowとSkipItems確認
   - **434-435行目**: コンテキストとスタイルの取得
   - **437-438行目**: ImFormatStringToTempBufferVでフォーマット処理
   - **439行目**: CalcTextSizeでテキストサイズ計算
   - **440行目**: 全体サイズの計算（空テキストの場合パディングなし）
   - **441-442行目**: カーソル位置をCurrLineTextBaseOffsetで調整
   - **443-445行目**: ItemSize/ItemAdd
   - **449行目**: RenderBulletでビュレットを描画
   - **450行目**: g.FontSize分オフセット後、RenderTextでテキストを描画
   - **451行目**: RenderTextでテキストを描画

#### Step 3: ビュレット描画を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | imgui_draw.cpp | `imgui_draw.cpp` | RenderBullet関数 |

**主要処理フロー**:
- RenderBullet: ImDrawList::AddCircleFilledで円を描画

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

```
ImGui::BulletText(fmt, ...)
    │
    ├─ va_start(args, fmt)
    │
    └─ ImGui::BulletTextV(fmt, args)
           │
           ├─ GetCurrentWindow()
           │
           ├─ ImFormatStringToTempBufferV()
           │
           ├─ CalcTextSize()
           │
           ├─ ItemSize() / ItemAdd()
           │
           ├─ GetColorU32(ImGuiCol_Text)
           │
           ├─ RenderBullet(draw_list, pos, color)
           │      │
           │      └─ ImDrawList::AddCircleFilled()
           │
           └─ RenderText(pos, text)
```

### データフロー図

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

fmt + ...   ───▶ フォーマット ───▶ サイズ計算 ───▶ ItemAdd ───▶ RenderBullet
                                                                   │
                                                                   └─▶ RenderText
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| imgui.h | `imgui.h` | ヘッダー | BulletText/BulletTextV関数の宣言（625-626行目） |
| imgui_widgets.cpp | `imgui_widgets.cpp` | ソース | BulletText/BulletTextV関数の実装（419-452行目） |
| imgui_draw.cpp | `imgui_draw.cpp` | ソース | RenderBullet関数、AddCircleFilled |
| imgui_internal.h | `imgui_internal.h` | 内部ヘッダー | RenderBullet関数宣言 |
