# 機能設計書 174-TableNextRow

## 概要

本ドキュメントは、ImGuiライブラリにおける`TableNextRow`関数の機能設計を記載する。この関数は、テーブル内で新しい行を開始し、最初のセルへの追加を準備する。

### 本機能の処理概要

**業務上の目的・背景**：テーブルデータの表示において、行単位でのデータ追加は基本的な操作である。`TableNextRow`関数は、新しい行を開始し、行の高さやフラグを設定することで、整然としたテーブルレイアウトを実現する。ヘッダー行と通常のデータ行を区別することも可能。

**機能の利用シーン**：
- データベースレコードを行ごとに表示する場合
- ループ処理で複数行のデータを追加する場合
- ヘッダー行とデータ行を区別して表示する場合
- 行の最小高さを指定して統一的なレイアウトを作成する場合

**主要な処理内容**：
1. テーブルレイアウトの完了（初回呼び出し時にTableUpdateLayoutを実行）
2. 現在の行が存在する場合は終了処理（TableEndRow）
3. 行フラグと最小高さの設定
4. 新しい行の開始処理（TableBeginRow）
5. 行高さの計算（CellPaddingを含む）
6. 出力の無効化（TableNextColumnが呼ばれるまで）

**関連システム・外部連携**：テーブルの行/列管理システム、描画システム

**権限による制御**：特になし。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 26 | Tables | 主画面 | テーブル行の追加 |

## 機能種別

UI制御機能（行操作）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| row_flags | ImGuiTableRowFlags | No（デフォルト:0） | 行の動作を制御するフラグ | ビットフラグ |
| min_row_height | float | No（デフォルト:0.0f） | 行の最小高さ（CellPadding.y * 2を含む） | 0以上 |

### ImGuiTableRowFlagsの主要フラグ

| フラグ | 説明 |
|--------|------|
| ImGuiTableRowFlags_None | デフォルト（フラグなし） |
| ImGuiTableRowFlags_Headers | ヘッダー行として扱う |

### 入力データソース

- ImGuiコンテキストのカレントテーブル
- ユーザー指定のパラメータ

## 出力仕様

### 出力データ

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

### 出力先

- テーブルの行状態（table->CurrentRow, table->RowFlags等）
- ウィンドウのカーソル位置

## 処理フロー

### 処理シーケンス

```
1. カレントテーブルの取得
   └─ g.CurrentTableを参照
2. レイアウトの完了確認
   └─ IsLayoutLockedがfalseならTableUpdateLayoutを呼び出し
3. 現在の行の終了
   └─ IsInsideRowがtrueならTableEndRowを呼び出し
4. 行フラグの設定
   ├─ table->LastRowFlags = table->RowFlags
   └─ table->RowFlags = row_flags
5. CellPaddingの設定
   └─ table->RowCellPaddingY = g.Style.CellPadding.y
6. 行の最小高さ設定
   └─ table->RowMinHeight = row_min_height
7. 新しい行の開始
   └─ TableBeginRowを呼び出し
8. 行高さの計算
   └─ RowPosY2 += RowCellPaddingY * 2 + min_row_height
9. 出力の無効化
   └─ InnerWindow->SkipItems = true
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{レイアウト<br/>完了?}
    B -->|No| C[TableUpdateLayout]
    B -->|Yes| D{行が<br/>開いている?}
    C --> D
    D -->|Yes| E[TableEndRow]
    D -->|No| F[行フラグ設定]
    E --> F
    F --> G[CellPadding設定]
    G --> H[最小高さ設定]
    H --> I[TableBeginRow]
    I --> J[行高さ計算]
    J --> K[SkipItems = true]
    K --> L[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-174-01 | 自動レイアウト | 最初のTableNextRow呼び出し時にTableUpdateLayoutが実行される | IsLayoutLocked == false |
| BR-174-02 | 行高さ計算 | min_row_heightにはCellPadding.y * 2が含まれている前提 | 常に |
| BR-174-03 | 出力無効化 | TableNextRow後はTableNextColumnまで出力が無効 | 常に |

### 計算ロジック

行高さの計算:
```
RowPosY2 = RowPosY1 + RowCellPaddingY * 2.0f + max(RowPosY2 - RowPosY1, min_row_height)
```

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

該当なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| N/A | 暗黙的な失敗 | BeginTable外で呼び出し | g.CurrentTableがNULLで何も起きない |

### リトライ仕様

該当なし

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

該当なし

## パフォーマンス要件

- O(1)の処理コスト
- 初回呼び出し時のみTableUpdateLayoutが呼ばれO(n)（nは列数）

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

特になし

## 備考

- TableNextColumnから自動的に呼び出されることもある
- min_row_heightは上下のCellPaddingを含む最小高さ

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | imgui_internal.h | `imgui_internal.h` | ImGuiTable構造体のCurrentRow, RowFlags, RowPosY1, RowPosY2等 |

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | imgui.h | `imgui.h` | 903行目: 公開APIの宣言 |
| 2-2 | imgui_tables.cpp | `imgui_tables.cpp` | 1881-1904行目: TableNextRow実装 |

**主要処理フロー**:
- **1886-1887行目**: レイアウト未完了時のTableUpdateLayout
- **1888-1889行目**: 既存行の終了
- **1891-1894行目**: 行パラメータの設定
- **1895行目**: TableBeginRow呼び出し
- **1899-1900行目**: 行高さの計算
- **1903行目**: SkipItemsの設定

#### Step 3: 内部関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | imgui_tables.cpp | `imgui_tables.cpp` | 1907-1931行目: TableBeginRow実装 |

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

```
TableNextRow(row_flags, min_row_height)
    │
    ├─ TableUpdateLayout(table) [初回時]
    │      └─ テーブルレイアウトの計算
    │
    ├─ TableEndRow(table) [行が開いている場合]
    │      └─ 現在の行を終了
    │
    └─ TableBeginRow(table)
           └─ 新しい行を開始
               ├─ CurrentRow++
               ├─ RowBgColor初期化
               └─ カーソル位置設定
```

### データフロー図

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

row_flags ──────────────▶ ┌──────────────────┐
                         │ TableNextRow()    │
min_row_height ─────────▶│   - レイアウト完了│ ────▶ [table->CurrentRow更新]
                         │   - 行終了/開始   │
g.CurrentTable ─────────▶│   - 高さ計算     │ ────▶ [table->RowPosY1/Y2更新]
                         └──────────────────┘
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| imgui.h | `imgui.h` | ヘッダー | 公開API宣言 |
| imgui_internal.h | `imgui_internal.h` | ヘッダー | ImGuiTableRowFlags定義 |
| imgui_tables.cpp | `imgui_tables.cpp` | ソース | 実装本体 |
