Customize Shortcuts

Overview

In order to allow the application layer to customize shortcuts conveniently, Foxit PDF SDK for Web provides interfaces such as PDFViewer.onShortcutKey. This article will introduce how to use these interfaces and the relevant precautions.

Definition

To avoid confusion, we have defined the following terms in this document before starting:

1. key combination: A specific combination of keys, such as Ctrl+Z is a key combination, and Cmd+Z is another key combination.
2. Shortcut key: A combination of keys that triggers a specific function, such as the shortcut key for undo is Ctrl+Z or Cmd+Z.

The Built-in Key Combinations and Their Descriptions

Here, we list the built-in key combinations in Foxit PDF SDK for Web. Developers can refer to this table and customize the key combinations at the application level by replacing the built-in implementation.

Key Combination	Description
Esc	Close the dialog box, exit edit mode or exit the search panel.
Home	Jump to the first page.
End	Jump to the last page.
Delete	Delete the selected object. In edit mode: delete the selected text object; in non-edit mode: delete the selected annotation object.
PageUp	Move the current view upward when a vertical scroll bar is present.
PageDown	Move the current view downward when a vertical scroll bar is present.
UpArrow	Move the vertical scroll bar upward when it is present.
DownArrow	Move the vertical scroll bar downward when it is present.
LeftArrow	Move the horizontal scroll bar to the left when it is present.
RightArrow	Move the horizontal scroll bar to the right when it is present.
Enter	Confirm or continue.
Ctrl+Z	Undo. On Mac platform, it is Cmd+Z.
Ctrl+Y	Redo. On Mac platform, it is Cmd+Shift+Z.
Ctrl+MouseLeft	Select multiple objects, annotations, paths, text editing
Ctrl+F	Open search panel. On Mac platform, it is Cmd+F.
Ctrl+P	Open print panel. On Mac platform, it is Cmd+P.
Ctrl+RightArrow	Open left navigation panel. On Mac platform, it is Cmd+RightArrow.
Ctrl+LeftArrow	Close left navigation panel. On Mac platform, it is Cmd+LeftArrow.
Ctrl+C	Copy annotation (path, text, image). On Mac platform, it is Cmd+C.
Ctrl+X	Cut annotation (text). On Mac platform, it is Cmd+X.
Ctrl+V	Paste annotation (path, text, image). On Mac platform, it is Cmd+V.

Start Customization

Developers can add shortcut key event handling functions through the PDFViewer.onShortcutKey interface. If the received shortcut key is already defined within the SDK (as listed in the table above), setting the preventDefaultImplementation parameter to true will replace the implementation of the internal shortcut key in the SDK. Otherwise, when the shortcut key is triggered, the internal implementation of the SDK and the developer's custom processing function will be executed simultaneously.

Replace the Implementation of Built-in Shortcut Keys

Here, we take the shortcut key of the print function as an example:

<script>
    const libPath = window.top.location.origin + '/lib';
    const FRAGMENT_ACTION = UIExtension.UIConsts.FRAGMENT_ACTION;
    const pdfui = new UIExtension.PDFUI({
        viewerOptions: {
            libPath: libPath,
            jr: {
                licenseSN: licenseSN,
                licenseKey: licenseKey
            }
        },
        renderTo: document.body,
        appearance: UIExtension.appearances.adaptive,
        addons: libPath + '/uix-addons/allInOne.js'
    });
    pdfui.onShortcutKey("Ctrl+P", function() {
        pdfui.getComponentByName('print-dialog').then(printDialog => {
            if(printDialog) {
                printDialog.show();
            }
        })
    });
</script>

{
    "iframeOptions": {
        "style": "height: 500px"
    }
}

In the above example, the built-in implementation of the shortcut key in the SDK was replaced. When the user presses the Ctrl+P key combination, the custom print implementation will be triggered. You can obtain the print-dialog to display the print dialog box in this implementation or use other methods to implement custom printing functionality.

Replace Key Combination

If you do not want to use Ctrl+P to trigger the print function, you need to replace the built-in implementation in the SDK and register a custom shortcut key to implement the print function. Following is an example code:

<script>
    const libPath = window.top.location.origin + '/lib';
    const FRAGMENT_ACTION = UIExtension.UIConsts.FRAGMENT_ACTION;
    const pdfui = new UIExtension.PDFUI({
        viewerOptions: {
            libPath: libPath,
            jr: {
                licenseSN: licenseSN,
                licenseKey: licenseKey
            }
        },
        renderTo: document.body,
        appearance: UIExtension.appearances.adaptive,
        addons: libPath + '/uix-addons/allInOne.js'
    });
    pdfui.onShortcutKey('Ctrl+P', function() {
        // PASS
    }, true);
    pdfui.onShortcutKey('Ctrl+Alt+P', function(e) {
        pdfui.print({
            pages: [0]
        });
    })
</script>

{
    "iframeOptions": {
        "style": "height: 500px"
    }
}

In the example above, we first register an empty function using PDFViewer.onShortcutKey to replace the built-in implementation of Ctrl+P in the SDK. Then, we register an event listener for Ctrl+Alt+P. When the user presses Ctrl+Alt+P, the pdfui.print() method will be called to implement the print function.

It is important to note that when replacing the built-in implementation of the shortcut key, the third parameter of the onShortcutKey interface should be set to true. In this way, the custom implementation will replace the default built-in implementation of the SDK, rather than coexisting with it.

Remove Shortcut Key Listener Event

In some cases, you may need to remove a shortcut key listener event under specific conditions. For example, you can listen for the Ctrl+W event to close a document when it is open. But after the document is closed, you need to cancel the Ctrl+W event listener to avoid unnecessary operations. To do this, the PDFViewer.onShortcutKey interface returns a function that you can use to remove the listener for a shortcut key event. Following is an example:

<script>
    const libPath = window.top.location.origin + '/lib';
    const FRAGMENT_ACTION = UIExtension.UIConsts.FRAGMENT_ACTION;
    const pdfui = new UIExtension.PDFUI({
        viewerOptions: {
            libPath: libPath,
            jr: {
                licenseSN: licenseSN,
                licenseKey: licenseKey
            }
        },
        renderTo: document.body,
        appearance: UIExtension.appearances.adaptive,
        addons: libPath + '/uix-addons/allInOne.js'
    });
    var removeShortcutKeyHandler = () => {};
    pdfui.addViewerEventListener(UIExtension.PDFViewCtrl.ViewerEvents.openFileSuccess, () => {
        removeShortcutKeyHandler();
        pdfui.onShortcutKey('Ctrl+Shift+K', function(e) {
            e.preventDefault();// Prevent the default implementation of the browser's native behavior.
            pdfui.close(); // User closes the document.
        }).then((remove) => {
            removeShortcutKeyHandler = remove;
        })
    });
    pdfui.addViewerEventListener(UIExtension.PDFViewCtrl.ViewerEvents.willCloseDocument, () => {
        removeShortcutKeyHandler();
    });
</script>

{
    "iframeOptions": {
        "style": "height: 500px"
    }
}

In the above example, we first use PDFViewer.onShortcutKey to listen for the Ctrl+Shift+K event in the openFileSuccess event callback, and save the returned function to the variable removeShortcutKeyHandler. When the document is going to be closed, we can call the removeShortcutKeyHandler function to remove the listener for the Ctrl+Shift+K event.

It is important to note that if you use multiple PDFViewer.onShortcutKey listener events, each event will return a corresponding function, and you need to save each function and call them separately when needed.

Disable/enable Global Shortcut Key

In some cases, you may need to disable the shortcut key feature. You can achieve this by using the setEnableShortcutKey interface. This interface accepts a boolean value parameter. If it is true, the shortcut key feature will be enabled; if it is false, the shortcut key feature will be disabled.

<script>
    const libPath = window.top.location.origin + '/lib';
    const FRAGMENT_ACTION = UIExtension.UIConsts.FRAGMENT_ACTION;
    const pdfui = new UIExtension.PDFUI({
        viewerOptions: {
            libPath: libPath,
            jr: {
                licenseSN: licenseSN,
                licenseKey: licenseKey
            }
        },
        renderTo: document.body,
        appearance: UIExtension.appearances.adaptive,
        addons: libPath + '/uix-addons/allInOne.js'
    });
    pdfui.setEnableShortcutKey(false);
</script>

{
    "iframeOptions": {
        "style": "height: 500px"
    }
}

The example above disables the shortcut key feature, which means that all key combinations will not be triggered. To re-enable the shortcut key feature, you can call pdfui.setEnableShortcutKey(true).

Notes

To better meet the habits of Mac users, we use different key combinations on the Mac platform. Usually, we use Cmd instead of the Ctrl key. For example, the shortcut key for "Undo" on Windows/Linux is Ctrl+Z, while on Mac it is Cmd+Z.

If you want to replace the shortcut key for the "Undo" function, you need to choose one of these two key combinations depending on the system type to listen for the shortcut key event.