# 機能設計書 183-BeginTabBar

## 概要

本ドキュメントは、ImGuiライブラリのBeginTabBar関数の機能設計を記述する。この関数はタブバーを作成し、タブアイテムの追加を開始するためのAPIである。

### 本機能の処理概要

BeginTabBar関数は、タブ形式のナビゲーションUIを作成するための開始関数である。この関数呼び出しの後、BeginTabItem/EndTabItemを使用して個々のタブを追加し、最後にEndTabBarで終了する。

**業務上の目的・背景**：複数のコンテンツ領域を限られたスペース内で切り替えて表示するタブインターフェースは、現代のGUIアプリケーションで広く使用される重要なUIパターンである。BeginTabBarは、このタブナビゲーションの基盤を提供し、ユーザーが直感的にコンテンツを切り替えられるUIを実現する。

**機能の利用シーン**：
- 複数のパネルやビューを切り替えるインターフェース
- 設定画面のカテゴリ分け
- ドキュメントエディタのマルチタブ表示
- プロパティインスペクタの分類表示

**主要な処理内容**：
1. タブバーIDの計算（文字列IDからハッシュ）
2. タブバー構造体の取得または作成（プール管理）
3. タブバーの矩形領域の計算
4. BeginTabBarExへの委譲による初期化処理
5. タブバースタックへのプッシュ

**関連システム・外部連携**：
- EndTabBarとのペア使用（必須）
- BeginTabItem/EndTabItemとの連携（タブ追加）
- TabItemButtonとの連携（ボタン型タブ）
- スタイルシステム（FramePadding、ItemSpacing等）

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 21 | Documents | 主機能 | タブバーの開始 |

## 機能種別

UI構造制御処理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| str_id | const char* | Yes | タブバーの識別子（ウィンドウ内で一意） | 空文字列不可 |
| flags | ImGuiTabBarFlags | No | タブバーの動作フラグ（デフォルト: 0） | 有効なフラグ値 |

### ImGuiTabBarFlags列挙型（主要なもの）

| フラグ | 説明 |
|--------|------|
| ImGuiTabBarFlags_None | デフォルト |
| ImGuiTabBarFlags_Reorderable | タブのドラッグ並び替えを許可 |
| ImGuiTabBarFlags_AutoSelectNewTabs | 新しいタブを自動選択 |
| ImGuiTabBarFlags_TabListButton | タブリストのドロップダウンボタンを表示 |
| ImGuiTabBarFlags_NoCloseWithMiddleMouseButton | 中ボタンクリックでの閉じるを無効化 |
| ImGuiTabBarFlags_NoTabListScrollingButtons | スクロールボタンを非表示 |
| ImGuiTabBarFlags_FittingPolicyResizeDown | タブ幅を縮小してフィット |
| ImGuiTabBarFlags_FittingPolicyScroll | スクロールでフィット |

### 入力データソース

- 現在のウィンドウコンテキスト
- スタイル設定（FramePadding、ItemSpacing）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 戻り値 | bool | タブバーが開始されたかどうか。falseの場合はEndTabBarを呼ばない |

### 出力先

- グローバルタブバースタック（g.CurrentTabBarStack）
- 現在のタブバーポインタ（g.CurrentTabBar）

## 処理フロー

### 処理シーケンス

```
1. ウィンドウのスキップ状態チェック
   └─ SkipItemsの場合はfalseを返却
2. タブバーIDの計算
   └─ str_idからハッシュ値を生成
3. タブバー構造体の取得/作成
   └─ g.TabBarsプールから取得または新規作成
4. タブバー矩形の計算
   └─ カーソル位置とワークレクトから計算
5. IsFocusedフラグの設定
6. BeginTabBarExへの委譲
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{window->SkipItems?}
    B -->|Yes| C[return false]
    B -->|No| D[IDを計算]
    D --> E[TabBarを取得/作成]
    E --> F[矩形を計算]
    F --> G[フラグにIsFocusedを追加]
    G --> H[BeginTabBarEx呼び出し]
    H --> I[return 結果]
    C --> J[終了]
    I --> J
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-183-01 | ペアリング | BeginTabBarがtrueを返した場合のみEndTabBarを呼び出す | 常時 |
| BR-183-02 | ID一意性 | 同一ウィンドウ内でstr_idは一意である必要がある | 常時 |
| BR-183-03 | フィッティングポリシー | FittingPolicyMaskが未設定の場合はデフォルトポリシーを適用 | フラグ未設定時 |
| BR-183-04 | 複数回呼び出し | 同一フレームで複数回呼び出すと追記モードになる | 2回目以降 |

### 計算ロジック

タブバー矩形の計算:
```
Min.x = window->DC.CursorPos.x
Min.y = window->DC.CursorPos.y
Max.x = window->WorkRect.Max.x
Max.y = Min.y + FontSize + FramePadding.y * 2
```

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| N/A | false返却 | ウィンドウがスキップ状態 | EndTabBarを呼ばない |

### リトライ仕様

該当なし

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

該当なし

## パフォーマンス要件

- タブバー構造体はプール管理され、頻繁な割り当て/解放を回避
- 毎フレーム呼び出しても効率的に動作すること

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

該当なし

## 備考

- BeginTabBarがfalseを返した場合、EndTabBarを呼び出してはならない
- タブの並び替え機能はImGuiTabBarFlags_Reorderableで有効化
- ドッキングブランチでは、ドッキングシステムがタブバーを自動作成する

---

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

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

### 推奨読解順序

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

まず、タブバーを表現するデータ構造を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | imgui.h | `imgui.h` | ImGuiTabBarFlags列挙型の定義 |
| 1-2 | imgui_internal.h | `imgui_internal.h` | ImGuiTabBar構造体（2812-2854行目） |
| 1-3 | imgui_internal.h | `imgui_internal.h` | ImGuiTabItem構造体（2793-2810行目） |

**読解のコツ**: ImGuiTabBarはタブのリスト、選択状態、スクロール状態などを保持する。ImGuiTabItemは個々のタブの情報を保持する。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | imgui_widgets.cpp | `imgui_widgets.cpp` | BeginTabBar関数（9624-9639行目） |

**主要処理フロー**:
1. **9627-9628行目**: SkipItemsチェック
2. **9631行目**: IDの計算
3. **9632行目**: タブバーの取得/作成
4. **9633行目**: 矩形の計算
5. **9638行目**: IsFocusedフラグの追加
6. **9639行目**: BeginTabBarExへの委譲

#### Step 3: 内部実装を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | imgui_widgets.cpp | `imgui_widgets.cpp` | BeginTabBarEx関数（9642-9700行目） |

**主要処理フロー**:
- **9650-9651行目**: IDのプッシュ
- **9654行目**: タブバースタックへのプッシュ
- **9667-9669行目**: タブの再ソート処理
- **9676-9678行目**: フラグとレイアウト状態の初期化
- **9694-9699行目**: セパレータの描画

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

```
ImGui::BeginTabBar(str_id, flags)
    │
    ├─ window->GetID(str_id) - ID計算
    │
    ├─ g.TabBars.GetOrAddByKey(id) - タブバー取得/作成
    │
    └─ BeginTabBarEx(tab_bar, rect, flags)
           │
           ├─ PushOverrideID(id)
           ├─ スタックへプッシュ
           ├─ タブの再ソート（必要時）
           ├─ 状態の初期化
           └─ セパレータの描画
```

### データフロー図

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

str_id ───────▶ BeginTabBar() ───────▶ g.CurrentTabBar
flags                  │                  g.CurrentTabBarStack
                       │
                       ├─ ID計算
                       ├─ プール検索
                       └─ 初期化
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| imgui.h | `imgui.h` | ヘッダー | API宣言、ImGuiTabBarFlags定義 |
| imgui_widgets.cpp | `imgui_widgets.cpp` | ソース | BeginTabBar/BeginTabBarEx実装 |
| imgui_internal.h | `imgui_internal.h` | 内部ヘッダー | ImGuiTabBar/ImGuiTabItem構造体定義 |
| imgui_demo.cpp | `imgui_demo.cpp` | デモ | 使用例（Tabsセクション） |
