# 機能設計書 201-BeginDisabled

## 概要

本ドキュメントは、ImGuiライブラリにおける `BeginDisabled` 関数の機能設計を定義する。この関数は、ユーザー操作を一時的に無効化し、アイテムのビジュアルを薄暗く表示するためのBETA APIである。

### 本機能の処理概要

BeginDisabled関数は、ImGuiのウィジェットやアイテムに対するユーザーインタラクションを一時的に無効化する機能を提供する。無効化されたアイテムは、`style.DisabledAlpha`を現在の色に適用することで視覚的に薄暗く表示される。

**業務上の目的・背景**：GUIアプリケーションでは、特定の条件が満たされるまでユーザー操作を制限する必要がある場面が多い。例えば、必須項目が入力されるまでの送信ボタンの無効化、権限がないユーザーに対する機能の無効化、処理中の操作ロックなどがある。BeginDisabledは、このような無効化状態を簡潔かつ一貫した方法で実装するために設計されている。

**機能の利用シーン**：
- フォームの必須項目が未入力の場合に送信ボタンを無効化
- 読み取り専用モードで編集機能を無効化
- 特定の権限を持たないユーザーに対する機能制限
- 非同期処理中の重複操作防止
- 設定項目間の依存関係による動的な有効/無効切り替え

**主要な処理内容**：
1. 現在のItemFlagsスタックに無効化フラグ（ImGuiItemFlags_Disabled）をプッシュ
2. まだ無効化されていない場合、現在のAlpha値をバックアップしてDisabledAlphaを乗算
3. DisabledStackSizeをインクリメントしてネスト状態を追跡
4. 以降のウィジェットはクリック、ホバー、キーボード入力を受け付けなくなる

**関連システム・外部連携**：ImGuiスタイルシステム（DisabledAlpha設定）、ItemFlagsスタック、ナビゲーションシステムと連携する。ツールチップウィンドウは自動的に無効化から除外される。

**権限による制御**：本機能自体に権限制御はないが、アプリケーション側でユーザー権限に基づいてBeginDisabledの引数を制御することで、機能の有効/無効を動的に切り替えることができる。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 6 | Style Editor | 参照画面 | DisabledAlphaの設定による無効化時の見た目調整 |
| 23 | Widgets | 参照画面 | 各種ウィジェットの無効化デモ |
| 1 | Demo Window | 参照画面 | デバッグオプションやバックエンドフラグの無効化表示 |

## 機能種別

状態制御 / スタック操作 / ビジュアルエフェクト

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| disabled | bool | No（デフォルト: true） | 無効化を開始するかどうか。falseの場合は実質的に何もしない | なし |

### 入力データソース

プログラムコードからの直接呼び出し。引数はアプリケーションロジックによって決定される（例：フォームの入力状態、ユーザー権限、処理状態など）。

## 出力仕様

### 出力データ

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

### 出力先

- ImGuiContext内部状態（CurrentItemFlags、ItemFlagsStack、DisabledStackSize、Style.Alpha）
- 以降に描画されるウィジェットのビジュアル表示と入力応答

## 処理フロー

### 処理シーケンス

```
1. ImGuiContextの取得
   └─ グローバルコンテキスト（GImGui）を取得
2. 現在の無効化状態の確認
   └─ CurrentItemFlagsにImGuiItemFlags_Disabledが設定されているか確認
3. Alpha値の調整（初回無効化時のみ）
   └─ DisabledAlphaBackupに現在のAlpha値を保存
   └─ Style.AlphaにDisabledAlphaを乗算
4. ItemFlagsの更新
   └─ ImGuiItemFlags_Disabledをフラグに追加
   └─ ItemFlagsStackに現在のフラグをプッシュ
5. DisabledStackSizeのインクリメント
   └─ ネスト追跡用カウンタを増加
```

### フローチャート

```mermaid
flowchart TD
    A[BeginDisabled呼び出し] --> B{disabled == true?}
    B -->|No| C[フラグのみプッシュ]
    B -->|Yes| D{既に無効化中?}
    D -->|Yes| E[フラグを追加してプッシュ]
    D -->|No| F[Alpha値をバックアップ]
    F --> G[Style.Alpha *= DisabledAlpha]
    G --> E
    C --> H[DisabledStackSize++]
    E --> H
    H --> I[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-201 | ネスト可能性 | BeginDisabled/EndDisabledはネスト可能だが、無効化セクション内で再度有効化することはできない | 常時 |
| BR-202 | 視覚効果 | 無効化されたアイテムはDisabledAlpha（デフォルト0.6）で薄暗く表示される | disabled=true時 |
| BR-203 | ツールチップ除外 | ツールチップウィンドウは自動的に無効化から除外される | 常時 |
| BR-204 | ホバー判定 | 無効化アイテムはIsItemHovered()がデフォルトでfalseを返す | AllowWhenDisabledフラグなし時 |

### 計算ロジック

Alpha値の計算：
```
新しいAlpha = 現在のAlpha × DisabledAlpha
```
デフォルトのDisabledAlphaは0.6であり、約60%の不透明度になる。

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

### 操作別データベース影響一覧

本機能はデータベース操作を行わない（純粋なUI制御機能）。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| なし | アサーション | EndDisabledなしでフレーム終了 | デバッグビルドでスタック不整合を検出。対応するEndDisabledを追加 |

### リトライ仕様

リトライ機能なし（即時処理）

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

トランザクション管理なし（UI状態のスタック操作）。BeginDisabled/EndDisabledは必ずペアで使用し、フレーム内でスタックを整合させる必要がある。

## パフォーマンス要件

- BeginDisabled(false)/EndDisabled()は実質的にほぼ何もしないため、大量呼び出しのオーバーヘッドは最小限
- ただし、数万回の呼び出しがある場合はコード構造の見直しを推奨

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

- 無効化はUI表示上の制御であり、セキュリティ上の保護機能ではない
- バックエンド側での権限チェックは別途必要
- 無効化状態でも内部状態は変更される可能性がある

## 備考

- BETA APIとして提供されており、将来のバージョンで仕様が変更される可能性がある
- PushItemFlag(ImGuiItemFlags_Disabled)との混合使用は現在サポートされていない
- フィードバックはGitHub Issue #211で受け付けている

---

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

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

### 推奨読解順序

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

まず、無効化機能で使用されるフラグとコンテキスト変数を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | imgui_internal.h | `imgui_internal.h` | ImGuiItemFlags_Disabledフラグの定義（1038行目付近） |
| 1-2 | imgui_internal.h | `imgui_internal.h` | DisabledAlphaBackup、DisabledStackSizeの定義（2484-2485行目） |

**読解のコツ**: ImGuiItemFlagsはビットフラグで、複数のフラグを組み合わせて使用する。ImGuiItemFlags_Disabledは無効化状態を示す。

#### Step 2: API宣言を理解する

公開APIの宣言とドキュメントコメントを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | imgui.h | `imgui.h` | BeginDisabled/EndDisabledの宣言と使用上の注意（980-986行目） |

**主要処理フロー**:
- **980-984行目**: 無効化機能のコメント説明（ネスト可能性、ツールチップの除外など）
- **985行目**: BeginDisabled関数宣言（disabled引数のデフォルト値true）
- **986行目**: EndDisabled関数宣言

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

BeginDisabled関数の実装詳細を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | imgui.cpp | `imgui.cpp` | BeginDisabled関数の実装（8233-8246行目） |

**主要処理フロー**:
- **8233行目**: 関数定義の開始
- **8236行目**: 現在の無効化状態を確認（was_disabled）
- **8237-8241行目**: 初回無効化時のAlpha値調整
- **8242-8243行目**: フラグの設定
- **8244行目**: ItemFlagsStackへのプッシュ
- **8245行目**: DisabledStackSizeのインクリメント

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

```
BeginDisabled(bool disabled)
    │
    ├─ GImGui（グローバルコンテキスト取得）
    │
    ├─ CurrentItemFlags参照
    │      └─ ImGuiItemFlags_Disabled確認
    │
    ├─ Style.Alpha操作
    │      └─ DisabledAlphaBackup保存
    │      └─ DisabledAlpha乗算
    │
    └─ ItemFlagsStack.push_back()
           └─ DisabledStackSize++
```

### データフロー図

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

disabled(bool) ───────▶ BeginDisabled() ───────▶ CurrentItemFlags更新
                              │                            │
                              ├─────────────────▶ Style.Alpha更新
                              │                            │
                              └─────────────────▶ ItemFlagsStack更新
                                                           │
                                                  DisabledStackSize++
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| imgui.h | `imgui.h` | ヘッダ | 公開API宣言 |
| imgui.cpp | `imgui.cpp` | ソース | 実装コード |
| imgui_internal.h | `imgui_internal.h` | ヘッダ | 内部データ構造定義 |
| imgui_demo.cpp | `imgui_demo.cpp` | ソース | 使用例（559行目、582行目など） |
