# 機能設計書 211-IsItemClicked

## 概要

本ドキュメントは、ImGuiのIsItemClicked関数の機能設計書である。直前に追加されたアイテムがマウスでクリックされたかを判定する機能について、入出力仕様、処理フロー、実装詳細を記載する。

### 本機能の処理概要

IsItemClicked関数は、直前に追加されたウィジェット（アイテム）がマウスでクリックされたかを判定するAPIである。指定されたマウスボタンのクリックとアイテムのホバー状態を組み合わせて判定を行う。

**業務上の目的・背景**：GUIアプリケーションにおいて、ボタン以外のカスタムウィジェットや描画要素に対するクリック操作を検出する必要がある。本機能を使用することで、任意のアイテムに対するクリックイベントを簡潔に判定でき、カスタムUIの実装が容易になる。また、TreeNodeやSelectableなどのウィジェットと組み合わせて、選択状態の変更を検出する際にも活用される。

**機能の利用シーン**：
- ツリービューでノードをクリックして選択状態を切り替える場合
- カスタム描画されたアイテムに対するクリック操作を検出する場合
- コンテキストメニューのトリガー（右クリック検出）
- ダブルクリックではなくシングルクリックを明示的に検出したい場合

**主要な処理内容**：
1. 指定されたマウスボタン（デフォルトは左クリック）がクリックされたかを判定
2. 直前のアイテムがマウスでホバーされているかを判定
3. 両方の条件が満たされた場合にtrueを返却

**関連システム・外部連携**：ImGuiの内部状態管理システム（ImGuiContext）と連携し、LastItemDataおよびマウス入力状態を参照する。

**権限による制御**：特になし。ただし、無効化されたアイテム（BeginDisabled内）の場合、ホバー判定の挙動が変わる可能性がある。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | Demo Window | 参照画面 | Querying StatusセクションでIsItemClickedの動作確認 |
| 23 | Widgets | 参照画面 | Tree Nodesセクションでクリック選択に使用 |

## 機能種別

状態判定 / クエリ機能

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| mouse_button | ImGuiMouseButton | No | 判定するマウスボタン（デフォルト: 0 = 左ボタン） | 0-4の範囲（ImGuiMouseButton_Count未満） |

### 入力データソース

- ImGuiContext::LastItemData - 直前に追加されたアイテムの情報
- マウス入力状態 - IsMouseClicked関数で取得

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 戻り値 | bool | クリックされた場合true、それ以外はfalse |

### 出力先

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

## 処理フロー

### 処理シーケンス

```
1. マウスボタンクリック判定
   └─ IsMouseClicked(mouse_button)でクリック状態を確認
2. ホバー状態判定
   └─ IsItemHovered(ImGuiHoveredFlags_None)で直前アイテムのホバー状態を確認
3. 結果返却
   └─ 両方がtrueの場合にtrueを返却
```

### フローチャート

```mermaid
flowchart TD
    A[IsItemClicked呼び出し] --> B{IsMouseClicked?}
    B -->|Yes| C{IsItemHovered?}
    B -->|No| D[false を返却]
    C -->|Yes| E[true を返却]
    C -->|No| D
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-211-01 | Button動作との違い | IsItemClickedはButton()のような複雑な動作（押下中のビジュアル変化、マウスが外れた後の戻りなど）をシミュレートしない | 常時 |
| BR-211-02 | デフォルトボタン | 引数なしの場合は左マウスボタン（ImGuiMouseButton_Left = 0）を使用 | mouse_button引数省略時 |

### 計算ロジック

```cpp
return IsMouseClicked(mouse_button) && IsItemHovered(ImGuiHoveredFlags_None);
```

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 暗黙的エラー | 無効なmouse_button値（範囲外） | 内部的に範囲チェックされるが、結果は未定義動作の可能性 |

### リトライ仕様

該当なし

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

該当なし

## パフォーマンス要件

- 軽量な判定処理であり、フレームごとに複数回呼び出しても問題なし
- 内部的にはImGuiContext参照のみで、追加のメモリ割り当てなし

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

該当なし

## 備考

- **重要**: IsItemClickedはButton()と同等の動作ではない。Button()はマウス押下から離すまでの間にマウスが要素外に出た場合の処理など、より複雑なインタラクションを実装している。単純なクリック検出には適しているが、完全なボタン動作が必要な場合はButton()や専用ウィジェットを使用すること。
- TreeNodeとIsItemClickedを組み合わせる場合、IsItemToggledOpen()との併用が推奨される（開閉状態の切り替えとクリック選択を区別するため）

---

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

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

### 推奨読解順序

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

まず、アイテム状態管理のためのデータ構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | imgui_internal.h | `imgui_internal.h` | ImGuiLastItemData構造体の定義（ID, StatusFlags, Rect等） |
| 1-2 | imgui_internal.h | `imgui_internal.h` | ImGuiItemStatusFlags_の定義（985-1010行目） |

**読解のコツ**: ImGuiLastItemDataはアイテム追加時に設定され、後続のIs*Item*()関数で参照される。StatusFlagsビットフラグで各種状態を管理している。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | imgui.h | `imgui.h` | 関数宣言（1009行目）と公式コメント |
| 2-2 | imgui.cpp | `imgui.cpp` | 関数実装（6234-6237行目） |

**主要処理フロー**:
1. **6232-6233行目**: 重要な警告コメント - Button()と同等ではないことの説明
2. **6234行目**: 関数定義
3. **6236行目**: IsMouseClicked && IsItemHoveredの組み合わせで判定

#### Step 3: 依存関数を理解する

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

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

```
ImGui::IsItemClicked(mouse_button)
    │
    ├─ ImGui::IsMouseClicked(mouse_button)
    │      └─ マウス入力状態の取得
    │
    └─ ImGui::IsItemHovered(ImGuiHoveredFlags_None)
           └─ g.LastItemData の参照
```

### データフロー図

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

mouse_button ─────┐
                  │
                  ▼
              IsMouseClicked() ──────┐
                                     │
                                     ├──▶ AND判定 ──▶ bool (true/false)
                                     │
g.LastItemData ──▶ IsItemHovered() ──┘
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| imgui.h | `imgui.h` | ヘッダー | 公開API宣言 |
| imgui.cpp | `imgui.cpp` | ソース | 関数実装 |
| imgui_internal.h | `imgui_internal.h` | ヘッダー | 内部データ構造定義 |
| imgui_demo.cpp | `imgui_demo.cpp` | デモ | 使用例（2159行目、4157行目等） |
