@coderline/alphatab 1.8.0-alpha.1647 → 1.8.0-alpha.1651

package/dist/alphaTab.d.ts

@@ -357,12 +357,14 @@ export declare class AlphaTabApiBase<TSettings> {
     private _startTime;
     private _trackIndexes;
     private _trackIndexLookup;
+    private readonly _beatVisibilityChecker;
     private _isDestroyed;
     private _score;
     private _tracks;
     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.
@@ -835,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
@@ -1642,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
@@ -1662,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.
@@ -5263,6 +5303,12 @@ declare class BeatTickLookup {
      * @returns The first beat which is visible according to the given tracks or null.
      */
     getVisibleBeatAtStart(visibleTracks: Set<number>): Beat | null;
+    /**
+     * Looks for the first visible beat which starts at this lookup so it can be used for cursor placement.
+     * @param checker The custom checker to see if a beat is visible.
+     * @returns The first beat which is visible according to the given tracks or null.
+     */
+    getVisibleBeatAtStartWithChecker(checker: IBeatVisibilityChecker): Beat | null;
 }
 
 /**
@@ -9017,6 +9063,15 @@ declare interface IBackingTrackSynthOutput extends ISynthOutput {
     loadBackingTrack(backingTrack: BackingTrack): void;
 }
 
+/**
+ * Classes implementing this interface can help in checking whether beats are currently being
+ * displayed so that they can be considered for a tick-search.
+ * @public
+ */
+declare interface IBeatVisibilityChecker {
+    isVisible(beat: Beat): boolean;
+}
+
 /**
  * This is the base public interface for canvas implementations on different plattforms.
  * @public
@@ -9760,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.
@@ -9991,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
@@ -10006,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.
      */
@@ -10498,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;
     /**
@@ -11106,6 +11218,14 @@ declare class MidiTickLookup {
      * @returns The information about the current beat or null if no beat could be found.
      */
     findBeat(trackLookup: Set<number>, tick: number, currentBeatHint?: MidiTickLookupFindBeatResult | null): MidiTickLookupFindBeatResult | null;
+    /**
+     * Finds the currently played beat given a list of tracks and the current time.
+     * @param checker The checker to ask whether a beat is visible and should be considered for result.
+     * @param tick The current time in midi ticks.
+     * @param currentBeatHint Used for optimized lookup during playback. By passing in a previous result lookup of the next one can be optimized using heuristics. (optional).
+     * @returns The information about the current beat or null if no beat could be found.
+     */
+    findBeatWithChecker(checker: IBeatVisibilityChecker, tick: number, currentBeatHint?: MidiTickLookupFindBeatResult | null): MidiTickLookupFindBeatResult | null;
     private _findBeatFast;
     private _fillNextBeatMultiBarRest;
     private _fillNextBeat;
@@ -14288,6 +14408,23 @@ declare class RenderStylesheet {
      * Whether barlines should be drawn across staves within the same system.
      */
     extendBarLines: boolean;
+    /**
+     * Whether to hide empty staves.
+     */
+    hideEmptyStaves: boolean;
+    /**
+     * Whether to also hide empty staves in the first system.
+     * @remarks
+     * Only has an effect when activating {@link hideEmptyStaves}.
+     */
+    hideEmptyStavesInFirstSystem: boolean;
+    /**
+     * Whether to show brackets and braces across single staves.
+     * @remarks
+     * This allows a more consistent view for identifying staves when using
+     * {@link hideEmptyStaves}
+     */
+    showSingleStaffBrackets: boolean;
 }
 
 /**
@@ -14666,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
 }
 
 /**