@coderline/alphatab 1.8.0-alpha.1650 → 1.8.0-alpha.1653

package/dist/alphaTab.d.ts

@@ -364,6 +364,7 @@ export declare class AlphaTabApiBase<TSettings> {
     private _actualPlayerMode;
     private _player;
     private _renderer;
+    private _defaultScrollHandler?;
     /**
      * An indicator by how many midi-ticks the song contents are shifted.
      * Grace beats at start might require a shift for the first beat to start at 0.
@@ -836,6 +837,42 @@ export declare class AlphaTabApiBase<TSettings> {
      */
     render(): void;
     private _tickCache;
+    /**
+     * A custom scroll handler which will be used to handle scrolling operations during playback.
+     *
+     * @category Properties - Player
+     * @since 1.8.0
+     * @example
+     * JavaScript
+     * ```js
+     * const api = new alphaTab.AlphaTabApi(document.querySelector('#alphaTab'));
+     * api.customScrollHandler = {
+     *   forceScrollTo(currentBeatBounds) {
+     *     const scroll = api.uiFacade.getScrollElement();
+     *     api.uiFacade.scrollToY(scroll, currentBeatBounds.barBounds.masterBarBounds.realBounds.y, 0);
+     *   },
+     *   onBeatCursorUpdating(startBeat, endBeat, cursorMode, relativePosition, actualBeatCursorStartX, actualBeatCursorEndX, actualBeatCursorTransitionDuration) {
+     *     const scroll = api.uiFacade.getScrollElement();
+     *     api.uiFacade.scrollToY(scroll, startBeat.barBounds.masterBarBounds.realBounds.y, 0);
+     *   }
+     * }
+     * ```
+     *
+     * @example
+     * C#
+     * ```cs
+     * var api = new AlphaTabApi<MyControl>(...);
+     * api.CustomScrollHandler = new CustomScrollHandler();
+     * ```
+     *
+     * @example
+     * Android
+     * ```kotlin
+     * val api = AlphaTabApi<MyControl>(...)
+     * api.customScrollHandler = CustomScrollHandler();
+     * ```
+     */
+    customScrollHandler?: IScrollHandler;
     /**
      * The tick cache allowing lookup of midi ticks to beats.
      * @remarks
@@ -1643,9 +1680,12 @@ export declare class AlphaTabApiBase<TSettings> {
     private _isInitialBeatCursorUpdate;
     private _previousStateForCursor;
     private _previousCursorCache;
-    private _lastScroll;
     private _destroyCursors;
+    private _createCursors;
     private _updateCursors;
+    private _scrollHandlerMode;
+    private _scrollHandlerVertical;
+    private _updateScrollHandler;
     /**
      * updates the cursors to highlight the beat at the specified tick position
      * @param tick
@@ -1663,7 +1703,6 @@ export declare class AlphaTabApiBase<TSettings> {
      * @category Methods - Player
      */
     scrollToCursor(): void;
-    private _internalScrollToCursor;
     private _internalCursorUpdateBeat;
     /**
      * This event is fired when the played beat changed.
@@ -9776,6 +9815,47 @@ declare interface IScoreRenderer {
     readonly error: IEventEmitterOfT<Error>;
 }
 
+/**
+ * Classes implementing this interface can handle the scroll logic
+ * as the playback in alphaTab progresses.
+ *
+ *
+ * @public
+ */
+export declare interface IScrollHandler extends Disposable {
+    /**
+     * Requests a instant scrolling to the specified beat.
+     * @param currentBeatBounds The bounds and information about the current beat.
+     */
+    forceScrollTo(currentBeatBounds: BeatBounds): void;
+    /**
+     * Updates whenever the currently beat cursor is updating its start and end location
+     * from which it starts and animates to.
+     * @remarks
+     * This method is tightly coupled to how alphaTab internally handles the beat cursor display.
+     * alphaTab looks up the current and next beat to which the beat cursor needs to transition
+     * in a specific amount of time.
+     *
+     * In some occations the cursor will transition to the end of the bar instead of the next beat.
+     *
+     * @param startBeat the information about the beat where the cursor is starting its animation.
+     * @param endBeat the information about the beat where the cursor is ending its animation.
+     * @param cursorMode how the cursor is transitioning (e.g. to end of bar or to the location of the next beat)
+     * @param actualBeatCursorStartX the exact start position of the beat cursor animation.
+     * Depending on the exact time of the player, this position might be relatively adjusted.
+     * @param actualBeatCursorEndX the exact end position of the beat cursor animation.
+     * Depending on the exact time of the player and cursor mode,
+     * this might be beyond the expected bounds.
+     * To ensure a smooth cursor experience (no jumping/flicking back and forth), alphaTab
+     * optimizes the used end position and animation durations.
+     * @param actualBeatCursorTransitionDuration The duration of the beat cursor transition in milliseconds.
+     * Similar to the start and end positions, this duration is adjusted accordingly to ensure
+     * that the beat cursor remains smoothly at the expected position for the currently played time.
+     *
+     */
+    onBeatCursorUpdating(startBeat: BeatBounds, endBeat: BeatBounds | undefined, cursorMode: MidiTickLookupFindBeatResultCursorMode, actualBeatCursorStartX: number, actualBeatCursorEndX: number, actualBeatCursorTransitionDuration: number): void;
+}
+
 /**
  * This is the base interface for output devices which can
  * request and playback audio samples.
@@ -10007,6 +10087,11 @@ declare interface IUiFacade<TSettings> {
      * @param speed How fast the scrolling from the current offset to the given one should happen in milliseconds.
      */
     scrollToX(scrollElement: IContainer, offset: number, speed: number): void;
+    /**
+     * Stops any ongoing scrolling of the given element.
+     * @param scrollElement The element which might be scrolling dynamically.
+     */
+    stopScrolling(scrollElement: IContainer): void;
     /**
      * Attempts a load of the score represented by the given data object.
      * @param data The data object to decode
@@ -10022,6 +10107,17 @@ declare interface IUiFacade<TSettings> {
      * @returns true if the data object is supported and a load was initiated, otherwise false
      */
     loadSoundFont(data: unknown, append: boolean): boolean;
+    /**
+     * Updates the overflows needed to ensure the smooth scrolling
+     * can reach the "end" at the desired position.
+     * @param canvasElement The canvas element.
+     * @param offset The offset we need
+     * @param isVertical Whether we have a vertical or horizontal overflow
+     * @remarks
+     * Without these overflows we might not have enough scroll space
+     * and we cannot reach a "sticky cursor" behavior.
+     */
+    setCanvasOverflow(canvasElement: IContainer, overflow: number, isVertical: boolean): void;
     /**
      * This events is fired when the {@link canRender} property changes.
      */
@@ -10514,7 +10610,7 @@ declare class MasterBar {
  */
 declare class MasterBarBounds {
     /**
-     * Gets or sets the index of this bounds relative within the parent lookup.
+     * The MasterBar index within the data model represented by these bounds.
      */
     index: number;
     /**
@@ -14707,7 +14803,13 @@ export declare enum ScrollMode {
     /**
      * Scrolling happens as soon the cursors exceed the displayed range.
      */
-    OffScreen = 2
+    OffScreen = 2,
+    /**
+     * Scrolling happens constantly in a smooth fashion.
+     * This will disable the use of any native scroll optimizations but
+     * manually scroll the scroll container in the required speed.
+     */
+    Smooth = 3
 }
 
 /**