vexflow

<!DOCTYPE html> <html> <head> <title>note.js</title> <meta http-equiv="content-type" content="text/html; charset=UTF-8"> <link rel="stylesheet" media="all" href="public/stylesheets/normalize.css" /> <link rel="stylesheet" media="all" href="docco.css" /> </head> <body> <div class="container"> <div class="page"> <div class="header"> <h1>note.js</h1> <div class="toc"> <h3>Table of Contents</h3> <ol> <li> <a class="source" href="accidental.html"> accidental.js </a> </li> <li> <a class="source" href="annotation.html"> annotation.js </a> </li> <li> <a class="source" href="articulation.html"> articulation.js </a> </li> <li> <a class="source" href="barnote.html"> barnote.js </a> </li> <li> <a class="source" href="beam.html"> beam.js </a> </li> <li> <a class="source" href="bend.html"> bend.js </a> </li> <li> <a class="source" href="boundingbox.html"> boundingbox.js </a> </li> <li> <a class="source" href="boundingboxcomputation.html"> boundingboxcomputation.js </a> </li> <li> <a class="source" href="canvascontext.html"> canvascontext.js </a> </li> <li> <a class="source" href="clef.html"> clef.js </a> </li> <li> <a class="source" href="clefnote.html"> clefnote.js </a> </li> <li> <a class="source" href="crescendo.html"> crescendo.js </a> </li> <li> <a class="source" href="curve.html"> curve.js </a> </li> <li> <a class="source" href="dot.html"> dot.js </a> </li> <li> <a class="source" href="easyscore.html"> easyscore.js </a> </li> <li> <a class="source" href="element.html"> element.js </a> </li> <li> <a class="source" href="factory.html"> factory.js </a> </li> <li> <a class="source" href="formatter.html"> formatter.js </a> </li> <li> <a class="source" href="fraction.html"> fraction.js </a> </li> <li> <a class="source" href="frethandfinger.html"> frethandfinger.js </a> </li> <li> <a class="source" href="ghostnote.html"> ghostnote.js </a> </li> <li> <a class="source" href="glyph.html"> glyph.js </a> </li> <li> <a class="source" href="glyphnote.html"> glyphnote.js </a> </li> <li> <a class="source" href="gracenote.html"> gracenote.js </a> </li> <li> <a class="source" href="gracenotegroup.html"> gracenotegroup.js </a> </li> <li> <a class="source" href="gracetabnote.html"> gracetabnote.js </a> </li> <li> <a class="source" href="index.html"> index.js </a> </li> <li> <a class="source" href="keymanager.html"> keymanager.js </a> </li> <li> <a class="source" href="keysignature.html"> keysignature.js </a> </li> <li> <a class="source" href="keysignote.html"> keysignote.js </a> </li> <li> <a class="source" href="modifier.html"> modifier.js </a> </li> <li> <a class="source" href="modifiercontext.html"> modifiercontext.js </a> </li> <li> <a class="source" href="multimeasurerest.html"> multimeasurerest.js </a> </li> <li> <a class="source" href="music.html"> music.js </a> </li> <li> <a class="source" href="note.html"> note.js </a> </li> <li> <a class="source" href="notehead.html"> notehead.js </a> </li> <li> <a class="source" href="notesubgroup.html"> notesubgroup.js </a> </li> <li> <a class="source" href="ornament.html"> ornament.js </a> </li> <li> <a class="source" href="parser.html"> parser.js </a> </li> <li> <a class="source" href="pedalmarking.html"> pedalmarking.js </a> </li> <li> <a class="source" href="raphaelcontext.html"> raphaelcontext.js </a> </li> <li> <a class="source" href="registry.html"> registry.js </a> </li> <li> <a class="source" href="renderer.html"> renderer.js </a> </li> <li> <a class="source" href="repeatnote.html"> repeatnote.js </a> </li> <li> <a class="source" href="smufl.html"> smufl.js </a> </li> <li> <a class="source" href="stave.html"> stave.js </a> </li> <li> <a class="source" href="stavebarline.html"> stavebarline.js </a> </li> <li> <a class="source" href="staveconnector.html"> staveconnector.js </a> </li> <li> <a class="source" href="stavehairpin.html"> stavehairpin.js </a> </li> <li> <a class="source" href="staveline.html"> staveline.js </a> </li> <li> <a class="source" href="stavemodifier.html"> stavemodifier.js </a> </li> <li> <a class="source" href="stavenote.html"> stavenote.js </a> </li> <li> <a class="source" href="staverepetition.html"> staverepetition.js </a> </li> <li> <a class="source" href="stavesection.html"> stavesection.js </a> </li> <li> <a class="source" href="stavetempo.html"> stavetempo.js </a> </li> <li> <a class="source" href="stavetext.html"> stavetext.js </a> </li> <li> <a class="source" href="stavetie.html"> stavetie.js </a> </li> <li> <a class="source" href="stavevolta.html"> stavevolta.js </a> </li> <li> <a class="source" href="stem.html"> stem.js </a> </li> <li> <a class="source" href="stemmablenote.html"> stemmablenote.js </a> </li> <li> <a class="source" href="stringnumber.html"> stringnumber.js </a> </li> <li> <a class="source" href="strokes.html"> strokes.js </a> </li> <li> <a class="source" href="svgcontext.html"> svgcontext.js </a> </li> <li> <a class="source" href="system.html"> system.js </a> </li> <li> <a class="source" href="tables.html"> tables.js </a> </li> <li> <a class="source" href="tabnote.html"> tabnote.js </a> </li> <li> <a class="source" href="tabslide.html"> tabslide.js </a> </li> <li> <a class="source" href="tabstave.html"> tabstave.js </a> </li> <li> <a class="source" href="tabtie.html"> tabtie.js </a> </li> <li> <a class="source" href="textbracket.html"> textbracket.js </a> </li> <li> <a class="source" href="textdynamics.html"> textdynamics.js </a> </li> <li> <a class="source" href="textnote.html"> textnote.js </a> </li> <li> <a class="source" href="tickable.html"> tickable.js </a> </li> <li> <a class="source" href="tickcontext.html"> tickcontext.js </a> </li> <li> <a class="source" href="timesignature.html"> timesignature.js </a> </li> <li> <a class="source" href="timesignote.html"> timesignote.js </a> </li> <li> <a class="source" href="tremolo.html"> tremolo.js </a> </li> <li> <a class="source" href="tuning.html"> tuning.js </a> </li> <li> <a class="source" href="tuplet.html"> tuplet.js </a> </li> <li> <a class="source" href="vex.html"> vex.js </a> </li> <li> <a class="source" href="vibrato.html"> vibrato.js </a> </li> <li> <a class="source" href="vibratobracket.html"> vibratobracket.js </a> </li> <li> <a class="source" href="voice.html"> voice.js </a> </li> <li> <a class="source" href="voicegroup.html"> voicegroup.js </a> </li> </ol> </div> </div> <a href="http://vexflow.com">VexFlow</a> - Copyright (c) Mohit Muthanna 2010. <h2 id="description">Description</h2> This file implements an abstract interface for notes and chords that are rendered on a stave. Notes have some common properties: All of them have a value (e.g., pitch, fret, etc.) and a duration (quarter, half, etc.) Some notes have stems, heads, dots, etc. Most notational elements that surround a note are called modifiers, and every note has an associated array of them. All notes also have a rendering context and belong to a stave. <div class='highlight'><pre> import { Vex } from './vex'; import { Flow } from './tables'; import { Tickable } from './tickable'; export class Note extends Tickable { static get CATEGORY() { return 'note'; }</pre></div> Debug helper. Displays various note metrics for the given note. <div class='highlight'><pre> static plotMetrics(ctx, note, yPos) { const metrics = note.getMetrics(); const xStart = note.getAbsoluteX() - metrics.modLeftPx - metrics.leftDisplacedHeadPx; const xPre1 = note.getAbsoluteX() - metrics.leftDisplacedHeadPx; const xAbs = note.getAbsoluteX(); const xPost1 = note.getAbsoluteX() + metrics.notePx; const xPost2 = note.getAbsoluteX() + metrics.notePx + metrics.rightDisplacedHeadPx; const xEnd = note.getAbsoluteX() + metrics.notePx + metrics.rightDisplacedHeadPx + metrics.modRightPx; const xFreedomRight = xEnd + (note.getFormatterMetrics().freedom.right || 0); const xWidth = xEnd - xStart; ctx.save(); ctx.setFont('Arial', 8, ''); ctx.fillText(Math.round(xWidth) + 'px', xStart + note.getXShift(), yPos); const y = (yPos + 7); function stroke(x1, x2, color, yy = y) { ctx.beginPath(); ctx.setStrokeStyle(color); ctx.setFillStyle(color); ctx.setLineWidth(3); ctx.moveTo(x1 + note.getXShift(), yy); ctx.lineTo(x2 + note.getXShift(), yy); ctx.stroke(); } stroke(xStart, xPre1, 'red'); stroke(xPre1, xAbs, '#999'); stroke(xAbs, xPost1, 'green'); stroke(xPost1, xPost2, '#999'); stroke(xPost2, xEnd, 'red'); stroke(xEnd, xFreedomRight, '#DD0'); stroke(xStart - note.getXShift(), xStart, '#BBB'); // Shift Vex.drawDot(ctx, xAbs + note.getXShift(), y, 'blue'); const formatterMetrics = note.getFormatterMetrics(); if (formatterMetrics.iterations > 0) { const spaceDeviation = formatterMetrics.space.deviation; const prefix = spaceDeviation >= 0 ? '+' : ''; ctx.setFillStyle('red'); ctx.fillText(prefix + Math.round(spaceDeviation), xAbs + note.getXShift(), yPos - 10); } ctx.restore(); } static parseDuration(durationString) { if (typeof (durationString) !== 'string') { return null; } const regexp = /(\d*\/?\d+|[a-z])(d*)([nrhms]|$)/; const result = regexp.exec(durationString); if (!result) { return null; } const duration = result[1]; const dots = result[2].length; const type = result[3] || 'n'; return { duration, dots, type }; } static parseNoteStruct(noteStruct) { const durationString = noteStruct.duration; const customTypes = [];</pre></div> Preserve backwards-compatibility <div class='highlight'><pre> const durationProps = Note.parseDuration(durationString); if (!durationProps) { return null; }</pre></div> If specified type is invalid, return null <div class='highlight'><pre> let type = noteStruct.type; if (type && !Flow.getGlyphProps.validTypes[type]) { return null; }</pre></div> If no type specified, check duration or custom types <div class='highlight'><pre> if (!type) { type = durationProps.type || 'n';</pre></div> If we have keys, try and check if we’ve got a custom glyph <div class='highlight'><pre> if (noteStruct.keys !== undefined) { noteStruct.keys.forEach((k, i) => { const result = k.split('/');</pre></div> We have a custom glyph specified after the note eg. /X2 <div class='highlight'><pre> customTypes[i] = (result && result.length === 3) ? result[2] : type; }); } }</pre></div> Calculate the tick duration of the note <div class='highlight'><pre> let ticks = Flow.durationToTicks(durationProps.duration); if (ticks == null) { return null; }</pre></div> Are there any dots? <div class='highlight'><pre> const dots = noteStruct.dots ? noteStruct.dots : durationProps.dots; if (typeof (dots) !== 'number') { return null; }</pre></div> Add ticks as necessary depending on the numbr of dots <div class='highlight'><pre> let currentTicks = ticks; for (let i = 0; i < dots; i++) { if (currentTicks <= 1) return null; currentTicks = currentTicks / 2; ticks += currentTicks; } return { duration: durationProps.duration, type, customTypes, dots, ticks, }; }</pre></div> Every note is a tickable, i.e., it can be mutated by the <code>Formatter</code> class for positioning and layout. To create a new note you need to provide a <code>noteStruct</code>, which consists of the following fields: <code>type</code>: The note type (e.g., <code>r</code> for rest, <code>s</code> for slash notes, etc.) <code>dots</code>: The number of dots, which affects the duration. <code>duration</code>: The time length (e.g., <code>q</code> for quarter, <code>h</code> for half, <code>8</code> for eighth etc.) The range of values for these parameters are available in <code>src/tables.js</code>. <div class='highlight'><pre> constructor(noteStruct) { super(); this.setAttribute('type', 'Note'); if (!noteStruct) { throw new Vex.RuntimeError( 'BadArguments', 'Note must have valid initialization data to identify duration and type.' ); }</pre></div> Parse <code>noteStruct</code> and get note properties. <div class='highlight'><pre> const initStruct = Note.parseNoteStruct(noteStruct); if (!initStruct) { throw new Vex.RuntimeError( 'BadArguments', `Invalid note initialization object: ${JSON.stringify(noteStruct)}` ); }</pre></div> Set note properties from parameters. <div class='highlight'><pre> this.duration = initStruct.duration; this.dots = initStruct.dots; this.noteType = initStruct.type; this.customTypes = initStruct.customTypes; if (noteStruct.duration_override) {</pre></div> Custom duration <div class='highlight'><pre> this.setDuration(noteStruct.duration_override); } else {</pre></div> Default duration <div class='highlight'><pre> this.setIntrinsicTicks(initStruct.ticks); } this.modifiers = [];</pre></div> Get the glyph code for this note from the font. <div class='highlight'><pre> this.glyph = Flow.getGlyphProps(this.duration, this.noteType); this.customGlyphs = this.customTypes.map(t => Flow.getGlyphProps(this.duration, t)); if (this.positions && (typeof (this.positions) !== 'object' || !this.positions.length)) { throw new Vex.RuntimeError('BadArguments', 'Note keys must be array type.'); }</pre></div> Note to play for audio players. <div class='highlight'><pre> this.playNote = null;</pre></div> Positioning contexts used by the Formatter. <div class='highlight'><pre> this.tickContext = null; // The current tick context. this.modifierContext = null; this.ignore_ticks = false;</pre></div> Positioning variables <div class='highlight'><pre> this.width = 0; // Width in pixels calculated after preFormat this.leftDisplacedHeadPx = 0; // Extra room on left for displaced note head this.rightDisplacedHeadPx = 0; // Extra room on right for displaced note head this.x_shift = 0; // X shift from tick context X this.voice = null; // The voice that this note is in this.preFormatted = false; // Is this note preFormatted? this.ys = []; // list of y coordinates for each note</pre></div> we need to hold on to these for ties and beams. <div class='highlight'><pre> if (noteStruct.align_center) { this.setCenterAlignment(noteStruct.align_center); }</pre></div> The render surface. <div class='highlight'><pre> this.stave = null; this.render_options = { annotation_spacing: 5, }; }</pre></div> Get and set the play note, which is arbitrary data that can be used by an audio player. <div class='highlight'><pre> getPlayNote() { return this.playNote; } setPlayNote(note) { this.playNote = note; return this; }</pre></div> Don’t play notes by default, call them rests. This is also used by things like beams and dots for positioning. <div class='highlight'><pre> isRest() { return false; }</pre></div> TODO(0xfe): Why is this method here? <div class='highlight'><pre> addStroke(index, stroke) { stroke.setNote(this); stroke.setIndex(index); this.modifiers.push(stroke); this.setPreFormatted(false); return this; }</pre></div> Get and set the target stave. <div class='highlight'><pre> getStave() { return this.stave; } setStave(stave) { this.stave = stave; this.setYs([stave.getYForLine(0)]); // Update Y values if the stave is changed. this.context = this.stave.context; return this; }</pre></div> <code>Note</code> is not really a modifier, but is used in a <code>ModifierContext</code>. <div class='highlight'><pre> getCategory() { return Note.CATEGORY; }</pre></div> Set the rendering context for the note. <div class='highlight'><pre> setContext(context) { this.context = context; return this; }</pre></div> Get and set spacing to the left and right of the notes. <div class='highlight'><pre> getLeftDisplacedHeadPx() { return this.leftDisplacedHeadPx; } getRightDisplacedHeadPx() { return this.rightDisplacedHeadPx; } setLeftDisplacedHeadPx(x) { this.leftDisplacedHeadPx = x; return this; } setRightDisplacedHeadPx(x) { this.rightDisplacedHeadPx = x; return this; }</pre></div> Returns true if this note has no duration (e.g., bar notes, spacers, etc.) <div class='highlight'><pre> shouldIgnoreTicks() { return this.ignore_ticks; }</pre></div> Get the stave line number for the note. <div class='highlight'><pre> getLineNumber() { return 0; }</pre></div> Get the stave line number for rest. <div class='highlight'><pre> getLineForRest() { return 0; }</pre></div> Get the glyph associated with this note. <div class='highlight'><pre> getGlyph() { return this.glyph; } getGlyphWidth() {</pre></div> TODO: FIXME (multiple potential values for this.glyph) <div class='highlight'><pre> if (this.glyph) { if (this.glyph.getMetrics) { return this.glyph.getMetrics().width; } else if (this.glyph.getWidth) { return this.glyph.getWidth(this.render_options.glyph_font_scale); } } return 0; }</pre></div> Set and get Y positions for this note. Each Y value is associated with an individual pitch/key within the note/chord. <div class='highlight'><pre> setYs(ys) { this.ys = ys; return this; } getYs() { if (this.ys.length === 0) { throw new Vex.RERR('NoYValues', 'No Y-values calculated for this note.'); } return this.ys; }</pre></div> Get the Y position of the space above the stave onto which text can be rendered. <div class='highlight'><pre> getYForTopText(text_line) { if (!this.stave) { throw new Vex.RERR('NoStave', 'No stave attached to this note.'); } return this.stave.getYForTopText(text_line); }</pre></div> Get a <code>BoundingBox</code> for this note. <div class='highlight'><pre> getBoundingBox() { return null; }</pre></div> Returns the voice that this note belongs in. <div class='highlight'><pre> getVoice() { if (!this.voice) throw new Vex.RERR('NoVoice', 'Note has no voice.'); return this.voice; }</pre></div> Attach this note to <code>voice</code>. <div class='highlight'><pre> setVoice(voice) { this.voice = voice; this.preFormatted = false; return this; }</pre></div> Get and set the <code>TickContext</code> for this note. <div class='highlight'><pre> getTickContext() { return this.tickContext; } setTickContext(tc) { this.tickContext = tc; this.preFormatted = false; return this; }</pre></div> Accessors for the note type. <div class='highlight'><pre> getDuration() { return this.duration; } isDotted() { return (this.dots > 0); } hasStem() { return false; } getDots() { return this.dots; } getNoteType() { return this.noteType; } setBeam() { return this; } // ignore parameters</pre></div> Attach this note to a modifier context. <div class='highlight'><pre> setModifierContext(mc) { this.modifierContext = mc; return this; }</pre></div> Attach a modifier to this note. <div class='highlight'><pre> addModifier(modifier, index = 0) { modifier.setNote(this); modifier.setIndex(index); this.modifiers.push(modifier); this.setPreFormatted(false); return this; }</pre></div> Get the coordinates for where modifiers begin. <div class='highlight'><pre> getModifierStartXY() { if (!this.preFormatted) { throw new Vex.RERR('UnformattedNote', "Can't call GetModifierStartXY on an unformatted note"); } return { x: this.getAbsoluteX(), y: this.ys[0], }; }</pre></div> Get bounds and metrics for this note. Returns a struct with fields: <code>width</code>: The total width of the note (including modifiers.) <code>notePx</code>: The width of the note head only. <code>left_shift</code>: The horizontal displacement of the note. <code>modLeftPx</code>: Start <code>X</code> for left modifiers. <code>modRightPx</code>: Start <code>X</code> for right modifiers. <code>leftDisplacedHeadPx</code>: Extra space on left of note. <code>rightDisplacedHeadPx</code>: Extra space on right of note. <div class='highlight'><pre> getMetrics() { if (!this.preFormatted) { throw new Vex.RERR('UnformattedNote', "Can't call getMetrics on an unformatted note."); } const modLeftPx = this.modifierContext ? this.modifierContext.state.left_shift : 0; const modRightPx = this.modifierContext ? this.modifierContext.state.right_shift : 0; const width = this.getWidth(); const glyphWidth = this.getGlyphWidth(); const notePx = width - modLeftPx // subtract left modifiers - modRightPx // subtract right modifiers - this.leftDisplacedHeadPx // subtract left displaced head - this.rightDisplacedHeadPx; // subtract right displaced head return {</pre></div> <hr> <h2 id="note-if-you-change-this-remember-to-update-mocktickable-in-the-tests-directory">NOTE: If you change this, remember to update MockTickable in the tests/ directory.</h2> <div class='highlight'><pre> width, glyphWidth, notePx,</pre></div> Modifier spacing. <div class='highlight'><pre> modLeftPx, modRightPx,</pre></div> Displaced note head on left or right. <div class='highlight'><pre> leftDisplacedHeadPx: this.leftDisplacedHeadPx, rightDisplacedHeadPx: this.rightDisplacedHeadPx, }; }</pre></div> Get the absolute <code>X</code> position of this note’s tick context. This excludes x_shift, so you’ll need to factor it in if you’re looking for the post-formatted x-position. <div class='highlight'><pre> getAbsoluteX() { if (!this.tickContext) { throw new Vex.RERR('NoTickContext', 'Note needs a TickContext assigned for an X-Value'); }</pre></div> Position note to left edge of tick context. <div class='highlight'><pre> let x = this.tickContext.getX(); if (this.stave) { x += this.stave.getNoteStartX() + this.musicFont.lookupMetric('stave.padding'); } if (this.isCenterAligned()) { x += this.getCenterXShift(); } return x; } setPreFormatted(value) { this.preFormatted = value; } }</pre></div> <div class="fleur">h</div> </div> </div> </body> </html>