# 機能設計書 176-TableSetColumnIndex

## 概要

本ドキュメントは、ImGuiライブラリにおける`TableSetColumnIndex`関数の機能設計を記載する。この関数は、指定した列インデックスに直接移動し、そのセルへのコンテンツ追加を開始する。

### 本機能の処理概要

**業務上の目的・背景**：テーブル内の特定の列に直接アクセスしたい場合がある。例えば、すべての列を順番に埋める必要がない場合や、特定の列にのみデータを追加したい場合である。`TableSetColumnIndex`関数は、列インデックスを指定して直接その列に移動することで、柔軟なテーブル操作を可能にする。

**機能の利用シーン**：
- 特定の列のみにデータを追加する場合
- 列の順序に関係なくランダムアクセスでデータを追加する場合
- 条件付きで特定の列にのみコンテンツを出力する場合

**主要な処理内容**：
1. カレントテーブルの存在確認
2. 現在の列と異なる場合のみ処理を実行
3. 現在のセルの終了処理（TableEndCell）
4. 指定された列でセルを開始（TableBeginCell）
5. 列の可視性状態の返却

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

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 26 | Tables | 主画面 | 列への直接移動 |

## 機能種別

UI制御機能（セル操作）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| column_n | int | Yes | 移動先の列インデックス（0始まり） | 0以上、ColumnsCount未満 |

### 入力データソース

- ImGuiコンテキストのカレントテーブル
- 現在の列インデックス（table->CurrentColumn）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 戻り値 | bool | 列が可視でコンテンツを出力すべき場合true |

### 出力先

- テーブルの列状態（table->CurrentColumn）
- ウィンドウのカーソル位置

## 処理フロー

### 処理シーケンス

```
1. カレントテーブルの取得
   └─ g.CurrentTableがNULLならfalseを返却
2. 列インデックスの検証
   └─ column_n が有効範囲内かアサートで確認
3. 現在の列との比較
   └─ CurrentColumn == column_n なら何もしない
4. 現在のセルの終了
   └─ CurrentColumn != -1 ならTableEndCellを呼び出し
5. 新しいセルの開始
   └─ TableBeginCell(table, column_n)を呼び出し
6. 列の可視性を返却
   └─ table->Columns[column_n].IsRequestOutputを返す
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{テーブル<br/>存在?}
    B -->|No| C[false を返却]
    B -->|Yes| D{column_n ==<br/>CurrentColumn?}
    D -->|Yes| E[IsRequestOutput<br/>を返却]
    D -->|No| F{CurrentColumn<br/>!= -1?}
    F -->|Yes| G[TableEndCell]
    F -->|No| H[TableBeginCell<br/>column_n]
    G --> H
    H --> E
    C --> I[終了]
    E --> I
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-176-01 | インデックス検証 | column_nは0以上、ColumnsCount未満である必要がある | 常に |
| BR-176-02 | 同一列スキップ | 現在の列と同じ列を指定した場合は何も処理しない | CurrentColumn == column_n |
| BR-176-03 | 可視性ベースのスキップ | 戻り値がfalseでも、行高さに寄与しない場合のみコンテンツをスキップ可能 | 常に |

### 計算ロジック

特になし

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

該当なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| N/A | 暗黙的な失敗 | BeginTable外で呼び出し | falseを返却 |
| N/A | アサーション失敗 | column_nが範囲外 | デバッグビルドで停止、falseを返却 |

### リトライ仕様

該当なし

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

該当なし

## パフォーマンス要件

- O(1)の処理コスト

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

特になし

## 備考

- TableNextColumnとは異なり、絶対的な列インデックスで移動する
- 同じ列を連続して指定しても問題ない（効率的にスキップされる）

---

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

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

### 推奨読解順序

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

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

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

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

**主要処理フロー**:
- **2112-2115行目**: カレントテーブルの確認
- **2117-2123行目**: 列変更処理
- **2127行目**: 可視性の返却

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | imgui_tables.cpp | `imgui_tables.cpp` | TableBeginCell, TableEndCell |

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

```
TableSetColumnIndex(column_n)
    │
    ├─ [現在の列と異なる場合]
    │   ├─ TableEndCell(table) [CurrentColumn != -1]
    │   └─ TableBeginCell(table, column_n)
    │
    └─ return Columns[column_n].IsRequestOutput
```

### データフロー図

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

column_n ───────────────▶ ┌────────────────────┐
                         │ TableSetColumnIndex │
g.CurrentTable ─────────▶│   - 列検証          │ ────▶ [bool: 可視性]
                         │   - セル終了/開始   │
table->CurrentColumn ───▶│                     │ ────▶ [CurrentColumn更新]
                         └────────────────────┘
```

### 関連ファイル一覧

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