Manage events

Extensive development effort required

This guide outlines a functionality that requires extensive development effort. Use the readily available features of the PDF Viewer SDK instead of implementing a viewer from scratch. Only use this guide if you want to implement your PDF viewer and customize it as much as possible. To test and implement the primary functionality of this SDK, review Getting started with the PDF Viewer SDK.

Listen to and programmatically dispatch built-in and custom events with the PDF Web SDK.

The PDF Viewer SDK EventEmitter class provides a powerful and typesafe mechanism for managing and dispatching events by classes which are designed to emit events. By default, there are multiple classes which support events, such as Pdf.Document, Pdf.Page, UI.DocumentView. You can also create custom classes extending EventEmitter. The EventEmitter template type describes which events are supported by a concrete class and specifies the expected structure of the provided callback functions.

This guide explains the following:

1. Generic EventEmitter concept
2. Listening to built-in events
3. Full example

---

Before you begin

The EventEmitter class can be used noth within or outside of the context of the PDF Viewer SDK. However, if you want to listen to events emitted by or dispatch events to the PDF Viewer SDK, first learn how to work with the PDF Web SDK, for example how to view a document or read document information.

Generic EventEmitter concept

The EventEmitter class makes use of event maps - a type safe approach to define the name and the parameters of supported events.

For example, if you want to define an event named 'sampleEventOccurred' that takes one parameter of type number, you can describe this with an interface like this:

interface SampleEventMap {
  sampleEventOccurred: (sampleParam: number) => void;
}

When now creating an EventEmitter using this event map, the EventEmitter template type will make the typescript compiler assure, that only suitable event names and handlers are accepted on addEventListener, dispatchEvent, and removeEventListener.

import { Core } from '@pdftools/pdf-web-sdk';

// extend EventEmitter using the event map defined above
class SampleEventEmitter extends Core.EventEmitter<SampleEventMap> {}

// Create an instance of class which extends EventEmitter
const eventEmitter = new SampleEventEmitter();

Now event function is typesafe, for example:

const goodListener = (sampleParam: number) => {
  console.log('Sample event occurred', sampleParam);
};
const badListener = (sampleParam: string) => {
  console.log('Sample event occurred', sampleParam);
};

// add event listener
// OK
eventEmitter.addEventListener('sampleEventOccurred', goodListener);
// NOT OK: unsupported event name
eventEmitter.addEventListener('sampleEvent', goodListener);
// NOT OK: wrong listener parameters
eventEmitter.addEventListener('sampleEventOccurred', badListener);

// dispatch event
// OK
eventEmitter.dispatchEvent('sampleEventOccurred', [123]);
// NOT OK: unsupported event name
eventEmitter.dispatchEvent('sampleEvent', [123]);
// NOT OK: wrong listener parameters
eventEmitter.dispatchEvent('sampleEventOccurred', ["foo"]);

// remove event listener
// OK
eventEmitter.removeEventListener('sampleEventOccurred', goodListener);
// NOT OK: unsupported event name
eventEmitter.removeEventListener('sampleEvent', goodListener);
// NOT OK: wrong listener parameters
eventEmitter.removeEventListener('sampleEventOccurred', badListener);

Listening to built-in events

Listening to built-in events works exactly as described in the generic concept above. For each class emitting events you find the definition of the supported events as an event map in the API references, for example:

• Controller ➡️ ControllerEventMap
• Document ➡️ DocumentEventMap
• DocumentView ➡️ DocumentViewEventMap
• Page ➡️ PageEventMap

Full example

This full example demonstrates how to react to changes in the DocumentView and log them to the console.

import { pdfToolsWebSdk, Pdf, UI } from '@pdftools/pdf-web-sdk';

async function initialize() {
  await pdfToolsWebSdk.initialize({
    path: './pdftools-web-sdk/',
  });

  const container = document.querySelector('#pdftools-web-viewer-container');
  const documentView = new UI.DocumentView(container);

  const controller = new Pdf.Controller();
  const pdfDocument = await controller.openDocument({
    uri: '/pdf/WebViewer_Demo.pdf',
  });

  const zoomListener = (zoomLevel: number) => {
    const percent = number * 100;
    console.log(`zoom changed to ${percent}%`);
  };

  documentView.addEventListener('zoomChanged', zoomListener);
  documentView.initialize(pdfDocument);
}

initialize();