Merge branch 'develop' into feature/Articulations

src/Common/DataObjects/Fraction.ts

@@ -121,6 +121,7 @@ export class Fraction {
   public set Denominator(value: number) {
     if (this.denominator !== value) {
       this.denominator = value;
+      // don't simplify in case of a GraceNote (need it in order to set the right symbol)
       if (this.numerator !== 0) {
         this.simplify();
       }
@@ -139,6 +140,10 @@ export class Fraction {
     }
   }
 
+  /**
+   * Returns the unified numerator where the whole value will be expanded
+   * with the denominator and added to the existing numerator.
+   */
   public GetExpandedNumerator(): number {
     return this.wholeValue * this.denominator + this.numerator;
   }
@@ -166,6 +171,8 @@ export class Fraction {
   // }
 
   public Add(fraction: Fraction): void {
+    // normally should check if denominator or fraction.denominator is 0 but in our case
+    // a zero denominator doesn't make sense
     this.numerator = (this.wholeValue * this.denominator + this.numerator) * fraction.denominator +
       (fraction.wholeValue * fraction.denominator + fraction.numerator) * this.denominator;
     this.denominator = this.denominator * fraction.denominator;
@@ -175,6 +182,8 @@ export class Fraction {
   }
 
   public Sub(fraction: Fraction): void {
+    // normally should check if denominator or fraction.denominator is 0 but in our case
+    // a zero denominator doesn't make sense
     this.numerator = (this.wholeValue * this.denominator + this.numerator) * fraction.denominator -
       (fraction.wholeValue * fraction.denominator + fraction.numerator) * this.denominator;
     this.denominator = this.denominator * fraction.denominator;
@@ -182,7 +191,11 @@ export class Fraction {
     this.simplify();
     this.setRealValue();
   }
-
+  /**
+   * Brute Force quanization by searching incremental with the numerator until the denominator is
+   * smaller/equal than the desired one.
+   * @param maxAllowedDenominator
+   */
   public Quantize(maxAllowedDenominator: number): Fraction {
     if (this.denominator <= maxAllowedDenominator) {
       return this;
@@ -239,11 +252,14 @@ export class Fraction {
   }
 
   private simplify(): void {
+    // don't simplify in case of a GraceNote (need it in order to set the right symbol)
     if (this.numerator === 0) {
       this.denominator = 1;
       return;
     }
 
+    // normally should check if denominator or fraction.denominator is 0 but in our case a zero denominator
+    // doesn't make sense. Could probably be optimized
     const i: number = Fraction.greatestCommonDenominator(Math.abs(this.numerator), Math.abs(this.denominator));
 
     this.numerator /= i;

src/MusicalScore/Instrument.ts

@@ -173,6 +173,8 @@ export class Instrument extends InstrumentalGroup {
     public SetStaffAudible(staffId: number, audible: boolean): void {
         const staff: Staff = this.staves[staffId - 1];
         staff.audible = audible;
+        // hack for now:
+        // activate all voices needed so that the staff notes will be played
         if (audible) {
             for (let idx: number = 0, len: number = staff.Voices.length; idx < len; ++idx) {
                 const v: Voice = staff.Voices[idx];

src/MusicalScore/MusicParts/MusicPartManager.ts

@@ -13,9 +13,17 @@ export class MusicPartManager /*implements ISelectionListener*/ {
     private musicSheet: MusicSheet;
     private sheetStart: Fraction;
     private sheetEnd: Fraction;
+
+    /**
+     * This method is called from CoreContainer when the user changes a Repetitions's userNumberOfRepetitions.
+     */
     public reInit(): void {
         this.init();
     }
+
+    /**
+     * Main initialize method for MusicPartManager.
+     */
     public init(): void {
         this.parts = this.musicSheet.Repetitions.slice();
         this.sheetStart = this.musicSheet.SelectionStart = new Fraction(0, 1);
@@ -73,6 +81,8 @@ export class MusicPartManager /*implements ISelectionListener*/ {
         while (!iterator.EndReached) {
             if (iterator.JumpOccurred || currentRepetition !== iterator.CurrentRepetition) {
                 currentRepetition = iterator.CurrentRepetition;
+                // if we are still in the same repetition but in a different repetition run, we remember
+                // that we have to jump backwards at this position
                 if (iterator.backJumpOccurred) {
                     const jumpRep: Repetition = iterator.JumpResponsibleRepetition;
                     curTimestampTransform.nextBackJump = iterator.CurrentEnrolledTimestamp;

src/MusicalScore/MusicParts/MusicPartManagerIterator.ts

@@ -128,6 +128,10 @@ export class MusicPartManagerIterator {
     public get JumpResponsibleRepetition(): Repetition {
         return this.jumpResponsibleRepetition;
     }
+
+    /**
+     * Creates a clone of this iterator which has the same actual position.
+     */
     public clone(): MusicPartManagerIterator {
         const ret: MusicPartManagerIterator = new MusicPartManagerIterator(this.manager);
         ret.currentVoiceEntryIndex = this.currentVoiceEntryIndex;
@@ -139,6 +143,11 @@ export class MusicPartManagerIterator {
         return ret;
     }
 
+    /**
+     * Returns the visible voice entries for the provided instrument of the current iterator position.
+     * @param instrument
+     * Returns: A List of voiceEntries. If there are no entries the List has a Count of 0 (it does not return null).
+     */
     public CurrentVisibleVoiceEntries(instrument?: Instrument): VoiceEntry[] {
         const voiceEntries: VoiceEntry[] = [];
         if (this.currentVoiceEntries === undefined) {
@@ -159,6 +168,11 @@ export class MusicPartManagerIterator {
         return voiceEntries;
     }
 
+    /**
+     * Returns the visible voice entries for the provided instrument of the current iterator position.
+     * @param instrument
+     * Returns: A List of voiceEntries. If there are no entries the List has a Count of 0 (it does not return null).
+     */
     public CurrentAudibleVoiceEntries(instrument?: Instrument): VoiceEntry[] {
         const voiceEntries: VoiceEntry[] = [];
         if (this.currentVoiceEntries === undefined) {
@@ -179,10 +193,20 @@ export class MusicPartManagerIterator {
         return voiceEntries;
     }
 
+    /**
+     * Returns the audible dynamics of the current iterator position.
+     * Returns: A List of Dynamics. If there are no entries the List has a Count of 0 (it does not return null).
+     */
     public getCurrentDynamicChangingExpressions(): DynamicsContainer[] {
         return this.currentDynamicChangingExpressions;
     }
 
+    /**
+     * Returns the score following voice entries for the provided instrument of the current iterator position.
+     * @param instrument
+     * Returns: A List of voiceEntries. If there are no entries the List has a Count of 0
+     * (it does not return null).
+     */
     public CurrentScoreFollowingVoiceEntries(instrument?: Instrument): VoiceEntry[] {
         const voiceEntries: VoiceEntry[] = [];
         if (this.currentVoiceEntries === undefined) {
@@ -471,6 +495,7 @@ export class MusicPartManagerIterator {
             this.handleRepetitionsAtMeasureBegin();
             this.activateCurrentRhythmInstructions();
         }
+        // everything fine, no complications
         if (this.currentVoiceEntryIndex >= 0 && this.currentVoiceEntryIndex < this.currentMeasure.VerticalSourceStaffEntryContainers.length) {
             const currentContainer: VerticalSourceStaffEntryContainer = this.currentMeasure.VerticalSourceStaffEntryContainers[this.currentVoiceEntryIndex];
             this.currentVoiceEntries = this.getVoiceEntries(currentContainer);
@@ -491,11 +516,18 @@ export class MusicPartManagerIterator {
             this.recursiveMove();
             return;
         }
+        // we reached the end
         this.currentVerticalContainerInMeasureTimestamp = new Fraction();
         this.currentMeasure = undefined;
         this.currentVoiceEntries = undefined;
         this.endReached = true;
     }
+
+    /**
+     * helper function for moveToNextVisibleVoiceEntry and moveToPreviousVisibleVoiceEntry
+     * Get all entries and check if there is at least one valid entry in the list
+     * @param notesOnly
+     */
     private checkEntries(notesOnly: boolean): boolean {
         const tlist: VoiceEntry[] = this.CurrentVisibleVoiceEntries();
         if (tlist.length > 0) {

src/MusicalScore/MusicSheet.ts

@@ -27,15 +27,19 @@ export class PlaybackSettings {
 /**
  * This is the representation of a complete piece of sheet music.
  * It includes the contents of a MusicXML file after the reading.
+ * Notes: the musicsheet might not need the Rules, e.g. in the testframework. The EngravingRules Constructor
+ * fails when no FontInfo exists, which needs a TextMeasurer
  */
 export class MusicSheet /*implements ISettableMusicSheet, IComparable<MusicSheet>*/ {
     constructor() {
         this.rules = EngravingRules.Rules;
         this.playbackSettings = new PlaybackSettings();
         // FIXME?
+        // initialize SheetPlaybackSetting with default values
         this.playbackSettings.rhythm = new Fraction(4, 4, 0, false);
         this.userStartTempoInBPM = 100;
         this.pageWidth = 120;
+        // create MusicPartManager
         this.MusicPartManager = new MusicPartManager(this);
     }
     public static defaultTitle: string = "[kein Titel]";
@@ -291,6 +295,10 @@ export class MusicSheet /*implements ISettableMusicSheet, IComparable<MusicSheet
         }
         return measures;
     }
+    /**
+     * Returns the next SourceMeasure from a given SourceMeasure.
+     * @param measure
+     */
     public getNextSourceMeasure(measure: SourceMeasure): SourceMeasure {
         const index: number = this.sourceMeasures.indexOf(measure);
         if (index === this.sourceMeasures.length - 1) {
@@ -298,9 +306,15 @@ export class MusicSheet /*implements ISettableMusicSheet, IComparable<MusicSheet
         }
         return this.sourceMeasures[index + 1];
     }
+    /**
+     * Returns the first SourceMeasure of MusicSheet.
+     */
     public getFirstSourceMeasure(): SourceMeasure {
         return this.sourceMeasures[0];
     }
+    /**
+     * Returns the last SourceMeasure of MusicSheet.
+     */
     public getLastSourceMeasure(): SourceMeasure {
         return this.sourceMeasures[this.sourceMeasures.length - 1];
     }

src/MusicalScore/SubInstrument.ts

@@ -93,6 +93,7 @@ export class SubInstrument {
     private parseMidiInstrument(instrumentType: string): string {
         // FIXME: test this function
         try {
+            // find the best match for the given instrumentType:
             if (instrumentType) {
                 const tmpName: string = instrumentType.toLowerCase().trim();
                 for (const key in SubInstrument.midiInstrument) {
@@ -101,6 +102,7 @@ export class SubInstrument {
                     }
                 }
             }
+            // if the instrumentType didn't work, use the name:
             if (this.parentInstrument.Name) {
                 const tmpName: string = this.parentInstrument.Name.toLowerCase().trim();
                 for (const key in SubInstrument.midiInstrument) {