# 機能設計書 179-TableHeadersRow

## 概要

本ドキュメントは、ImGuiライブラリにおける`TableHeadersRow`関数の機能設計を記載する。この関数は、テーブルのヘッダー行を自動的に出力し、各列のヘッダーを表示する。

### 本機能の処理概要

**業務上の目的・背景**：テーブルにはほとんどの場合、列の内容を示すヘッダー行が必要である。`TableHeadersRow`関数は、`TableSetupColumn`で設定された列名を使用して、標準的なヘッダー行を自動的に生成する。これにより、開発者は各列のヘッダーを個別に出力する手間を省くことができる。

**機能の利用シーン**：
- テーブルの先頭にヘッダー行を表示する場合
- ソート可能なテーブルを作成する場合（クリックでソート）
- 列の並べ替えを可能にする場合（ドラッグ）
- コンテキストメニューで列の表示/非表示を切り替える場合

**主要な処理内容**：
1. テーブルレイアウトの完了確認
2. ヘッダー行の高さ計算
3. ヘッダー行の開始（TableNextRow with Headers flag）
4. 各列に対してTableHeader()を呼び出し
5. コンテキストメニューの処理

**関連システム・外部連携**：テーブルソートシステム、コンテキストメニューシステム

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 26 | Tables | 主画面 | ヘッダー行の出力 |

## 機能種別

UI描画機能

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| なし | - | - | パラメータなし | - |

### 入力データソース

- ImGuiコンテキストのカレントテーブル
- TableSetupColumnで設定された列名

## 出力仕様

### 出力データ

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

### 出力先

- テーブル内のヘッダー行（描画リスト）

## 処理フロー

### 処理シーケンス

```
1. カレントテーブルの取得と検証
   └─ BeginTableスコープ内であることを確認
2. レイアウトの完了確認
   └─ IsLayoutLockedがfalseならTableUpdateLayoutを呼び出し
3. ヘッダー行の高さを計算
   └─ TableGetHeaderRowHeight()を呼び出し
4. ヘッダー行の開始
   └─ TableNextRow(ImGuiTableRowFlags_Headers, row_height)
5. ホストのスキップ確認
   └─ HostSkipItemsがtrueならリターン
6. 各列に対してループ
   ├─ TableSetColumnIndex()で列に移動
   ├─ NoHeaderLabelフラグでない場合は列名を取得
   ├─ PushID(column_n)でID設定
   ├─ TableHeader(name)でヘッダーを出力
   └─ PopID()
7. コンテキストメニュー処理
   └─ 最後の列の右側で右クリック時にメニューを開く
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{テーブル<br/>スコープ内?}
    B -->|No| C[アサート/リターン]
    B -->|Yes| D{レイアウト<br/>完了?}
    D -->|No| E[TableUpdateLayout]
    D -->|Yes| F[ヘッダー高さ計算]
    E --> F
    F --> G[TableNextRow<br/>Headers]
    G --> H{HostSkipItems?}
    H -->|Yes| I[リターン]
    H -->|No| J[列ループ開始]
    J --> K[TableSetColumnIndex]
    K --> L{列が<br/>可視?}
    L -->|No| M{次の列<br/>あり?}
    L -->|Yes| N[PushID]
    N --> O[TableHeader]
    O --> P[PopID]
    P --> M
    M -->|Yes| K
    M -->|No| Q{右クリック<br/>最右列?}
    Q -->|Yes| R[TableOpenContextMenu]
    Q -->|No| S[終了]
    R --> S
    I --> S
    C --> S
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-179-01 | 自動レイアウト | TableHeadersRowがTableUpdateLayoutを呼び出す可能性がある | IsLayoutLocked == false |
| BR-179-02 | NoHeaderLabel | NoHeaderLabelフラグが設定された列は空文字列でヘッダーを出力 | AngledHeader等の場合 |
| BR-179-03 | コンテキストメニュー | 最右列の右側で右クリックするとコンテキストメニューが開く | 常に |

### 計算ロジック

ヘッダー行高さ:
```
row_height = TableGetHeaderRowHeight()
// FontSize + CellPadding.y * 2等から計算
```

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

該当なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| N/A | アサーション失敗 | BeginTable外で呼び出し | デバッグビルドで停止 |

### リトライ仕様

該当なし

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

該当なし

## パフォーマンス要件

- O(n)の処理コスト（nは列数）

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

特になし

## 備考

- ソートインジケータは自動的に表示される
- カスタムヘッダーが必要な場合はTableHeader()を直接使用

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | imgui_internal.h | `imgui_internal.h` | ImGuiTableColumn構造体のNameOffset |

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

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

**主要処理フロー**:
- **3105-3107行目**: 検証
- **3111-3112行目**: レイアウト確認/完了
- **3115-3116行目**: ヘッダー行開始
- **3122-3132行目**: 各列のヘッダー出力
- **3135-3138行目**: コンテキストメニュー処理

#### Step 3: 関連関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | imgui_tables.cpp | `imgui_tables.cpp` | 3144行目以降: TableHeader実装 |
| 3-2 | imgui_tables.cpp | `imgui_tables.cpp` | TableGetHeaderRowHeight実装 |

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

```
TableHeadersRow()
    │
    ├─ TableUpdateLayout(table) [レイアウト未完了時]
    │
    ├─ TableGetHeaderRowHeight()
    │      └─ ヘッダー行高さの計算
    │
    ├─ TableNextRow(Headers, row_height)
    │      └─ ヘッダー行の開始
    │
    ├─ [各列に対してループ]
    │   ├─ TableSetColumnIndex(column_n)
    │   ├─ TableGetColumnName(column_n)
    │   ├─ PushID(column_n)
    │   ├─ TableHeader(name)
    │   │      ├─ ヘッダーの描画
    │   │      ├─ ソートインジケータの描画
    │   │      └─ ドラッグ/クリック処理
    │   └─ PopID()
    │
    └─ TableOpenContextMenu() [右クリック時]
```

### データフロー図

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

g.CurrentTable ─────────────▶ ┌──────────────────┐
                             │ TableHeadersRow() │
table->ColumnsNames ────────▶│   - 高さ計算      │ ────▶ [描画リスト]
                             │   - 各列ヘッダー  │
TableSetupColumnで設定 ─────▶│   - ソート状態    │ ────▶ [ソート状態更新]
                             └──────────────────┘
```

### 関連ファイル一覧

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