# 機能設計書 65-PushTextWrapPos

## 概要

本ドキュメントは、Dear ImGuiライブラリにおける`PushTextWrapPos`関数の機能設計を定義する。この関数は、テキスト折り返し位置をスタックにプッシュし、以降のText*()コマンドで使用される折り返し位置を設定する。

### 本機能の処理概要

PushTextWrapPos関数は、Text、TextWrapped、TextColoredなどのテキスト描画コマンドにおける自動折り返し位置を制御するためのスタックベースの設定機能を提供する。

**業務上の目的・背景**：GUIアプリケーションでは、長いテキストを適切な位置で自動的に折り返す機能が必要である。特に、ウィンドウ幅に応じた動的な折り返しや、特定の位置での折り返しが求められる。PushTextWrapPosは、ネストされた構造でも折り返し設定を維持・復元できるスタック機構を提供し、柔軟なテキストレイアウトを可能にする。

**機能の利用シーン**：
- 長い説明文やヘルプテキストを表示する場合
- ウィンドウ幅いっぱいまでテキストを折り返したい場合（0.0f指定）
- 特定の列位置で折り返しを行いたい場合
- 折り返しを一時的に無効にしたい場合（負の値指定）

**主要な処理内容**：
1. 現在のテキスト折り返し位置（window->DC.TextWrapPos）をスタックにバックアップ
2. 引数で指定された折り返し位置を新しい設定として適用

**関連システム・外部連携**：Text*()系の描画関数内部でDC.TextWrapPosが参照され、テキストレンダリング時の折り返し処理に使用される。

**権限による制御**：特になし。任意のウィンドウコンテキスト内で使用可能。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | 特定の画面に紐づかない汎用機能 |

## 機能種別

レイアウト制御 / パラメータスタック操作

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| wrap_local_pos_x | float | No（デフォルト: 0.0f） | 折り返し位置（ウィンドウローカル座標）。< 0.0f: 折り返しなし、0.0f: ウィンドウ（または列）の終端で折り返し、> 0.0f: 指定位置で折り返し | 特になし |

### 入力データソース

- 呼び出し元からの直接パラメータ指定

## 出力仕様

### 出力データ

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

### 出力先

- ImGuiWindow::DC.TextWrapPos（現在の折り返し位置設定）
- ImGuiWindow::DC.TextWrapPosStack（折り返し設定のバックアップスタック）

## 処理フロー

### 処理シーケンス

```
1. グローバルコンテキストGImGuiを取得
   └─ ImGuiContext& g = *GImGui

2. 現在のウィンドウを取得
   └─ ImGuiWindow* window = g.CurrentWindow

3. 現在のTextWrapPosをスタックにバックアップ
   └─ window->DC.TextWrapPosStack.push_back(window->DC.TextWrapPos)

4. 新しい折り返し位置を設定
   └─ window->DC.TextWrapPos = wrap_local_pos_x
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[グローバルコンテキスト取得]
    B --> C[現在のウィンドウ取得]
    C --> D[現在のTextWrapPosをスタックにpush]
    D --> E[wrap_local_pos_xをTextWrapPosに設定]
    E --> F[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-65-01 | スタックペアリング | PushTextWrapPosを呼び出したら必ずPopTextWrapPosを呼び出すこと | 常時 |
| BR-65-02 | ゼロ値のウィンドウ終端折り返し | wrap_local_pos_x=0.0fの場合はウィンドウ（または列）の終端で折り返す | wrap_local_pos_x == 0.0f |
| BR-65-03 | 負値の折り返し無効化 | wrap_local_pos_x<0.0fの場合は折り返しを行わない | wrap_local_pos_x < 0.0f |
| BR-65-04 | ローカル座標系 | 折り返し位置はウィンドウローカル座標で指定する（レガシー仕様） | 常時 |

### 計算ロジック

特になし（単純なスタック操作のみ）

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | アサーション | PopTextWrapPosを呼びすぎた場合 | PopTextWrapPosで警告が発生する |

### リトライ仕様

該当なし

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

該当なし

## パフォーマンス要件

- O(1)の定数時間操作
- スタック操作のみで軽量

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

特になし

## 備考

- TextWrapped()関数は内部でPushTextWrapPos(0.0f)とPopTextWrapPos()を呼び出すショートカットである
- ウィンドウローカル座標はレガシー仕様であり、将来的に変更される可能性がある
- 自動リサイズウィンドウでは他のウィジェットがないとウィンドウ幅が決まらないため、折り返しが期待通り動作しない場合がある

---

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

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

### 推奨読解順序

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

まず、テキスト折り返しに関連するデータ構造を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | imgui_internal.h | `imgui_internal.h` | ImGuiWindowTempData構造体内のTextWrapPos、TextWrapPosStackの定義（2635、2637行目） |

**読解のコツ**: TextWrapPosStackはImVector<float>型で、push_back/pop_backでスタック操作を行う。TextWrapPosは現在適用される折り返し位置。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | imgui.h | `imgui.h` | PushTextWrapPosの関数宣言（544行目）とコメントで値の意味を確認 |

**主要処理フロー**:
1. **544行目**: 関数宣言とデフォルト引数（0.0f）、各値の意味についてのコメント

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | imgui.cpp | `imgui.cpp` | PushTextWrapPos関数の実装（8286-8292行目） |

**主要処理フロー**:
- **8285行目**: "ATTENTION THIS IS IN LEGACY LOCAL SPACE"というコメント
- **8288-8289行目**: コンテキストとウィンドウの取得
- **8290行目**: 現在のTextWrapPosをスタックにバックアップ
- **8291行目**: 新しい折り返し位置の設定

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

```
PushTextWrapPos(float wrap_local_pos_x)
    │
    ├─ window->DC.TextWrapPosStack.push_back()
    │      └─ ImVector<float>::push_back() [スタック操作]
    │
    └─ window->DC.TextWrapPos = wrap_local_pos_x
           └─ 折り返し位置の設定

           ↓ (テキスト描画時)

Text*() 系関数
    └─ DC.TextWrapPos を参照してテキスト折り返し
```

### データフロー図

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

wrap_local_pos_x ────▶ PushTextWrapPos() ────▶ DC.TextWrapPos（更新）
                              │
                              └──▶ DC.TextWrapPosStack（push）
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| imgui.h | `imgui.h` | ヘッダ | 公開API宣言 |
| imgui.cpp | `imgui.cpp` | ソース | 関数実装 |
| imgui_internal.h | `imgui_internal.h` | ヘッダ | 内部データ構造定義 |
