Source: ui/externs/ui.js

  1. /**
  2.  * @license
  3.  * Copyright 2016 Google Inc.
  4.  *
  5.  * Licensed under the Apache License, Version 2.0 (the "License");
  6.  * you may not use this file except in compliance with the License.
  7.  * You may obtain a copy of the License at
  8.  *
  9.  *     http://www.apache.org/licenses/LICENSE-2.0
  10.  *
  11.  * Unless required by applicable law or agreed to in writing, software
  12.  * distributed under the License is distributed on an "AS IS" BASIS,
  13.  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14.  * See the License for the specific language governing permissions and
  15.  * limitations under the License.
  16.  */
  19. /**
  20.  * @externs
  21.  * @suppress {duplicate} To prevent compiler errors with the namespace
  22.  *   being declared both here and by goog.provide in the library.
  23.  */
  25. /** @namespace */
  26. var shaka = {};
  28. /** @namespace */
  29. shaka.extern = {};
  31. /**
  32.  * @typedef {{
  33.  *   base: string,
  34.  *   buffered: string,
  35.  *   played: string
  36.  * }}
  37.  *
  38.  * @property {string} base
  39.  *   The CSS background color applied to the base of the seek bar, on top of
  40.  *   which the buffer level and playback position are shown.
  41.  * @property {string} buffered
  42.  *   The CSS background color applied to the portion of the seek bar showing
  43.  *   what has been buffered ahead of the playback position.
  44.  * @property {string} played
  45.  *   The CSS background color applied to the portion of the seek bar showing
  46.  *   what has been played already.
  47.  * @exportDoc
  48.  */
  49. shaka.extern.UISeekBarColors;
  51. /**
  52.  * @typedef {{
  53.  *   base: string,
  54.  *   level: string
  55.  * }}
  56.  *
  57.  * @property {string} base
  58.  *   The CSS background color applied to the base of the volume bar, on top of
  59.  *   which the volume level is shown.
  60.  * @property {string} level
  61.  *   The CSS background color applied to the portion of the volume bar showing
  62.  *   the volume level.
  63.  * @exportDoc
  64.  */
  65. shaka.extern.UIVolumeBarColors;
  67. /**
  68.  * @description
  69.  * The UI's configuration options.
  70.  *
  71.  * @typedef {{
  72.  *   controlPanelElements: !Array.<string>,
  73.  *   overflowMenuButtons: !Array.<string>,
  74.  *   addSeekBar: boolean,
  75.  *   addBigPlayButton: boolean,
  76.  *   castReceiverAppId: string,
  77.  *   clearBufferOnQualityChange: boolean,
  78.  *   showUnbufferedStart: boolean,
  79.  *   seekBarColors: shaka.extern.UISeekBarColors,
  80.  *   volumeBarColors: shaka.extern.UIVolumeBarColors,
  81.  *   trackLabelFormat: shaka.ui.Overlay.TrackLabelFormat,
  82.  *   fadeDelay: number,
  83.  *   doubleClickForFullscreen: boolean,
  84.  *   enableKeyboardPlaybackControls: boolean,
  85.  *   enableFullscreenOnRotation: boolean
  86.  * }}
  87.  *
  88.  * @property {!Array.<string>} controlPanelElements
  89.  *   The ordered list of control panel elements of the UI.
  90.  * @property {!Array.<string>} overflowMenuButtons
  91.  *   The ordered list of the overflow menu buttons.
  92.  * @property {boolean} addSeekBar
  93.  *   Whether or not a seek bar should be part of the UI.
  94.  * @property {boolean} addBigPlayButton
  95.  *   Whether or not a big play button in the center of the video
  96.  *   should be part of the UI.
  97.  * @property {string} castReceiverAppId
  98.  *   Receiver app id to use for the Chromecast support.
  99.  * @property {boolean} clearBufferOnQualityChange
  100.  *   Only applicable if the resolution selection is part of the UI.
  101.  *   Whether buffer should be cleared when changing resolution
  102.  *   via UI. Clearing buffer would result in immidiate change of quality,
  103.  *   but playback may flicker/stall for a sec as the content in new
  104.  *   resolution is being buffered. Not clearing the buffer will mean
  105.  *   we play the content in the previously selected resolution that we
  106.  *   already have buffered before switching to the new resolution.
  107.  * @property {boolean} showUnbufferedStart
  108.  *   If true, color any unbuffered region at the start of the seek bar as
  109.  *   unbuffered (using the "base" color).  If false, color any unbuffered region
  110.  *   at the start of the seek bar as played (using the "played" color).
  111.  *   <br>
  112.  *   A value of false matches the default behavior of Chrome's native controls
  113.  *   and Shaka Player v3.0+.
  114.  *   <br>
  115.  *   A value of true matches the default behavior of Shaka Player v2.5.
  116.  *   <br>
  117.  *   Defaults to true in v2.5.  Will default to false in v3.0+.
  118.  * @property {shaka.extern.UISeekBarColors} seekBarColors
  119.  *   The CSS colors applied to the seek bar.  This allows you to override the
  120.  *   colors used in the linear gradient constructed in JavaScript, since you
  121.  *   cannot easily do this in pure CSS.
  122.  * @property {shaka.extern.UIVolumeBarColors} volumeBarColors
  123.  *   The CSS colors applied to the volume bar.  This allows you to override the
  124.  *   colors used in the linear gradient constructed in JavaScript, since you
  125.  *   cannot do this in pure CSS.
  126.  * @property {shaka.ui.Overlay.TrackLabelFormat} trackLabelFormat
  127.  *   An enum that determines what is shown in the labels for text track and
  128.  *   audio variant selection.
  129.  *   LANGUAGE means that only the language of the item is shown.
  130.  *   ROLE means that only the role of the item is shown.
  131.  *   LANGUAGE_ROLE means both are shown, or just language if there is no role.
  132.  *   Defaults to LANGUAGE.
  133.  * @property {number} fadeDelay
  134.  *   The delay (in seconds) before fading out the controls once the user stops
  135.  *   interacting with them.  We recommend setting this to 3 on your cast
  136.  *   receiver UI.
  137.  *   Defaults to 0.
  138.  * @property {boolean} doubleClickForFullscreen
  139.  *   Whether or not double-clicking on the UI should cause it to enter
  140.  *   fullscreen.
  141.  *   Defaults to true.
  142.  * @property {boolean} enableKeyboardPlaybackControls
  143.  *   Whether or not playback controls via keyboard is enabled, such as seek
  144.  *   forward, seek backward, jump to the beginning/end of the video.
  145.  *   Defaults to true.
  146.  * @property {boolean} enableFullscreenOnRotation
  147.  *   Whether or not to enter/exit fullscreen mode when the screen is rotated.
  148.  *   Defaults to true.
  149.  * @exportDoc
  150.  */
  151. shaka.extern.UIConfiguration;
  154. /**
  155.  * Interface for UI elements.
  156.  *
  157.  * @extends {shaka.util.IDestroyable}
  158.  * @interface
  159.  * @exportDoc
  160.  */
  161. shaka.extern.IUIElement = class {
  162.   /**
  163.    * @param {!HTMLElement} parent
  164.    * @param {!shaka.ui.Controls} controls
  165.    */
  166.   constructor(parent, controls) {
  167.     /**
  168.      * @protected {HTMLElement}
  169.      * @exportDoc
  170.      */
  171.     this.parent;
  173.     /**
  174.      * @protected {shaka.ui.Controls}
  175.      * @exportDoc
  176.      */
  177.     this.controls;
  179.     /**
  180.      * @protected {shaka.util.EventManager}
  181.      * @exportDoc
  182.      */
  183.     this.eventManager;
  185.     /**
  186.      * @protected {shaka.ui.Localization}
  187.      * @exportDoc
  188.      */
  189.     this.localization;
  191.     /**
  192.      * @protected {shaka.Player}
  193.      * @exportDoc
  194.      */
  195.     this.player;
  197.     /**
  198.      * @protected {HTMLMediaElement}
  199.      * @exportDoc
  200.      */
  201.     this.video;
  202.   }
  204.   /**
  205.    * @override
  206.    */
  207.   destroy() {}
  208. };
  211. /**
  212.  * A factory for creating a UI element.
  213.  *
  214.  * @interface
  215.  * @exportDoc
  216.  */
  217. shaka.extern.IUIElement.Factory = class {
  218.   /**
  219.    * @param {!HTMLElement} rootElement
  220.    * @param {!shaka.ui.Controls} controls
  221.    * @return {!shaka.extern.IUIElement}
  222.    */
  223.   create(rootElement, controls) {}
  224. };
  227. /**
  228.  * Interface for UI range elements.  UI range elements should inherit from the
  229.  * concrete base class shaka.ui.RangeElement.  The members defined in this
  230.  * extern's constructor are all available from the base class, and are defined
  231.  * here to keep the compiler from renaming them.
  232.  *
  233.  * @extends {shaka.extern.IUIElement}
  234.  * @interface
  235.  * @exportDoc
  236.  */
  237. shaka.extern.IUIRangeElement = class {
  238.   /**
  239.    * @param {!HTMLElement} parent
  240.    * @param {!shaka.ui.Controls} controls
  241.    * @param {!Array.<string>} containerClassNames
  242.    * @param {!Array.<string>} barClassNames
  243.    */
  244.   constructor(parent, controls, containerClassNames, barClassNames) {
  245.     /**
  246.      * @protected {!HTMLElement}
  247.      * @exportDoc
  248.      */
  249.     this.container;
  251.     /**
  252.      * @protected {!HTMLInputElement}
  253.      * @exportDoc
  254.      */
  255.     this.bar;
  256.   }
  258.   /**
  259.    * @param {number} min
  260.    * @param {number} max
  261.    */
  262.   setRange(min, max) {}
  264.   /**
  265.    * Called when user interaction begins.
  266.    * To be overridden by subclasses.
  267.    */
  268.   onChangeStart() {}
  270.   /**
  271.    * Called when a new value is set by user interaction.
  272.    * To be overridden by subclasses.
  273.    */
  274.   onChange() {}
  276.   /**
  277.    * Called when user interaction ends.
  278.    * To be overridden by subclasses.
  279.    */
  280.   onChangeEnd() {}
  282.   /** @return {number} */
  283.   getValue() {}
  285.   /** @param {number} value */
  286.   setValue(value) {}
  288.   /** @param {number} value */
  289.   changeTo(value) {}
  290. };
  292. /**
  293.  * Interface for UI settings menus.  UI settings menus should inherit from the
  294.  * concrete base class shaka.ui.SettingsMenu.  The members defined in this
  295.  * extern's constructor are all available from the base class, and are defined
  296.  * here to keep the compiler from renaming them.
  297.  *
  298.  * @extends {shaka.extern.IUIElement}
  299.  * @interface
  300.  * @exportDoc
  301.  */
  302. shaka.extern.IUISettingsMenu = class {
  303.   /**
  304.    * @param {!HTMLElement} parent
  305.    * @param {!shaka.ui.Controls} controls
  306.    * @param {string} iconText
  307.    */
  308.   constructor(parent, controls, iconText) {
  309.     /**
  310.      * @protected {!HTMLButtonElement}
  311.      * @exportDoc
  312.      */
  313.     this.button;
  315.     /**
  316.      * @protected {!HTMLElement}
  317.      * @exportDoc
  318.      */
  319.     this.icon;
  321.     /**
  322.      * @protected {!HTMLElement}
  323.      * @exportDoc
  324.      */
  325.     this.nameSpan;
  327.     /**
  328.      * @protected {!HTMLElement}
  329.      * @exportDoc
  330.      */
  331.     this.currentSelection;
  333.     /**
  334.      * @protected {!HTMLElement}
  335.      * @exportDoc
  336.      */
  337.     this.menu;
  339.     /**
  340.      * @protected {!HTMLButtonElement}
  341.      * @exportDoc
  342.      */
  343.     this.backButton;
  345.     /**
  346.      * @protected {!HTMLElement}
  347.      * @exportDoc
  348.      */
  349.     this.backSpan;
  350.   }
  351. };