[api-minor] Deprecate getGlobalEventBus and update the "viewer components" examples accordingly

To avoid outright breaking third-party usages of the "viewer components" the `getGlobalEventBus` functionality is left intact, but a deprecation message is printed if the function is invoked.

The various examples are updated to *explicitly* initialize an `EventBus` instance, and provide that when initializing the relevant viewer components.

Author: Snuffleupagus

examples/acroforms/acroforms.js

@@ -23,6 +23,8 @@ var DEFAULT_SCALE = 1.0;
 
 var container = document.getElementById("pageContainer");
 
+var eventBus = new pdfjsViewer.EventBus();
+
 // Fetch the PDF document from the URL using promises.
 var loadingTask = pdfjsLib.getDocument(DEFAULT_URL);
 loadingTask.promise.then(function(doc) {
@@ -39,6 +41,7 @@ loadingTask.promise.then(function(doc) {
             id: pageNum,
             scale: DEFAULT_SCALE,
             defaultViewport: pdfPage.getViewport({ scale: DEFAULT_SCALE }),
+            eventBus: eventBus,
             annotationLayerFactory: new pdfjsViewer.DefaultAnnotationLayerFactory(),
             renderInteractiveForms: true,
           });

examples/components/pageviewer.js

@@ -35,6 +35,8 @@ var SCALE = 1.0;
 
 var container = document.getElementById("pageContainer");
 
+var eventBus = new pdfjsViewer.EventBus();
+
 // Loading document.
 var loadingTask = pdfjsLib.getDocument({
   url: DEFAULT_URL,
@@ -50,6 +52,7 @@ loadingTask.promise.then(function(pdfDocument) {
       id: PAGE_TO_VIEW,
       scale: SCALE,
       defaultViewport: pdfPage.getViewport({ scale: SCALE }),
+      eventBus: eventBus,
       // We can enable text/annotations layers, if needed
       textLayerFactory: new pdfjsViewer.DefaultTextLayerFactory(),
       annotationLayerFactory: new pdfjsViewer.DefaultAnnotationLayerFactory(),

examples/components/simpleviewer.js

@@ -34,22 +34,28 @@ var SEARCH_FOR = ""; // try 'Mozilla';
 
 var container = document.getElementById("viewerContainer");
 
+var eventBus = new pdfjsViewer.EventBus();
+
 // (Optionally) enable hyperlinks within PDF files.
-var pdfLinkService = new pdfjsViewer.PDFLinkService();
+var pdfLinkService = new pdfjsViewer.PDFLinkService({
+  eventBus: eventBus,
+});
 
 // (Optionally) enable find controller.
 var pdfFindController = new pdfjsViewer.PDFFindController({
+  eventBus: eventBus,
   linkService: pdfLinkService,
 });
 
 var pdfViewer = new pdfjsViewer.PDFViewer({
   container: container,
+  eventBus: eventBus,
   linkService: pdfLinkService,
   findController: pdfFindController,
 });
 pdfLinkService.setViewer(pdfViewer);
 
-document.addEventListener("pagesinit", function() {
+eventBus.on("pagesinit", function() {
   // We can use pdfViewer now, e.g. let's change default scale.
   pdfViewer.currentScaleValue = "page-width";
 

examples/components/singlepageviewer.js

@@ -34,22 +34,28 @@ var SEARCH_FOR = ""; // try 'Mozilla';
 
 var container = document.getElementById("viewerContainer");
 
+var eventBus = new pdfjsViewer.EventBus();
+
 // (Optionally) enable hyperlinks within PDF files.
-var pdfLinkService = new pdfjsViewer.PDFLinkService();
+var pdfLinkService = new pdfjsViewer.PDFLinkService({
+  eventBus: eventBus,
+});
 
 // (Optionally) enable find controller.
 var pdfFindController = new pdfjsViewer.PDFFindController({
+  eventBus: eventBus,
   linkService: pdfLinkService,
 });
 
 var pdfSinglePageViewer = new pdfjsViewer.PDFSinglePageViewer({
   container: container,
+  eventBus: eventBus,
   linkService: pdfLinkService,
   findController: pdfFindController,
 });
 pdfLinkService.setViewer(pdfSinglePageViewer);
 
-document.addEventListener("pagesinit", function() {
+eventBus.on("pagesinit", function() {
   // We can use pdfSinglePageViewer now, e.g. let's change default scale.
   pdfSinglePageViewer.currentScaleValue = "page-width";
 

examples/mobile-viewer/viewer.js

@@ -40,6 +40,7 @@ var PDFViewerApplication = {
   pdfViewer: null,
   pdfHistory: null,
   pdfLinkService: null,
+  eventBus: null,
 
   /**
    * Opens PDF document specified by URL.
@@ -340,14 +341,19 @@ var PDFViewerApplication = {
   },
 
   initUI: function pdfViewInitUI() {
-    var linkService = new pdfjsViewer.PDFLinkService();
+    var eventBus = new pdfjsViewer.EventBus();
+
+    var linkService = new pdfjsViewer.PDFLinkService({
+      eventBus: eventBus,
+    });
     this.pdfLinkService = linkService;
 
     this.l10n = pdfjsViewer.NullL10n;
 
     var container = document.getElementById("viewerContainer");
     var pdfViewer = new pdfjsViewer.PDFViewer({
       container: container,
+      eventBus: eventBus,
       linkService: linkService,
       l10n: this.l10n,
       useOnlyCssZoom: USE_ONLY_CSS_ZOOM,
@@ -357,6 +363,7 @@ var PDFViewerApplication = {
     linkService.setViewer(pdfViewer);
 
     this.pdfHistory = new pdfjsViewer.PDFHistory({
+      eventBus: eventBus,
       linkService: linkService,
     });
     linkService.setHistory(this.pdfHistory);
@@ -394,15 +401,15 @@ var PDFViewerApplication = {
         }
       });
 
-    document.addEventListener("pagesinit", function() {
+    eventBus.on("pagesinit", function() {
       // We can use pdfViewer now, e.g. let's change default scale.
       pdfViewer.currentScaleValue = DEFAULT_SCALE_VALUE;
     });
 
-    document.addEventListener(
+    eventBus.on(
       "pagechanging",
       function(evt) {
-        var page = evt.detail.pageNumber;
+        var page = evt.pageNumber;
         var numPages = PDFViewerApplication.pagesCount;
 
         document.getElementById("pageNumber").value = page;

examples/svgviewer/viewer.js

@@ -33,18 +33,23 @@ var DEFAULT_URL = "../../web/compressed.tracemonkey-pldi-09.pdf";
 
 var container = document.getElementById("viewerContainer");
 
+var eventBus = new pdfjsViewer.EventBus();
+
 // (Optionally) enable hyperlinks within PDF files.
-var pdfLinkService = new pdfjsViewer.PDFLinkService();
+var pdfLinkService = new pdfjsViewer.PDFLinkService({
+  eventBus: eventBus,
+});
 
 var pdfViewer = new pdfjsViewer.PDFViewer({
   container: container,
+  eventBus: eventBus,
   linkService: pdfLinkService,
   renderer: "svg",
   textLayerMode: 0,
 });
 pdfLinkService.setViewer(pdfViewer);
 
-document.addEventListener("pagesinit", function() {
+eventBus.on("pagesinit", function() {
   // We can use pdfViewer now, e.g. let's change default scale.
   pdfViewer.currentScaleValue = "page-width";
 });

web/app.js

@@ -18,7 +18,7 @@ import {
   animationStarted,
   AutoPrintRegExp,
   DEFAULT_SCALE_VALUE,
-  getGlobalEventBus,
+  EventBus,
   getPDFFileNameFromURL,
   isValidRotation,
   isValidScrollMode,
@@ -343,7 +343,7 @@ const PDFViewerApplication = {
 
     const eventBus =
       appConfig.eventBus ||
-      getGlobalEventBus(AppOptions.get("eventBusDispatchToDOM"));
+      new EventBus({ dispatchToDOM: AppOptions.get("eventBusDispatchToDOM") });
     this.eventBus = eventBus;
 
     const pdfRenderingQueue = new PDFRenderingQueue();

web/base_viewer.js

@@ -1094,11 +1094,12 @@ class BaseViewer {
     textLayerDiv,
     pageIndex,
     viewport,
-    enhanceTextSelection = false
+    enhanceTextSelection = false,
+    eventBus
   ) {
     return new TextLayerBuilder({
       textLayerDiv,
-      eventBus: this.eventBus,
+      eventBus,
       pageIndex,
       viewport,
       findController: this.isInPresentationMode ? null : this.findController,

web/interfaces.js

@@ -146,13 +146,15 @@ class IPDFTextLayerFactory {
    * @param {number} pageIndex
    * @param {PageViewport} viewport
    * @param {boolean} enhanceTextSelection
+   * @param {EventBus} eventBus
    * @returns {TextLayerBuilder}
    */
   createTextLayerBuilder(
     textLayerDiv,
     pageIndex,
     viewport,
-    enhanceTextSelection = false
+    enhanceTextSelection = false,
+    eventBus
   ) {}
 }
 

web/pdf_find_bar.js

@@ -25,7 +25,7 @@ const MATCHES_COUNT_LIMIT = 1000;
  * is done by PDFFindController.
  */
 class PDFFindBar {
-  constructor(options, eventBus = getGlobalEventBus(), l10n = NullL10n) {
+  constructor(options, eventBus, l10n = NullL10n) {
     this.opened = false;
 
     this.bar = options.bar || null;
@@ -38,7 +38,7 @@ class PDFFindBar {
     this.findResultsCount = options.findResultsCount || null;
     this.findPreviousButton = options.findPreviousButton || null;
     this.findNextButton = options.findNextButton || null;
-    this.eventBus = eventBus;
+    this.eventBus = eventBus || getGlobalEventBus();
     this.l10n = l10n;
 
     // Add event listeners to the DOM elements.

web/pdf_find_controller.js

@@ -67,9 +67,9 @@ class PDFFindController {
   /**
    * @param {PDFFindControllerOptions} options
    */
-  constructor({ linkService, eventBus = getGlobalEventBus() }) {
+  constructor({ linkService, eventBus }) {
     this._linkService = linkService;
-    this._eventBus = eventBus;
+    this._eventBus = eventBus || getGlobalEventBus();
 
     this._reset();
     eventBus.on("findbarclose", this._onFindBarClose.bind(this));

web/pdf_page_view.js

@@ -444,7 +444,8 @@ class PDFPageView {
         textLayerDiv,
         this.id - 1,
         this.viewport,
-        this.textLayerMode === TextLayerMode.ENABLE_ENHANCE
+        this.textLayerMode === TextLayerMode.ENABLE_ENHANCE,
+        this.eventBus
       );
     }
     this.textLayer = textLayer;

web/pdf_viewer.component.js

@@ -21,12 +21,7 @@ import {
   DefaultTextLayerFactory,
   TextLayerBuilder,
 } from "./text_layer_builder.js";
-import {
-  EventBus,
-  getGlobalEventBus,
-  NullL10n,
-  ProgressBar,
-} from "./ui_utils.js";
+import { EventBus, NullL10n, ProgressBar } from "./ui_utils.js";
 import { PDFLinkService, SimpleLinkService } from "./pdf_link_service.js";
 import { DownloadManager } from "./download_manager.js";
 import { GenericL10n } from "./genericl10n.js";
@@ -41,9 +36,6 @@ const pdfjsVersion = PDFJSDev.eval("BUNDLE_VERSION");
 // eslint-disable-next-line no-unused-vars
 const pdfjsBuild = PDFJSDev.eval("BUNDLE_BUILD");
 
-// For backwards compatibility, ensure that events are re-dispatched to the DOM.
-getGlobalEventBus(/* dispatchToDOM = */ true);
-
 export {
   PDFViewer,
   PDFSinglePageViewer,

web/text_layer_builder.js

@@ -444,19 +444,22 @@ class DefaultTextLayerFactory {
    * @param {number} pageIndex
    * @param {PageViewport} viewport
    * @param {boolean} enhanceTextSelection
+   * @param {EventBus} eventBus
    * @returns {TextLayerBuilder}
    */
   createTextLayerBuilder(
     textLayerDiv,
     pageIndex,
     viewport,
-    enhanceTextSelection = false
+    enhanceTextSelection = false,
+    eventBus
   ) {
     return new TextLayerBuilder({
       textLayerDiv,
       pageIndex,
       viewport,
       enhanceTextSelection,
+      eventBus,
     });
   }
 }

web/ui_utils.js

@@ -757,9 +757,8 @@ const animationStarted = new Promise(function(resolve) {
 });
 
 /**
- * Simple event bus for an application. Listeners are attached using the
- * `on` and `off` methods. To raise an event, the `dispatch` method shall be
- * used.
+ * Simple event bus for an application. Listeners are attached using the `on`
+ * and `off` methods. To raise an event, the `dispatch` method shall be used.
  */
 class EventBus {
   constructor({ dispatchToDOM = false } = {}) {
@@ -832,6 +831,9 @@ class EventBus {
 
 let globalEventBus = null;
 function getGlobalEventBus(dispatchToDOM = false) {
+  console.error(
+    "getGlobalEventBus is deprecated, use a manually created EventBus instance instead."
+  );
   if (!globalEventBus) {
     globalEventBus = new EventBus({ dispatchToDOM });
   }

web/viewer.js

@@ -60,7 +60,7 @@ function getViewerConfiguration() {
     appContainer: document.body,
     mainContainer: document.getElementById("viewerContainer"),
     viewerContainer: document.getElementById("viewer"),
-    eventBus: null, // Using global event bus with (optional) DOM events.
+    eventBus: null,
     toolbar: {
       container: document.getElementById("toolbarViewer"),
       numPages: document.getElementById("numPages"),