shortcuts JavaScript API Module

Ben Tiedt — Fri, 08 Mar 2024 17:51:10 GMT

Current Revision posted to API Documentation by Ben Tiedt on 03/08/2024 17:51:10

jQuery.telligent.evolution.shortcuts

This module provides a simple way to register keyboard shortcuts. Shortcuts can be defined with simple key combinations and can be assigned managed by their handle as well as optional namespaces. Shortcuts can also be scoped to target specific focused elements. Combined with the Keyboard Shortcuts widget, currently registered and available shortcuts can be displayed.

Methods

register

Registers a keyboard shortcut and returns a registration handle.

var handleId = $.telligent.evolution.shortcuts.register(shortcut, function(data) {
    // handle the shortcut
}, options);

shortcut: Keyboard combination string or array of strings to handle. Can be a simple string such as 'j' or any combination of case-insensitive modifiers such as 'ctrl + shift + j'. Modifiers include alt, meta, ctrl, shift, cmd, and opt. Additionally, direction arrows and special keys can also be used, such as 'ctrl + up', 'shift + esc', or simply 'ret'. If passed an array, maps each shortcut to the same handler.
If the handler function returns false, it prevents further bubbling of the key event.

Options is optional and can include:

description: optional description. When provided, the shortcut will be included by the Keyboard Shortcut widget when listing available shortcuts at any given time.
scope: optional DOM element, jQuery selection, or selector. When provided, shortcut will only trigger if the focused element is contained within the scope.
namespace: optional namespace string or array of namespace strings to allow clearing one or many multiple registered keyboard shortcuts later without having the registeration handle
direction: Whether to trigger on 'down' or 'up'. Default: direction.down.

unregister

Unregisters a keyboard shortcut or multiple shortcuts by handle id or namespace.

// Unregister by registration handle ID
$.telligent.evolution.shortcuts.unregister(handleId);
// Unregister by namespace
$.telligent.evolution.shortcuts.unregister('myNameSpace');
// Unregister all
$.telligent.evolution.shortcuts.unregister();

list

Lists currently registered shortcuts

$.telligent.evolution.shortcuts.list(options);

Options is optional and can include:

scoped: When true, only includes shortcuts which would be effectively triggerable based on the current focused element.

captureFocus

Stores the current focused element, useful for returning focus later

$.telligent.evolution.shortcuts.captureFocus();

refocus

Attempts to refocus on the last remembered focused element, including form inputs and rich text editors.

$.telligent.evolution.shortcuts.captureFocus();