# 機能設計書 109-ツール切替

## 概要

本ドキュメントは、K-Shoot Editor(譜面エディタ)における編集モード切替/編集対象切替/グリッド分割数切替/アナログ詳細度切替/各種オプション切替の設計を記述する。

### 本機能の処理概要

本機能は、譜面エディタ上の編集動作を制御する各種ツール設定の切替を提供する。編集モード(Point/Pencil/Erase)の切替、編集対象(ノート種別/アナログ/エフェクト等)の切替、グリッド分割数(4分音符~192分音符)の切替、アナログオブジェクトの配置詳細度(標準/詳細/最も詳細)の切替、およびアナログ配置に関するオプション(16分挿入連打抑制/最小挿入抑制/はみ出しLASER始点位置補正)の切替で構成される。

**業務上の目的・背景**: 譜面編集において、操作対象や編集方法をユーザーが自由に切り替えることは、効率的な譜面作成の基盤となる機能である。

**機能の利用シーン**: ツールメニュー、ツールバー、キーボードショートカット、画面下部のアイコンクリック、マウスホイール(Shift/Alt修飾)から実行する。

**主要な処理内容**:
1. 編集モード切替: editmode変数をMODE_POINT/MODE_PENCIL/MODE_ERASEに設定
2. 編集対象切替: edittarget変数をTARGET_POS~TARGET_STOPの16種類に設定
3. グリッド分割数切替: editdiv変数を4/8/12/16/24/32/48/64/96/192に設定
4. アナログ詳細度切替: analogdetail変数を0(標準)/1(詳細)/2(最も詳細)に設定
5. オプション切替: disableanan/disableanmin/anaranadjpos/isDirectChartEditingEnabledの各フラグをトグル

**関連システム・外部連携**: なし。

**権限による制御**: なし。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | 譜面エディタ | 主画面 | ツールメニュー、ツールバー、画面下部アイコン、キーボードショートカット |

## 機能種別

UI制御(エディタ状態管理)

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| cmd | 整数 | Yes | コマンドID(CMD_TOOL_POINT~CMD_TOOL_DIRECTCHARTEDITING) | 有効なコマンド値 |

### 入力データソース

メニュー選択、ツールバークリック、キーボードショートカット、画面下部アイコンクリック、マウスホイール(Shift/Alt修飾)

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| editmode | 整数 | 編集モード(0:Point, 1:Pencil, 2:Erase) |
| edittarget | 整数 | 編集対象(0:POS~14:STOP) |
| editdiv | 整数 | グリッド分割数(4/8/12/16/24/32/48/64/96/192) |
| analogdetail | 整数 | アナログ詳細度(0/1/2) |
| disableanan | 整数 | 16分挿入連打抑制フラグ(0/1) |
| disableanmin | 整数 | 最小挿入抑制フラグ(0/1) |
| anaranadjpos | 整数 | はみ出しLASER始点位置補正フラグ(0/1) |
| isDirectChartEditingEnabled | 整数 | 譜面ファイル直接編集フラグ(0/1) |

### 出力先

メモリ上の状態変数、メニューのチェック状態、ツールバーの押下状態

## 処理フロー

### 処理シーケンス

```
1. 編集モード切替 (CMD_TOOL_POINT/PENCIL/ERASE)
   ├─ editmode変数を対応するMODE_xxx値に設定
   ├─ *refreshmenu_editmode でメニュー/ツールバーのチェック状態を更新
   └─ *draw で画面を再描画

2. 編集対象切替 (CMD_TOOL_POS~CMD_TOOL_STOP)
   ├─ edittarget変数を対応するTARGET_xxx値に設定
   ├─ *refreshmenu_edittarget でメニュー/ツールバーのチェック状態を更新
   └─ *draw で画面を再描画

3. グリッド分割数切替 (CMD_TOOL_4~CMD_TOOL_192)
   ├─ 全CMD_TOOL_4~192のCheckMenuItemを0x00(未チェック)に設定
   ├─ 選択したコマンドのCheckMenuItemを0x08(チェック)に設定
   ├─ editdiv変数を対応する値に設定
   └─ *draw で画面を再描画

4. アナログ詳細度切替 (CMD_TOOL_ANALOGDETAIL0/1/2)
   ├─ 全ANALOGDETAIL系のCheckMenuItemを更新(排他選択)
   └─ analogdetail変数を0/1/2に設定

5. オプション切替 (DISABLEANAN/DISABLEANMIN/ANARAN2XSTARTPOS/DIRECTCHARTEDITING)
   ├─ 対応フラグをトグル(1-現在値)
   └─ CheckMenuItemでメニューのチェック状態を更新
```

### フローチャート

```mermaid
flowchart TD
    A[コマンド受信] --> B{コマンド種別?}
    B -->|POINT/PENCIL/ERASE| C[editmode設定]
    C --> D[*refreshmenu_editmode]
    D --> E[*draw]
    B -->|POS~STOP| F[edittarget設定]
    F --> G[*refreshmenu_edittarget]
    G --> E
    B -->|4~192| H[全CheckMenuItem解除]
    H --> I[選択項目チェック]
    I --> J[editdiv設定]
    J --> E
    B -->|ANALOGDETAIL| K[analogdetail設定]
    K --> L[CheckMenuItem排他更新]
    B -->|オプション| M[フラグトグル]
    M --> N[CheckMenuItem更新]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-109-01 | 編集モード排他 | editmode値は0/1/2のいずれか1つのみ(Point/Pencil/Erase) | CMD_TOOL_POINT/PENCIL/ERASE |
| BR-109-02 | 編集対象排他 | edittarget値は0~14のいずれか1つのみ | CMD_TOOL_POS~STOP |
| BR-109-03 | グリッド分割数排他 | editdiv値は4/8/12/16/24/32/48/64/96/192のいずれか1つのみ | CMD_TOOL_4~192 |
| BR-109-04 | アナログ詳細度排他 | analogdetail値は0/1/2のいずれか1つのみ | CMD_TOOL_ANALOGDETAIL0/1/2 |
| BR-109-05 | オプショントグル | disableanan/disableanmin/anaranadjpos/isDirectChartEditingEnabledは0/1のトグル | 各オプションコマンド |
| BR-109-06 | 画面下部サイクル切替 | 画面下部アイコンの左クリックで次へ、右クリックで前へサイクル | 画面下部アイコン操作 |
| BR-109-07 | ホイール切替 | Shift+ホイールでeditmode切替、Alt+ホイールでedittarget切替 | マウスホイール操作 |

### 計算ロジック

メニューチェック状態:
- `CheckMenuItem hmenu, CMD_xxx, 0x08*(editmode=MODE_xxx)` (条件式が真のとき0x08、偽のとき0x00)
- ツールバー: `sendmsg hTool, 0x402, CMD_xxx, (editmode=MODE_xxx)`

画面下部サイクル:
- 左クリック(iparam=0): editmode++ (2を超えたら0に戻る)
- 右クリック(iparam!=0): editmode-- (0未満なら2に戻る)

ホイール切替(Shift+ホイール):
- 120以上: editmode++ (2を超えない)
- -120以下: editmode-- (0未満にならない)

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

該当なし。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | - | 特になし | - |

### リトライ仕様

該当なし。

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

該当なし。

## パフォーマンス要件

特になし。切替後の画面再描画(*draw)がメインの処理コストとなる。

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

特になし。

## 備考

- 編集モード(editmode)のデフォルトはMODE_POINT(0)
- 編集対象(edittarget)のデフォルトはTARGET_POS(0)
- グリッド分割数(editdiv)のデフォルトは16
- *refreshmenu_editmodeはメニュー3項目とツールバー3ボタンの状態を同時に更新する
- *refreshmenu_edittargetはメニュー15項目とツールバー7ボタンの状態を同時に更新する
- グリッド分割数の切替はCheckMenuItem API呼び出しで10個全てのメニュー項目の状態を更新する
- CMD_TOOL_DIRECTCHARTEDITINGは譜面ファイルの直接編集機能の有効/無効を切り替える

---

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

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

### 推奨読解順序

#### Step 1: データ構造(enum定義)を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | kshooteditor.hsp | `kshooteditor.hsp` | 83-85行目: CMD_TOOL_POINT/PENCIL/ERASEのenum定義 |
| 1-2 | kshooteditor.hsp | `kshooteditor.hsp` | 86-101行目: CMD_TOOL_POS~CMD_TOOL_STOPのenum定義 |
| 1-3 | kshooteditor.hsp | `kshooteditor.hsp` | 102-111行目: CMD_TOOL_4~CMD_TOOL_192のenum定義 |
| 1-4 | kshooteditor.hsp | `kshooteditor.hsp` | 150-153行目: CMD_TOOL_ANALOGDETAIL0~2, CMD_TOOL_DIRECTCHARTEDITINGのenum定義 |
| 1-5 | kshooteditor.hsp | `kshooteditor.hsp` | 155-173行目: MODE_POINT/PENCIL/ERASEおよびTARGET_POS~TARGET_STOPのenum定義 |

#### Step 2: メニュー/ツールバー登録を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | kshooteditor.hsp | `kshooteditor.hsp` | 729-767行目: ツールメニューへの各コマンド登録(ショートカットキー含む) |
| 2-2 | kshooteditor.hsp | `kshooteditor.hsp` | 14071-14081行目: ツールバーへのPoint/Pencil/Erase/POS/NOTE等のボタン登録 |

#### Step 3: コマンド処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | kshooteditor.hsp | `kshooteditor.hsp` | 6747-6757行目: CMD_TOOL_POINT/PENCIL/ERASE処理(editmode設定) |
| 3-2 | kshooteditor.hsp | `kshooteditor.hsp` | 6758-6817行目: CMD_TOOL_POS~CMD_TOOL_STOP処理(edittarget設定) |
| 3-3 | kshooteditor.hsp | `kshooteditor.hsp` | 6818-6947行目: CMD_TOOL_4~CMD_TOOL_192処理(editdiv設定、CheckMenuItemで排他チェック) |
| 3-4 | kshooteditor.hsp | `kshooteditor.hsp` | 6948-6974行目: CMD_TOOL_ANALOGDETAIL0~2およびオプション切替処理 |

**主要処理フロー(編集モード切替)**:
- **6747行目**: `if(cmd=CMD_TOOL_POINT)` → `editmode=MODE_POINT`
- **6748行目**: `gosub *refreshmenu_editmode` でメニュー/ツールバー状態更新
- **6749行目**: `gosub *draw` で画面再描画

**主要処理フロー(グリッド分割数切替)**:
- **6818-6828行目**: CMD_TOOL_4の場合、10個のCheckMenuItemを全て0x00にリセットし、CMD_TOOL_4のみ0x08(チェック)に設定
- **6829行目**: `editdiv=4`
- **6830行目**: `gosub *draw` で画面再描画

#### Step 4: メニュー/ツールバー更新サブルーチンを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | kshooteditor.hsp | `kshooteditor.hsp` | 14120-14127行目: *refreshmenu_editmode(3つのCheckMenuItemと3つのツールバーボタン状態更新) |
| 4-2 | kshooteditor.hsp | `kshooteditor.hsp` | 14129-14152行目: *refreshmenu_edittarget(15のCheckMenuItemと7つのツールバーボタン状態更新) |

#### Step 5: 画面下部/ホイールによる切替を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | kshooteditor.hsp | `kshooteditor.hsp` | 10270-10280行目: 画面下部アイコンによるeditmode切替(左/右クリックでサイクル) |
| 5-2 | kshooteditor.hsp | `kshooteditor.hsp` | 10282-10292行目: 画面下部アイコンによるedittarget切替 |
| 5-3 | kshooteditor.hsp | `kshooteditor.hsp` | 10294-10318行目: 画面下部アイコンによるeditdiv切替(サイクル順序定義) |
| 5-4 | kshooteditor.hsp | `kshooteditor.hsp` | 13526-13541行目: Shift+ホイールによるeditmode切替 |
| 5-5 | kshooteditor.hsp | `kshooteditor.hsp` | 13542-13558行目: Alt+ホイールによるedittarget切替 |

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

```
*OnCommand
    │
    ├─ CMD_TOOL_POINT/PENCIL/ERASE
    │   ├─ editmode = MODE_xxx
    │   ├─ *refreshmenu_editmode
    │   │   ├─ CheckMenuItem (メニュー3項目)
    │   │   └─ sendmsg hTool (ツールバー3ボタン)
    │   └─ *draw
    │
    ├─ CMD_TOOL_POS~CMD_TOOL_STOP
    │   ├─ edittarget = TARGET_xxx
    │   ├─ *refreshmenu_edittarget
    │   │   ├─ CheckMenuItem (メニュー15項目)
    │   │   └─ sendmsg hTool (ツールバー7ボタン)
    │   └─ *draw
    │
    ├─ CMD_TOOL_4~CMD_TOOL_192
    │   ├─ CheckMenuItem x10 (全項目リセット+選択チェック)
    │   ├─ editdiv = 値
    │   └─ *draw
    │
    ├─ CMD_TOOL_ANALOGDETAIL0/1/2
    │   ├─ CheckMenuItem x3 (排他チェック)
    │   └─ analogdetail = 0/1/2
    │
    └─ CMD_TOOL_DISABLEANAN/DISABLEANMIN/ANARAN2XSTARTPOS/DIRECTCHARTEDITING
        ├─ フラグ = 1 - フラグ (トグル)
        └─ CheckMenuItem (チェック状態更新)

画面下部アイコン (10270-10318行目)
    ├─ editmode++/-- → *refreshmenu_editmode → *draw
    ├─ edittarget++/-- → *refreshmenu_edittarget → *draw
    └─ editdiv切替 → *OnCommand(CMD_TOOL_xxx)

ホイール (13526-13558行目)
    ├─ Shift+ホイール → editmode++/-- → *refreshmenu_editmode → *draw
    └─ Alt+ホイール → edittarget++/-- → *refreshmenu_edittarget → *draw
```

### データフロー図

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

メニュー/ツールバー     ──────▶  CMD_TOOL_xxx             ───▶  editmode/edittarget/editdiv
/ショートカット                  (状態変数設定)                  (メニュー/ツールバー状態更新)

画面下部アイコン        ──────▶  サイクル切替              ───▶  editmode/edittarget/editdiv
(左/右クリック)                  (++/--でサイクル)

Shift/Alt+ホイール      ──────▶  ホイール切替              ───▶  editmode/edittarget
                                (方向に応じて++/--)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| kshooteditor.hsp | `kshooteditor.hsp` | ソース | enum定義(83-173行目)、メニュー登録(729-767行目)、コマンド処理(6747-6974行目)、画面下部/ホイール切替(10270-10318,13526-13558行目)、メニュー更新サブルーチン(14120-14152行目)、ツールバー登録(14071-14081行目) |
