# 機能設計書 215-IsItemDeactivated

## 概要

本ドキュメントは、ImGuiのIsItemDeactivated関数の機能設計書である。直前に追加されたアイテムが「非アクティブになった瞬間」かを判定する機能について記載する。

### 本機能の処理概要

IsItemDeactivated関数は、直前に追加されたウィジェット（アイテム）が、このフレームで非アクティブ状態になった瞬間かを判定するAPIである。アイテムが「アクティブ→非アクティブ」に遷移したタイミングを検出できる。

**業務上の目的・背景**：連続的な編集を行うウィジェット（スライダー、ドラッグ、テキスト入力など）において、編集が完了したタイミングを検出することは重要である。Undo/Redoシステムでは、編集操作の「終了」を検出して履歴に追加するタイミングとして使用される。IsItemActivatedと組み合わせることで、編集の開始から終了までの完全なライフサイクルを追跡できる。

**機能の利用シーン**：
- Undo/Redoシステムで編集終了時に履歴を記録する場合
- データベースやファイルへの保存処理を編集完了時にトリガーする場合
- 編集モードから通常モードへの遷移を検出する場合
- テキスト入力終了時にIMEを無効化する場合

**主要な処理内容**：
1. ウィジェットがImGuiItemStatusFlags_HasDeactivatedフラグを持つ場合、ImGuiItemStatusFlags_Deactivatedで判定
2. そうでない場合、DeactivatedItemDataを参照して判定
3. 条件が満たされた場合にtrueを返却

**関連システム・外部連携**：ImGuiの内部状態管理システム（ImGuiContext）のLastItemData.StatusFlags、DeactivatedItemDataを参照する。

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | Demo Window | 参照画面 | Querying StatusセクションでIsItemDeactivatedの動作確認 |
| 26 | Tables | 参照画面 | テーブル内でのソートトリガーに使用 |

## 機能種別

状態判定 / クエリ機能

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| なし | - | - | 引数なし | - |

### 入力データソース

- ImGuiContext::LastItemData.StatusFlags - 直前に追加されたアイテムの状態フラグ
- ImGuiContext::DeactivatedItemData - 非アクティブ化されたアイテムの情報
- ImGuiContext::FrameCount - 現在のフレームカウント

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 戻り値 | bool | このフレームで非アクティブになった場合true、それ以外はfalse |

### 出力先

呼び出し元への戻り値として返却

## 処理フロー

### 処理シーケンス

```
1. HasDeactivatedフラグ確認
   └─ StatusFlagsにImGuiItemStatusFlags_HasDeactivatedが設定されているか
2. 分岐処理
   ├─ HasDeactivatedがある場合
   │     └─ Deactivatedビットで判定
   └─ HasDeactivatedがない場合
         └─ DeactivatedItemDataでIDとフレームを照合
3. 結果返却
   └─ 条件が満たされればtrue、そうでなければfalse
```

### フローチャート

```mermaid
flowchart TD
    A[IsItemDeactivated呼び出し] --> B{HasDeactivatedフラグあり?}
    B -->|Yes| C{Deactivatedビット設定?}
    C -->|Yes| E[true を返却]
    C -->|No| F[false を返却]
    B -->|No| D{DeactivatedItemData.ID == LastItemData.ID<br>かつ フレーム条件成立?}
    D -->|Yes| E
    D -->|No| F
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-215-01 | 遷移検出 | 「アクティブ→非アクティブ」の遷移のみを検出 | 常時 |
| BR-215-02 | 2つの検出パス | ウィジェットによりHasDeactivatedフラグの有無が異なり、判定パスが分岐する | 常時 |
| BR-215-03 | 単一フレーム | 非アクティブになった瞬間の1フレームのみtrueを返す | 常時 |

### 計算ロジック

```cpp
bool ImGui::IsItemDeactivated()
{
    ImGuiContext& g = *GImGui;
    if (g.LastItemData.StatusFlags & ImGuiItemStatusFlags_HasDeactivated)
        return (g.LastItemData.StatusFlags & ImGuiItemStatusFlags_Deactivated) != 0;
    return g.DeactivatedItemData.ID == g.LastItemData.ID &&
           g.LastItemData.ID != 0 &&
           g.DeactivatedItemData.ElapseFrame >= g.FrameCount;
}
```

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

該当なし（GUIフレームワーク内部の状態参照のみ）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 暗黙的エラー | 前にアイテムが追加されていない場合 | LastItemData.IDが0となり、falseを返す |

### リトライ仕様

該当なし

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

該当なし

## パフォーマンス要件

- 単純なビット演算と比較のみで構成される軽量な判定処理
- フレームごとに複数回呼び出しても問題なし

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

該当なし

## 備考

- IsItemActivated()と対になる機能であり、「アクティブになった」と「非アクティブになった」のペアで使用されることが多い
- Undo/Redoパターンでは、IsItemDeactivatedAfterEdit()を使用することで、「編集を伴う非アクティブ化」のみを検出できる
- ウィジェットによってはImGuiItemStatusFlags_HasDeactivatedを設定しないものがあり、その場合はDeactivatedItemDataにより判定される

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | imgui_internal.h | `imgui_internal.h` | ImGuiItemStatusFlags_HasDeactivated, ImGuiItemStatusFlags_Deactivated（995-996行目） |
| 1-2 | imgui_internal.h | `imgui_internal.h` | ImGuiDeactivatedItemData構造体（1451-1457行目） |
| 1-3 | imgui_internal.h | `imgui_internal.h` | ImGuiContext内のDeactivatedItemDataフィールド（2270行目） |

**読解のコツ**:
- ImGuiItemStatusFlags_HasDeactivatedは、ウィジェットが「非アクティブ化を報告できる」ことを示す
- ImGuiDeactivatedItemDataは、非アクティブ化の情報を別途保存する構造体

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | imgui.h | `imgui.h` | 関数宣言（1013行目） |
| 2-2 | imgui.cpp | `imgui.cpp` | 関数実装（6211-6217行目） |

**主要処理フロー**:
1. **6211行目**: 関数定義
2. **6213行目**: ImGuiContext参照の取得
3. **6214行目**: HasDeactivatedフラグの確認
4. **6215行目**: Deactivatedビットでの判定（フラグあり時）
5. **6216行目**: DeactivatedItemDataでの判定（フラグなし時）

#### Step 3: 関連機能を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | imgui.cpp | `imgui.cpp` | IsItemActivated実装（6202-6209行目） |
| 3-2 | imgui.cpp | `imgui.cpp` | IsItemDeactivatedAfterEdit実装（6219-6223行目） |

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

```
ImGui::IsItemDeactivated()
    │
    ├─ g.LastItemData.StatusFlags 参照
    │      ├─ ImGuiItemStatusFlags_HasDeactivated チェック
    │      └─ ImGuiItemStatusFlags_Deactivated チェック
    │
    └─ g.DeactivatedItemData 参照
           ├─ ID 比較
           └─ ElapseFrame チェック
```

### データフロー図

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

g.LastItemData.StatusFlags ────┐
                               │
                               ├──▶ 判定ロジック ────────▶ bool (true/false)
                               │
g.DeactivatedItemData ─────────┘
    ├─ ID
    └─ ElapseFrame
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| imgui.h | `imgui.h` | ヘッダー | 公開API宣言 |
| imgui.cpp | `imgui.cpp` | ソース | 関数実装 |
| imgui_internal.h | `imgui_internal.h` | ヘッダー | 内部データ構造定義 |
| imgui_widgets.cpp | `imgui_widgets.cpp` | ソース | ウィジェット実装（Deactivatedフラグ設定箇所） |
| imgui_demo.cpp | `imgui_demo.cpp` | デモ | 使用例（2156行目、7539行目） |
