Interactive Editor

There is a built in system for instantly updating the visual music as the end user is typing an ABC string into a textarea.

Constructor

Call this constructor to link a textarea with a div that should display the music:

let editor = new abcjs.Editor(editArea, editorParams);
Editor ParametersDescription
editAreaIf it is a string, then it is an HTML id of a textarea control. Otherwise, it should be an instantiation of an object that expresses the EditArea interface.
editorParamsHash of parameters for the editor.

Editor Params

editorParamsDescription
canvas_id or paper_idHTML id to draw in. If not present, then the drawing happens just below the editor. This can either be an ID or the actual HTML element.
generate_warningsIf present, then parser warnings are displayed on the page. The warnings are displayed just above the music.
warnings_idIf present, the HTML id to place the warnings. This supersedes generate_warnings. This can either be an id or the actual HTML element.
onchangeIf present, the callback function to call whenever there has been a change in the ABC string.
selectionChangeCallbackIf present, the callback function to call whenever there has been a change of selection.
abcjsParamsOptions to send to abcjs when re-rendering both the visual and the audio.
indicate_changedThe dirty flag is set if this is true. When the user types in the textarea then the class abc_textarea_dirty is added to the textarea. Also see the isDirty and setNotDirty methods below.
synthIf present, add an audio control. This is an object. See below for the possible properties. Note: if the browser doesn't support synth, then this parameter has no effect.

Deprecated parameters:

The following parameters are still supported, but they are for the old style of audio generation that used midi.js.

editorParamsDescription
generate_midiif present, then midi is generated.
midi_idif present, the HTML id to place the midi control. Otherwise it is placed in the same div as the paper. An encompassing div surrounds each control with the class in the format "inline-midi midi-%d".
midi_download_idif present, the HTML id to place the midi download link. Otherwise, if midi_id is present it is placed there, otherwise it is placed in the same div as the paper. An encompassing div surrounds each control with the class in the format "download-midi midi-%d".

Synth Properties

This is the object that is passed into the editor in the synth property. If this is present, then a SynthController object is created to handle the audio.

PropertyDescription
elEither a CSS selector or an HTML element for where to place the audio control.
cursorControlOptional: The callback object of type CursorControl if you want to get notified when timing events happen. (See the audioopen in new window section for more details.)
optionsOptional: The options to pass directly to the SynthControlleropen in new window object.

Available Methods

Editor entry pointsDescription
setReadOnly(bool)adds or removes the class abc_textarea_readonly, and adds or removes the attribute readonly.
updateSelection()Called when the user has changed the selection. This calls the engraver_controller to show the selection.
fireSelectionChanged()Called by the textarea object when the user has changed the selection.
`fireChanged()Can be called if the textarea is changed programmatically but the editor doesn't detect it. (For instance, useful in Vue when using modelValue)
paramChanged(abcjsParams)Called to set the abcjsParams after the editor has been created. The music is re-rendered immediately.
setNotDirty()Called by the client app to reset the dirty flag. (For instance, when the user saves their work.)
isDirty()Returns true or false, whether the textarea contains the same text that it started with.
pause(bool)Stops the automatic rendering when the user is typing.
millisecondsPerMeasure()Called to return the number of milliseconds in a measure for the first tune in the editor.
synthParamChanged(options)Called to replace the options passed in when the editor is created. It replaces the options here: { synth: { options: originalOptions } }

Example

<textarea id="abc"></textarea>
<div id="warnings"></div>
<div id="paper"></div>
window.onload = function() {
    abc_editor = new abcjs.Editor("abc", { 
        canvas_id: "paper", 
        warnings_id:"warnings" 
    });
}
Last Updated:
Contributors: Paul Rosen, paulrosen