@coderline/alphatab 1.8.0 → 1.8.1

package/dist/alphaTab.d.ts

@@ -365,6 +365,8 @@ export declare class AlphaTabApiBase<TSettings> {
     private _player;
     private _renderer;
     private _defaultScrollHandler?;
+    private _defaultCursorHandler?;
+    private _customCursorHandler?;
     /**
      * 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.
@@ -839,6 +841,62 @@ export declare class AlphaTabApiBase<TSettings> {
      * ```
      */
     render(renderHints?: RenderHints): void;
+    /**
+     * A custom cursor handler which will be used to update the cursor positions during playback.
+     *
+     * @category Properties - Player
+     * @since 1.8.1
+     * @example
+     * JavaScript
+     * ```js
+     * const api = new alphaTab.AlphaTabApi(document.querySelector('#alphaTab'));
+     * api.customCursorHandler = {
+     *   _customAdorner: undefined,
+     *   onAttach(cursors) {
+     *     this._customAdorner = document.createElement('div');
+     *     this._customAdorner.classList.add('cursor-adorner');
+     *     cursors.cursorWrapper.element.appendChild(this._customAdorner);
+     *   },
+     *   onDetach(cursors) { this._customAdorner.remove(); },
+     *   placeBarCursor(barCursor, beatBounds) {
+     *     const barBoundings = beatBounds.barBounds.masterBarBounds;
+     *     const barBounds = barBoundings.visualBounds;
+     *     barCursor.setBounds(barBounds.x, barBounds.y, barBounds.w, barBounds.h);
+     *   },
+     *   placeBeatCursor(beatCursor, beatBounds, startBeatX) {
+     *     const barBoundings = beatBounds.barBounds.masterBarBounds;
+     *     const barBounds = barBoundings.visualBounds;
+     *     beatCursor.transitionToX(0, startBeatX);
+     *     beatCursor.setBounds(startBeatX, barBounds.y, 1, barBounds.h);
+     *     this._customAdorner.style.left = startBeatX + 'px';
+     *     this._customAdorner.style.top = (barBounds.y - 10) + 'px';
+     *     this._customAdorner.style.width = '1px';
+     *     this._customAdorner.style.height = '10px';
+     *     this._customAdorner.style.transition = 'left 0ms linear'; // stop animation
+     *   },
+     *   transitionBeatCursor(beatCursor, beatBounds, startBeatX, endBeatX, duration, cursorMode) {
+     *     this._customAdorner.style.transition = `left ${duration}ms linear`; // start animation
+     *     this._customAdorner.style.left = endBeatX + 'px';
+     *   }
+     * }
+     * ```
+     *
+     * @example
+     * C#
+     * ```cs
+     * var api = new AlphaTabApi<MyControl>(...);
+     * api.CustomCursorHandler = new CustomCursorHandler();
+     * ```
+     *
+     * @example
+     * Android
+     * ```kotlin
+     * val api = AlphaTabApi<MyControl>(...)
+     * api.customCursorHandler = CustomCursorHandler();
+     * ```
+     */
+    get customCursorHandler(): ICursorHandler | undefined;
+    set customCursorHandler(value: ICursorHandler | undefined);
     private _tickCache;
     /**
      * A custom scroll handler which will be used to handle scrolling operations during playback.
@@ -1686,6 +1744,8 @@ export declare class AlphaTabApiBase<TSettings> {
     private _destroyCursors;
     private _createCursors;
     private _updateCursors;
+    private _cursorHandlerMode;
+    private _updateCursorHandler;
     private _scrollHandlerMode;
     private _scrollHandlerVertical;
     private _updateScrollHandler;
@@ -9283,6 +9343,50 @@ declare interface IContainer {
     mouseUp: IEventEmitterOfT<IMouseEventArgs>;
 }
 
+/**
+ * Classes implementing this interface can handle the cursor placement logic
+ * as the playback in alphaTab progresses.
+ *
+ * @public
+ */
+declare interface ICursorHandler {
+    /**
+     * Called when this handler activates. This can be on dynamic cursor creation
+     * or when setting a custom handler with cursors already created.
+     * @param cursors  A container holding information about the cursor elements.
+     */
+    onAttach(cursors: Cursors): void;
+    /**
+     * Called when this handler deactivates. This can be on dynamic cursor destroy
+     * or when setting a new custom handler.
+     * @param cursors A container holding information about the cursor elements.
+     */
+    onDetach(cursors: Cursors): void;
+    /**
+     * Instructs the handler to place the bar cursor for the given beat bounds instantly .
+     * @param barCursor The bar cursor.
+     * @param beatBounds The bounds of the currently active beat.
+     */
+    placeBarCursor(barCursor: IContainer, beatBounds: BeatBounds): void;
+    /**
+     * Instructs the handler to place the beat cursor for the given beat bounds instantly.
+     * @param barCursor The beat cursor.
+     * @param beatBounds The bounds of the currently active beat.
+     */
+    placeBeatCursor(beatCursor: IContainer, beatBounds: BeatBounds, startBeatX: number): void;
+    /**
+     * Instructs the handler to initiate a transition of the beat cursor (e.g. for dynamic animation).
+     * @param beatCursor The beat cursor
+     * @param beatBounds The bounds of the currently active beat.
+     * @param startBeatX The X-position where the transition of the beat cursor should start.
+     * @param nextBeatX The X-position where the transition of the beat cursor should end
+     * (typically the next beat or end of bar depending on the cursor mode and seeks)
+     * @param duration The duration in milliseconds on how long the transition should take.
+     * @param cursorMode The active cursor mode for the cursor placement.
+     */
+    transitionBeatCursor(beatCursor: IContainer, beatBounds: BeatBounds, startBeatX: number, nextBeatX: number, duration: number, cursorMode: MidiTickLookupFindBeatResultCursorMode): void;
+}
+
 /**
  * An emitter for an event without any value passed to the listeners.
  * @public
@@ -9372,6 +9476,18 @@ declare interface IExternalMediaSynthOutput extends IBackingTrackSynthOutput {
     updatePosition(currentTime: number): void;
 }
 
+/**
+ * A UI element implementation wrapping HTML elements.
+ * @target web
+ * @public
+ */
+declare interface IHtmlElementContainer extends IContainer {
+    /**
+     * The wrapped UI element.
+     */
+    readonly element: HTMLElement;
+}
+
 /**
  * @public
  */
@@ -11371,6 +11487,11 @@ declare class MidiTickLookup {
      * This info allows building the correct "next" beat and duration.
      */
     multiBarRestInfo: Map<number, number[]> | null;
+    /**
+     * An optional playback range to consider when performing lookups.
+     * This will mainly influence the used {@link MidiTickLookupFindBeatResultCursorMode}
+     */
+    playbackRange: PlaybackRange | null;
     /**
      * Finds the currently played beat given a list of tracks and the current time.
      * @param trackLookup The tracks indices in which to search the played beat for.
@@ -11488,9 +11609,14 @@ declare enum MidiTickLookupFindBeatResultCursorMode {
      */
     ToNextBext = 1,
     /**
-     * The cursor should animate to the end of the bar (typically on repeats and jumps)
+     * @deprecated replaced by {@link ToEndOfBeat}
      */
-    ToEndOfBar = 2
+    ToEndOfBar = 2,
+    /**
+     * The cursor should animate to the end of the **beat** (typically on repeats and jumps)
+     * (this is named end of bar historically)
+     */
+    ToEndOfBeat = 3
 }
 
 /**
@@ -13283,12 +13409,13 @@ export declare namespace platform {
     export {
         Cursors,
         ICanvas,
+        MeasuredText,
         TextAlign,
         TextBaseline,
-        MeasuredText,
         IContainer,
         IMouseEventArgs,
-        IUiFacade
+        IUiFacade,
+        IHtmlElementContainer
     }
 }