Skip to content

editor.md

Latest commit

 

History

History
213 lines (157 loc) · 9.61 KB

editor.md

File metadata and controls

213 lines (157 loc) · 9.61 KB
sidebar_position 2

Editor

context.editor exposes the active editor surface, model, cursor state, quantize helper, and selection object.

Properties

Property Type Writable Example Description
activeRegion object no — Active region surface. Only available when editing a region/part.
cursorInfo object no — Cursor position data.
environment object no — Editor environment surface.
model object no — Editor model surface.
selection object no — Selection control surface.
quantize object no — Quantize grid helper.

Methods

Method Returns Parameters Description
canSelect(note) number note (object, req) Checks if a note can be selected. Returns 1 if selectable.
createSelectFunctions(functions) object functions (object, req): context.functions. Builds a selection helper surface.
deleteItem(note) — note (object, req) Deletes a note from the editor.
editItem(note) number note (object, req) Starts editing a note in place. Returns 1 on success.
isSameItem(n1, n2) number n1, n2 (object, req) Checks if two references point to the same item. Returns 1 if same, 0 if different.
showSelection(show) — show (boolean, req): Show or hide. Shows or hides the current selection.
sizeAdjacent() — (none) Resizes adjacent items to fill gaps.
sizeLeft(event, size) object event (object, req), size (number, req) Resize left edge of an event by the given amount.
sizeRight(event, size) object event (object, req), size (number, req) Resize right edge of an event by the given amount.
suspendFollowEvents() — (none) Suspends follow-event mode.

SelectFunctions

Returned by editor.createSelectFunctions(functions). The journal methods (beginMultiple, endMultiple, setJournalEnabled, isJournalEnabled) are the same as context.functions — see functions.md.

Properties

Property Type Writable Example Description
executeImmediately number yes 1 0 = defer operations, 1 = execute immediately.

Methods

Method Returns Parameters Description
selectMultiple(events) — events (array, req): Array of event objects. Selects multiple events.

Active Region

context.editor.activeRegion exposes the active region surface.

Method Returns Parameters Description
createSequenceIterator() object (none) Creates an iterator over the sequence's note events.
getSoundVariationForNote(note) number note (note event, req): A note event from the iterator. Returns the sound variation index.
getLyricsForNote(note) object note (note event, req): A note event from the iterator. Returns a lyrics object for events with lyrics.

The Event Object — Lyrics Events for the full lyrics object surface.

Cursor Info

context.editor.cursorInfo exposes cursor position data. The cursorTime, loopStart, and loopEnd properties return time objects — see Time Object for their full surface.

Properties

Property Type Writable Example Description
cursorTime object - Time Object No — Current cursor position.
loopEnd object - Time Object No — Loop region end position.
loopStart object - Time Object No — Loop region start position.

Methods

Method Returns Parameters Description
beginEdit(editFollow) — editFollow (boolean, opt): Edit-follow mode control. Begins a cursor transaction. Use with endEdit() to group cursor changes under edit-follow.
endEdit() — (none) Ends a cursor editing transaction.
toggleLoop() — (none) Toggles loop mode on/off.
toggleStart() — (none) Toggles the start marker at the current cursor position.
setCursorTime(time) — time (Time Object, req): A time position. Moves the cursor to the given time.
setEditCursorTime(time) — time (Time Object, req): A time position. Sets the edit cursor position during playback.
setLoopRange(start, end) — start, end (Time Object, req): Loop boundaries. Sets the loop region.

Model

context.editor.model exposes the editor model surface.

Properties

Property Type Writable Example Description
arranger object No — Arranger track surface.

Methods

Method Returns Parameters Description
setDocumentDirty() — (none) Marks document as modified.
selectAllOnTrack(editor) — editor (object, req): context.editor. Selects all events on track.

Arranger

context.editor.model.arranger is the control surface for the Arranger Track.

Methods

Method Returns Parameters Description
getArrangerTrack() object (none) Returns the ArrangerTrack object handle.
showArrangerTrack() — (none) Shows the Arranger Track in the editor.
addArrangerEvent(track, start, end) object track (object, req): from getArrangerTrack(), start (Time Object, req), end (Time Object, req) Creates an arranger section and returns the event object.

ArrangerTrack Object

Returned by getArrangerTrack().

Property Type Writable Example Description
name string No "Arranger Track" Track name.
color number No 13333248 Track color as integer.
length number No 600 Track length.
startTime object - Time Object No — Track start time boundary.
endTime object - Time Object No — Track end time boundary.
parent object No — Parent object.

Arranger event object:

The arranger event object shares the same properties as other event types — see Event Object — Arranger Events for the full surface (name, startTime, endTime, length, lengthTime, color).

Working Pattern:

var arranger = context.editor.model.arranger;
var track    = arranger.getArrangerTrack();

var start = fn.newMediaTime();
var end   = fn.newMediaTime();
start.musical = 1;   // Start at beat 1
end.musical   = 9;   // End at beat 9 (8 beats long)

var event = arranger.addArrangerEvent(track, start, end);
fn.renameEvent(event, "Section Name");
fn.colorizeEvent(event, colorIntValue);
arranger.showArrangerTrack();

Quantize

context.editor.quantize provides a quantize grid helper. Time objects passed to these methods are modified in-place.

Method Returns Parameters Description
clone() object (none) Returns a new independent quantize surface.
getPeriod() number (none) Returns the current grid period in musical beats.
nextTime(time) — time (Time Object, req): Time to advance. Advances to the next grid position in-place.
quantizeTime(time) — time (Time Object, req): Time to quantize. Identical to snapTime.
snapTime(time) — time (Time Object, req): Time to snap. Rounds to the nearest grid position in-place.

Selection

context.editor.selection exposes the selection control surface.

Property Type Writable Example Description
showHideSuspended number yes 0 Suspends selection visibility updates. 0 = visible, 1 = suspended.
Method Returns Parameters Description
isSelected(event) number event (note event, req): A note event from the iterator. Checks selection state. 1 = selected, 0 = not selected.
isEmpty() number (none) Returns 1 if empty, 0 if items are selected.
isMultiple() number (none) Returns 1 if 2+ items selected, 0 otherwise.
newIterator() object (none) Creates an iterator over selected events.
unselectAll() — (none) Clears the current selection.

Setup Example

var editor = context.editor;
var selection = editor.selection;
var functions = context.functions;
var select = editor.createSelectFunctions(functions);

if (!editor.activeRegion) return;

var cursor = editor.cursorInfo.cursorTime.musical;

editor.showSelection(false);
selection.showHideSuspended = true;
selection.unselectAll();
select.selectMultiple([]);

Selection Control Pattern

// Deselect all:
context.editor.selection.unselectAll()

// Suppress visual updates during batch selection:
context.editor.showSelection(false);
context.editor.selection.showHideSuspended = true;
// ... perform selections ...
context.editor.selection.showHideSuspended = false;
context.editor.showSelection(true);

// Reliable multi-select:
var selector = context.editor.createSelectFunctions(context.functions);
selector.executeImmediately = true;
selector.selectMultiple(arrayOfNotes);
selector.select(singleNote);