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.  *   playbackRates: !Array.<number>,
  69.  *   fastForwardRates: !Array.<number>,
  70.  *   rewindRates: !Array.<number>,
  71.  *   addSeekBar: boolean,
  72.  *   addBigPlayButton: boolean,
  73.  *   customContextMenu: boolean,
  74.  *   castReceiverAppId: string,
  75.  *   clearBufferOnQualityChange: boolean,
  76.  *   showUnbufferedStart: boolean,
  77.  *   seekBarColors: shaka.extern.UISeekBarColors,
  78.  *   volumeBarColors: shaka.extern.UIVolumeBarColors,
  79.  *   trackLabelFormat: shaka.ui.Overlay.TrackLabelFormat,
  80.  *   fadeDelay: number,
  81.  *   doubleClickForFullscreen: boolean,
  82.  *   singleClickForPlayAndPause: boolean,
  83.  *   enableKeyboardPlaybackControls: boolean,
  84.  *   enableFullscreenOnRotation: boolean,
  85.  *   forceLandscapeOnFullscreen: boolean,
  86.  *   enableTooltips: boolean
  87.  * }}
  88.  *
  89.  * @property {!Array.<string>} controlPanelElements
  90.  *   The ordered list of control panel elements of the UI.
  91.  * @property {!Array.<string>} overflowMenuButtons
  92.  *   The ordered list of the overflow menu buttons.
  93.  * @property {!Array.<string>} contextMenuElements
  94.  *   The ordered list of buttons in the context menu.
  95.  * @property {!Array.<string>} statisticsList
  96.  *   The ordered list of statistics present in the statistics container.
  97.  * @property {!Array.<number>} playbackRates
  98.  *   The ordered list of rates for playback selection.
  99.   * @property {!Array.<number>} fastForwardRates
  100.  *   The ordered list of rates for fast forward selection.
  101.  * @property {!Array.<number>} rewindRates
  102.  *   The ordered list of rates for rewind selection.
  103.  * @property {boolean} addSeekBar
  104.  *   Whether or not a seek bar should be part of the UI.
  105.  * @property {boolean} addBigPlayButton
  106.  *   Whether or not a big play button in the center of the video
  107.  *   should be part of the UI.
  108.  * @property {boolean} customContextMenu
  109.  *   Whether or not a custom context menu replaces the default.
  110.  * @property {string} castReceiverAppId
  111.  *   Receiver app id to use for the Chromecast support.
  112.  * @property {boolean} clearBufferOnQualityChange
  113.  *   Only applicable if the resolution selection is part of the UI.
  114.  *   Whether buffer should be cleared when changing resolution
  115.  *   via UI. Clearing buffer would result in immidiate change of quality,
  116.  *   but playback may flicker/stall for a sec as the content in new
  117.  *   resolution is being buffered. Not clearing the buffer will mean
  118.  *   we play the content in the previously selected resolution that we
  119.  *   already have buffered before switching to the new resolution.
  120.  * @property {boolean} showUnbufferedStart
  121.  *   If true, color any unbuffered region at the start of the seek bar as
  122.  *   unbuffered (using the "base" color).  If false, color any unbuffered region
  123.  *   at the start of the seek bar as played (using the "played" color).
  124.  *   <br>
  125.  *   A value of false matches the default behavior of Chrome's native controls
  126.  *   and Shaka Player v3.0+.
  127.  *   <br>
  128.  *   A value of true matches the default behavior of Shaka Player v2.5.
  129.  *   <br>
  130.  *   Defaults to false.
  131.  * @property {shaka.extern.UISeekBarColors} seekBarColors
  132.  *   The CSS colors applied to the seek bar.  This allows you to override the
  133.  *   colors used in the linear gradient constructed in JavaScript, since you
  134.  *   cannot easily do this in pure CSS.
  135.  * @property {shaka.extern.UIVolumeBarColors} volumeBarColors
  136.  *   The CSS colors applied to the volume bar.  This allows you to override the
  137.  *   colors used in the linear gradient constructed in JavaScript, since you
  138.  *   cannot do this in pure CSS.
  139.  * @property {shaka.ui.Overlay.TrackLabelFormat} trackLabelFormat
  140.  *   An enum that determines what is shown in the labels for text track and
  141.  *   audio variant selection.
  142.  *   LANGUAGE means that only the language of the item is shown.
  143.  *   ROLE means that only the role of the item is shown.
  144.  *   LANGUAGE_ROLE means both language and role are shown, or just language if
  145.  *   there is no role.
  146.  *   LABEL means the non-standard DASH "label" attribute or the HLS "NAME"
  147.  *   attribute are shown.
  148.  *   Defaults to LANGUAGE.
  149.  * @property {number} fadeDelay
  150.  *   The delay (in seconds) before fading out the controls once the user stops
  151.  *   interacting with them.  We recommend setting this to 3 on your cast
  152.  *   receiver UI.
  153.  *   Defaults to 0.
  154.  * @property {boolean} doubleClickForFullscreen
  155.  *   Whether or not double-clicking on the UI should cause it to enter
  156.  *   fullscreen.
  157.  *   Defaults to true.
  158.  * @property {boolean} singleClickForPlayAndPause
  159.  *   Whether or not clicking on the video should cause it to play or pause.
  160.  *   Defaults to true.
  161.  * @property {boolean} enableKeyboardPlaybackControls
  162.  *   Whether or not playback controls via keyboard is enabled, such as seek
  163.  *   forward, seek backward, jump to the beginning/end of the video.
  164.  *   Defaults to true.
  165.  * @property {boolean} enableFullscreenOnRotation
  166.  *   Whether or not to enter/exit fullscreen mode when the screen is rotated.
  167.  *   Defaults to true.
  168.  * @property {boolean} forceLandscapeOnFullscreen
  169.  *   Whether or not the device should rotate to landscape mode when the video
  170.  *   enters fullscreen.  Note that this behavior is based on an experimental
  171.  *   browser API, and may not work on all platforms.
  172.  *   Defaults to true.
  173.  * @property {boolean} enableTooltips
  174.  *   Whether or not buttons in the control panel display tooltips that contain
  175.  *   information about their function.
  176.  *   Defaults to false.
  177.  * @exportDoc
  178.  */
  179. shaka.extern.UIConfiguration;
  182. /**
  183.  * Interface for UI elements.  UI elements should inherit from the concrete base
  184.  * class shaka.ui.Element.  The members defined in this extern's constructor are
  185.  * all available from the base class, and are defined here to keep the compiler
  186.  * from renaming them.
  187.  *
  188.  * @extends {shaka.util.IReleasable}
  189.  * @interface
  190.  * @exportDoc
  191.  */
  192. shaka.extern.IUIElement = class {
  193.   /**
  194.    * @param {!HTMLElement} parent
  195.    * @param {!shaka.ui.Controls} controls
  196.    */
  197.   constructor(parent, controls) {
  198.     /**
  199.      * @protected {HTMLElement}
  200.      * @exportDoc
  201.      */
  202.     this.parent;
  204.     /**
  205.      * @protected {shaka.ui.Controls}
  206.      * @exportDoc
  207.      */
  208.     this.controls;
  210.     /**
  211.      * @protected {shaka.util.EventManager}
  212.      * @exportDoc
  213.      */
  214.     this.eventManager;
  216.     /**
  217.      * @protected {shaka.ui.Localization}
  218.      * @exportDoc
  219.      */
  220.     this.localization;
  222.     /**
  223.      * @protected {shaka.Player}
  224.      * @exportDoc
  225.      */
  226.     this.player;
  228.     /**
  229.      * @protected {HTMLMediaElement}
  230.      * @exportDoc
  231.      */
  232.     this.video;
  234.     /**
  235.      * @protected {shaka.extern.IAdManager}
  236.      * @exportDoc
  237.      */
  238.     this.adManager;
  240.     /**
  241.      * @protected {shaka.extern.IAd}
  242.      * @exportDoc
  243.      */
  244.     this.ad;
  245.   }
  247.   /**
  248.    * @override
  249.    */
  250.   release() {}
  251. };
  254. /**
  255.  * A factory for creating a UI element.
  256.  *
  257.  * @interface
  258.  * @exportDoc
  259.  */
  260. shaka.extern.IUIElement.Factory = class {
  261.   /**
  262.    * @param {!HTMLElement} rootElement
  263.    * @param {!shaka.ui.Controls} controls
  264.    * @return {!shaka.extern.IUIElement}
  265.    */
  266.   create(rootElement, controls) {}
  267. };
  270. /**
  271.  * Interface for UI range elements.  UI range elements should inherit from the
  272.  * concrete base class shaka.ui.RangeElement.  The members defined in this
  273.  * extern's constructor are all available from the base class, and are defined
  274.  * here to keep the compiler from renaming them.
  275.  *
  276.  * @extends {shaka.extern.IUIElement}
  277.  * @interface
  278.  * @exportDoc
  279.  */
  280. shaka.extern.IUIRangeElement = class {
  281.   /**
  282.    * @param {!HTMLElement} parent
  283.    * @param {!shaka.ui.Controls} controls
  284.    * @param {!Array.<string>} containerClassNames
  285.    * @param {!Array.<string>} barClassNames
  286.    */
  287.   constructor(parent, controls, containerClassNames, barClassNames) {
  288.     /**
  289.      * @protected {!HTMLElement}
  290.      * @exportDoc
  291.      */
  292.     this.container;
  294.     /**
  295.      * @protected {!HTMLInputElement}
  296.      * @exportDoc
  297.      */
  298.     this.bar;
  299.   }
  301.   /**
  302.    * @param {number} min
  303.    * @param {number} max
  304.    */
  305.   setRange(min, max) {}
  307.   /**
  308.    * Called when user interaction begins.
  309.    * To be overridden by subclasses.
  310.    */
  311.   onChangeStart() {}
  313.   /**
  314.    * Called when a new value is set by user interaction.
  315.    * To be overridden by subclasses.
  316.    */
  317.   onChange() {}
  319.   /**
  320.    * Called when user interaction ends.
  321.    * To be overridden by subclasses.
  322.    */
  323.   onChangeEnd() {}
  325.   /** @return {number} */
  326.   getValue() {}
  328.   /** @param {number} value */
  329.   setValue(value) {}
  331.   /** @param {number} value */
  332.   changeTo(value) {}
  333. };
  335. /**
  336.  * Interface for UI settings menus.  UI settings menus should inherit from the
  337.  * concrete base class shaka.ui.SettingsMenu.  The members defined in this
  338.  * extern's constructor are all available from the base class, and are defined
  339.  * here to keep the compiler from renaming them.
  340.  *
  341.  * @extends {shaka.extern.IUIElement}
  342.  * @interface
  343.  * @exportDoc
  344.  */
  345. shaka.extern.IUISettingsMenu = class {
  346.   /**
  347.    * @param {!HTMLElement} parent
  348.    * @param {!shaka.ui.Controls} controls
  349.    * @param {string} iconText
  350.    */
  351.   constructor(parent, controls, iconText) {
  352.     /**
  353.      * @protected {!HTMLButtonElement}
  354.      * @exportDoc
  355.      */
  356.     this.button;
  358.     /**
  359.      * @protected {!HTMLElement}
  360.      * @exportDoc
  361.      */
  362.     this.icon;
  364.     /**
  365.      * @protected {!HTMLElement}
  366.      * @exportDoc
  367.      */
  368.     this.nameSpan;
  370.     /**
  371.      * @protected {!HTMLElement}
  372.      * @exportDoc
  373.      */
  374.     this.currentSelection;
  376.     /**
  377.      * @protected {!HTMLElement}
  378.      * @exportDoc
  379.      */
  380.     this.menu;
  382.     /**
  383.      * @protected {!HTMLButtonElement}
  384.      * @exportDoc
  385.      */
  386.     this.backButton;
  388.     /**
  389.      * @protected {!HTMLElement}
  390.      * @exportDoc
  391.      */
  392.     this.backSpan;
  393.   }
  394. };
  396. /**
  397.  * Interface for SeekBars. SeekBars should inherit from the concrete base
  398.  * class shaka.ui.Element. If you do not need to totaly rebuild the
  399.  * SeekBar, you should consider using shaka.ui.RangeElement or
  400.  * shaka.ui.SeekBar as your base class.
  401.  *
  402.  * @extends {shaka.extern.IUIRangeElement}
  403.  * @interface
  404.  * @exportDoc
  405.  */
  406. shaka.extern.IUISeekBar = class {
  407.   /** @return {number} */
  408.   getValue() {}
  410.   /** @param {number} value */
  411.   setValue(value) {}
  413.   /**
  414.    * Called by Controls on a timer to update the state of the seek bar.
  415.    * Also called internally when the user interacts with the input element.
  416.    */
  417.   update() {}
  419.   /** @return {boolean} */
  420.   isShowing() {}
  421. };
  423. /**
  424.  * A factory for creating a SeekBar element.
  425.  *
  426.  * @interface
  427.  * @exportDoc
  428.  */
  429. shaka.extern.IUISeekBar.Factory = class {
  430.   /**
  431.    * @param {!HTMLElement} rootElement
  432.    * @param {!shaka.ui.Controls} controls
  433.    * @return {!shaka.extern.IUISeekBar}
  434.    */
  435.   create(rootElement, controls) {}
  436. };