# 機能設計書 177-TableSetupColumn

## 概要

本ドキュメントは、ImGuiライブラリにおける`TableSetupColumn`関数の機能設計を記載する。この関数は、テーブルの列の名前、フラグ、初期幅/重み、ユーザーIDを設定するために使用される。

### 本機能の処理概要

**業務上の目的・背景**：テーブルの各列には、ヘッダー名、サイズポリシー、ソート設定、表示/非表示のデフォルト状態など、様々な属性を設定する必要がある。`TableSetupColumn`関数は、これらの列属性を一箇所で設定できるようにし、テーブルの構造を明確に定義することを可能にする。

**機能の利用シーン**：
- テーブルのヘッダー行に表示する列名を設定する場合
- 列の初期幅または相対的な重みを指定する場合
- ソート可能な列を定義する場合
- デフォルトで非表示にする列を設定する場合
- リサイズ不可の列を作成する場合

**主要な処理内容**：
1. テーブルのスコープ内であることの検証
2. 列フラグの設定と正規化
3. サイズポリシーの適用（幅または重み）
4. 列名の保存
5. ユーザーIDの設定
6. 初期化時のデフォルト値適用

**関連システム・外部連携**：テーブル設定保存システム（INIファイル）

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 26 | Tables | 主画面 | 列の設定 |

## 機能種別

設定機能

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| label | const char* | No | 列のヘッダー名（NULL可） | 文字列またはNULL |
| flags | ImGuiTableColumnFlags | No（デフォルト:0） | 列の動作フラグ | ビットフラグ |
| init_width_or_weight | float | No（デフォルト:-1.0f） | 初期幅（固定列）または重み（ストレッチ列） | -1.0fでデフォルト |
| user_id | ImGuiID | No（デフォルト:0） | ユーザー定義のID | 任意のID値 |

### ImGuiTableColumnFlagsの主要フラグ

| フラグ | 説明 |
|--------|------|
| ImGuiTableColumnFlags_Disabled | 列を無効化（表示されない） |
| ImGuiTableColumnFlags_DefaultHide | デフォルトで非表示 |
| ImGuiTableColumnFlags_DefaultSort | デフォルトでソート |
| ImGuiTableColumnFlags_WidthStretch | ストレッチ（可変幅）モード |
| ImGuiTableColumnFlags_WidthFixed | 固定幅モード |
| ImGuiTableColumnFlags_NoResize | リサイズ不可 |
| ImGuiTableColumnFlags_NoSort | ソート不可 |
| ImGuiTableColumnFlags_NoHide | 非表示不可 |
| ImGuiTableColumnFlags_NoReorder | 並べ替え不可 |
| ImGuiTableColumnFlags_AngledHeader | 角度付きヘッダー |
| ImGuiTableColumnFlags_PreferSortAscending | 昇順ソートを優先 |
| ImGuiTableColumnFlags_PreferSortDescending | 降順ソートを優先 |

### 入力データソース

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

## 出力仕様

### 出力データ

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

### 出力先

- テーブル列の属性（ImGuiTableColumn構造体）

## 処理フロー

### 処理シーケンス

```
1. カレントテーブルの取得と検証
   └─ BeginTableスコープ内であることを確認
2. 列数の検証
   └─ DeclColumnsCount < ColumnsCountを確認
3. レイアウトロック前の確認
   └─ IsLayoutLocked == falseを確認
4. 列の取得
   └─ table->Columns[DeclColumnsCount]
5. 列カウンタのインクリメント
   └─ DeclColumnsCount++
6. サイズポリシーの推論
   └─ init_width_or_weight > 0でポリシー未指定の場合、WidthFixedを適用
7. AngledHeader処理
   └─ フラグ設定時、NoHeaderLabelを追加しAngledHeadersCountを増加
8. 列フラグの設定
   └─ TableSetupColumnFlags()を呼び出し
9. ユーザーIDの設定
   └─ column->UserID = user_id
10. 初期化時のデフォルト適用
    └─ TableInitColumnDefaults()を呼び出し
11. 列名の保存
    └─ ColumnsNamesバッファに追加
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{テーブル<br/>スコープ内?}
    B -->|No| C[アサート/リターン]
    B -->|Yes| D{列数<br/>超過?}
    D -->|Yes| C
    D -->|No| E{レイアウト<br/>ロック済み?}
    E -->|Yes| C
    E -->|No| F[列を取得]
    F --> G[DeclColumnsCount++]
    G --> H{幅指定あり<br/>ポリシー未指定?}
    H -->|Yes| I[WidthFixedを設定]
    H -->|No| J{AngledHeader<br/>フラグ?}
    I --> J
    J -->|Yes| K[NoHeaderLabel追加<br/>AngledHeadersCount++]
    J -->|No| L[TableSetupColumnFlags]
    K --> L
    L --> M[UserID設定]
    M --> N{初期化中?}
    N -->|Yes| O[TableInitColumnDefaults]
    N -->|No| P[列名を保存]
    O --> P
    P --> Q[終了]
    C --> Q
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-177-01 | 最初の行前に呼び出し | TableSetupColumnはTableNextRow前に呼び出す必要がある | IsLayoutLocked == false |
| BR-177-02 | 列数以内で呼び出し | BeginTableで指定した列数を超えて呼び出すことはできない | DeclColumnsCount < ColumnsCount |
| BR-177-03 | 幅指定時のポリシー推論 | 幅が指定され、サイズポリシーが未指定の場合、固定幅モードが適用される | init_width_or_weight > 0 |

### 計算ロジック

init_width_or_weightの解釈:
- WidthFixed列: 列の初期幅（ピクセル）
- WidthStretch列: 列の相対的な重み
- <= 0: デフォルト値を使用

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

該当なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| N/A | アサーション失敗 | BeginTable外で呼び出し | デバッグビルドで停止 |
| N/A | アサーション失敗 | 列数を超えて呼び出し | デバッグビルドで停止 |
| N/A | アサーション失敗 | TableNextRow後に呼び出し | デバッグビルドで停止 |
| N/A | アサーション失敗 | デフォルトポリシーで幅/重みを指定 | デバッグビルドで停止 |

### リトライ仕様

該当なし

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

該当なし

## パフォーマンス要件

- O(1)の処理コスト（列名保存を除く）
- 列名保存はO(m)（mは列名の長さ）

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

特になし

## 備考

- 毎フレーム呼び出す必要がある（ImGuiの即時モードの特性）
- 列名はテーブル内部に保存されるため、一時的な文字列でも使用可能

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | imgui_internal.h | `imgui_internal.h` | ImGuiTableColumn構造体の各フィールド |
| 1-2 | imgui.h | `imgui.h` | ImGuiTableColumnFlags定義 |

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

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

**主要処理フロー**:
- **1612-1616行目**: 検証とアサート
- **1619-1620行目**: 列の取得とカウンタ増加
- **1624-1631行目**: サイズポリシーの推論
- **1632-1636行目**: AngledHeader処理
- **1638-1640行目**: フラグ設定
- **1644-1650行目**: 初期化時のデフォルト適用
- **1655-1659行目**: 列名の保存

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | imgui_tables.cpp | `imgui_tables.cpp` | 759-811行目: TableSetupColumnFlags実装 |
| 3-2 | imgui_tables.cpp | `imgui_tables.cpp` | 1585-1599行目: TableInitColumnDefaults実装 |

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

```
TableSetupColumn(label, flags, init_width_or_weight, user_id)
    │
    ├─ TableSetupColumnFlags(table, column, flags)
    │      ├─ サイズポリシーの設定
    │      ├─ リサイズ設定
    │      ├─ ソート設定
    │      └─ ソート方向の計算
    │
    └─ TableInitColumnDefaults(table, column, init_flags) [初期化時]
           ├─ 幅/重みの初期化
           ├─ 表示順序の初期化
           └─ 表示状態の初期化
```

### データフロー図

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

label ──────────────────────▶ ┌────────────────────┐
                             │ TableSetupColumn() │
flags ──────────────────────▶│   - フラグ設定     │ ────▶ [column->Flags]
                             │   - ポリシー推論   │
init_width_or_weight ───────▶│   - 名前保存       │ ────▶ [column->NameOffset]
                             │   - デフォルト適用 │
user_id ────────────────────▶│                    │ ────▶ [column->UserID]
                             └────────────────────┘
```

### 関連ファイル一覧

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