# 機能設計書 181-TableGetSortSpecs

## 概要

本ドキュメントは、ImGuiライブラリのTableGetSortSpecs関数の機能設計を記述する。この関数はテーブルのソート仕様を取得するためのAPIである。

### 本機能の処理概要

TableGetSortSpecs関数は、現在のテーブルに対するソート仕様（ImGuiTableSortSpecs構造体）へのポインタを取得する機能である。ユーザーはこの情報を基に、テーブルデータのソート処理を実装できる。

**業務上の目的・背景**：データを表形式で表示するアプリケーションでは、ユーザーがカラムヘッダーをクリックしてデータをソートする機能が必要不可欠である。TableGetSortSpecsは、ユーザーが指定したソート条件（どの列を、昇順か降順か）をアプリケーションに伝達し、カスタムソートロジックの実装を可能にする。

**機能の利用シーン**：
- ユーザーがテーブルのカラムヘッダーをクリックしてソート順序を変更した時
- 複数カラムによるソート（Shiftキーを押しながらクリック）を実装する時
- テーブル表示の初期化時にデフォルトのソート順序を適用する時

**主要な処理内容**：
1. 現在のテーブルコンテキストを取得
2. テーブルにImGuiTableFlags_Sortableフラグが設定されているか確認
3. テーブルレイアウトが未完了の場合はTableUpdateLayoutを呼び出し
4. ソート仕様をビルドしてImGuiTableSortSpecs構造体へのポインタを返却

**関連システム・外部連携**：
- BeginTable/EndTableとの連携（テーブルコンテキスト内でのみ使用可能）
- TableSetupColumnとの連携（ソート対象カラムの設定）
- TableHeadersRowとの連携（ヘッダークリックによるソート変更）

**権限による制御**：本機能に権限制御はない。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 26 | Tables | 補助機能 | ソート仕様の取得 |

## 機能種別

データ取得処理

## 入力仕様

### 入力パラメータ

なし（引数を取らない関数）

### 入力データソース

- 現在のImGuiコンテキスト（g.CurrentTable）
- テーブルのソート状態（table->IsSortSpecsDirty、各カラムのSortOrder/SortDirection）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 戻り値 | ImGuiTableSortSpecs* | ソート仕様へのポインタ。ソート不可の場合はNULL |

### ImGuiTableSortSpecs構造体

| フィールド名 | 型 | 説明 |
|-------------|-----|------|
| Specs | const ImGuiTableColumnSortSpecs* | ソート仕様の配列 |
| SpecsCount | int | ソート仕様の数 |
| SpecsDirty | bool | ソート仕様が変更されたかどうか |

### ImGuiTableColumnSortSpecs構造体

| フィールド名 | 型 | 説明 |
|-------------|-----|------|
| ColumnUserID | ImGuiID | カラムのユーザーID |
| ColumnIndex | ImS16 | カラムインデックス |
| SortOrder | ImS16 | マルチソート時の優先順位 |
| SortDirection | ImGuiSortDirection | ソート方向（Ascending/Descending） |

### 出力先

アプリケーションコード（戻り値として返却）

## 処理フロー

### 処理シーケンス

```
1. コンテキストからCurrentTableを取得
   └─ テーブル外での呼び出しはNULLを返却
2. ImGuiTableFlags_Sortableフラグのチェック
   └─ フラグがない場合はNULLを返却
3. テーブルレイアウトの確認
   └─ 未完了の場合はTableUpdateLayoutを呼び出し
4. TableSortSpecsBuildの呼び出し
   └─ ソート仕様を構築
5. table->SortSpecsへのポインタを返却
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{CurrentTable != NULL?}
    B -->|No| C[return NULL]
    B -->|Yes| D{Sortableフラグあり?}
    D -->|No| C
    D -->|Yes| E{レイアウト完了?}
    E -->|No| F[TableUpdateLayout]
    F --> G[TableSortSpecsBuild]
    E -->|Yes| G
    G --> H[return &table->SortSpecs]
    C --> I[終了]
    H --> I
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-181-01 | ソート可能チェック | ImGuiTableFlags_Sortableフラグが設定されている場合のみソート仕様を返却 | 常時 |
| BR-181-02 | ダーティフラグ管理 | SpecsDirtyがtrueの場合、アプリケーションはソートを実行し、falseに設定すべき | ソート仕様変更時 |
| BR-181-03 | ライフタイム制限 | 返却されたポインタはフレームをまたいで保持してはならない | 常時 |

### 計算ロジック

特になし

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

該当なし（ImGuiはUIライブラリであり、データベース操作は行わない）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| N/A | NULL返却 | テーブルコンテキスト外での呼び出し | NULLを返却、エラーログなし |
| N/A | NULL返却 | Sortableフラグなし | NULLを返却、エラーログなし |

### リトライ仕様

該当なし

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

該当なし

## パフォーマンス要件

- 毎フレーム呼び出しても十分に高速であること
- SpecsDirtyがfalseの場合、ソート処理をスキップして効率化すべき

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

該当なし

## 備考

- ソート仕様が変更された場合のみSpecsDirtyがtrueになる
- アプリケーションはソート完了後にSpecsDirtyをfalseに設定する責任がある
- マルチソート（複数カラムによるソート）はShiftキーを押しながらカラムヘッダーをクリックすることで有効になる

---

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

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

### 推奨読解順序

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

まず、ソート仕様を表現するデータ構造を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | imgui.h | `imgui.h` | ImGuiTableSortSpecs構造体（2277行目付近）、ImGuiTableColumnSortSpecs構造体の定義 |
| 1-2 | imgui_internal.h | `imgui_internal.h` | ImGuiTable構造体のSortSpecs関連フィールド |

**読解のコツ**: ImGuiTableSortSpecsはユーザー向けのシンプルな構造体で、ImGuiTableColumnSortSpecsの配列を保持する。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | imgui_tables.cpp | `imgui_tables.cpp` | TableGetSortSpecs関数（2878-2891行目） |

**主要処理フロー**:
1. **2880行目**: グローバルコンテキストからCurrentTableを取得
2. **2882-2883行目**: NULLチェックとSortableフラグチェック
3. **2886-2887行目**: レイアウト未完了時のTableUpdateLayout呼び出し
4. **2889行目**: TableSortSpecsBuildの呼び出し
5. **2890行目**: SortSpecsポインタの返却

#### Step 3: ソート仕様ビルド処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | imgui_tables.cpp | `imgui_tables.cpp` | TableSortSpecsBuild関数の実装 |

**主要処理フロー**:
- ソート対象カラムの収集
- SortOrder順にソート仕様を構築
- SpecsDirtyフラグの設定

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

```
ImGui::TableGetSortSpecs()
    │
    ├─ (条件チェック: CurrentTable, Sortableフラグ)
    │
    ├─ ImGui::TableUpdateLayout() [条件付き]
    │      └─ テーブルのレイアウト計算
    │
    └─ TableSortSpecsBuild()
           └─ ソート仕様の構築
```

### データフロー図

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

g.CurrentTable ───▶ TableGetSortSpecs() ───▶ ImGuiTableSortSpecs*
                           │
                           ├─ テーブル検証
                           ├─ レイアウト更新
                           └─ ソート仕様ビルド
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| imgui.h | `imgui.h` | ヘッダー | API宣言、ImGuiTableSortSpecs構造体定義 |
| imgui_tables.cpp | `imgui_tables.cpp` | ソース | TableGetSortSpecs実装 |
| imgui_internal.h | `imgui_internal.h` | 内部ヘッダー | ImGuiTable内部構造体定義 |
| imgui_demo.cpp | `imgui_demo.cpp` | デモ | 使用例の参照 |
