Source: ui/externs/ui.js

  1. /*! @license
  2.  * Shaka Player
  3.  * Copyright 2016 Google LLC
  4.  * SPDX-License-Identifier: Apache-2.0
  5.  */
  7. /**
  8.  * @externs
  9.  * @suppress {duplicate} To prevent compiler errors with the namespace
  10.  *   being declared both here and by goog.provide in the library.
  11.  */
  13. /** @namespace */
  14. var shaka = {};
  16. /** @namespace */
  17. shaka.extern = {};
  19. /**
  20.  * @typedef {{
  21.  *   base: string,
  22.  *   buffered: string,
  23.  *   played: string,
  24.  *   adBreaks: string
  25.  * }}
  26.  *
  27.  * @property {string} base
  28.  *   The CSS background color applied to the base of the seek bar, on top of
  29.  *   which the buffer level and playback position are shown.
  30.  * @property {string} buffered
  31.  *   The CSS background color applied to the portion of the seek bar showing
  32.  *   what has been buffered ahead of the playback position.
  33.  * @property {string} played
  34.  *   The CSS background color applied to the portion of the seek bar showing
  35.  *   what has been played already.
  36.  * @property {string} adBreaks
  37.  *   The CSS background color applied to the portion of the seek bar showing
  38.  *   when the ad breaks are scheduled to occur on the timeline.
  39.  * @exportDoc
  40.  */
  41. shaka.extern.UISeekBarColors;
  43. /**
  44.  * @typedef {{
  45.  *   base: string,
  46.  *   level: string
  47.  * }}
  48.  *
  49.  * @property {string} base
  50.  *   The CSS background color applied to the base of the volume bar, on top of
  51.  *   which the volume level is shown.
  52.  * @property {string} level
  53.  *   The CSS background color applied to the portion of the volume bar showing
  54.  *   the volume level.
  55.  * @exportDoc
  56.  */
  57. shaka.extern.UIVolumeBarColors;
  59. /**
  60.  * @description
  61.  * The UI's configuration options.
  62.  *
  63.  * @typedef {{
  64.  *   controlPanelElements: !Array.<string>,
  65.  *   overflowMenuButtons: !Array.<string>,
  66.  *   contextMenuElements: !Array.<string>,
  67.  *   statisticsList: !Array.<string>,
  68.  *   adStatisticsList: !Array.<string>,
  69.  *   playbackRates: !Array.<number>,
  70.  *   fastForwardRates: !Array.<number>,
  71.  *   rewindRates: !Array.<number>,
  72.  *   addSeekBar: boolean,
  73.  *   addBigPlayButton: boolean,
  74.  *   customContextMenu: boolean,
  75.  *   castReceiverAppId: string,
  76.  *   castAndroidReceiverCompatible: boolean,
  77.  *   clearBufferOnQualityChange: boolean,
  78.  *   showUnbufferedStart: boolean,
  79.  *   seekBarColors: shaka.extern.UISeekBarColors,
  80.  *   volumeBarColors: shaka.extern.UIVolumeBarColors,
  81.  *   trackLabelFormat: shaka.ui.Overlay.TrackLabelFormat,
  82.  *   textTrackLabelFormat: shaka.ui.Overlay.TrackLabelFormat,
  83.  *   fadeDelay: number,
  84.  *   doubleClickForFullscreen: boolean,
  85.  *   singleClickForPlayAndPause: boolean,
  86.  *   enableKeyboardPlaybackControls: boolean,
  87.  *   enableFullscreenOnRotation: boolean,
  88.  *   forceLandscapeOnFullscreen: boolean,
  89.  *   enableTooltips: boolean,
  90.  *   keyboardSeekDistance: number,
  91.  *   keyboardLargeSeekDistance: number,
  92.  *   fullScreenElement: HTMLElement,
  93.  *   preferDocumentPictureInPicture: boolean,
  94.  *   showAudioChannelCountVariants: boolean,
  95.  *   seekOnTaps: boolean,
  96.  *   tapSeekDistance: number,
  97.  *   refreshTickInSeconds: number,
  98.  *   displayInVrMode: boolean,
  99.  *   defaultVrProjectionMode: string
  100.  * }}
  101.  *
  102.  * @property {!Array.<string>} controlPanelElements
  103.  *   The ordered list of control panel elements of the UI.
  104.  * @property {!Array.<string>} overflowMenuButtons
  105.  *   The ordered list of the overflow menu buttons.
  106.  * @property {!Array.<string>} contextMenuElements
  107.  *   The ordered list of buttons in the context menu.
  108.  * @property {!Array.<string>} statisticsList
  109.  *   The ordered list of statistics present in the statistics container.
  110.  * @property {!Array.<string>} adStatisticsList
  111.  *   The ordered list of ad statistics present in the ad statistics container.
  112.  * @property {!Array.<number>} playbackRates
  113.  *   The ordered list of rates for playback selection.
  114.   * @property {!Array.<number>} fastForwardRates
  115.  *   The ordered list of rates for fast forward selection.
  116.  * @property {!Array.<number>} rewindRates
  117.  *   The ordered list of rates for rewind selection.
  118.  * @property {boolean} addSeekBar
  119.  *   Whether or not a seek bar should be part of the UI.
  120.  * @property {boolean} addBigPlayButton
  121.  *   Whether or not a big play button in the center of the video
  122.  *   should be part of the UI.
  123.  * @property {boolean} customContextMenu
  124.  *   Whether or not a custom context menu replaces the default.
  125.  * @property {string} castReceiverAppId
  126.  *   Receiver app id to use for the Chromecast support.
  127.  * @property {boolean} castAndroidReceiverCompatible
  128.  *   Indicates if the app is compatible with an Android Cast Receiver.
  129.  * @property {boolean} clearBufferOnQualityChange
  130.  *   Only applicable if the resolution selection is part of the UI.
  131.  *   Whether buffer should be cleared when changing resolution
  132.  *   via UI. Clearing buffer would result in immidiate change of quality,
  133.  *   but playback may flicker/stall for a sec as the content in new
  134.  *   resolution is being buffered. Not clearing the buffer will mean
  135.  *   we play the content in the previously selected resolution that we
  136.  *   already have buffered before switching to the new resolution.
  137.  * @property {boolean} showUnbufferedStart
  138.  *   If true, color any unbuffered region at the start of the seek bar as
  139.  *   unbuffered (using the "base" color).  If false, color any unbuffered region
  140.  *   at the start of the seek bar as played (using the "played" color).
  141.  *   <br>
  142.  *   A value of false matches the default behavior of Chrome's native controls
  143.  *   and Shaka Player v3.0+.
  144.  *   <br>
  145.  *   A value of true matches the default behavior of Shaka Player v2.5.
  146.  *   <br>
  147.  *   Defaults to false.
  148.  * @property {shaka.extern.UISeekBarColors} seekBarColors
  149.  *   The CSS colors applied to the seek bar.  This allows you to override the
  150.  *   colors used in the linear gradient constructed in JavaScript, since you
  151.  *   cannot easily do this in pure CSS.
  152.  * @property {shaka.extern.UIVolumeBarColors} volumeBarColors
  153.  *   The CSS colors applied to the volume bar.  This allows you to override the
  154.  *   colors used in the linear gradient constructed in JavaScript, since you
  155.  *   cannot do this in pure CSS.
  156.  * @property {shaka.ui.Overlay.TrackLabelFormat} trackLabelFormat
  157.  *   An enum that determines what is shown in the labels for audio variant
  158.  *   selection.
  159.  *   LANGUAGE means that only the language of the item is shown.
  160.  *   ROLE means that only the role of the item is shown.
  161.  *   LANGUAGE_ROLE means both language and role are shown, or just language if
  162.  *   there is no role.
  163.  *   LABEL means the non-standard DASH "label" attribute or the standard DASH
  164.  *   "Label" element or the HLS "NAME" attribute are shown.
  165.  *   Defaults to LANGUAGE.
  166.  * @property {shaka.ui.Overlay.TrackLabelFormat} textTrackLabelFormat
  167.  *   An enum that determines what is shown in the labels for text track
  168.  *   selection.
  169.  *   LANGUAGE means that only the language of the item is shown.
  170.  *   ROLE means that only the role of the item is shown.
  171.  *   LANGUAGE_ROLE means both language and role are shown, or just language if
  172.  *   there is no role.
  173.  *   LABEL means the non-standard DASH "label" attribute or the standard DASH
  174.  *   "Label" element or the HLS "NAME" attribute are shown.
  175.  *   Defaults to LANGUAGE.
  176.  * @property {number} fadeDelay
  177.  *   The delay (in seconds) before fading out the controls once the user stops
  178.  *   interacting with them.  We recommend setting this to 3 on your cast
  179.  *   receiver UI.
  180.  *   Defaults to 0.
  181.  * @property {boolean} doubleClickForFullscreen
  182.  *   Whether or not double-clicking on the UI should cause it to enter
  183.  *   fullscreen.
  184.  *   Defaults to true.
  185.  * @property {boolean} singleClickForPlayAndPause
  186.  *   Whether or not clicking on the video should cause it to play or pause.
  187.  *   It does not work in VR mode.
  188.  *   Defaults to true.
  189.  * @property {boolean} enableKeyboardPlaybackControls
  190.  *   Whether or not playback controls via keyboard is enabled, such as seek
  191.  *   forward, seek backward, jump to the beginning/end of the video.
  192.  *   Defaults to true.
  193.  * @property {boolean} enableFullscreenOnRotation
  194.  *   Whether or not to enter/exit fullscreen mode when the screen is rotated.
  195.  *   Defaults to true.
  196.  * @property {boolean} forceLandscapeOnFullscreen
  197.  *   Whether or not the device should rotate to landscape mode when the video
  198.  *   enters fullscreen.  Note that this behavior is based on an experimental
  199.  *   browser API, and may not work on all platforms.
  200.  *   Defaults to true.
  201.  * @property {boolean} enableTooltips
  202.  *   Whether or not buttons in the control panel display tooltips that contain
  203.  *   information about their function.
  204.  *   Defaults to false.
  205.  * @property {number} keyboardSeekDistance
  206.  *   The time interval, in seconds, to seek when the user presses the left or
  207.  *   right keyboard keys when the video is selected. If less than or equal to 0,
  208.  *   no seeking will occur.
  209.  *   Defaults to 5 seconds.
  210.  * @property {number} keyboardLargeSeekDistance
  211.  *   The time interval, in seconds, to seek when the user presses the page up or
  212.  *   page down keyboard keys when the video is selected. If less than or equal
  213.  *   to 0, no seeking will occur.
  214.  *   Defaults to 60 seconds.
  215.  * @property {HTMLElement} fullScreenElement
  216.  *   DOM element on which fullscreen will be done.
  217.  *   Defaults to Shaka Player Container.
  218.  * @property {boolean} preferDocumentPictureInPicture
  219.  *   Indicates whether the Document Picture in Picture API is preferred or the
  220.  *   Video Element Picture in Picture API is preferred.
  221.  *   Changing this property in mid-playback may produce undesired behavior if
  222.  *   you are already in PiP.
  223.  *   Defaults to true.
  224.  * @property {boolean} showAudioChannelCountVariants
  225.  *   Indicates whether the combination of language and channel count should be
  226.  *   displayed or if, on the contrary, only the language should be displayed
  227.  *   regardless of the channel count.
  228.  *   Defaults to true.
  229.  * @property {boolean} seekOnTaps
  230.  *   Indicates whether or not a fast-forward and rewind tap button that seeks
  231.  *   video some seconds.
  232.  *   Defaults to true.
  233.  * @property {number} tapSeekDistance
  234.  *   The time interval, in seconds, to seek when the user presses the left or
  235.  *   right part of the video. If less than or equal to 0,
  236.  *   no seeking will occur.
  237.  *   Defaults to 10 seconds.
  238.  * @property {number} refreshTickInSeconds
  239.  *   The time interval, in seconds, to update the seek bar.
  240.  *   Defaults to 0.125 seconds.
  241.  * @property {boolean} displayInVrMode
  242.  *   If true, the content will be treated as VR.
  243.  *   If false, it will only be treated as VR if we automatically detect it as
  244.  *   such. (See the Enabling VR section in docs/tutorials/ui.md)
  245.  *   Defaults to false.
  246.  * @property {string} defaultVrProjectionMode
  247.  *   Indicate the default VR projection mode.
  248.  *   Possible values: <code>'equirectangular'</code> or <code>'cubemap'</code>.
  249.  *   Defaults to <code>'equirectangular'</code>.
  250.  * @exportDoc
  251.  */
  252. shaka.extern.UIConfiguration;
  255. /**
  256.  * Interface for UI elements.  UI elements should inherit from the concrete base
  257.  * class shaka.ui.Element.  The members defined in this extern's constructor are
  258.  * all available from the base class, and are defined here to keep the compiler
  259.  * from renaming them.
  260.  *
  261.  * @extends {shaka.util.IReleasable}
  262.  * @interface
  263.  * @exportDoc
  264.  */
  265. shaka.extern.IUIElement = class {
  266.   /**
  267.    * @param {!HTMLElement} parent
  268.    * @param {!shaka.ui.Controls} controls
  269.    */
  270.   constructor(parent, controls) {
  271.     /**
  272.      * @protected {HTMLElement}
  273.      * @exportDoc
  274.      */
  275.     this.parent;
  277.     /**
  278.      * @protected {shaka.ui.Controls}
  279.      * @exportDoc
  280.      */
  281.     this.controls;
  283.     /**
  284.      * @protected {shaka.util.EventManager}
  285.      * @exportDoc
  286.      */
  287.     this.eventManager;
  289.     /**
  290.      * @protected {shaka.ui.Localization}
  291.      * @exportDoc
  292.      */
  293.     this.localization;
  295.     /**
  296.      * @protected {shaka.Player}
  297.      * @exportDoc
  298.      */
  299.     this.player;
  301.     /**
  302.      * @protected {HTMLMediaElement}
  303.      * @exportDoc
  304.      */
  305.     this.video;
  307.     /**
  308.      * @protected {shaka.extern.IAdManager}
  309.      * @exportDoc
  310.      */
  311.     this.adManager;
  313.     /**
  314.      * @protected {shaka.extern.IAd}
  315.      * @exportDoc
  316.      */
  317.     this.ad;
  318.   }
  320.   /**
  321.    * @override
  322.    */
  323.   release() {}
  324. };
  327. /**
  328.  * A factory for creating a UI element.
  329.  *
  330.  * @interface
  331.  * @exportDoc
  332.  */
  333. shaka.extern.IUIElement.Factory = class {
  334.   /**
  335.    * @param {!HTMLElement} rootElement
  336.    * @param {!shaka.ui.Controls} controls
  337.    * @return {!shaka.extern.IUIElement}
  338.    */
  339.   create(rootElement, controls) {}
  340. };
  343. /**
  344.  * Interface for UI range elements.  UI range elements should inherit from the
  345.  * concrete base class shaka.ui.RangeElement.  The members defined in this
  346.  * extern's constructor are all available from the base class, and are defined
  347.  * here to keep the compiler from renaming them.
  348.  *
  349.  * @extends {shaka.extern.IUIElement}
  350.  * @interface
  351.  * @exportDoc
  352.  */
  353. shaka.extern.IUIRangeElement = class {
  354.   /**
  355.    * @param {!HTMLElement} parent
  356.    * @param {!shaka.ui.Controls} controls
  357.    * @param {!Array.<string>} containerClassNames
  358.    * @param {!Array.<string>} barClassNames
  359.    */
  360.   constructor(parent, controls, containerClassNames, barClassNames) {
  361.     /**
  362.      * @protected {!HTMLElement}
  363.      * @exportDoc
  364.      */
  365.     this.container;
  367.     /**
  368.      * @protected {!HTMLInputElement}
  369.      * @exportDoc
  370.      */
  371.     this.bar;
  372.   }
  374.   /**
  375.    * @param {number} min
  376.    * @param {number} max
  377.    */
  378.   setRange(min, max) {}
  380.   /**
  381.    * Called when user interaction begins.
  382.    * To be overridden by subclasses.
  383.    */
  384.   onChangeStart() {}
  386.   /**
  387.    * Called when a new value is set by user interaction.
  388.    * To be overridden by subclasses.
  389.    */
  390.   onChange() {}
  392.   /**
  393.    * Called when user interaction ends.
  394.    * To be overridden by subclasses.
  395.    */
  396.   onChangeEnd() {}
  398.   /** @return {number} */
  399.   getValue() {}
  401.   /** @param {number} value */
  402.   setValue(value) {}
  404.   /** @param {number} value */
  405.   changeTo(value) {}
  406. };
  408. /**
  409.  * Interface for UI settings menus.  UI settings menus should inherit from the
  410.  * concrete base class shaka.ui.SettingsMenu.  The members defined in this
  411.  * extern's constructor are all available from the base class, and are defined
  412.  * here to keep the compiler from renaming them.
  413.  *
  414.  * @extends {shaka.extern.IUIElement}
  415.  * @interface
  416.  * @exportDoc
  417.  */
  418. shaka.extern.IUISettingsMenu = class {
  419.   /**
  420.    * @param {!HTMLElement} parent
  421.    * @param {!shaka.ui.Controls} controls
  422.    * @param {string} iconText
  423.    */
  424.   constructor(parent, controls, iconText) {
  425.     /**
  426.      * @protected {!HTMLButtonElement}
  427.      * @exportDoc
  428.      */
  429.     this.button;
  431.     /**
  432.      * @protected {!HTMLElement}
  433.      * @exportDoc
  434.      */
  435.     this.icon;
  437.     /**
  438.      * @protected {!HTMLElement}
  439.      * @exportDoc
  440.      */
  441.     this.nameSpan;
  443.     /**
  444.      * @protected {!HTMLElement}
  445.      * @exportDoc
  446.      */
  447.     this.currentSelection;
  449.     /**
  450.      * @protected {!HTMLElement}
  451.      * @exportDoc
  452.      */
  453.     this.menu;
  455.     /**
  456.      * @protected {!HTMLButtonElement}
  457.      * @exportDoc
  458.      */
  459.     this.backButton;
  461.     /**
  462.      * @protected {!HTMLElement}
  463.      * @exportDoc
  464.      */
  465.     this.backSpan;
  466.   }
  467. };
  469. /**
  470.  * Interface for SeekBars. SeekBars should inherit from the concrete base
  471.  * class shaka.ui.Element. If you do not need to totaly rebuild the
  472.  * SeekBar, you should consider using shaka.ui.RangeElement or
  473.  * shaka.ui.SeekBar as your base class.
  474.  *
  475.  * @extends {shaka.extern.IUIRangeElement}
  476.  * @interface
  477.  * @exportDoc
  478.  */
  479. shaka.extern.IUISeekBar = class {
  480.   /** @return {number} */
  481.   getValue() {}
  483.   /** @param {number} value */
  484.   setValue(value) {}
  486.   /**
  487.    * Called by Controls on a timer to update the state of the seek bar.
  488.    * Also called internally when the user interacts with the input element.
  489.    */
  490.   update() {}
  492.   /** @return {boolean} */
  493.   isShowing() {}
  494. };
  496. /**
  497.  * A factory for creating a SeekBar element.
  498.  *
  499.  * @interface
  500.  * @exportDoc
  501.  */
  502. shaka.extern.IUISeekBar.Factory = class {
  503.   /**
  504.    * @param {!HTMLElement} rootElement
  505.    * @param {!shaka.ui.Controls} controls
  506.    * @return {!shaka.extern.IUISeekBar}
  507.    */
  508.   create(rootElement, controls) {}
  509. };
  511. /**
  512.  * @interface
  513.  * @exportDoc
  514.  */
  515. shaka.extern.IUIPlayButton = class {
  516.   /**
  517.    * @param {!HTMLElement} parent
  518.    * @param {!shaka.ui.Controls} controls
  519.    */
  520.   constructor(parent, controls) {
  521.     /**
  522.      * @protected {!HTMLButtonElement}
  523.      * @exportDoc
  524.      */
  525.     this.button;
  526.   }
  528.   /** @return {boolean} */
  529.   isPaused() {}
  531.   /** @return {boolean} */
  532.   isEnded() {}
  533. };