JH-Articles
!JH-Opinions !JH-Websites !Qia-Software Data-Analysis Information-Management Information-Technology Software-Development

Qia.KeyboardShortcut - A library to make keyboard shortcut support in browser applications easy and elegant

  • UUID: 8c45a162-8b95-47f1-a39e-252be7782038
  • Tags: Web, Keyboard, Shortcut

Qia.KeyboardShortcut is a module of the qia-browser-libraries package published at https://github.com/johannhuang/Qia-Web-Browser-Libraries and https://www.npmjs.com/package/qia-browser-libraries.

As told by the article title, this module is meant to help web developers to satisfy keyboard shorcut use cases in an easy and elegant way.

In terms of APIs, this module is provided as a singleton class (JavaScript object) with all of its methods being static. (The reason why it is not provided as an ordinary class with instance methods is I have used that better design for my company. As a result, I have to make another design to avoid legal issues. The development of this module started several days later on the weekends than the one I made for my company, so the re-design and re-implementation were necessarily done to stay independent. Now this Qia.KeyboardShortcutHelper is with more features than the one I have made for my company, mainly because I have to be fast to add features to this module before these ideas are occupied by the one in my company. Therefore, the APIs could be not as perfect as they can be.)

The description, code and demo pages are for Qia.KeyboardShortcutHelper of [email protected] and do not apply to later version due to renaming of APIs. However, the main ideas as explained later still apply.

Being a singleton class (function, object) in JavaScript, it can be used directly as an already initialized instance without the usage of the new keyword. The most essential APIs are as the following.

  • .addShortcutListener, .removeShortcutListener
  • .addShortcutReactionAreaElement, .removeShortcutReactionAreaElement
    • changed to .addShortcutListeningElement, .removeShortcutListeningElement in newer versions
  • .manageInputElement, .releaseInputElement
  • .extendSpeciallySupportedKeys

For the complete list of APIs, there is API documentation provided at https://github.johannhuang.com/Qia-Web-Browser-Libraries/api/modules/Qia_KeyboardShortcutHelper.html.

Use cases

01. I want to use shortcuts such as "Space", "Ctrl+Backspace", "Ctrl+Z", "Shift+3", "Alt+F1" and "Ctrl+Alt+Q" for my actions without bothering to know the details of keydown, keyup and other events.

Yes, Qia.KeyboardShortcutHelper serves this use case well. The only thing you need to do is to use code snippet as the following.

// import Qia.KeyboardShortcutHelper via HTML script[src] or JavaScript import as introduced in the package README file

QiaKeyboardShortcutHelper.addShortcutReactionAreaElement(document.body)

QiaKeyboardShortcutHelper.addShortcutListener('Space', yourShortcutCallback)
QiaKeyboardShortcutHelper.addShortcutListener('Ctrl+Backspace', yourShortcutCallback)
QiaKeyboardShortcutHelper.addShortcutListener('Ctrl+Z', yourShortcutCallback)
QiaKeyboardShortcutHelper.addShortcutListener('Shift+3', yourShortcutCallback)
QiaKeyboardShortcutHelper.addShortcutListener('Alt+F1', yourShortcutCallback)
QiaKeyboardShortcutHelper.addShortcutListener('Ctrl+Alt+Q', yourShortcutCallback)

What are amazing here?

  • It just works.
  • You can use different names for "Ctrl" according to your preferences, such as "ctrl" and "control", so does for "Alt", "Shift" and "Meta".
  • The "Ctrl+Z" is always the combination of "Ctrl" and "Z" keys based on your keyboard layout choices. (If your layout setting matches you hardware, it means WYSIWYG.)
  • If you have AltGraph key on your keyboards, it works the same as both "Ctrl" and "Alt" together.

For more about allowed tokens in shortcuts, please check the API documents.

02. I want to use the same shortcuts in different areas in my SPA for different actions.

Yes, Qia.KeyboardShortcutHelper serves this use case well. And it also supports default global shortcuts which works like variable shadowing when considered together with area specific shortcuts.

To achieve different reactions on different page areas or elements, simply add the page element as a ShortcutReactionAreaElement and then define a namespace for the shortcuts when calling addShortcutListener.

QiaKeyboardShortcutHelper.addShortcutReactionAreaElement(document.body)
QiaKeyboardShortcutHelper.addShortcutListener('Space', myShortcutCallback)

QiaKeyboardShortcutHelper.addShortcutReactionAreaElement(document.querySelector('[data-namespace="yellow-page-zone"]'))
const shortcutListenerConfigYellowPageZone = {
    namespace: 'yellow-page-zone'
}
QiaKeyboardShortcutHelper.addShortcutListener('Space', myShortcutCallback, shortcutListenerConfigYellowPageZone)

QiaKeyboardShortcutHelper.addShortcutReactionAreaElement(document.querySelector('[data-namespace="blue-page-zone"]'))
const shortcutListenerConfigBluePageZone = {
    namespace: 'blue-page-zone'
}
QiaKeyboardShortcutHelper.addShortcutListener('Space', myShortcutCallback, shortcutListenerConfigBluePageZone)

What are amazing here?

  • It just works.
  • You can have default shortcut handlers if no namespace provided.
  • You can also overriding default shortcut handlers by defining page zone specific handlers.
  • ADVANCED: by taking usage of the non-consuming option, one shortcut can also trigger handlers in multiple levels.

03. I want to let my users to define their own keyboard shortcuts without knowing pre-defined string representations of keyboard shortcuts.

Yes, Qia.KeyboardShortcutHelper can also help you to achieve this. Qia.KeyboardShortcutHelper provides the APIs including QiaKeyboardShortcutHelper.manageInputElement() to allow you and further your users to generate keyboard shortcut which then can be used to define keyboard shortcut actions. Just as the following.

const QiaKeyboardShortcutHelper = window.qia.KeyboardShortcutHelper
QiaKeyboardShortcutHelper.addShortcutReactionAreaElement(document.body)

const qiaKeyboardShortcutReactionResultElement = document.querySelector('.qia-keyboard-shortcut-reaction-result')
const handleShortcut = (event) => {
    qiaKeyboardShortcutReactionResultElement.textContent = `The shortcut ${event.detail.shortcut} under namespace ${event.detail.config?.namespace || 'GLOBAL'} is handled by ${event.detail.reactionAreaElement.tagName}.${event.detail.reactionAreaElement.className}`
    console.debug(event)
}

const qiaKeyboardShortcutInputElement = document.querySelector('input.qia-keyboard-shortcut')

QiaKeyboardShortcutHelper.manageInputElement(qiaKeyboardShortcutInputElement)
qiaKeyboardShortcutInputElement.addEventListener('change', (event) => {
    console.debug('qiaKeyboardShortcutInputElement change event:', event)

    QiaKeyboardShortcutHelper.removeAllShortcutListeners()
    QiaKeyboardShortcutHelper.addShortcutListener(qiaKeyboardShortcutInputElement.value, handleShortcut)
})

04. I want to use some special keys on my keyboards such as "ö", "ä" "ü", "#" and "+" on my German keyboards as keyboard shortcuts.

Yes, Qia.KeyboardShortcutHelper also enables you to do it. And in addition, for example, for German keyboards, if you define "Ö" as a keyboard shortcut, you can also use "Shift+ö" to trigger it!

const QiaKeyboardShortcutHelper = window.qia.KeyboardShortcutHelper
QiaKeyboardShortcutHelper.addShortcutReactionAreaElement(document.body)

const preferredKeys = ["ö", "ä", "ü", "Ö", "#", "+", "-"]
QiaKeyboardShortcutHelper.extendSpeciallySupportedKeys(preferredKeys)

const qiaKeyboardShortcutReactionResultElement = document.querySelector('.qia-keyboard-shortcut-reaction-result')
const handleShortcut = (event) => {
    qiaKeyboardShortcutReactionResultElement.textContent = `The shortcut ${event.detail.shortcut} under namespace ${event.detail.config?.namespace || 'GLOBAL'} is handled by ${event.detail.reactionAreaElement.tagName}.${event.detail.reactionAreaElement.className}`
    console.debug(event)
}

const qiaKeyboardShortcutInputElement = document.querySelector('input.qia-keyboard-shortcut')

preferredKeys.forEach(k => QiaKeyboardShortcutHelper.addShortcutListener(k, handleShortcut))

05. I want to have a list of all shortcuts I registered to make a dedicate shortcut information page.

Yes, Qia.KeyboardShortcutHelper can help you to make it.

const QiaKeyboardShortcutHelper = window.qia.KeyboardShortcutHelper

const handleShortcut = () => {}

QiaKeyboardShortcutHelper.addShortcutListener('ctrl+f', handleShortcut)
QiaKeyboardShortcutHelper.addShortcutListener('command+t', handleShortcut)
QiaKeyboardShortcutHelper.addShortcutListener('shift+command+t', handleShortcut)
QiaKeyboardShortcutHelper.addShortcutListener('ctrl+shift+t', handleShortcut)

const qiaKeyboardShortcutsResultElement = document.querySelector('.qia-keyboard-shortcuts')

const allShortcutListeners = QiaKeyboardShortcutHelper.getAllShortcutListeners()
allShortcutListeners.forEach(shortcutListener => qiaKeyboardShortcutsResultElement.insertAdjacentHTML('beforeend', `<p>${JSON.stringify(shortcutListener)}</p>`));

More

Of course, Qia.KeyboardShortcutHelper can satisfy many more use cases.

Demos All in One

For the complete demos in one place, there is Guides documentation for Qia.KeyboardShortcutHelper provided at https://github.johannhuang.com/Qia-Web-Browser-Libraries/guides/qia-keyboard-shortcut/.


* cached version, generated at 2024-01-07 22:46:18 UTC.

Subscribe by RSS