Source: lib/util/event_manager.js

  1. /*! @license
  2.  * Shaka Player
  3.  * Copyright 2016 Google LLC
  4.  * SPDX-License-Identifier: Apache-2.0
  5.  */
  7. goog.provide('shaka.util.EventManager');
  9. goog.require('goog.asserts');
  10. goog.require('shaka.util.IReleasable');
  11. goog.require('shaka.util.MultiMap');
  14. /**
  15.  * @summary
  16.  * An EventManager maintains a collection of "event
  17.  * bindings" between event targets and event listeners.
  18.  *
  19.  * @implements {shaka.util.IReleasable}
  20.  * @export
  21.  */
  22. shaka.util.EventManager = class {
  23.   constructor() {
  24.     /**
  25.      * Maps an event type to an array of event bindings.
  26.      * @private {shaka.util.MultiMap<!shaka.util.EventManager.Binding_>}
  27.      */
  28.     this.bindingMap_ = new shaka.util.MultiMap();
  29.   }
  32.   /**
  33.    * Detaches all event listeners.
  34.    * @override
  35.    * @export
  36.    */
  37.   release() {
  38.     this.removeAll();
  39.     this.bindingMap_ = null;
  40.   }
  43.   /**
  44.    * Attaches an event listener to an event target.
  45.    * @param {EventTarget} target The event target.
  46.    * @param {string} type The event type.
  47.    * @param {shaka.util.EventManager.ListenerType} listener The event listener.
  48.    * @param {(boolean|!AddEventListenerOptions)=} options An object that
  49.    *    specifies characteristics about the event listener.
  50.    *    The passive option, if true, indicates that this function will never
  51.    *    call preventDefault(), which improves scrolling performance.
  52.    * @export
  53.    */
  54.   listen(target, type, listener, options) {
  55.     if (!this.bindingMap_) {
  56.       return;
  57.     }
  59.     const binding =
  60.         new shaka.util.EventManager.Binding_(target, type, listener, options);
  61.     this.bindingMap_.push(type, binding);
  62.   }
  65.   /**
  66.    * Attaches an event listener to an event target.  The listener will be
  67.    * removed when the first instance of the event is fired.
  68.    * @param {EventTarget} target The event target.
  69.    * @param {string} type The event type.
  70.    * @param {shaka.util.EventManager.ListenerType} listener The event listener.
  71.    * @param {(boolean|!AddEventListenerOptions)=} options An object that
  72.    *    specifies characteristics about the event listener.
  73.    *    The passive option, if true, indicates that this function will never
  74.    *    call preventDefault(), which improves scrolling performance.
  75.    * @export
  76.    */
  77.   listenOnce(target, type, listener, options) {
  78.     // Install a shim listener that will stop listening after the first event.
  79.     const shim = (event) => {
  80.       // Stop listening to this event.
  81.       this.unlisten(target, type, shim);
  82.       // Call the original listener.
  83.       listener(event);
  84.     };
  85.     this.listen(target, type, shim, options);
  86.   }
  89.   /**
  90.    * Detaches an event listener from an event target.
  91.    * @param {EventTarget} target The event target.
  92.    * @param {string} type The event type.
  93.    * @param {shaka.util.EventManager.ListenerType=} listener The event listener.
  94.    * @export
  95.    */
  96.   unlisten(target, type, listener) {
  97.     if (!this.bindingMap_) {
  98.       return;
  99.     }
  101.     const list = this.bindingMap_.get(type) || [];
  103.     for (const binding of list) {
  104.       if (binding.target == target) {
  105.         if (listener == binding.listener || !listener) {
  106.           binding.unlisten();
  107.           this.bindingMap_.remove(type, binding);
  108.         }
  109.       }
  110.     }
  111.   }
  114.   /**
  115.    * Detaches all event listeners from all targets.
  116.    * @export
  117.    */
  118.   removeAll() {
  119.     if (!this.bindingMap_) {
  120.       return;
  121.     }
  123.     const list = this.bindingMap_.getAll();
  125.     for (const binding of list) {
  126.       binding.unlisten();
  127.     }
  129.     this.bindingMap_.clear();
  130.   }
  131. };
  134. /**
  135.  * @typedef {function(!Event)}
  136.  * @export
  137.  */
  138. shaka.util.EventManager.ListenerType;
  141. /**
  142.  * Creates a new Binding_ and attaches the event listener to the event target.
  143.  *
  144.  * @private
  145.  */
  146. shaka.util.EventManager.Binding_ = class {
  147.   /**
  148.    * @param {EventTarget} target The event target.
  149.    * @param {string} type The event type.
  150.    * @param {shaka.util.EventManager.ListenerType} listener The event listener.
  151.    * @param {(boolean|!AddEventListenerOptions)=} options An object that
  152.    *    specifies characteristics about the event listener.
  153.    *    The passive option, if true, indicates that this function will never
  154.    *    call preventDefault(), which improves scrolling performance.
  155.    */
  156.   constructor(target, type, listener, options) {
  157.     /** @type {EventTarget} */
  158.     this.target = target;
  160.     /** @type {string} */
  161.     this.type = type;
  163.     /** @type {?shaka.util.EventManager.ListenerType} */
  164.     this.listener = listener;
  166.     /** @type {(boolean|!AddEventListenerOptions)} */
  167.     this.options =
  168.         shaka.util.EventManager.Binding_.convertOptions_(target, options);
  170.     this.target.addEventListener(type, listener, this.options);
  171.   }
  174.   /**
  175.    * Detaches the event listener from the event target. This does nothing if
  176.    * the event listener is already detached.
  177.    */
  178.   unlisten() {
  179.     goog.asserts.assert(this.target, 'Missing target');
  180.     this.target.removeEventListener(this.type, this.listener, this.options);
  182.     this.target = null;
  183.     this.listener = null;
  184.     this.options = false;
  185.   }
  187.   /**
  188.    * Converts the provided options value into a value accepted by the browser.
  189.    * Some browsers (e.g. Tizen) don't support passing options as an
  190.    * object.  So this detects this case and converts it.
  191.    *
  192.    * @param {EventTarget} target
  193.    * @param {(boolean|!AddEventListenerOptions)=} value
  194.    * @return {(boolean|!AddEventListenerOptions)}
  195.    * @private
  196.    */
  197.   static convertOptions_(target, value) {
  198.     if (value == undefined) {
  199.       return false;
  200.     } else if (typeof value == 'boolean') {
  201.       return value;
  202.     } else {
  203.       // Ignore the 'passive' option since it is just an optimization and
  204.       // doesn't affect behavior.  Assert there aren't any other settings to
  205.       // ensure we don't have different behavior on different browsers by
  206.       // ignoring an important option.
  207.       const ignored = new Set(['passive', 'capture']);
  208.       const keys = Object.keys(value).filter((k) => !ignored.has(k));
  209.       goog.asserts.assert(
  210.           keys.length == 0,
  211.           'Unsupported flag(s) to addEventListener: ' + keys.join(','));
  213.       const supports =
  214.           shaka.util.EventManager.Binding_.doesSupportObject_(target);
  215.       if (supports) {
  216.         return value;
  217.       } else {
  218.         return value['capture'] || false;
  219.       }
  220.     }
  221.   }
  223.   /**
  224.    * Checks whether the browser supports passing objects as the third argument
  225.    * to addEventListener.  This caches the result value in a static field to
  226.    * avoid a bunch of checks.
  227.    *
  228.    * @param {EventTarget} target
  229.    * @return {boolean}
  230.    * @private
  231.    */
  232.   static doesSupportObject_(target) {
  233.     // https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener#Safely_detecting_option_support
  234.     let supports = shaka.util.EventManager.Binding_.supportsObject_;
  235.     if (supports == undefined) {
  236.       supports = false;
  237.       try {
  238.         const options = {};
  239.         // This defines a getter that will set this variable if called.  So if
  240.         // the browser gets this property, it supports using an object.  If the
  241.         // browser doesn't get these fields, it won't support objects.
  242.         const prop = {
  243.           get: () => {
  244.             supports = true;
  245.             return false;
  246.           },
  247.         };
  248.         Object.defineProperty(options, 'passive', prop);
  249.         Object.defineProperty(options, 'capture', prop);
  251.         const call = () => {};
  252.         target.addEventListener('test', call, options);
  253.         target.removeEventListener('test', call, options);
  254.       } catch (e) {
  255.         supports = false;
  256.       }
  257.       shaka.util.EventManager.Binding_.supportsObject_ = supports;
  258.     }
  259.     return supports || false;  // "false" fallback needed for compiler.
  260.   }
  261. };
  263. /** @private {(boolean|undefined)} */
  264. shaka.util.EventManager.Binding_.supportsObject_ = undefined;