Merge branch 'develop' of https://github.com/opensheetmusicdisplay/opensheetmusicdisplay into develop

# Conflicts:
#	src/MusicalScore/Interfaces/IGraphicalSymbolFactory.ts

src/Common/Logging.ts

@@ -1,5 +1,10 @@
 /* tslint:disable:no-console */
 
+/**
+ * Class for logging messages, mainly for debugging purposes.
+ * It should be refactored soon, when an external logging framework
+ * will be chosen (probably log4js).
+ */
 export class Logging {
     public static debug(...args: any[]): void {
         console.debug("[OSMD] ", args.join(" "));

src/MusicalScore/Exceptions.ts

@@ -1,3 +1,4 @@
+
 export class MusicSheetReadingException implements Error {
     public name: string;
     public message: string;

src/MusicalScore/Graphical/AccidentalCalculator.ts

@@ -6,6 +6,9 @@ import {Pitch} from "../../Common/DataObjects/Pitch";
 import {NoteEnum} from "../../Common/DataObjects/Pitch";
 import Dictionary from "typescript-collections/dist/lib/Dictionary";
 
+/**
+ * Compute the accidentals for notes according to the current key instruction
+ */
 export class AccidentalCalculator {
     private symbolFactory: IGraphicalSymbolFactory;
     private keySignatureNoteAlterationsDict: Dictionary<number, AccidentalEnum> = new Dictionary<number, AccidentalEnum>();

src/MusicalScore/Graphical/BoundingBox.ts

@@ -3,6 +3,9 @@ import {PointF2D} from "../../Common/DataObjects/PointF2D";
 import {SizeF2D} from "../../Common/DataObjects/SizeF2D";
 import {RectangleF2D} from "../../Common/DataObjects/RectangleF2D";
 
+/**
+ * A bounding box delimits an area on the 2D plane.
+ */
 export class BoundingBox {
     protected isSymbol: boolean = false;
     protected relativePositionHasBeenSet: boolean = false;

src/MusicalScore/Graphical/GraphicalComment.ts

@@ -1,4 +1,5 @@
 import {GraphicalLabel} from "./GraphicalLabel";
+
 export class GraphicalComment {
     constructor(label: GraphicalLabel, settingsLabel: GraphicalLabel) {
         this.label = label;

src/MusicalScore/Graphical/GraphicalLabel.ts

@@ -5,6 +5,9 @@ import {BoundingBox} from "./BoundingBox";
 import {EngravingRules} from "./EngravingRules";
 import {MusicSheetCalculator} from "./MusicSheetCalculator";
 
+/**
+ * The graphical counterpart of a Label
+ */
 export class GraphicalLabel extends Clickable {
     private label: Label;
 

src/MusicalScore/Graphical/GraphicalMusicSheet.ts

@@ -25,6 +25,9 @@ import {SelectionStartSymbol} from "./SelectionStartSymbol";
 import {SelectionEndSymbol} from "./SelectionEndSymbol";
 import {OutlineAndFillStyleEnum} from "./DrawingEnums";
 
+/**
+ * The graphical counterpart of a [[MusicSheet]]
+ */
 export class GraphicalMusicSheet {
     constructor(musicSheet: MusicSheet, calculator: MusicSheetCalculator) {
         this.musicSheet = musicSheet;

src/MusicalScore/Graphical/GraphicalNote.ts

@@ -9,6 +9,9 @@ import {GraphicalObject} from "./GraphicalObject";
 import {MusicSheetCalculator} from "./MusicSheetCalculator";
 import {BoundingBox} from "./BoundingBox";
 
+/**
+ * The graphical counterpart of a Note
+ */
 export class GraphicalNote extends GraphicalObject {
     constructor(note: Note, parent: GraphicalStaffEntry, graphicalNoteLength: Fraction = undefined) {
         super();

src/MusicalScore/Graphical/GraphicalRectangle.ts

@@ -2,6 +2,7 @@ import {OutlineAndFillStyleEnum} from "./DrawingEnums";
 import {BoundingBox} from "./BoundingBox";
 import {PointF2D} from "../../Common/DataObjects/PointF2D";
 import {GraphicalObject} from "./GraphicalObject";
+
 export class GraphicalRectangle extends GraphicalObject {
     constructor(upperLeftPoint: PointF2D, lowerRightPoint: PointF2D, parent: BoundingBox, style: OutlineAndFillStyleEnum) {
         super();

src/MusicalScore/Graphical/GraphicalStaffEntry.ts

@@ -17,6 +17,9 @@ import {AbstractGraphicalInstruction} from "./AbstractGraphicalInstruction";
 import {GraphicalStaffEntryLink} from "./GraphicalStaffEntryLink";
 import {CollectionUtil} from "../../Util/CollectionUtil";
 
+/**
+ * The graphical counterpart of a SourceStaffEntry
+ */
 export abstract class GraphicalStaffEntry extends GraphicalObject {
     constructor(parentMeasure: StaffMeasure, sourceStaffEntry: SourceStaffEntry = undefined, staffEntryParent: GraphicalStaffEntry = undefined) {
         super();

src/MusicalScore/Graphical/GraphicalTie.ts

@@ -1,6 +1,9 @@
 import {Tie} from "../VoiceData/Tie";
 import {GraphicalNote} from "./GraphicalNote";
 
+/**
+ * The graphical counterpart of a Tie
+ */
 export class GraphicalTie {
     private tie: Tie;
     private startNote: GraphicalNote;

src/MusicalScore/Graphical/MusicSheetCalculator.ts

@@ -52,6 +52,9 @@ import {Logging} from "../../Common/Logging";
 import Dictionary from "typescript-collections/dist/lib/Dictionary";
 import {CollectionUtil} from "../../Util/CollectionUtil";
 
+/**
+ * Class used to do all the calculations in a MusicSheet, which in the end populates a GraphicalMusicSheet.
+ */
 export abstract class MusicSheetCalculator {
     public static transposeCalculator: ITransposeCalculator;
     protected static textMeasurer: ITextMeasurer;

src/MusicalScore/Graphical/MusicSheetDrawer.ts

@@ -25,6 +25,9 @@ import {MusicSymbolDrawingStyle, PhonicScoreModes} from "./DrawingMode";
 import {GraphicalOctaveShift} from "./GraphicalOctaveShift";
 import {GraphicalObject} from "./GraphicalObject";
 
+/**
+ * Class used to draw a GraphicalMusicSheet (with the .drawSheet method)
+ */
 export abstract class MusicSheetDrawer {
     public drawingParameters: DrawingParameters = new DrawingParameters();
     public splitScreenLineColor: number;

src/MusicalScore/Graphical/MusicSystem.ts

@@ -21,6 +21,9 @@ import {SystemLine} from "./SystemLine";
 import {SystemLinePosition} from "./SystemLinePosition";
 import {Staff} from "../VoiceData/Staff";
 
+/**
+ * A MusicSystem contains the StaffLines for all instruments, until a line break
+ */
 export abstract class MusicSystem extends GraphicalObject {
     public needsToBeRedrawn: boolean = true;
     protected parent: GraphicalMusicPage;

src/MusicalScore/Graphical/StaffLine.ts

@@ -9,6 +9,10 @@ import {MusicSystem} from "./MusicSystem";
 import {StaffLineActivitySymbol} from "./StaffLineActivitySymbol";
 import {PointF2D} from "../../Common/DataObjects/PointF2D";
 
+/**
+ * A StaffLine contains the measures in one line of the music sheet
+ * (one instrument, one line, until a line break)
+ */
 export abstract class StaffLine extends GraphicalObject {
     protected measures: StaffMeasure[] = [];
     protected staffLines: GraphicalLine[] = new Array(5);

src/MusicalScore/Graphical/StaffMeasure.ts

@@ -15,6 +15,9 @@ import {SystemLinesEnum} from "./SystemLinesEnum";
 import {BoundingBox} from "./BoundingBox";
 import {PointF2D} from "../../Common/DataObjects/PointF2D";
 
+/**
+ * Represents a measure in the music sheet (one measure in one staff line)
+ */
 export abstract class StaffMeasure extends GraphicalObject {
     protected firstInstructionStaffEntry: GraphicalStaffEntry;
     protected lastInstructionStaffEntry: GraphicalStaffEntry;

src/MusicalScore/Graphical/VexFlow/VexFlowConverter.ts

@@ -16,16 +16,33 @@ import {FontStyles} from "../../../Common/Enums/FontStyles";
 import {Fonts} from "../../../Common/Enums/Fonts";
 import {OutlineAndFillStyleEnum} from "../DrawingEnums";
 
+/**
+ * Helper class, which contains static methods which actually convert
+ * from OSMD objects to VexFlow objects.
+ */
 export class VexFlowConverter {
+    /**
+     * Mapping from numbers of alterations on the key signature to major keys
+     * @type {[alterationsNo: number]: string; }
+     */
     private static majorMap: {[_: number]: string; } = {
         "0": "C", 1: "G", 2: "D", 3: "A", 4: "E", 5: "B", 6: "F#", 7: "C#",
         8: "G#", "-1": "F", "-8": "Fb", "-7": "Cb", "-6": "Gb", "-5": "Db", "-4": "Ab", "-3": "Eb", "-2": "Bb",
     };
+    /**
+     * Mapping from numbers of alterations on the key signature to minor keys
+     * @type {[alterationsNo: number]: string; }
+     */
     private static minorMap: {[_: number]: string; } = {
         "1": "E", "7": "A#", "0": "A", "6": "D#", "3": "F#", "-5": "Bb", "-4": "F", "-7": "Ab", "-6": "Eb",
         "-1": "D", "4": "C#", "-3": "C", "-2": "G", "2": "B", "5": "G#", "-8": "Db", "8": "E#",
     };
 
+    /**
+     * Convert a fraction to a string which represents a duration in VexFlow
+     * @param fraction a fraction representing the duration of a note
+     * @returns {string}
+     */
     public static duration(fraction: Fraction): string {
         let dur: number = fraction.RealValue;
         if (dur >= 1) {
@@ -59,7 +76,7 @@ export class VexFlowConverter {
     }
 
     /**
-     * Converts AccidentalEnum to vexFlow accidental string
+     * Converts AccidentalEnum to a string which represents an accidental in VexFlow
      * @param accidental
      * @returns {string}
      */
@@ -86,7 +103,11 @@ export class VexFlowConverter {
         return acc;
     }
 
-
+    /**
+     * Convert a set of GraphicalNotes to a VexFlow StaveNote
+     * @param notes form a chord on the staff
+     * @returns {Vex.Flow.StaveNote}
+     */
     public static StaveNote(notes: GraphicalNote[]): Vex.Flow.StaveNote {
         let keys: string[] = [];
         let accidentals: string[] = [];
@@ -125,6 +146,12 @@ export class VexFlowConverter {
         return vfnote;
     }
 
+    /**
+     * Convert a ClefInstruction to a string representing a clef type in VexFlow
+     * @param clef
+     * @returns {string}
+     * @constructor
+     */
     public static Clef(clef: ClefInstruction): string {
         let type: string;
         switch (clef.ClefType) {
@@ -148,6 +175,12 @@ export class VexFlowConverter {
         return type;
     }
 
+    /**
+     * Convert a RhythmInstruction to a VexFlow TimeSignature object
+     * @param rhythm
+     * @returns {Vex.Flow.TimeSignature}
+     * @constructor
+     */
     public static TimeSignature(rhythm: RhythmInstruction): Vex.Flow.TimeSignature {
         let timeSpec: string;
         switch (rhythm.SymbolEnum) {
@@ -165,6 +198,11 @@ export class VexFlowConverter {
         return new Vex.Flow.TimeSignature(timeSpec);
     }
 
+    /**
+     * Convert a KeyInstruction to a string representing in VexFlow a key
+     * @param key
+     * @returns {string}
+     */
     public static keySignature(key: KeyInstruction): string {
         if (key === undefined) {
             return undefined;
@@ -185,7 +223,13 @@ export class VexFlowConverter {
         return ret;
     }
 
+    /**
+     * Converts a lineType to a VexFlow StaveConnector type
+     * @param lineType
+     * @returns {any}
+     */
     public static line(lineType: SystemLinesEnum): any {
+        // TODO Not all line types are correctly mapped!
         switch (lineType) {
             case SystemLinesEnum.SingleThin:
                 return Vex.Flow.StaveConnector.type.SINGLE;
@@ -205,6 +249,13 @@ export class VexFlowConverter {
         }
     }
 
+    /**
+     * Construct a string which can be used in a CSS font property
+     * @param fontSize
+     * @param fontStyle
+     * @param font
+     * @returns {string}
+     */
     public static font(fontSize: number, fontStyle: FontStyles = FontStyles.Regular, font: Fonts = Fonts.TimesNewRoman): string {
         let style: string = "normal";
         let weight: string = "normal";
@@ -239,8 +290,13 @@ export class VexFlowConverter {
         return  style + " " + weight + " " + Math.floor(fontSize) + "px " + family;
     }
 
+    /**
+     * Convert OutlineAndFillStyle to CSS properties
+     * @param styleId
+     * @returns {string}
+     */
     public static style(styleId: OutlineAndFillStyleEnum): string {
-        // TODO
+        // TODO To be implemented
         return "purple";
     }
 }

src/MusicalScore/Graphical/VexFlow/VexFlowGraphicalNote.ts

@@ -8,6 +8,9 @@ import {Pitch} from "../../../Common/DataObjects/Pitch";
 import {Fraction} from "../../../Common/DataObjects/Fraction";
 import {OctaveEnum} from "../../VoiceData/Expressions/ContinuousExpressions/OctaveShift";
 
+/**
+ * The VexFlow version of a [[GraphicalNote]].
+ */
 export class VexFlowGraphicalNote extends GraphicalNote {
     constructor(note: Note, parent: GraphicalStaffEntry, activeClef: ClefInstruction, octaveShift: OctaveEnum = OctaveEnum.NONE,  graphicalNoteLength: Fraction = undefined) {
         super(note, parent, graphicalNoteLength);
@@ -18,10 +21,18 @@ export class VexFlowGraphicalNote extends GraphicalNote {
         }
     }
 
+    // The pitch of this note as given by VexFlowConverter.pitch
     public vfpitch: [string, string, ClefInstruction];
+    // The corresponding VexFlow StaveNote (plus its index in the chord)
     private vfnote: [Vex.Flow.StaveNote, number];
+    // The current clef
     private clef: ClefInstruction;
 
+    /**
+     * Update the pitch of this note. Necessary in order to display correctly
+     * accidentals, this is called by VexFlowGraphicalSymbolFactory.addGraphicalAccidental.
+     * @param pitch
+     */
     public setPitch(pitch: Pitch): void {
         if (this.vfnote) {
             let acc: string = VexFlowConverter.accidental(pitch.Accidental);
@@ -35,14 +46,11 @@ export class VexFlowGraphicalNote extends GraphicalNote {
     }
 
     /**
-     * Set the corresponding VexFlow StaveNote together with its index
+     * Set the VexFlow StaveNote corresponding to this GraphicalNote, together with its index in the chord.
      * @param note
      * @param index
      */
     public setIndex(note: Vex.Flow.StaveNote, index: number): void {
         this.vfnote = [note, index];
-        //if (this.vfpitch && this.vfpitch[1]) {
-        //    note.addAccidental(index, new Vex.Flow.Accidental(this.vfpitch[1]));
-        //}
     }
 }

src/MusicalScore/Graphical/VexFlow/VexFlowMeasure.ts

@@ -291,6 +291,10 @@ export class VexFlowMeasure extends StaffMeasure {
         this.connectors.push(connector);
     }
 
+    /**
+     * Return the VexFlow Stave corresponding to this StaffMeasure
+     * @returns {Vex.Flow.Stave}
+     */
     public getVFStave(): Vex.Flow.Stave {
         return this.stave;
     }
@@ -313,8 +317,11 @@ export class VexFlowMeasure extends StaffMeasure {
     //
     //}
 
+    /**
+     * After re-running the formatting on the VexFlow Stave, update the
+     * space needed by Instructions (in VexFlow: StaveModifiers)
+     */
     private updateInstructionWidth(): void {
-        //this.stave.format();
         this.beginInstructionsWidth = (this.stave.getNoteStartX() - this.stave.getX()) / unitInPixels;
         this.endInstructionsWidth = (this.stave.getNoteEndX() - this.stave.getX()) / unitInPixels;
     }

src/MusicalScore/Graphical/VexFlow/VexFlowMusicSystem.ts

@@ -8,8 +8,6 @@ import {SystemLine} from "../SystemLine";
 import {VexFlowMeasure} from "./VexFlowMeasure";
 import {VexFlowConverter} from "./VexFlowConverter";
 
-//import Vex = require("vexflow");
-
 export class VexFlowMusicSystem extends MusicSystem {
     constructor(parent: GraphicalMusicPage, id: number) {
         super(parent, id);

src/MusicalScore/Graphical/VexFlow/VexFlowStaffEntry.ts

@@ -16,7 +16,7 @@ export class VexFlowStaffEntry extends GraphicalStaffEntry {
 
     /**
      *
-     * @returns {number} the x-position (in units) of this Staff Entry
+     * @returns {number} the x-position (in units) of this StaffEntry
      */
     public getX(): number {
         let x: number = 0;
@@ -28,6 +28,9 @@ export class VexFlowStaffEntry extends GraphicalStaffEntry {
                 n += 1;
             }
         }
+        if (n === 0) {
+            return 0;
+        }
         return x / n / unitInPixels;
     }
 }

src/MusicalScore/Graphical/VexFlow/VexFlowTextMeasurer.ts

@@ -11,8 +11,16 @@ export class VexFlowTextMeasurer implements ITextMeasurer {
         let canvas: HTMLCanvasElement = document.createElement("canvas");
         this.context = canvas.getContext("2d");
     }
+    // The context of a canvas used internally to compute font sizes
     private context: CanvasRenderingContext2D;
 
+    /**
+     *
+     * @param text
+     * @param font
+     * @param style
+     * @returns {number}
+     */
     public computeTextWidthToHeightRatio(text: string, font: Fonts, style: FontStyles): number {
         this.context.font = VexFlowConverter.font(20, style, font);
         return this.context.measureText(text).width / 20;

src/MusicalScore/InstrumentalGroup.ts

@@ -6,6 +6,7 @@ export class InstrumentalGroup {
         this.musicSheet = musicSheet;
         this.parent = parent;
     }
+
     private name: string;
     private musicSheet: MusicSheet;
     private parent: InstrumentalGroup;

src/MusicalScore/Label.ts

@@ -3,6 +3,10 @@ import {OSMDColor} from "../Common/DataObjects/OSMDColor";
 import {Fonts} from "../Common/Enums/Fonts";
 import {FontStyles} from "../Common/Enums/FontStyles";
 
+/**
+ * A text label on the graphical music sheet.
+ * It is used e.g. for titles, composer names, instrument names and dynamic instructions.
+ */
 export class Label {
     constructor(text: string = "", alignment: TextAlignment = TextAlignment.LeftBottom, font: Fonts = Fonts.TimesNewRoman) {
         this.text = text;

src/MusicalScore/MusicSheet.ts

@@ -18,30 +18,21 @@ import {Note} from "./VoiceData/Note";
 import {VoiceEntry} from "./VoiceData/VoiceEntry";
 import {Logging} from "../Common/Logging";
 
-// FIXME
-//type MusicSheetParameters = any;
-//type MultiTempoExpression = any;
-//type PlaybackSettings = any;
-//type MusicSheetParameterObject = any;
-//type EngravingRules = any;
-//type MusicSheetErrors = any;
-//type IPhonicScoreInterface = any;
-//type MusicSheetParameterChangedDelegate = any;
-//type IInstrument = any;
-//type ISettableInstrument = any;
-//type IRepetition = any;
-
-// FIXME Andrea: Commented out some things, have a look at (*)
+// FIXME Andrea: Commented out some unnecessary/not-ported-yet code, have a look at (*)
 
 export class PlaybackSettings {
     public rhythm: Fraction;
 }
 
+/**
+ * This is the representation of a complete piece of sheet music.
+ * It includes the contents of a MusicXML file after the reading.
+ */
 export class MusicSheet /*implements ISettableMusicSheet, IComparable<MusicSheet>*/ {
     constructor() {
         this.rules = EngravingRules.Rules;
         this.playbackSettings = new PlaybackSettings();
-        // FIXME:
+        // FIXME?
         this.playbackSettings.rhythm = new Fraction(4, 4, false);
         this.userStartTempoInBPM = 100;
         this.pageWidth = 120;
@@ -365,7 +356,7 @@ export class MusicSheet /*implements ISettableMusicSheet, IComparable<MusicSheet
     //        }
     //        return repetitions;
     //    } catch (ex) {
-    //        console.log(/*Logger.DefaultLogger.LogError(LogLevel.NORMAL, FIXME */ "MusicSheet.IRepetitions get: ", ex);
+    //        Logging.log("MusicSheet.IRepetitions get: ", ex);
     //        return undefined;
     //    }
     //
@@ -451,11 +442,12 @@ export class MusicSheet /*implements ISettableMusicSheet, IComparable<MusicSheet
     public set IdString(value: string) {
        this.idString = value;
     }
+    // (*)
     // public Dispose(): void {
     //    this.MusicSheetParameterChanged = undefined;
     //    for (let idx: number = 0, len: number = this.instruments.length; idx < len; ++idx) {
     //        let instrument: Instrument = this.instruments[idx];
-    //        instrument.dispose(); // FIXME
+    //        instrument.dispose();
     //    }
     // }
     public getEnrolledSelectionStartTimeStampWorkaround(): Fraction {

src/MusicalScore/ScoreIO/InstrumentReader.ts

@@ -45,6 +45,10 @@ import {MidiInstrument} from "../VoiceData/Instructions/ClefInstruction";
 
 export type repetitionInstructionReader = any;
 
+/**
+ * An InstrumentReader is used during the reading phase to keep parsing new measures from the MusicXML file
+ * with the readNextXmlMeasure method.
+ */
 export class InstrumentReader {
     constructor(repetitionInstructionReader: repetitionInstructionReader, xmlMeasureList: IXmlElement[], instrument: Instrument) {
         // (*) this.repetitionInstructionReader = repetitionInstructionReader;

src/OSMD/Cursor.ts

@@ -6,7 +6,9 @@ import {MusicSystem} from "../MusicalScore/Graphical/MusicSystem";
 import {OSMD} from "./OSMD";
 import {GraphicalMusicSheet} from "../MusicalScore/Graphical/GraphicalMusicSheet";
 
-
+/**
+ * A cursor which can iterate through the music sheet.
+ */
 export class Cursor {
     constructor(container: HTMLElement, osmd: OSMD) {
         this.container = container;
@@ -33,15 +35,19 @@ export class Cursor {
         this.hide();
     }
 
+    /**
+     * Make the cursor visible
+     */
     public show(): void {
         this.hidden = false;
         this.update();
-        // Forcing the sheet to re-render is not necessary anymore
-        //this.osmd.render();
+        // Forcing the sheet to re-render is not necessary anymore,
+        // since the cursor is an HTML element.
+        // this.osmd.render();
     }
 
     public update(): void {
-        // Should NEVER call this.osmd.render()
+        // Warning! This should NEVER call this.osmd.render()
         if (this.hidden) {
             return;
         }
@@ -65,7 +71,8 @@ export class Cursor {
                     musicSystem.StaffLines[musicSystem.StaffLines.length - 1].PositionAndShape.RelativePosition.y + 4.0;
                 height = endY - y;
             }
-            // The following code is not necessary (for now); it highlights the current notes.
+            // The following code is not necessary (for now, but it could come useful later):
+            // it highlights the notes under the cursor.
             //let vfNotes: { [voiceID: number]: Vex.Flow.StaveNote; } = gse.vfNotes;
             //for (let voiceId in vfNotes) {
             //    if (vfNotes.hasOwnProperty(voiceId)) {
@@ -91,7 +98,7 @@ export class Cursor {
             this.updateStyle(newWidth);
         }
 
-        // Show cursors
+        // Show cursor
         // // Old cursor: this.graphic.Cursors.push(cursor);
         this.cursorElement.style.display = "";
     }

src/OSMD/ResizeHandler.ts

@@ -1,11 +1,7 @@
 /**
- * Created by acondolu on 15/07/16.
- */
-
-/**
  * Helper function for managing window's onResize events
- * @param startCallback
- * @param endCallback
+ * @param startCallback is the function called when resizing starts
+ * @param endCallback is the function called when resizing (kind-of) ends
  */
 export function handleResize(startCallback: () => void, endCallback: () => void): void {
     "use strict";
@@ -14,7 +10,7 @@ export function handleResize(startCallback: () => void, endCallback: () => void)
     let delta: number = 200;
 
     function resizeEnd(): void {
-        //timeout = undefined;
+        timeout = undefined;
         window.clearTimeout(timeout);
         if ((new Date()).getTime() - rtime < delta) {
             timeout = window.setTimeout(resizeEnd, delta);