@coderline/alphatab 1.8.0-alpha.1636 → 1.8.0-alpha.1637

package/dist/alphaTab.js

@@ -1,5 +1,5 @@
 /*!
- * alphaTab v1.8.0-alpha.1636 (develop, build 1636)
+ * alphaTab v1.8.0-alpha.1637 (develop, build 1637)
  *
  * Copyright © 2025, Daniel Kuschny and Contributors, All rights reserved.
  *
@@ -209,9 +209,9 @@
      * @internal
      */
     class VersionInfo {
-        static version = '1.8.0-alpha.1636';
-        static date = '2025-12-06T02:04:52.462Z';
-        static commit = '49c68ed64403080028c852fe371cc6bdcca8dc3a';
+        static version = '1.8.0-alpha.1637';
+        static date = '2025-12-07T02:26:27.382Z';
+        static commit = 'aa2c8101456d3ddfc777491468bc483789cc6c12';
         static print(print) {
             print(`alphaTab ${VersionInfo.version}`);
             print(`commit: ${VersionInfo.commit}`);
@@ -12956,25 +12956,31 @@
         /**
          * Gets or sets the X-position of the rectangle within the music notation.
          */
-        x = 0;
+        x;
         /**
          * Gets or sets the Y-position of the rectangle within the music notation.
          */
-        y = 0;
+        y;
         /**
          * Gets or sets the width of the rectangle.
          */
-        w = 0;
+        w;
         /**
          * Gets or sets the height of the rectangle.
          */
-        h = 0;
+        h;
         scaleWith(scale) {
             this.x *= scale;
             this.y *= scale;
             this.w *= scale;
             this.h *= scale;
         }
+        constructor(x = 0, y = 0, w = 0, h = 0) {
+            this.x = x;
+            this.y = y;
+            this.h = h;
+            this.w = w;
+        }
     }
 
     /**
@@ -49460,16 +49466,6 @@
         }
     }
 
-    /**
-     * @internal
-     */
-    class SelectionInfo {
-        beat;
-        bounds = null;
-        constructor(beat) {
-            this.beat = beat;
-        }
-    }
     /**
      * This class represents the public API of alphaTab and provides all logic to display
      * a music sheet in any UI using the given {@link IUiFacade}
@@ -51569,8 +51565,8 @@
         }
         _isBeatMouseDown = false;
         _isNoteMouseDown = false;
-        _selectionStart = null;
-        _selectionEnd = null;
+        _selectionStart;
+        _selectionEnd;
         /**
          * This event is fired whenever a the user presses the mouse button on a beat.
          * @eventProperty
@@ -51813,8 +51809,8 @@
                 return;
             }
             if (this._hasCursor && this.settings.player.enableUserInteraction) {
-                this._selectionStart = new SelectionInfo(beat);
-                this._selectionEnd = null;
+                this._selectionStart = { beat };
+                this._selectionEnd = undefined;
             }
             this._isBeatMouseDown = true;
             this.beatMouseDown.trigger(beat);
@@ -51834,7 +51830,7 @@
             }
             if (this.settings.player.enableUserInteraction) {
                 if (!this._selectionEnd || this._selectionEnd.beat !== beat) {
-                    this._selectionEnd = new SelectionInfo(beat);
+                    this._selectionEnd = { beat };
                     this._cursorSelectRange(this._selectionStart, this._selectionEnd);
                 }
             }
@@ -51853,45 +51849,7 @@
                 return;
             }
             if (this._hasCursor && this.settings.player.enableUserInteraction) {
-                if (this._selectionEnd) {
-                    const startTick = this._tickCache?.getBeatStart(this._selectionStart.beat) ??
-                        this._selectionStart.beat.absolutePlaybackStart;
-                    const endTick = this._tickCache?.getBeatStart(this._selectionEnd.beat) ??
-                        this._selectionEnd.beat.absolutePlaybackStart;
-                    if (endTick < startTick) {
-                        const t = this._selectionStart;
-                        this._selectionStart = this._selectionEnd;
-                        this._selectionEnd = t;
-                    }
-                }
-                if (this._selectionStart && this._tickCache) {
-                    // get the start and stop ticks (which consider properly repeats)
-                    const tickCache = this._tickCache;
-                    const realMasterBarStart = tickCache.getMasterBarStart(this._selectionStart.beat.voice.bar.masterBar);
-                    // move to selection start
-                    this._currentBeat = null; // reset current beat so it is updating the cursor
-                    if (this._player.state === PlayerState.Paused) {
-                        this._cursorUpdateTick(this._tickCache.getBeatStart(this._selectionStart.beat), false, 1);
-                    }
-                    this.tickPosition = realMasterBarStart + this._selectionStart.beat.playbackStart;
-                    // set playback range
-                    if (this._selectionEnd && this._selectionStart.beat !== this._selectionEnd.beat) {
-                        const realMasterBarEnd = tickCache.getMasterBarStart(this._selectionEnd.beat.voice.bar.masterBar);
-                        const range = new PlaybackRange();
-                        range.startTick = realMasterBarStart + this._selectionStart.beat.playbackStart;
-                        range.endTick =
-                            realMasterBarEnd +
-                                this._selectionEnd.beat.playbackStart +
-                                this._selectionEnd.beat.playbackDuration -
-                                50;
-                        this.playbackRange = range;
-                    }
-                    else {
-                        this._selectionStart = null;
-                        this.playbackRange = null;
-                        this._cursorSelectRange(this._selectionStart, this._selectionEnd);
-                    }
-                }
+                this.applyPlaybackRangeFromHighlight();
             }
             this.beatMouseUp.trigger(beat);
             this.uiFacade.triggerEvent(this.container, 'beatMouseUp', beat, originalEvent);
@@ -51913,13 +51871,13 @@
                 const startBeat = this._tickCache.findBeat(this._trackIndexLookup, range.startTick);
                 const endBeat = this._tickCache.findBeat(this._trackIndexLookup, range.endTick);
                 if (startBeat && endBeat) {
-                    const selectionStart = new SelectionInfo(startBeat.beat);
-                    const selectionEnd = new SelectionInfo(endBeat.beat);
+                    const selectionStart = { beat: startBeat.beat };
+                    const selectionEnd = { beat: endBeat.beat };
                     this._cursorSelectRange(selectionStart, selectionEnd);
                 }
             }
             else {
-                this._cursorSelectRange(null, null);
+                this._cursorSelectRange(undefined, undefined);
             }
         }
         _setupClickHandling() {
@@ -51988,24 +51946,230 @@
                 this._cursorSelectRange(this._selectionStart, this._selectionEnd);
             });
         }
+        /**
+         * Places the highlight markers at the specified start and end-beat range.
+         * @param startBeat The start beat where the selection should start
+         * @param endBeat The end beat where the selection should end.
+         *
+         * @remarks
+         * Unlike actually setting {@link playbackRange} this method only places the selection markers without actually
+         * changing the playback range. This method can be used when building custom selection systems (e.g. having draggable handles).
+         *
+         * @category Methods - Player
+         * @since 1.8.0
+         *
+         * @example
+         * JavaScript
+         * ```js
+         * const api = new alphaTab.AlphaTabApi(document.querySelector('#alphaTab'));
+         * const startBeat = api.score.tracks[0].staves[0].bars[0].voices[0].beats[0];
+         * const endBeat = api.score.tracks[0].staves[0].bars[3].voices[0].beats[0];
+         * api.highlightPlaybackRange(startBeat, endBeat);
+         * ```
+         *
+         * @example
+         * C#
+         * ```cs
+         * var api = new AlphaTabApi<MyControl>(...);
+         * api.ChangeTrackVolume(new Track[] { api.Score.Tracks[0], api.Score.Tracks[1] }, 1.5);
+         * api.ChangeTrackVolume(new Track[] { api.Score.Tracks[2] }, 0.5);
+         * var startBeat = api.Score.Tracks[0].Staves[0].Bars[0].Voices[0].Beats[0];
+         * var endBeat = api.Score.Tracks[0].Staves[0].Bars[3].Voices[0].Beats[0];
+         * api.HighlightPlaybackRange(startBeat, endBeat);
+         * ```
+         *
+         * @example
+         * Android
+         * ```kotlin
+         * val api = AlphaTabApi<MyControl>(...)
+         * val startBeat = api.score.tracks[0].staves[0].bars[0].voices[0].beats[0]
+         * val endBeat = api.score.tracks[0].staves[0].bars[3].voices[0].beats[0]
+         * api.highlightPlaybackRange(startBeat, endBeat)
+         * ```
+         */
+        highlightPlaybackRange(startBeat, endBeat) {
+            this._selectionStart = { beat: startBeat };
+            this._selectionEnd = { beat: endBeat };
+            this._cursorSelectRange(this._selectionStart, this._selectionEnd);
+        }
+        /**
+         * Applies the playback range from the currently highlighted range.
+         *
+         * @remarks
+         * This method can be used when building custom selection systems (e.g. having draggable handles).
+         *
+         * @category Methods - Player
+         * @since 1.8.0
+         *
+         * @example
+         * JavaScript
+         * ```js
+         * const api = new alphaTab.AlphaTabApi(document.querySelector('#alphaTab'));
+         * const startBeat = api.score.tracks[0].staves[0].bars[0].voices[0].beats[0];
+         * const endBeat = api.score.tracks[0].staves[0].bars[3].voices[0].beats[0];
+         * api.highlightPlaybackRange(startBeat, endBeat);
+         * api.applyPlaybackRangeFromHighlight();
+         * ```
+         *
+         * @example
+         * C#
+         * ```cs
+         * var api = new AlphaTabApi<MyControl>(...);
+         * api.ChangeTrackVolume(new Track[] { api.Score.Tracks[0], api.Score.Tracks[1] }, 1.5);
+         * api.ChangeTrackVolume(new Track[] { api.Score.Tracks[2] }, 0.5);
+         * var startBeat = api.Score.Tracks[0].Staves[0].Bars[0].Voices[0].Beats[0];
+         * var endBeat = api.Score.Tracks[0].Staves[0].Bars[3].Voices[0].Beats[0];
+         * api.HighlightPlaybackRange(startBeat, endBeat);
+         * api.ApplyPlaybackRangeFromHighlight();
+         * ```
+         *
+         * @example
+         * Android
+         * ```kotlin
+         * val api = AlphaTabApi<MyControl>(...)
+         * val startBeat = api.score.tracks[0].staves[0].bars[0].voices[0].beats[0]
+         * val endBeat = api.score.tracks[0].staves[0].bars[3].voices[0].beats[0]
+         * api.highlightPlaybackRange(startBeat, endBeat)
+         * api.applyPlaybackRangeFromHighlight()
+         * ```
+         */
+        applyPlaybackRangeFromHighlight() {
+            if (this._selectionEnd) {
+                const startTick = this._tickCache?.getBeatStart(this._selectionStart.beat) ??
+                    this._selectionStart.beat.absolutePlaybackStart;
+                const endTick = this._tickCache?.getBeatStart(this._selectionEnd.beat) ??
+                    this._selectionEnd.beat.absolutePlaybackStart;
+                if (endTick < startTick) {
+                    const t = this._selectionStart;
+                    this._selectionStart = this._selectionEnd;
+                    this._selectionEnd = t;
+                }
+            }
+            if (this._selectionStart && this._tickCache) {
+                // get the start and stop ticks (which consider properly repeats)
+                const tickCache = this._tickCache;
+                const realMasterBarStart = tickCache.getMasterBarStart(this._selectionStart.beat.voice.bar.masterBar);
+                // move to selection start
+                this._currentBeat = null; // reset current beat so it is updating the cursor
+                if (this._player.state === PlayerState.Paused) {
+                    this._cursorUpdateTick(this._tickCache.getBeatStart(this._selectionStart.beat), false, 1);
+                }
+                this.tickPosition = realMasterBarStart + this._selectionStart.beat.playbackStart;
+                // set playback range
+                if (this._selectionEnd && this._selectionStart.beat !== this._selectionEnd.beat) {
+                    const realMasterBarEnd = tickCache.getMasterBarStart(this._selectionEnd.beat.voice.bar.masterBar);
+                    const range = new PlaybackRange();
+                    range.startTick = realMasterBarStart + this._selectionStart.beat.playbackStart;
+                    range.endTick =
+                        realMasterBarEnd +
+                            this._selectionEnd.beat.playbackStart +
+                            this._selectionEnd.beat.playbackDuration -
+                            50;
+                    this.playbackRange = range;
+                }
+                else {
+                    this._selectionStart = undefined;
+                    this.playbackRange = null;
+                    this._cursorSelectRange(this._selectionStart, this._selectionEnd);
+                }
+            }
+        }
+        /**
+         * Clears the highlight markers marking the currently selected playback range.
+         *
+         * @remarks
+         * Unlike actually setting {@link playbackRange} this method only clears the selection markers without actually
+         * changing the playback range. This method can be used when building custom selection systems (e.g. having draggable handles).
+         *
+         * @category Methods - Player
+         * @since 1.8.0
+         *
+         * @example
+         * JavaScript
+         * ```js
+         * const api = new alphaTab.AlphaTabApi(document.querySelector('#alphaTab'));
+         * api.clearPlaybackRangeHighlight();
+         * ```
+         *
+         * @example
+         * C#
+         * ```cs
+         * var api = new AlphaTabApi<MyControl>(...);
+         * api.clearPlaybackRangeHighlight();
+         * ```
+         *
+         * @example
+         * Android
+         * ```kotlin
+         * val api = AlphaTabApi<MyControl>(...)
+         * api.clearPlaybackRangeHighlight()
+         * ```
+         */
+        clearPlaybackRangeHighlight() {
+            this._cursorSelectRange(undefined, undefined);
+        }
+        /**
+         * This event is fired the shown highlights for the selected playback range changes.
+         *
+         * @remarks
+         * This event is fired already during selection and not only when the selection is completed.
+         * This event can be used to place additional custom selection markers (like drag handles).
+         *
+         * @eventProperty
+         * @category Events - Player
+         * @since 1.8.0
+         *
+         * @example
+         * JavaScript
+         * ```js
+         * const api = new alphaTab.AlphaTabApi(document.querySelector('#alphaTab'));
+         * api.playbackRangeHighlightChanged.on(e => {
+         *    updateSelectionHandles(e);
+         * });
+         * ```
+         *
+         * @example
+         * C#
+         * ```cs
+         * var api = new AlphaTabApi<MyControl>(...);
+         * api.PlaybackRangeHighlightChanged.On(e =>
+         * {
+         *    UpdateSelectionHandles(e);
+         * });
+         * ```
+         *
+         * @example
+         * Android
+         * ```kotlin
+         * val api = AlphaTabApi<MyControl>(...)
+         * api.playbackRangeHighlightChanged.on { e ->
+         *     updateSelectionHandles(e)
+         * }
+         * ```
+         *
+         */
+        playbackRangeHighlightChanged = new EventEmitterOfT();
         _cursorSelectRange(startBeat, endBeat) {
             const cache = this._renderer.boundsLookup;
             if (!cache) {
+                this.playbackRangeHighlightChanged.trigger({});
                 return;
             }
             const selectionWrapper = this._selectionWrapper;
             if (!selectionWrapper) {
+                this.playbackRangeHighlightChanged.trigger({});
                 return;
             }
             selectionWrapper.clear();
             if (!startBeat || !endBeat || startBeat.beat === endBeat.beat) {
+                this.playbackRangeHighlightChanged.trigger({});
                 return;
             }
             if (!startBeat.bounds) {
-                startBeat.bounds = cache.findBeat(startBeat.beat);
+                startBeat.bounds = cache.findBeat(startBeat.beat) ?? undefined;
             }
             if (!endBeat.bounds) {
-                endBeat.bounds = cache.findBeat(endBeat.beat);
+                endBeat.bounds = cache.findBeat(endBeat.beat) ?? undefined;
             }
             const startTick = this._tickCache?.getBeatStart(startBeat.beat) ?? startBeat.beat.absolutePlaybackStart;
             const endTick = this._tickCache?.getBeatStart(endBeat.beat) ?? endBeat.beat.absolutePlaybackStart;
@@ -52014,7 +52178,17 @@
                 startBeat = endBeat;
                 endBeat = t;
             }
-            const startX = startBeat.bounds.realBounds.x;
+            const eventArgs = {
+                startBeat: startBeat.beat,
+                startBeatBounds: startBeat.bounds,
+                endBeat: endBeat.beat,
+                endBeatBounds: endBeat.bounds,
+                highlightBlocks: []
+            };
+            let startX = startBeat.bounds.realBounds.x;
+            if (startBeat.beat.index === 0) {
+                startX = startBeat.bounds.barBounds.masterBarBounds.realBounds.x;
+            }
             let endX = endBeat.bounds.realBounds.x + endBeat.bounds.realBounds.w;
             if (endBeat.beat.index === endBeat.beat.voice.beats.length - 1) {
                 endX =
@@ -52031,18 +52205,24 @@
                 const staffEndX = startBeat.bounds.barBounds.masterBarBounds.staffSystemBounds.visualBounds.x +
                     startBeat.bounds.barBounds.masterBarBounds.staffSystemBounds.visualBounds.w;
                 const startSelection = this.uiFacade.createSelectionElement();
-                startSelection.setBounds(startX, startBeat.bounds.barBounds.masterBarBounds.visualBounds.y, staffEndX - startX, startBeat.bounds.barBounds.masterBarBounds.visualBounds.h);
+                const startSelectionBounds = new Bounds(startX, startBeat.bounds.barBounds.masterBarBounds.visualBounds.y, staffEndX - startX, startBeat.bounds.barBounds.masterBarBounds.visualBounds.h);
+                startSelection.setBounds(startSelectionBounds.x, startSelectionBounds.y, startSelectionBounds.w, startSelectionBounds.h);
+                eventArgs.highlightBlocks.push(startSelectionBounds);
                 selectionWrapper.appendChild(startSelection);
                 const staffStartIndex = startBeat.bounds.barBounds.masterBarBounds.staffSystemBounds.index + 1;
                 const staffEndIndex = endBeat.bounds.barBounds.masterBarBounds.staffSystemBounds.index;
                 for (let staffIndex = staffStartIndex; staffIndex < staffEndIndex; staffIndex++) {
                     const staffBounds = cache.staffSystems[staffIndex];
                     const middleSelection = this.uiFacade.createSelectionElement();
-                    middleSelection.setBounds(staffStartX, staffBounds.visualBounds.y, staffEndX - staffStartX, staffBounds.visualBounds.h);
+                    const middleSelectionBounds = new Bounds(staffStartX, staffBounds.visualBounds.y, staffEndX - staffStartX, staffBounds.visualBounds.h);
+                    eventArgs.highlightBlocks.push(middleSelectionBounds);
+                    middleSelection.setBounds(middleSelectionBounds.x, middleSelectionBounds.y, middleSelectionBounds.w, middleSelectionBounds.h);
                     selectionWrapper.appendChild(middleSelection);
                 }
                 const endSelection = this.uiFacade.createSelectionElement();
-                endSelection.setBounds(staffStartX, endBeat.bounds.barBounds.masterBarBounds.visualBounds.y, endX - staffStartX, endBeat.bounds.barBounds.masterBarBounds.visualBounds.h);
+                const endSelectionBounds = new Bounds(staffStartX, endBeat.bounds.barBounds.masterBarBounds.visualBounds.y, endX - staffStartX, endBeat.bounds.barBounds.masterBarBounds.visualBounds.h);
+                eventArgs.highlightBlocks.push(endSelectionBounds);
+                endSelection.setBounds(endSelectionBounds.x, endSelectionBounds.y, endSelectionBounds.w, endSelectionBounds.h);
                 selectionWrapper.appendChild(endSelection);
             }
             else {
@@ -52051,6 +52231,7 @@
                 selection.setBounds(startX, startBeat.bounds.barBounds.masterBarBounds.visualBounds.y, endX - startX, startBeat.bounds.barBounds.masterBarBounds.visualBounds.h);
                 selectionWrapper.appendChild(selection);
             }
+            this.playbackRangeHighlightChanged.trigger(eventArgs);
         }
         /**
          * This event is fired whenever a new song is loaded.