# 機能設計書 234-SetNextItemShortcut

## 概要

本ドキュメントは、ImGuiライブラリにおける次のアイテムへのショートカット設定機能「SetNextItemShortcut」の設計仕様を定義する。

### 本機能の処理概要

SetNextItemShortcut関数は、次に作成されるウィジェット（ボタン、メニューアイテム等）にキーボードショートカットを関連付ける機能である。この関数を呼び出した直後に作成されるウィジェットは、指定されたショートカットキーが押されると自動的にアクティブ化される。これにより、メニューアイテムやツールバーボタンにショートカットキーを簡単に割り当てることができる。

**業務上の目的・背景**：GUIアプリケーションでは、メニューアイテムやツールバーボタンにキーボードショートカットを割り当てることが一般的である。「ファイル」メニューの「保存」にCtrl+Sを割り当てるなど、ユーザーがマウスを使わずに機能を実行できるようにするために、この機能が必要とされる。SetNextItemShortcutは、ショートカットの設定を簡潔かつ一貫した方法で行うことを可能にする。

**機能の利用シーン**：
- メニューアイテムへのショートカット割り当て（Ctrl+S、Ctrl+O等）
- ツールバーボタンへのショートカット割り当て
- コンテキストメニューアイテムへのショートカット割り当て
- アクセシビリティ向上のためのキーボードナビゲーション
- ゲームUIのホットキー設定

**主要な処理内容**：
1. NextItemData構造体にショートカット情報を設定
2. HasFlagsにImGuiNextItemDataFlags_HasShortcutを追加
3. ショートカットキーコード（key_chord）を保存
4. ショートカットフラグ（flags）を保存
5. 後続のItemAdd()でItemHandleShortcut()が呼び出される

**関連システム・外部連携**：NextItemData構造体を介してウィジェット作成関数と連携する。内部的にShortcut()関数を呼び出してショートカット検出を行う。

**権限による制御**：フラグによりルーティング動作、リピート動作、ツールチップ表示などを制御できる。無効化されたアイテムはショートカットを受け付けない。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 27 | Inputs | 参照画面 | ショートカットキーのデモ表示 |

## 機能種別

設定処理 / ショートカット登録

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| key_chord | ImGuiKeyChord | Yes | ショートカットキーコード（修飾キー + キー） | なし |
| flags | ImGuiInputFlags | No | ショートカットフラグ（デフォルトは0） | ImGuiInputFlags_SupportedBySetNextItemShortcutで検証 |

### サポートされるフラグ

| フラグ | 説明 |
|--------|------|
| ImGuiInputFlags_Repeat | ショートカットのリピート機能を有効化 |
| ImGuiInputFlags_RouteTypeMask_ | ルーティングタイプの指定 |
| ImGuiInputFlags_Tooltip | ホバー時にショートカットをツールチップ表示 |

### 入力データソース

- なし（呼び出し元からのパラメータのみ）

## 出力仕様

### 出力データ

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

### 出力先

- ImGuiContext.NextItemData構造体
  - HasFlags: ImGuiNextItemDataFlags_HasShortcutが追加される
  - Shortcut: key_chordが設定される
  - ShortcutFlags: flagsが設定される

## 処理フロー

### 処理シーケンス

```
1. SetNextItemShortcut呼び出し
   └─ NextItemData.HasFlagsにHasShortcutフラグを追加

2. ショートカット情報の保存
   └─ NextItemData.Shortcut = key_chord
   └─ NextItemData.ShortcutFlags = flags

3. 後続のウィジェット作成（例：Button()、MenuItem()）
   └─ ItemAdd()内でItemHandleShortcut()が呼び出される

4. ItemHandleShortcut()による処理
   └─ フラグの検証（SupportedBySetNextItemShortcut）
   └─ 無効化チェック
   └─ Tooltip設定（フラグ指定時）
   └─ Shortcut()でショートカット検出
   └─ 検出時はNavActivateIdを設定してアイテムをアクティブ化
```

### フローチャート

```mermaid
flowchart TD
    A[開始: SetNextItemShortcut] --> B[HasFlags |= HasShortcut]
    B --> C[NextItemData.Shortcut = key_chord]
    C --> D[NextItemData.ShortcutFlags = flags]
    D --> E[終了: SetNextItemShortcut]

    F[後続のウィジェット作成] --> G[ItemAdd 内で ItemHandleShortcut 呼び出し]
    G --> H{フラグがサポート範囲内?}
    H -->|No| I[アサーションエラー]
    H -->|Yes| J{アイテムが無効化?}
    J -->|Yes| K[return 処理なし]
    J -->|No| L{Tooltip フラグ?}
    L -->|Yes| M[HasShortcut ステータス設定]
    L -->|No| N[Shortcut で押下判定]
    M --> N
    N --> O{ショートカット検出?}
    O -->|No| P[return]
    O -->|Yes| Q[NavActivateId = id]
    Q --> R[NavHighlightActivated id]
    R --> S[終了]
    I --> S
    K --> S
    P --> S
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-234-01 | 次アイテムのみ有効 | SetNextItemShortcutは直後に作成される1つのアイテムにのみ適用される | 常時 |
| BR-234-02 | 無効化アイテム除外 | 無効化されたアイテムはショートカットを受け付けない | ItemFlags_Disabled設定時 |
| BR-234-03 | Tooltipフラグ | Tooltipフラグ指定時、アイテムホバー時にショートカットキーを表示 | ImGuiInputFlags_Tooltip設定時 |
| BR-234-04 | アクティブ化競合回避 | NavActivateIdが既に設定されている場合はアクティブ化しない | NavActivateId != 0の場合 |

### 計算ロジック

該当なし（設定処理のため）

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

該当なし（メモリ上のコンテキストデータのみ操作）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | アサーションエラー | サポートされていないフラグが指定された場合 | デバッグビルドでアサーション発生 |

### リトライ仕様

該当なし

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

該当なし

## パフォーマンス要件

- 処理時間：O(1)の定数時間で完了
- NextItemData構造体への書き込みのみ
- メモリアロケーションなし

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

該当なし（UIライブラリ内部の設定処理のみ）

## 備考

- SetNextItemShortcutは、SetNextItemWidth()やSetNextItemOpen()と同様の「次のアイテムに対する設定」パターンに従う
- MenuItem()関数はshortcutパラメータを持つが、これは表示専用でありSetNextItemShortcutとは異なる
- Shortcut()関数を直接使用する場合と比較して、アイテムとの関連付けが自動化される

---

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

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

### 推奨読解順序

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

NextItemData構造体とショートカット関連フィールドを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | imgui_internal.h | `imgui_internal.h` | ImGuiNextItemData構造体でShortcut、ShortcutFlagsフィールドを確認 |
| 1-2 | imgui_internal.h | `imgui_internal.h` | ImGuiNextItemDataFlags_列挙型でHasShortcutフラグを確認 |
| 1-3 | imgui.h | `imgui.h` | ImGuiInputFlags_列挙型でサポートされるフラグを確認 |

**読解のコツ**: ImGuiNextItemDataは「次に作成されるアイテム」に対する設定を一時的に保持する構造体。SetNextItemXXX()関数群がこの構造体にデータを書き込み、後続のウィジェット作成関数がこれを読み取って処理する。

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

SetNextItemShortcut関数の宣言と実装を確認する。

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

**主要処理フロー**:
1. **10656行目**: HasFlagsにHasShortcutフラグを追加
2. **10657行目**: Shortcutにkey_chordを設定
3. **10658行目**: ShortcutFlagsにflagsを設定

#### Step 3: ショートカット処理を理解する

ItemHandleShortcut関数でショートカットがどのように処理されるかを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | imgui.cpp | `imgui.cpp` | ItemHandleShortcut関数の実装（10662-10684行目） |
| 3-2 | imgui.cpp | `imgui.cpp` | Shortcut関数との連携を確認 |

**主要処理フロー**:
- **10665行目**: NextItemData.ShortcutFlagsを取得
- **10666行目**: サポート範囲のフラグかをアサーションで検証
- **10668-10669行目**: 無効化チェック
- **10670-10674行目**: Tooltipフラグ時のステータス設定
- **10675-10676行目**: Shortcut()でショートカット検出、NavActivateIdチェック
- **10679-10680行目**: アクティブ化フラグの設定
- **10682行目**: NavActivateDownId、NavActivatePressedIdの設定
- **10683行目**: ハイライト表示

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

```
SetNextItemShortcut(ImGuiKeyChord key_chord, ImGuiInputFlags flags)  [imgui.cpp:10653]
    │
    └─ NextItemData構造体に設定を保存
           │
           │  （後続のウィジェット作成時）
           │
           └─ ItemAdd()  [ウィジェット内部]
                  │
                  └─ ItemHandleShortcut(id)  [imgui.cpp:10662]
                         │
                         ├─ Shortcut(NextItemData.Shortcut, flags, id)  [imgui.cpp:10686]
                         │      │
                         │      ├─ SetShortcutRouting()
                         │      │
                         │      └─ IsKeyChordPressed()
                         │
                         └─ NavHighlightActivated(id)
```

### データフロー図

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

SetNextItemShortcut()
        │
        ▼
ImGuiKeyChord key_chord  ───▶ NextItemData.Shortcut に保存
ImGuiInputFlags flags    ───▶ NextItemData.ShortcutFlags に保存
        │
        │  （後続のウィジェット作成）
        ▼
ItemAdd() ───▶ ItemHandleShortcut() ───▶ Shortcut() で検出
                                              │
                                              ▼
                                         NavActivateId設定 ───▶ アイテムのアクティブ化
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| imgui.h | `imgui.h` | ヘッダー | パブリックAPIの宣言 |
| imgui.cpp | `imgui.cpp` | ソース | SetNextItemShortcut、ItemHandleShortcutの実装 |
| imgui_internal.h | `imgui_internal.h` | ヘッダー | ImGuiNextItemData構造体の定義 |
| imgui_widgets.cpp | `imgui_widgets.cpp` | ソース | Button、MenuItem等でのショートカット使用例 |
| imgui_demo.cpp | `imgui_demo.cpp` | ソース | 使用例のデモコード |
