Documenting classes ii

src/MusicalScore/Graphical/DrawingEnums.ts

@@ -1,3 +1,6 @@
+/**
+ * The supported styles to draw a rectangle on the music sheet
+ */
 export enum OutlineAndFillStyleEnum {
     BaseWritingColor,
     FollowingCursor,
@@ -33,10 +36,15 @@ export enum OutlineAndFillStyleEnum {
     Comment9,
     Comment10
 }
+
 export enum StyleSets {
     MarkedArea,
     Comment
 }
+
+/**
+ * The layers which one can draw on (not suppoerted)
+ */
 export enum GraphicalLayers {
     Background,
     Highlight,
@@ -48,6 +56,7 @@ export enum GraphicalLayers {
     Comment,
     Debug_above
 }
+
 export enum NoteState {
     Normal,
     Selected,

src/MusicalScore/Graphical/EngravingRules.ts

@@ -139,13 +139,19 @@ export class EngravingRules {
     private noteDistancesScalingFactors: number[] = [1.0, 2.0, 4.0, 8.0, 16.0, 32.0, 64.0, 128.0];
     private durationDistanceDict: {[_: number]: number; } = {};
     private durationScalingDistanceDict: {[_: number]: number; } = {};
+
     constructor() {
+        // global variables
         this.samplingUnit = EngravingRules.unit * 3;
+
+        // Page Label Variables
         this.sheetTitleHeight = 4.0;
         this.sheetSubtitleHeight = 2.0;
         this.sheetMinimumDistanceBetweenTitleAndSubtitle = 1.0;
         this.sheetComposerHeight = 2.0;
         this.sheetAuthorHeight = 2.0;
+
+        // Staff sizing Variables
         this.pagePlacementEnum = PagePlacementEnum.Down;
         this.pageHeight = 100001.0;
         this.pageTopMargin = 5.0;
@@ -156,6 +162,8 @@ export class EngravingRules {
         this.titleBottomDistance = 1.0;
         this.staffDistance = 7.0;
         this.betweenStaffDistance = 5.0;
+
+        // System Sizing and Label Variables
         this.staffHeight = 4.0;
         this.betweenStaffLinesDistance = EngravingRules.unit;
         this.systemDistance = 10.0;
@@ -167,9 +175,13 @@ export class EngravingRules {
         this.instrumentLabelTextHeight = 2;
         this.minimumAllowedDistanceBetweenSystems = 3.0;
         this.lastSystemMaxScalingFactor = 1.4;
+
+        // Beam Sizing Variables
         this.beamWidth = EngravingRules.unit / 2.0;
         this.beamSpaceWidth = EngravingRules.unit / 3.0;
         this.beamForwardLength = 1.25 * EngravingRules.unit;
+
+        // Beam Sizing Variables
         this.clefLeftMargin = 0.5;
         this.clefRightMargin = 0.75;
         this.betweenKeySymbolsDistance = 0.2;
@@ -177,11 +189,15 @@ export class EngravingRules {
         this.rhythmRightMargin = 1.25;
         this.inStaffClefScalingFactor = 0.8;
         this.distanceBetweenNaturalAndSymbolWhenCancelling = 0.4;
+
+        // Beam Sizing Variables
         this.noteHelperLinesOffset = 0.25;
         this.measureLeftMargin = 0.7;
         this.measureRightMargin = 0.0;
         this.distanceBetweenLastInstructionAndRepetitionBarline = 1.0;
         this.arpeggioDistance = 0.6;
+
+        // Stems Variables
         this.staccatoShorteningFactor = 2;
         this.idealStemLength = 3.0;
         this.stemNoteHeadBorderYOffset = 0.2;
@@ -191,8 +207,12 @@ export class EngravingRules {
         this.stemMaxLength = 4.5;
         this.beamSlopeMaxAngle = 10.0;
         this.stemMinAllowedDistanceBetweenNoteHeadAndBeamLine = 1.0;
+
+        // GraceNote Variables
         this.graceNoteScalingFactor = 0.6;
         this.graceNoteXOffset = 0.2;
+
+        // GraceNote Variables
         this.wedgeOpeningLength = 1.2;
         this.wedgeMeasureEndOpeningLength = 0.75;
         this.wedgeMeasureBeginOpeningLength = 0.75;
@@ -203,19 +223,27 @@ export class EngravingRules {
         this.distanceOffsetBetweenTwoHorizontallyCrossedWedges = 0.3;
         this.wedgeMinLength = 2.0;
         this.distanceBetweenAdjacentDynamics = 0.75;
+
+        // GraceNote Variables
         this.tempoChangeMeasureValitidy = 4;
         this.tempoContinousFactor = 0.7;
+
+        // various
         this.staccatoScalingFactor = 0.8;
         this.betweenDotsDistance = 0.8;
         this.ornamentAccidentalScalingFactor = 0.65;
         this.chordSymbolTextHeight = 2.0;
         this.fingeringLabelFontHeight = 1.7;
+
+        // MeasureNumber- and TupletNumberLabel variables
         this.measureNumberLabelHeight = 1.5 * EngravingRules.unit;
         this.measureNumberLabelOffset = 2;
         this.tupletNumberLabelHeight = 1.5 * EngravingRules.unit;
         this.tupletNumberYOffset = 0.5;
         this.labelMarginBorderFactor = 0.1;
         this.tupletVerticalLineLength = 0.5;
+
+        // MeasureNumber- and TupletNumberLabel variables
         this.bezierCurveStepSize = 1000;
         this.calculateCurveParametersArrays();
         this.tieGhostObjectWidth = 0.75;
@@ -231,20 +259,28 @@ export class EngravingRules {
         this.slurTangentMinAngle = 30.0;
         this.slurTangentMaxAngle = 80.0;
         this.slursStartingAtSameStaffEntryYOffset = 0.8;
+
+        // MeasureNumber- and TupletNumberLabel variables
         this.repetitionEndingLabelHeight = 2.0;
         this.repetitionEndingLabelXOffset = 0.5;
         this.repetitionEndingLabelYOffset = 0.3;
         this.repetitionEndingLineYLowerOffset = 0.5;
         this.repetitionEndingLineYUpperOffset = 0.3;
+
+        // Lyrics
         this.lyricsHeight = 2.0;
         this.verticalBetweenLyricsDistance = 0.5;
         this.betweenSyllabelMaximumDistance = 10.0;
         this.minimumDistanceBetweenDashes = 5.0;
+
+        // expressions variables
         this.instantaniousTempoTextHeight = 2.3;
         this.continuousDynamicTextHeight = 2.3;
         this.moodTextHeight = 2.3;
         this.unknownTextHeight = 2.0;
         this.continuousTempoTextHeight = 2.3;
+
+        // Line Widths
         this.staffLineWidth = 0.12;
         this.ledgerLineWidth = 0.12;
         this.wedgeLineWidth = 0.12;
@@ -259,12 +295,17 @@ export class EngravingRules {
         this.octaveShiftLineWidth = 0.12;
         this.octaveShiftVerticalLineLength = EngravingRules.unit;
         this.graceLineWidth = this.staffLineWidth * this.GraceNoteScalingFactor;
+
+        // Line Widths
         this.minimumStaffLineDistance = 1.0;
         this.minimumCrossedBeamDifferenceMargin = 0.0001;
+
+        // xSpacing Variables
         this.displacedNoteMargin = 0.1;
         this.minNoteDistance = 2.0;
         this.subMeasureXSpacingThreshold = 35;
         this.measureDynamicsMaxScalingFactor = 2.5;
+
         this.populateDictionaries();
         try {
             this.maxInstructionsConstValue = this.ClefLeftMargin + this.ClefRightMargin + this.KeyRightMargin + this.RhythmRightMargin + 11;
@@ -1067,6 +1108,10 @@ export class EngravingRules {
     public get DurationScalingDistanceDict(): {[_: number]: number; } {
         return this.durationScalingDistanceDict;
     }
+
+    /**
+     * This method maps NoteDurations to Distances and DistancesScalingFactors.
+     */
     private populateDictionaries(): void {
         for (let i: number = 0; i < this.noteDistances.length; i++) {
             switch (i) {
@@ -1107,6 +1152,10 @@ export class EngravingRules {
             }
         }
     }
+
+    /**
+     * Calculate Curve-independend factors, to be used later in the Slur- and TieCurvePoints calculation
+     */
     private calculateCurveParametersArrays(): void {
         this.tPower3 = new Array(this.bezierCurveStepSize);
         this.oneMinusTPower3 = new Array(this.bezierCurveStepSize);

src/MusicalScore/Graphical/GraphicalLabel.ts

@@ -26,6 +26,9 @@ export class GraphicalLabel extends Clickable {
         return this.label.text;
     }
 
+    /**
+     * Calculate GraphicalLabel's Borders according to its Alignment
+     */
     public setLabelPositionAndShapeBorders(): void {
         if (this.Label.text.trim() === "") {
             return;
@@ -37,6 +40,7 @@ export class GraphicalLabel extends Clickable {
         let height: number = this.Label.fontHeight;
         let width: number = height * widthToHeightRatio;
         let psi: BoundingBox = this.PositionAndShape;
+
         switch (this.Label.textAlignment) {
             case TextAlignment.CenterBottom:
                 psi.BorderTop = -height;

src/MusicalScore/Graphical/GraphicalLyricEntry.ts

@@ -6,6 +6,9 @@ import {Label} from "../Label";
 import {TextAlignment} from "../../Common/Enums/TextAlignment";
 import {PointF2D} from "../../Common/DataObjects/PointF2D";
 
+/**
+ * The graphical counterpart of a [[LyricEntry]]
+ */
 export class GraphicalLyricEntry {
     private lyricsEntry: LyricsEntry;
     private graphicalLyricWord: GraphicalLyricWord;

src/MusicalScore/Graphical/GraphicalLyricWord.ts

@@ -1,6 +1,9 @@
 import {LyricWord} from "../VoiceData/Lyrics/LyricsWord";
 import {GraphicalLyricEntry} from "./GraphicalLyricEntry";
 
+/**
+ * The graphical counterpart of a [[LyricWord]]
+ */
 export class GraphicalLyricWord {
     private lyricWord: LyricWord;
     private graphicalLyricsEntries: GraphicalLyricEntry[] = [];

src/MusicalScore/Graphical/GraphicalMarkedArea.ts

@@ -1,5 +1,6 @@
 import {GraphicalLabel} from "./GraphicalLabel";
 import {GraphicalRectangle} from "./GraphicalRectangle";
+
 export class GraphicalMarkedArea {
     constructor(systemRectangle: GraphicalRectangle, labelRectangle: GraphicalRectangle = undefined, label: GraphicalLabel = undefined,
                 settingsLabel: GraphicalLabel = undefined) {
@@ -8,6 +9,7 @@ export class GraphicalMarkedArea {
         this.label = label;
         this.settings = settingsLabel;
     }
+
     public systemRectangle: GraphicalRectangle;
     public labelRectangle: GraphicalRectangle;
     public label: GraphicalLabel;

src/MusicalScore/Graphical/GraphicalMusicPage.ts

@@ -41,12 +41,19 @@ export class GraphicalMusicPage extends GraphicalObject {
         this.parent = value;
     }
 
+    /**
+     * This method calculates the absolute Position of each GraphicalMusicPage according to a given placement
+     * @param pageIndex
+     * @param rules
+     * @returns {PointF2D}
+     */
     public setMusicPageAbsolutePosition(pageIndex: number, rules: EngravingRules): PointF2D {
         if (rules.PagePlacement === PagePlacementEnum.Down) {
             return new PointF2D(0.0, pageIndex * rules.PageHeight);
         } else if (rules.PagePlacement === PagePlacementEnum.Right) {
             return new PointF2D(pageIndex * this.parent.ParentMusicSheet.pageWidth, 0.0);
         } else {
+            // placement RightDown
             if (pageIndex % 2 === 0) {
                 if (pageIndex === 0) {
                     return new PointF2D(0.0, pageIndex * rules.PageHeight);
@@ -63,6 +70,7 @@ export class GraphicalMusicPage extends GraphicalObject {
         }
     }
 }
+
 export enum PagePlacementEnum {
     Down,
     Right,

src/MusicalScore/Graphical/GraphicalMusicSheet.ts

@@ -161,6 +161,10 @@ export class GraphicalMusicSheet {
         this.leadSheet = value;
     }
 
+    /**
+     * Calculate the Absolute Positions from the Relative Positions.
+     * @param graphicalMusicSheet
+     */
     public static transformRelativeToAbsolutePosition(graphicalMusicSheet: GraphicalMusicSheet): void {
         for (let i: number = 0; i < graphicalMusicSheet.MusicPages.length; i++) {
             let pageAbsolute: PointF2D = graphicalMusicSheet.MusicPages[i].setMusicPageAbsolutePosition(i, graphicalMusicSheet.ParentMusicSheet.rules);
@@ -201,6 +205,14 @@ export class GraphicalMusicSheet {
         return undefined;
     }
 
+    /**
+     * Search the MeasureList for a certain GraphicalStaffEntry with the given SourceStaffEntry,
+     * at a certain verticalIndex (eg a corresponnding Staff), starting at a specific horizontalIndex (eg specific GraphicalMeasure).
+     * @param staffIndex
+     * @param measureIndex
+     * @param sourceStaffEntry
+     * @returns {any}
+     */
     public findGraphicalStaffEntryFromMeasureList(staffIndex: number, measureIndex: number, sourceStaffEntry: SourceStaffEntry): GraphicalStaffEntry {
         for (let i: number = measureIndex; i < this.measureList.length; i++) {
             let graphicalMeasure: StaffMeasure = this.measureList[i][staffIndex];
@@ -214,6 +226,13 @@ export class GraphicalMusicSheet {
         return undefined;
     }
 
+    /**
+     * Return the next (to the right) not null GraphicalStaffEntry from a given Index.
+     * @param staffIndex
+     * @param measureIndex
+     * @param graphicalStaffEntry
+     * @returns {any}
+     */
     public findNextGraphicalStaffEntry(staffIndex: number, measureIndex: number, graphicalStaffEntry: GraphicalStaffEntry): GraphicalStaffEntry {
         let graphicalMeasure: StaffMeasure = graphicalStaffEntry.parentMeasure;
         let graphicalStaffEntryIndex: number = graphicalMeasure.staffEntries.indexOf(graphicalStaffEntry);
@@ -265,6 +284,10 @@ export class GraphicalMusicSheet {
         return orderedMeasures;
     }
 
+    /**
+     * Return the active Clefs at the start of the first SourceMeasure.
+     * @returns {ClefInstruction[]}
+     */
     public initializeActiveClefs(): ClefInstruction[] {
         let activeClefs: ClefInstruction[] = [];
         let firstSourceMeasure: SourceMeasure = this.musicSheet.getFirstSourceMeasure();
@@ -301,6 +324,11 @@ export class GraphicalMusicSheet {
         return undefined;
     }
 
+    /**
+     * Create the VerticalContainer and adds it to the List at the correct Timestamp position.
+     * @param timestamp
+     * @returns {any}
+     */
     public getOrCreateVerticalContainer(timestamp: Fraction): VerticalGraphicalStaffEntryContainer {
         if (this.verticalGraphicalStaffEntryContainers.length === 0 ||
             (CollectionUtil.getLastElement(this.verticalGraphicalStaffEntryContainers).AbsoluteTimestamp).lt(timestamp)) {
@@ -323,6 +351,15 @@ export class GraphicalMusicSheet {
         return undefined;
     }
 
+    /**
+     * Does a binary search on the container list and returns the VerticalContainer with the given Timestamp.
+     * The search begins at startIndex, if given.
+     * If the timestamp cannot be found, null is returned.
+     * @param timestamp - The timestamp for which the container shall be found.
+     * @param startIndex - The index from which the search starts in the container list.
+     * @returns {any}
+     * @constructor
+     */
     public GetVerticalContainerFromTimestamp(timestamp: Fraction, startIndex: number = 0): VerticalGraphicalStaffEntryContainer {
         let index: number = CollectionUtil.binarySearch(this.verticalGraphicalStaffEntryContainers,
                                                         new VerticalGraphicalStaffEntryContainer(0, timestamp),
@@ -334,6 +371,12 @@ export class GraphicalMusicSheet {
         return undefined;
     }
 
+    /**
+     * Perform a binary search for the absolute given Timestamp in all the GraphicalVerticalContainers.
+     * @param musicTimestamp
+     * @returns {number}
+     * @constructor
+     */
     public GetInterpolatedIndexInVerticalContainers(musicTimestamp: Fraction): number {
         let containers: VerticalGraphicalStaffEntryContainer[] = this.verticalGraphicalStaffEntryContainers;
         let leftIndex: number = 0;
@@ -358,6 +401,8 @@ export class GraphicalMusicSheet {
                     leftIndex = middleIndex;
                 }
             }
+
+            // no interpolation needed
             if (leftIndex === rightIndex) {
                 return this.verticalGraphicalStaffEntryContainers.indexOf(containers[leftIndex]);
             }
@@ -370,10 +415,18 @@ export class GraphicalMusicSheet {
         }
         let diff: number = rightTS.RealValue - leftTS.RealValue;
         let diffTS: number = rightTS.RealValue - musicTimestamp.RealValue;
+
+        // estimate the interpolated index
         foundIndex = rightIndex - (diffTS / diff);
         return Math.min(foundIndex, this.verticalGraphicalStaffEntryContainers.length);
     }
 
+    /**
+     * Get a List with the indeces of all the visible GraphicalMeasures and calculates their
+     * corresponding indices in the first SourceMeasure, taking into account Instruments with multiple Staves.
+     * @param visibleMeasures
+     * @returns {number[]}
+     */
     public getVisibleStavesIndecesFromSourceMeasure(visibleMeasures: StaffMeasure[]): number[] {
         let visibleInstruments: Instrument[] = [];
         let visibleStavesIndeces: number[] = [];
@@ -394,6 +447,12 @@ export class GraphicalMusicSheet {
         return visibleStavesIndeces;
     }
 
+    /**
+     * Returns the GraphicalMeasure with the given SourceMeasure as Parent at the given Index.
+     * @param sourceMeasure
+     * @param index
+     * @returns {any}
+     */
     public getGraphicalMeasureFromSourceMeasureAndIndex(sourceMeasure: SourceMeasure, index: number): StaffMeasure {
         for (let i: number = 0; i < this.measureList.length; i++) {
             if (this.measureList[i][0].parentSourceMeasure === sourceMeasure) {
@@ -420,12 +479,16 @@ export class GraphicalMusicSheet {
     public GetNearesNote(clickPosition: PointF2D, maxClickDist: PointF2D): GraphicalNote {
         let initialSearchArea: number = 10;
         let foundNotes: GraphicalNote[] = [];
+
+        // Prepare search area
         let region: BoundingBox = new BoundingBox();
         region.BorderLeft = clickPosition.x - initialSearchArea;
         region.BorderTop = clickPosition.y - initialSearchArea;
         region.BorderRight = clickPosition.x + initialSearchArea;
         region.BorderBottom = clickPosition.y + initialSearchArea;
         region.AbsolutePosition = new PointF2D(0, 0);
+
+        // Search for StaffEntries in region
         for (let idx: number = 0, len: number = this.MusicPages.length; idx < len; ++idx) {
             let graphicalMusicPage: GraphicalMusicPage = this.MusicPages[idx];
             let entries: GraphicalNote[] = graphicalMusicPage.PositionAndShape.getObjectsInRegion<GraphicalNote>(region);
@@ -442,6 +505,8 @@ export class GraphicalMusicSheet {
                 }
             }
         }
+
+        // Get closest entry
         let closest: GraphicalNote = undefined;
         for (let idx: number = 0, len: number = foundNotes.length; idx < len; ++idx) {
             let note: GraphicalNote = foundNotes[idx];
@@ -461,12 +526,15 @@ export class GraphicalMusicSheet {
         if (closest !== undefined) {
             return closest;
         }
+        // TODO No staff entry was found. Feedback?
+        // throw new ArgumentException("No staff entry found");
         return undefined;
     }
 
     public GetClickableLabel(clickPosition: PointF2D): GraphicalLabel {
         let initialSearchAreaX: number = 4;
         let initialSearchAreaY: number = 4;
+        // Prepare search area
         let region: BoundingBox = new BoundingBox();
         region.BorderLeft = clickPosition.x - initialSearchAreaX;
         region.BorderTop = clickPosition.y - initialSearchAreaY;
@@ -491,12 +559,14 @@ export class GraphicalMusicSheet {
     public GetNearestStaffEntry(clickPosition: PointF2D): GraphicalStaffEntry {
         let initialSearchArea: number = 10;
         let foundEntries: GraphicalStaffEntry[] = [];
+        // Prepare search area
         let region: BoundingBox = new BoundingBox(undefined);
         region.BorderLeft = clickPosition.x - initialSearchArea;
         region.BorderTop = clickPosition.y - initialSearchArea;
         region.BorderRight = clickPosition.x + initialSearchArea;
         region.BorderBottom = clickPosition.y + initialSearchArea;
         region.AbsolutePosition = new PointF2D(0, 0);
+        // Search for StaffEntries in region
         for (let idx: number = 0, len: number = this.MusicPages.length; idx < len; ++idx) {
             let graphicalMusicPage: GraphicalMusicPage = this.MusicPages[idx];
             let entries: GraphicalStaffEntry[] = graphicalMusicPage.PositionAndShape.getObjectsInRegion<GraphicalStaffEntry>(region, false);
@@ -509,6 +579,7 @@ export class GraphicalMusicSheet {
                 }
             }
         }
+        // Get closest entry
         let closest: GraphicalStaffEntry = undefined;
         for (let idx: number = 0, len: number = foundEntries.length; idx < len; ++idx) {
             let gse: GraphicalStaffEntry = foundEntries[idx];
@@ -528,6 +599,8 @@ export class GraphicalMusicSheet {
         if (closest !== undefined) {
             return closest;
         }
+        // TODO No staff entry was found. Feedback?
+        // throw new ArgumentException("No staff entry found");
         return undefined;
     }
 
@@ -585,6 +658,11 @@ export class GraphicalMusicSheet {
         return undefined;
     }
 
+    /**
+     * Get visible staffentry for the container given by the index.
+     * @param index
+     * @returns {GraphicalStaffEntry}
+     */
     public getStaffEntry(index: number): GraphicalStaffEntry {
         let container: VerticalGraphicalStaffEntryContainer = this.VerticalGraphicalStaffEntryContainers[index];
         let staffEntry: GraphicalStaffEntry = undefined;
@@ -609,6 +687,12 @@ export class GraphicalMusicSheet {
         return staffEntry;
     }
 
+    /**
+     * Returns the index of the closest previous (earlier) vertical container which has at least some visible staff entry, with respect to the given index.
+     * @param index
+     * @returns {number}
+     * @constructor
+     */
     public GetPreviousVisibleContainerIndex(index: number): number {
         for (let i: number = index - 1; i >= 0; i--) {
             let entries: GraphicalStaffEntry[] = this.verticalGraphicalStaffEntryContainers[i].StaffEntries;
@@ -622,6 +706,12 @@ export class GraphicalMusicSheet {
         return -1;
     }
 
+    /**
+     * Returns the index of the closest next (later) vertical container which has at least some visible staff entry, with respect to the given index.
+     * @param index
+     * @returns {number}
+     * @constructor
+     */
     public GetNextVisibleContainerIndex(index: number): number {
         for (let i: number = index + 1; i < this.verticalGraphicalStaffEntryContainers.length; ++i) {
             let entries: GraphicalStaffEntry[] = this.verticalGraphicalStaffEntryContainers[i].StaffEntries;
@@ -808,6 +898,11 @@ export class GraphicalMusicSheet {
         return (deltaX * deltaX) + (deltaY * deltaY);
     }
 
+    /**
+     * Return the longest StaffEntry duration from a GraphicalVerticalContainer.
+     * @param index
+     * @returns {Fraction}
+     */
     private getLongestStaffEntryDuration(index: number): Fraction {
         let maxLength: Fraction = new Fraction(0, 1);
         for (let idx: number = 0, len: number = this.verticalGraphicalStaffEntryContainers[index].StaffEntries.length; idx < len; ++idx) {