remote/shared/listeners/NavigationListener.sys.mjs

   1 /* This Source Code Form is subject to the terms of the Mozilla Public
   2  * License, v. 2.0. If a copy of the MPL was not distributed with this
   3  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   4
   5 const lazy = {};
   6
   7 ChromeUtils.defineESModuleGetters(lazy, {
   8   EventEmitter: "resource://gre/modules/EventEmitter.sys.mjs",
   9 });
  10
  11 /**
  12  * The NavigationListener simply wraps a NavigationManager instance and exposes
  13  * it with a convenient listener API, more consistent with the rest of the
  14  * remote codebase. NavigationManager is a singleton per session so it can't
  15  * be instanciated for each and every consumer.
  16  *
  17  * Example:
  18  * ```
  19  * const onNavigationStarted = (eventName, data = {}) => {
  20  *   const { level, message, stacktrace, timestamp } = data;
  21  *   ...
  22  * };
  23  *
  24  * const listener = new NavigationListener(this.messageHandler.navigationManager);
  25  * listener.on("navigation-started", onNavigationStarted);
  26  * listener.startListening();
  27  * ...
  28  * listener.stopListening();
  29  * ```
  30  *
  31  * @fires message
  32  *     The NavigationListener emits "fragment-navigated", "navigation-started",
  33  *     "navigation-stopped", and "same-document-changed" events,
  34  *     with the following object as payload:
  35  *       - {string} navigationId - The UUID for the navigation.
  36  *       - {string} navigableId - The UUID for the navigable.
  37  *       - {string} url - The target url for the navigation.
  38  */
  39 export class NavigationListener {
  40   #listening;
  41   #navigationManager;
  42
  43   /**
  44    * Create a new NavigationListener instance.
  45    *
  46    * @param {NavigationManager} navigationManager
  47    *     The underlying NavigationManager for this listener.
  48    */
  49   constructor(navigationManager) {
  50     lazy.EventEmitter.decorate(this);
  51
  52     this.#listening = false;
  53     this.#navigationManager = navigationManager;
  54   }
  55
  56   get listening() {
  57     return this.#listening;
  58   }
  59
  60   destroy() {
  61     this.stopListening();
  62   }
  63
  64   startListening() {
  65     if (this.#listening) {
  66       return;
  67     }
  68
  69     this.#navigationManager.on("fragment-navigated", this.#forwardEvent);
  70     this.#navigationManager.on("navigation-started", this.#forwardEvent);
  71     this.#navigationManager.on("navigation-stopped", this.#forwardEvent);
  72     this.#navigationManager.on("same-document-changed", this.#forwardEvent);
  73
  74     this.#listening = true;
  75   }
  76
  77   stopListening() {
  78     if (!this.#listening) {
  79       return;
  80     }
  81
  82     this.#navigationManager.off("fragment-navigated", this.#forwardEvent);
  83     this.#navigationManager.off("navigation-started", this.#forwardEvent);
  84     this.#navigationManager.off("navigation-stopped", this.#forwardEvent);
  85     this.#navigationManager.off("same-document-changed", this.#forwardEvent);
  86
  87     this.#listening = false;
  88   }
  89
  90   #forwardEvent = (name, data) => {
  91     this.emit(name, data);
  92   };
  93 }