hanez/xtc
2
1
Fork 1
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Docs file normalization.

Browse source
This commit is contained in:
Johannes Findeisen 2026-11-06 15:20:20 +01:00
commit 619c2d0808
46 changed files with 3587 additions and 2579 deletions
Download patch file Download diff file Expand all files Collapse all files

83
docs/EDITING.md
View file

@ -1,11 +1,13 @@
# Editing commands and undo audit
# Editing Commands and Undo Audit
The control thread owns project edits and history. Audio plans are immutable
snapshots; widgets never pass editable project pointers into the callback.
Graph commands and batch note commands use the existing public C command APIs.
The GUI groups a completed gesture or accepted dialog as one history step.
snapshots; widgets never pass editable project pointers into the callback. Graph
commands and batch note commands use the existing public C command APIs. The GUI
groups a completed gesture or accepted dialog as one history step.
## Operation audit
---
## Operation Audit
| Operation | History / grouping | Engine and external effects |
| --- | --- | --- |
@ -30,7 +32,9 @@ plus a baseline; new accepted edits discard redo, and eviction drops the oldest
baseline. Monotonic ID high-water marks survive undo and branches. History is
session-only; restart/New/Open discards it.
## History ownership and failure boundary
---
## History Ownership and Failure Boundary
`xtc_history_reserve` allocates one empty fixed-capacity project/graph snapshot
before an edit mutates the document or a candidate is submitted to the engine.
@ -47,8 +51,8 @@ The snapshot contains metadata/graph configuration only, never sample buffers,
DSP instances, module handles or GUI pointers. An unused reservation is freed
with history. This adds at most one pending metadata snapshot to the 33 retained
states. C clients that call record without reserving retain the original
clone-and-report-allocation-failure behavior; they must handle that result.
All history work is serialized on the control thread, never the audio callback.
clone-and-report-allocation-failure behavior; they must handle that result. All
history work is serialized on the control thread, never the audio callback.
Undo/redo checks out an owned candidate without moving the cursor, stops/resets
transport and prepares its assets/plans, then accepts the adjacent history step
@ -57,33 +61,38 @@ cursor/document, so retry is possible. Preparation failure may leave transport
stopped at zero; it does not resume playback automatically. Snapshot restoration
marks the document dirty conservatively, even if it matches a saved file.
## Selection, focus and menus
---
Ctrl+Z undoes; Ctrl+Shift+Z and Ctrl+Y redo. The main Edit menu disables unavailable
steps and disables history while recording. Piano roll also has Edit/Undo/Redo
shortcuts. Undo preserves currently selected track/clip, mixer strip, graph node
and piano-roll clip/note when their stable IDs still exist (notes must remain
visible under the current filter). Clip selection follows its restored track. A removed selection
clears, with track fallback for a removed clip. A visible piano roll stays open
when its clip survives; missing clips hide it. Historical selections/layouts are
not saved in snapshots; undo does not resurrect a selection already cleared by
a deletion. Open/New retain their reset behavior.
## Selection, Focus and Menus
Editor-local shortcuts act on focused editors. Text inputs retain Space and
text undo/editing keys; numeric mixer inputs do not invoke fader shortcuts.
Timeline Ctrl+D duplicates, F2 renames, Alt+Up/Down reorders tracks, S splits
audio at the cursor, A opens audio properties and Delete removes the selection.
Graph Left/Right chooses a node, L arranges by flow, I inserts unity gain in the
selected wire, Delete removes the selected node/wire and Escape cancels gestures.
Piano-roll commands are listed in its Notes menu. Escape cancels gestures;
ordinary deletion is reversible and does not add a confirmation dialog.
Ctrl+Z undoes; Ctrl+Shift+Z and Ctrl+Y redo. The main Edit menu disables
unavailable steps and disables history while recording. Piano roll also has
Edit/Undo/Redo shortcuts. Undo preserves currently selected track/clip, mixer
strip, graph node and piano-roll clip/note when their stable IDs still exist
(notes must remain visible under the current filter). Clip selection follows its
restored track. A removed selection clears, with track fallback for a removed
clip. A visible piano roll stays open when its clip survives; missing clips hide
it. Historical selections/layouts are not saved in snapshots; undo does not
resurrect a selection already cleared by a deletion. Open/New retain their reset
behavior.
Editor-local shortcuts act on focused editors. Text inputs retain Space and text
undo/editing keys; numeric mixer inputs do not invoke fader shortcuts. Timeline
Ctrl+D duplicates, F2 renames, Alt+Up/Down reorders tracks, S splits audio at
the cursor, A opens audio properties and Delete removes the selection. Graph
Left/Right chooses a node, L arranges by flow, I inserts unity gain in the
selected wire, Delete removes the selected node/wire and Escape cancels
gestures. Piano-roll commands are listed in its Notes menu. Escape cancels
gestures; ordinary deletion is reversible and does not add a confirmation
dialog.
Graph right-click now selects the node/wire under the pointer before showing
Inspect/Arrange/Insert/Delete; empty space clears a stale selection. Piano-roll
right-click selects the clicked note and offers Properties/Quantize/Repeat/Delete.
It no longer immediately deletes the note. Timeline context menus retain their
selection and duplicate/rename/delete/audio commands. Dismissing a context menu
does not edit the document. Context menus and widgets remain C++/FLTK UI code.
right-click selects the clicked note and offers
Properties/Quantize/Repeat/Delete. It no longer immediately deletes the note.
Timeline context menus retain their selection and duplicate/rename/delete/audio
commands. Dismissing a context menu does not edit the document. Context menus
and widgets remain C++/FLTK UI code.
Open/import/plugin load/replacement paint a busy cursor and operation status
before synchronous work, flushing drawing without dispatching new input or
@ -93,13 +102,15 @@ optional-support and audio errors. Unsaved New/Open/Quit and Save As overwrite
keep their existing confirmations; undoable deletes and external-media reference
edits do not request extra approval. No operation here deletes source media.
## Evidence and manual procedure
---
`make all test gui test-gui-plugins test-reliability analyze test-workflow
test-gui-jack` covers core commands, grouped gestures/batches, backend rollback,
selection retention, take undo/redo and real software JACK state restoration.
The GUI fixture injects history-reservation failure before graph/map/import
publication and verifies unchanged document, submission count and redo. The
## Evidence and Manual Procedure
`make all test gui test-gui-plugins test-reliability analyze test-workflow test-gui-jack`
covers core commands, grouped gestures/batches, backend rollback, selection
retention, take undo/redo and real software JACK state restoration. The GUI
fixture injects history-reservation failure before graph/map/import publication
and verifies unchanged document, submission count and redo. The
allocation-interposed reliability suite fails each reservation allocation, then
fails all allocations while capturing a reserved edit; redo branching and
snapshot restoration still succeed. ASan/UBSan cover the same ownership paths.