52 lines
5.0 KiB
Markdown
52 lines
5.0 KiB
Markdown
# src/shell/actions — bindable REAPER actions, drag/drop shells, ingest
|
|
|
|
## Scope
|
|
|
|
The bindable action families routed through REAPER's `command_id`/`gaccel`/
|
|
`hookcommand` contract (Design View toggle actions, bank actions, the prune
|
|
action, and the shared registration plumbing/table), plus the OS drag-out and
|
|
FX-drop shells, plus the extension-side ingest-through-the-bank shell. This is
|
|
where user-facing REAPER actions and OS-level drag/drop live; the underlying
|
|
mutation logic (bank verbs, prune's orphan computation, view-mode reconciliation)
|
|
is owned by other directories and only skinned here.
|
|
|
|
## Invariants
|
|
|
|
- **Ingest is an extension act; the instrument is a read-only bank consumer.** Any
|
|
instrument code path that captures, imports, inserts a timeline item, or writes
|
|
back into the bank is a bug — the instrument reads and plays only.
|
|
- **Ingest NEVER inserts a timeline item.** Arrange capture→bank→assign reuses the
|
|
existing capture add-path and assigns the resulting `Sample` id to the target
|
|
instance; it never places anything on the timeline — capture/placement
|
|
separation is load-bearing here same as everywhere else. Only the arrange-capture
|
|
surface writes the `assignment_request` wire; Media-Explorer import and file-drop
|
|
onto the bank panel do not, and neither affects a live instance's selection.
|
|
- **Every bank index verb wraps its mutation in a batched REAPER undo point**
|
|
(`Undo_BeginBlock2`/`EndBlock2`, `UNDO_STATE_MISCCFG`) so one bank operation is
|
|
one Ctrl-Z.
|
|
- **The prune action is the ONLY file-deletion action in the system**; it opens no
|
|
undo point (file deletion is not REAPER-undoable). It halts on
|
|
`abortedUnreadableUsage` and prints the offending `rsusage_*` key names.
|
|
|
|
## Modules
|
|
|
|
- `shell/actions` (`action_registry` / `design_view_actions` / `bank_actions` / `prune_action`) — the bindable action families, all routed via the `command_id`/`gaccel`/`hookcommand` contract. `action_registry` owns the shared registration plumbing (interned channel-qualified id strings; register and mirror-unregister present the identical pointer) **and the Q-W6 registration TABLE**: `main.cpp`'s own family (capture scopes, panel toggle, insert, batch, realtime, recapture, version) is one `ActionTableRow` array — suffix, phrase, flat function-pointer handler — that registration, hookcommand dispatch, and the unload mirror-unregister all iterate, so adding an action touches the table only (OCP). Bank mutations flow through the promptless `shell/bank_ops` verbs (`bankOp*` + `persistBankOp`, taking `ReaSamplerSession&`), which the panel menus and `bank_actions` consume as thin UX skins. **Every bank index verb wraps its mutation in a batched REAPER undo point (`Undo_BeginBlock2`/`EndBlock2`, `UNDO_STATE_MISCCFG`) so one bank operation is one Ctrl-Z.** The prune action (`prune_action`, `BANK_PRUNE_FOLDER`) is **the ONLY file-deletion action in the system**; it opens no undo point (file deletion is not REAPER-undoable). **pS-usage:** `BANK_PRUNE_FOLDER` halts on `abortedUnreadableUsage` and prints the offending `rsusage_*` key names with clear instructions.
|
|
- `drag_out_win` — OS drag-out shell: Windows OLE `DoDragDrop`/`CF_HDROP`, copy-only (`DROPEFFECT_MOVE` not offered); macOS/Linux via `SWELL_InitiateDragDropOfFileList`.
|
|
- `instrument_drop_win` — FX-button drop shell: resolves a screen point to a track + FX-surface hotspot, then adds a ReaSampler 9000 instance and applies the dragged capture's state via a transient `.vstpreset` + `TrackFX_SetPreset` (the former `TrackFX_SetNamedConfigParm` "vst_chunk" write was silently unappliable for VST3). Exposes `loadInstrumentOntoTrack` (inner half, no own undo block) and `performInstrumentDrop` (wraps in its own undo block). **Never captures, never writes the bank, never inserts a timeline item.**
|
|
- `ingest` — ingest-through-the-bank shell on the EXTENSION side: three surfaces — (1) arrange capture→bank→assign (bindable action), (2) Media-Explorer import→bank→instrument on the selected track, (3) file drop onto the bank panel→bank only. Only surface (1) writes the `assignment_request` ext-state wire. **ingest NEVER inserts a timeline item.**
|
|
|
|
## Gotchas
|
|
|
|
- **Structural wart, partly closed:** `ingest.cpp` / `ingest.h` now live in this
|
|
directory. `ext_keys.h` and `resource.h` still sit at `src/` root: `ext_keys.h`
|
|
is consumed mostly from `shell/instrument/`, so it is not this directory's to
|
|
claim, and `resource.h` is a build input paired with `src/resource.rc` (the SWELL
|
|
resgen step) rather than a shell module.
|
|
- Media-Explorer import is single-file, pull-on-action (`OpenMediaExplorer` +
|
|
`MediaExplorerGetLastPlayedFileInfo`) — there is no enumerate-selected-files or
|
|
register-a-drop-handler API on the Media Explorer surface.
|
|
- REAPER exposes no drag-drop registration API; drop handling is only on
|
|
ReaSampler's own HWNDs (`WM_DROPFILES`/`IDropTarget` on the docked `bank_panel`).
|
|
A drop onto the VST3 editor window relaying to the extension is an unproven
|
|
spike, not a shipped path.
|