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

package/dist/alphaTab.d.ts

@@ -1745,8 +1745,8 @@ export declare class AlphaTabApiBase<TSettings> {
     private _onActiveBeatsChanged;
     private _isBeatMouseDown;
     private _isNoteMouseDown;
-    private _selectionStart;
-    private _selectionEnd;
+    private _selectionStart?;
+    private _selectionEnd?;
     /**
      * This event is fired whenever a the user presses the mouse button on a beat.
      * @eventProperty
@@ -1990,6 +1990,163 @@ export declare class AlphaTabApiBase<TSettings> {
     private _onNoteMouseUp;
     private _updateSelectionCursor;
     private _setupClickHandling;
+    /**
+     * 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: Beat, endBeat: Beat): void;
+    /**
+     * 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(): void;
+    /**
+     * 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(): void;
+    /**
+     * 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)
+     * }
+     * ```
+     *
+     */
+    readonly playbackRangeHighlightChanged: IEventEmitterOfT<PlaybackHighlightChangeEventArgs>;
     private _cursorSelectRange;
     /**
      * This event is fired whenever a new song is loaded.
@@ -5230,6 +5387,7 @@ declare class Bounds {
      */
     h: number;
     scaleWith(scale: number): void;
+    constructor(x?: number, y?: number, w?: number, h?: number);
 }
 
 /**
@@ -12803,6 +12961,35 @@ export declare namespace platform {
     }
 }
 
+/**
+ * Holds information about the highlights shown for the playback range.
+ * @public
+ * @record
+ */
+export declare interface PlaybackHighlightChangeEventArgs {
+    /**
+     * The beat where the selection starts. undefined if there is no selection.
+     */
+    startBeat?: Beat;
+    /**
+     * The bounds of the start beat to determine its location and size.
+     */
+    startBeatBounds?: BeatBounds;
+    /**
+     * The beat where the selection ends. undefined if there is no selection.
+     */
+    endBeat?: Beat;
+    /**
+     * The bounds of the end beat to determine its location and size.
+     */
+    endBeatBounds?: BeatBounds;
+    /**
+     * A list of the individual rectangular areas where highlight blocks are placed.
+     * If a selection spans multiple lines this array will hold all items.
+     */
+    highlightBlocks?: Bounds[];
+}
+
 /**
  * This public class stores the midi specific information of a track needed
  * for playback.