# ViewerUI

Viewer UI defines methods for creating and displaying user interface components, which can be called by PDFViewCtrl or UIExtension. With Viewer UI, we can customize various UI elementsm, such as context menus, alert dialogs, loading overlays, and more.

The interface declaration of Viewer UI can be found in the API Reference (opens new window). Within the SDK, there are two sets of Viewer UI available: TinyViewerUI (opens new window) for PDFViewCtrl and XViewerUI (opens new window) for UIExtension.

In actual applications, we can choose either of the two built-in Viewer UI based on whether we are using PDFViewCtrl or UIExtension.

# List of Methods defined in IViewer

createContextMenu(key, anchor, config): Creates a context menu component and registers a context event. This method can be overridden to customize the context menu. The parameters are explained below:
- key: any type, represents the owner of the context menu instance, which can be the name of StateHandler (opens new window) or an instance of AnnotComponent.
- anchor: HTMLElement, the HTML element used to respond to the context event.
- config: object, configuration options.
  - config.selector: string, the CSS selector for the element that triggers this menu. This element should be the anchor or its child element.
  - config.items: array, contains the configuration of default menu items. Refer to JQuery contextmenu plugin documentation (opens new window).
  - config.items[].nameI18nKey: string, i18n key for the menu item's localized text.
Return Value: IContextMenu|undefined (opens new window), the context menu component, including show/hide and destroy APIs. Returning undefined means the context menu for the specified target will not be shown.
alert(message): Displays an alert dialog with optional content and an OK button, and then returns a completed Promise after the dialog is closed.
- message: string, the message for the alert dialog, using the i18next.js translation format.
Return Value: Promise<void>
confirm(message): Displays a modal dialog with an optional message and two buttons (OK and Cancel), and then returns a Promise. The Promise will be resolved if the user clicks OK, and it will be rejected if the user clicks Cancel.
- message: string, the message for the confirmation dialog, using the i18next.js translation format.
Return Value: Promise<void>
prompt(defaultValue, message, title): Displays a dialog with optional messages, prompting the user to enter some text.
- defaultValue: string, the default value to be displayed in the text input box.
- message: string, the text to display to the user.
- title: string, the title of the prompt dialog.
Return Value: Promise<string>, returns a Promise that resolves with the user's input value when the dialog is closed.
promptPassword(defaultValue, message, title): Displays a dialog with optional messages, prompting the user to enter a password.
- defaultValue: string, the default password to be displayed in the password input box.
- message: string, the text to display to the user.
- title: string, the title of the prompt dialog.
Return Value: Promise<string>, returns a Promise that resolves with the user's input value when the dialog is closed.
loading(coverOn): Displays a loading overlay to indicate the loading state of a page or component.
- coverOn: HTMLElement, the target element to cover.
Return Value: Function, a function that can be called to close the loading overlay.
createTextSelectionTooltip(pageRender): Creates a tooltip component that is displayed when the user selects text.
- pageRender: PDFPageRender.
Return Value: IFloatingTooltip (opens new window).

# Usage

Typically, we may only need to override certain methods in the Viewer UI, such as overriding the alert dialog. In that case, we can achieve this by inheriting the built-in Viewer UI of the SDK:

class CustomViewerUI extends UIExtension.XViewerUI {
    alert(message) {
        // Here we can display our custom alert dialog. Let's simply print the content to the console.
        console.log('alert:', message);
        return Promise.resolve();
    }
}

new PDFUI({
 viewerOptions: {
     viewerUI: new CustomViewerUI()
 }
})

To implement a custom Viewer UI at the PDFViewCtrl level, the process is similar:

class CustomViewerUI extends PDFViewCtrl.viewerui.TinyViewerUI {
    alert(message) {
        // Here we can display our custom alert dialog. Let's simply print the content to the console.
        console.log('alert:', message);
        return Promise.resolve();
    }
}
new PDFViewer({
    viewerUI: new CustomViewerUI()
})

For more examples, you can refer to the content in these two documents:

← Customize StorageDriver Progress Bar Component →