Documenting classes iii

src/MusicalScore/Graphical/GraphicalNote.ts

@@ -10,7 +10,7 @@ import {MusicSheetCalculator} from "./MusicSheetCalculator";
 import {BoundingBox} from "./BoundingBox";
 
 /**
- * The graphical counterpart of a Note
+ * The graphical counterpart of a [[Note]]
  */
 export class GraphicalNote extends GraphicalObject {
     constructor(note: Note, parent: GraphicalStaffEntry, graphicalNoteLength: Fraction = undefined) {
@@ -54,6 +54,11 @@ export class GraphicalNote extends GraphicalObject {
         return transposedPitch;
     }
 
+    /**
+     * Return the number of dots needed to represent the given fraction.
+     * @param fraction
+     * @returns {number}
+     */
     private calculateNumberOfNeededDots(fraction: Fraction): number {
         let dotCount: number = 0;
         if (this.sourceNote === undefined || this.sourceNote.NoteTuplet === undefined) {

src/MusicalScore/Graphical/GraphicalObject.ts

@@ -1,11 +1,15 @@
 import {BoundingBox} from "./BoundingBox";
 
 export class GraphicalObject {
+
     protected boundingBox: BoundingBox;
+
     public get PositionAndShape(): BoundingBox {
         return this.boundingBox;
     }
+
     public set PositionAndShape(value: BoundingBox) {
         this.boundingBox = value;
     }
+
 }

src/MusicalScore/Graphical/GraphicalOctaveShift.ts

@@ -4,7 +4,12 @@ import {BoundingBox} from "./BoundingBox";
 import {MusicSymbol} from "./MusicSymbol";
 import {ArgumentOutOfRangeException} from "../Exceptions";
 import {PointF2D} from "../../Common/DataObjects/PointF2D";
+
+/**
+ * The graphical counterpart of an [[OctaveShift]]
+ */
 export class GraphicalOctaveShift extends GraphicalObject {
+
     constructor(octaveShift: OctaveShift, parent: BoundingBox) {
         super();
         this.getOctaveShift = octaveShift;
@@ -40,4 +45,5 @@ export class GraphicalOctaveShift extends GraphicalObject {
                 throw new ArgumentOutOfRangeException("");
         }
     }
+
 }

src/MusicalScore/Graphical/GraphicalRectangle.ts

@@ -4,6 +4,7 @@ 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();
         this.boundingBox = new BoundingBox(parent);
@@ -12,5 +13,6 @@ export class GraphicalRectangle extends GraphicalObject {
         this.boundingBox.BorderBottom = lowerRightPoint.y - upperLeftPoint.y;
         this.style = style;
     }
+
     public style: OutlineAndFillStyleEnum;
 }

src/MusicalScore/Graphical/GraphicalStaffEntry.ts

@@ -18,7 +18,7 @@ import {GraphicalStaffEntryLink} from "./GraphicalStaffEntryLink";
 import {CollectionUtil} from "../../Util/CollectionUtil";
 
 /**
- * The graphical counterpart of a SourceStaffEntry
+ * The graphical counterpart of a [[SourceStaffEntry]].
  */
 export abstract class GraphicalStaffEntry extends GraphicalObject {
     constructor(parentMeasure: StaffMeasure, sourceStaffEntry: SourceStaffEntry = undefined, staffEntryParent: GraphicalStaffEntry = undefined) {
@@ -42,6 +42,8 @@ export abstract class GraphicalStaffEntry extends GraphicalObject {
 
     public graphicalChordContainer: GraphicalChordSymbolContainer;
     public graphicalLink: GraphicalStaffEntryLink;
+
+    // Extra member needed, as tie notes have no direct source entry with the right time stamp.
     public relInMeasureTimestamp: Fraction;
     public sourceStaffEntry: SourceStaffEntry;
     public parentMeasure: StaffMeasure;
@@ -67,6 +69,10 @@ export abstract class GraphicalStaffEntry extends GraphicalObject {
         return this.lyricsEntries;
     }
 
+    /**
+     * Calculate the absolute Timestamp.
+     * @returns {Fraction}
+     */
     public getAbsoluteTimestamp(): Fraction {
         let result: Fraction = this.parentMeasure.parentSourceMeasure.AbsoluteTimestamp.clone();
         if (this.relInMeasureTimestamp !== undefined) {
@@ -75,6 +81,11 @@ export abstract class GraphicalStaffEntry extends GraphicalObject {
         return result;
     }
 
+    /**
+     * Search through all the GraphicalNotes to find the suitable one for a TieEndNote.
+     * @param tieNote
+     * @returns {any}
+     */
     public findEndTieGraphicalNoteFromNote(tieNote: Note): GraphicalNote {
         for (let idx: number = 0, len: number = this.notes.length; idx < len; ++idx) {
             let graphicalNotes: GraphicalNote[] = this.notes[idx];
@@ -90,6 +101,12 @@ export abstract class GraphicalStaffEntry extends GraphicalObject {
         return undefined;
     }
 
+    /**
+     * Search through all [[GraphicalNote]]s to find the suitable one for an StartSlurNote (that 's also an EndTieNote).
+     * @param tieNote
+     * @param slur
+     * @returns {any}
+     */
     public findEndTieGraphicalNoteFromNoteWithStartingSlur(tieNote: Note, slur: Slur): GraphicalNote {
         for (let idx: number = 0, len: number = this.notes.length; idx < len; ++idx) {
             let graphicalNotes: GraphicalNote[] = this.notes[idx];
@@ -104,6 +121,11 @@ export abstract class GraphicalStaffEntry extends GraphicalObject {
         return undefined;
     }
 
+    /**
+     * Search through all GraphicalNotes to find the suitable one for an EndSlurNote (that 's also an EndTieNote).
+     * @param tieNote
+     * @returns {any}
+     */
     public findEndTieGraphicalNoteFromNoteWithEndingSlur(tieNote: Note): GraphicalNote {
         for (let idx: number = 0, len: number = this.notes.length; idx < len; ++idx) {
             let graphicalNotes: GraphicalNote[] = this.notes[idx];
@@ -157,6 +179,10 @@ export abstract class GraphicalStaffEntry extends GraphicalObject {
         return new Fraction(0, 1);
     }
 
+    /**
+     * Find the Linked GraphicalNotes which belong exclusively to the StaffEntry (in case of Linked StaffEntries).
+     * @param notLinkedNotes
+     */
     public findLinkedNotes(notLinkedNotes: GraphicalNote[]): void {
         if (this.sourceStaffEntry !== undefined && this.sourceStaffEntry.Link !== undefined) {
             for (let idx: number = 0, len: number = this.notes.length; idx < len; ++idx) {
@@ -171,6 +197,11 @@ export abstract class GraphicalStaffEntry extends GraphicalObject {
         }
     }
 
+    /**
+     * Find the [[StaffEntry]]'s [[GraphicalNote]]s that correspond to the given [[VoiceEntry]]'s [[Note]]s.
+     * @param voiceEntry
+     * @returns {any}
+     */
     public findVoiceEntryGraphicalNotes(voiceEntry: VoiceEntry): GraphicalNote[] {
         for (let idx: number = 0, len: number = this.notes.length; idx < len; ++idx) {
             let graphicalNotes: GraphicalNote[] = this.notes[idx];
@@ -184,6 +215,11 @@ export abstract class GraphicalStaffEntry extends GraphicalObject {
         return undefined;
     }
 
+    /**
+     * Check if the given [[VoiceEntry]] is part of the [[StaffEntry]]'s Linked [[VoiceEntry]].
+     * @param voiceEntry
+     * @returns {boolean}
+     */
     public isVoiceEntryPartOfLinkedVoiceEntry(voiceEntry: VoiceEntry): boolean {
         if (this.sourceStaffEntry.Link !== undefined) {
             for (let idx: number = 0, len: number = this.sourceStaffEntry.Link.LinkStaffEntries.length; idx < len; ++idx) {
@@ -206,6 +242,10 @@ export abstract class GraphicalStaffEntry extends GraphicalObject {
         return this.notes[0][0].sourceNote.ParentVoiceEntry.ParentVoice;
     }
 
+    /**
+     * Return the [[StaffEntry]]'s Minimum NoteLength.
+     * @returns {Fraction}
+     */
     public findStaffEntryMinNoteLength(): Fraction {
         let minLength: Fraction = new Fraction(Number.MAX_VALUE, 1);
         for (let idx: number = 0, len: number = this.notes.length; idx < len; ++idx) {
@@ -236,6 +276,11 @@ export abstract class GraphicalStaffEntry extends GraphicalObject {
         return maxLength;
     }
 
+    /**
+     * Find or creates the list of [[GraphicalNote]]s in case of a [[VoiceEntry]] (not from TiedNote).
+     * @param voiceEntry
+     * @returns {GraphicalNote[]}
+     */
     public findOrCreateGraphicalNotesListFromVoiceEntry(voiceEntry: VoiceEntry): GraphicalNote[] {
         let graphicalNotes: GraphicalNote[];
         if (this.notes.length === 0) {
@@ -253,6 +298,11 @@ export abstract class GraphicalStaffEntry extends GraphicalObject {
         return graphicalNotes;
     }
 
+    /**
+     * Find or creates the list of [[GraphicalNote]]s in case of a TiedNote.
+     * @param graphicalNote
+     * @returns {GraphicalNote[]}
+     */
     public findOrCreateGraphicalNotesListFromGraphicalNote(graphicalNote: GraphicalNote): GraphicalNote[] {
         let graphicalNotes: GraphicalNote[];
         let tieStartSourceStaffEntry: SourceStaffEntry = graphicalNote.sourceNote.ParentStaffEntry;
@@ -275,6 +325,13 @@ export abstract class GraphicalStaffEntry extends GraphicalObject {
         return graphicalNotes;
     }
 
+    /**
+     * Insert the [[GraphicalNote]] to the correct index of the [[GraphicalNote]]s list,
+     * so that the order of the [[GraphicalNote]]'s in the list corresponds to the [[VoiceEntry]]'s [[Note]]s order.
+     * (needed when adding Tie-EndNotes).
+     * @param graphicalNotes
+     * @param graphicalNote
+     */
     public addGraphicalNoteToListAtCorrectYPosition(graphicalNotes: GraphicalNote[], graphicalNote: GraphicalNote): void {
         if (graphicalNotes.length === 0 ||
             graphicalNote.PositionAndShape.RelativePosition.y < CollectionUtil.last(graphicalNotes).PositionAndShape.RelativePosition.Y) {

src/MusicalScore/Graphical/GraphicalStaffEntryLink.ts

@@ -2,6 +2,10 @@ import {StaffEntryLink} from "../VoiceData/StaffEntryLink";
 import {GraphicalStaffEntry} from "./GraphicalStaffEntry";
 import {GraphicalNote} from "./GraphicalNote";
 
+/**
+ * The graphical counterpart of a [[StaffEntryLink]].
+ * Used for linked voices.
+ */
 export class GraphicalStaffEntryLink {
     private staffEntryLink: StaffEntryLink;
     private graphicalLinkedStaffEntries: GraphicalStaffEntry[] = [];
@@ -26,6 +30,12 @@ export class GraphicalStaffEntryLink {
         }
         return true;
     }
+
+    /**
+     * Return all the [[GraphicalNote]]s that correspond to the [[LinkedVoiceEntry]] (the one saved in [[StaffEntryLink]]).
+     * @param graphicalStaffEntry
+     * @returns {any}
+     */
     public getLinkedStaffEntriesGraphicalNotes(graphicalStaffEntry: GraphicalStaffEntry): GraphicalNote[] {
         if (this.graphicalLinkedStaffEntries.indexOf(graphicalStaffEntry) !== -1) {
             let notes: GraphicalNote[] = [];

src/MusicalScore/Graphical/GraphicalTie.ts

@@ -2,17 +2,19 @@ import {Tie} from "../VoiceData/Tie";
 import {GraphicalNote} from "./GraphicalNote";
 
 /**
- * The graphical counterpart of a Tie
+ * The graphical counterpart of a [[Tie]].
  */
 export class GraphicalTie {
     private tie: Tie;
     private startNote: GraphicalNote;
     private endNote: GraphicalNote;
+
     constructor(tie: Tie, start: GraphicalNote = undefined, end: GraphicalNote = undefined) {
         this.tie = tie;
         this.startNote = start;
         this.endNote = end;
     }
+
     public get GetTie(): Tie {
         return this.tie;
     }
@@ -28,4 +30,5 @@ export class GraphicalTie {
     public set EndNote(value: GraphicalNote) {
         this.endNote = value;
     }
+
 }

src/MusicalScore/Graphical/MusicSheetCalculator.ts

@@ -58,11 +58,13 @@ import {CollectionUtil} from "../../Util/CollectionUtil";
 export abstract class MusicSheetCalculator {
     public static transposeCalculator: ITransposeCalculator;
     protected static textMeasurer: ITextMeasurer;
+
     protected staffEntriesWithGraphicalTies: GraphicalStaffEntry[] = [];
     protected staffEntriesWithOrnaments: GraphicalStaffEntry[] = [];
     protected staffEntriesWithChordSymbols: GraphicalStaffEntry[] = [];
     protected staffLinesWithLyricWords: StaffLine[] = [];
     protected staffLinesWithGraphicalExpressions: StaffLine[] = [];
+
     protected graphicalMusicSheet: GraphicalMusicSheet;
     protected rules: EngravingRules;
     protected symbolFactory: IGraphicalSymbolFactory;
@@ -112,27 +114,48 @@ export abstract class MusicSheetCalculator {
         //this.calculate();
     }
 
+    /**
+     * Build the 2D [[GraphicalMeasure]] ist needed for the [[MusicSheetCalculator]].
+     * Internally it creates [[GraphicalMeasure]]s, [[GraphicalStaffEntry]]'s and [[GraphicalNote]]s.
+     */
     public prepareGraphicalMusicSheet(): void {
-        //this.graphicalMusicSheet.SystemImages.length = 0;
+        // Clear the stored system images dict - all systems have to be redrawn.
+        // Not necessary now. TODO Check
+        // this.graphicalMusicSheet.SystemImages.length = 0;
         let musicSheet: MusicSheet = this.graphicalMusicSheet.ParentMusicSheet;
+
         this.staffEntriesWithGraphicalTies = [];
         this.staffEntriesWithOrnaments = [];
         this.staffEntriesWithChordSymbols = [];
         this.staffLinesWithLyricWords = [];
         this.staffLinesWithGraphicalExpressions = [];
+
         this.graphicalMusicSheet.Initialize();
         let measureList: StaffMeasure[][] = this.graphicalMusicSheet.MeasureList;
+
+        // one AccidentalCalculator for each Staff (regardless of Instrument)
         let accidentalCalculators: AccidentalCalculator[] = this.createAccidentalCalculators();
+
+        // List of Active ClefInstructions
         let activeClefs: ClefInstruction[] = this.graphicalMusicSheet.initializeActiveClefs();
+
+        // LyricWord - GraphicalLyricWord Lists
         let lyricWords: LyricWord[] = [];
+
         let completeNumberOfStaves: number = musicSheet.getCompleteNumberOfStaves();
+
+        // Octave Shifts List
         let openOctaveShifts: OctaveShiftParams[] = [];
+
+        // TieList - timestampsArray
         let tieTimestampListDictList: Dictionary<Tie, Fraction[]>[] = [];
         for (let i: number = 0; i < completeNumberOfStaves; i++) {
             let tieTimestampListDict: Dictionary<Tie, Fraction[]> = new Dictionary<Tie, Fraction[]>();
             tieTimestampListDictList.push(tieTimestampListDict);
             openOctaveShifts.push(undefined);
         }
+
+        // go through all SourceMeasures (taking into account normal SourceMusicParts and Repetitions)
         for (let idx: number = 0, len: number = musicSheet.SourceMeasures.length; idx < len; ++idx) {
             let sourceMeasure: SourceMeasure = musicSheet.SourceMeasures[idx];
             let graphicalMeasures: StaffMeasure[] = this.createGraphicalMeasuresForSourceMeasure(
@@ -150,19 +173,38 @@ export abstract class MusicSheetCalculator {
         this.setIndecesToVerticalGraphicalContainers();
     }
 
+    /**
+     * The main method for the Calculator.
+     */
     public calculate(): void {
         this.clearSystemsAndMeasures();
+
+        // delete graphicalObjects that will be recalculated and create the GraphicalObjects that strech over a single StaffEntry new.
         this.clearRecreatedObjects();
+
         this.createGraphicalTies();
+
+        // calculate SheetLabelBoundingBoxes
         this.calculateSheetLabelBoundingBoxes();
         this.calculateXLayout(this.graphicalMusicSheet, this.maxInstrNameLabelLength());
+
+        // create List<MusicPage>
         this.graphicalMusicSheet.MusicPages.length = 0;
+
+        // create new MusicSystems and StaffLines (as many as necessary) and populate them with Measures from measureList
         this.calculateMusicSystems();
+
+        // Add some white space at the end of the piece:
         this.graphicalMusicSheet.MusicPages[0].PositionAndShape.BorderMarginBottom += 9;
+
+        // transform Relative to Absolute Positions
         GraphicalMusicSheet.transformRelativeToAbsolutePosition(this.graphicalMusicSheet);
     }
 
     public calculateXLayout(graphicalMusicSheet: GraphicalMusicSheet, maxInstrNameLabelLength: number): void {
+        // for each inner List in big Measure List calculate new Positions for the StaffEntries
+        // and adjust Measures sizes
+        // calculate max measure length for maximum zoom in.
         let minLength: number = 0;
         let maxInstructionsLength: number = this.rules.MaxInstructionsConstValue;
         if (this.graphicalMusicSheet.MeasureList.length > 0) {
@@ -180,6 +222,11 @@ export abstract class MusicSheetCalculator {
         this.graphicalMusicSheet.MinAllowedSystemWidth = minLength;
     }
 
+    /**
+     * Calculates the x layout of the staff entries within the staff measures belonging to one source measure.
+     * All staff entries are x-aligned throughout all the measures.
+     * @param measures - The minimum required x width of the source measure
+     */
     protected calculateMeasureXLayout(measures: StaffMeasure[]): number {
         throw new Error("abstract, not implemented");
     }
@@ -188,6 +235,9 @@ export abstract class MusicSheetCalculator {
         throw new Error("abstract, not implemented");
     }
 
+    /**
+     * Called for every source measure when generating the list of staff measures for it.
+     */
     protected initStaffMeasuresCreation(): void {
         throw new Error("abstract, not implemented");
     }
@@ -196,6 +246,17 @@ export abstract class MusicSheetCalculator {
         throw new Error("abstract, not implemented");
     }
 
+    /**
+     * Check if the tied graphical note belongs to any beams or tuplets and react accordingly.
+     * @param tiedGraphicalNote
+     * @param beams
+     * @param activeClef
+     * @param octaveShiftValue
+     * @param graphicalStaffEntry
+     * @param duration
+     * @param openTie
+     * @param isLastTieNote
+     */
     protected handleTiedGraphicalNote(tiedGraphicalNote: GraphicalNote, beams: Beam[], activeClef: ClefInstruction,
                                       octaveShiftValue: OctaveEnum, graphicalStaffEntry: GraphicalStaffEntry, duration: Fraction,
                                       openTie: Tie, isLastTieNote: boolean): void {
@@ -240,32 +301,69 @@ export abstract class MusicSheetCalculator {
         throw new Error("abstract, not implemented");
     }
 
+    /**
+     * Iterate through all Measures and calculates the MeasureNumberLabels.
+     * @param musicSystem
+     */
     protected calculateMeasureNumberPlacement(musicSystem: MusicSystem): void {
         throw new Error("abstract, not implemented");
     }
 
+    /**
+     * Calculate the shape (Bézier curve) for this tie.
+     * @param tie
+     * @param tieIsAtSystemBreak
+     */
     protected layoutGraphicalTie(tie: GraphicalTie, tieIsAtSystemBreak: boolean): void {
         throw new Error("abstract, not implemented");
     }
 
+    /**
+     * Calculate the Lyrics YPositions for a single [[StaffLine]].
+     * @param staffLine
+     * @param lyricVersesNumber
+     */
     protected calculateSingleStaffLineLyricsPosition(staffLine: StaffLine, lyricVersesNumber: number[]): void {
         throw new Error("abstract, not implemented");
     }
 
+    /**
+     * Calculate a single OctaveShift for a [[MultiExpression]].
+     * @param sourceMeasure
+     * @param multiExpression
+     * @param measureIndex
+     * @param staffIndex
+     */
     protected calculateSingleOctaveShift(sourceMeasure: SourceMeasure, multiExpression: MultiExpression,
                                          measureIndex: number, staffIndex: number): void {
         throw new Error("abstract, not implemented");
     }
 
+    /**
+     * Calculate all the [[RepetitionInstruction]]s for a single [[SourceMeasure]].
+     * @param repetitionInstruction
+     * @param measureIndex
+     */
     protected calculateWordRepetitionInstruction(repetitionInstruction: RepetitionInstruction,
                                                  measureIndex: number): void {
         throw new Error("abstract, not implemented");
     }
 
+    /**
+     * Calculate all the Mood and Unknown Expressions for a single [[MultiExpression]].
+     * @param multiExpression
+     * @param measureIndex
+     * @param staffIndex
+     */
     protected calculateMoodAndUnknownExpression(multiExpression: MultiExpression, measureIndex: number, staffIndex: number): void {
         throw new Error("abstract, not implemented");
     }
 
+    /**
+     * Delete all Objects that must be recalculated.
+     * If graphicalMusicSheet.reCalculate has been called, then this method will be called to reset or remove all flexible
+     * graphical music symbols (e.g. Ornaments, Lyrics, Slurs) graphicalMusicSheet will have MusicPages, they will have MusicSystems etc...
+     */
     protected clearRecreatedObjects(): void {
         // Clear StaffEntries with GraphicalTies
         for (let idx: number = 0, len: number = this.staffEntriesWithGraphicalTies.length; idx < len; ++idx) {
@@ -276,11 +374,19 @@ export abstract class MusicSheetCalculator {
         return;
     }
 
+    /**
+     * This method handles a [[StaffEntryLink]].
+     * @param graphicalStaffEntry
+     * @param staffEntryLinks
+     */
     protected handleStaffEntryLink(graphicalStaffEntry: GraphicalStaffEntry,
                                    staffEntryLinks: StaffEntryLink[]): void {
         Logging.debug("handleStaffEntryLink not implemented");
     }
 
+    /**
+     * Store the newly computed [[Measure]]s in newly created [[MusicSystem]]s.
+     */
     protected calculateMusicSystems(): void {
         if (this.graphicalMusicSheet.MeasureList === undefined) {
             return;