# # 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+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.