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