User:PerfektesChaos/js/keyboardMapper

JavaScript gadget – divert keystrokes to insert specified text or trigger other activities.

Usage

 * If your project has registered this as a gadget, just activate on your Preferences page.
 * Otherwise include the following line into your common.js, global.js etc.:

More JavaScript statements will be needed anyway.

Configuration
After loading, the gadget does nothing. It needs to be specified which keystrokes should have which different effect.

Keymap specification
A keymap is an  with a number of single assignments. When defined, the array is communicated by a  call:
 * The order of elements within the array doesn’t matter since they are not supposed to define the same combination twice.
 * That should happen best before loading, but may be repeated as often as desired within a page.
 * Any repeated call will replace the entire previous call immediatedly.
 * If not an Array but  nothing is in effect any longer.
 * If not an Array but  nothing is in effect any longer.

Single assignment
Every assignment is an object with the following components:

If the following components are provided simultaneously, they take precedence in following order: Only one of these keys is permitted at same time.

Example
The following code demonstrates a complete sequence to be present at appropriate place.

Page context
The gadget is activated if the current page is in a mode that is supposed to process keystrokes.

By default the mode is  which is in effect on source code or VisualEditor editing.

The mode specification is a string of space separated keywords or one single special character. A new collection is communicated by a  call: This will replace the entire previous arrangement immediatedly.

User defined function
A user defined function will receive the DOM event object as parameter.

The return value might be a string which will be inserted at the currently edited text position. However, there is no need to produce text nor being in edit mode at all. In such cases no return value is possible (or explicitly  which is recommended).

All kind of functionality may be executed when triggered by keyboard shortcut, e. g.: The  component can provide such a function.
 * Opening another page, especially in another browser tab, even more a tool that is related to the current page.
 * Changing the appearance of the current page, in preview or for static view.

Survey page
On a maintenance page the effect of current configuration is shown, if gadget is active.

Additionally, keystrokes inserted here will be reflected: If nothing changes on this page when pressing regular keys, the current browser does not support this gadget or might have been disabled functionality for security reasons.
 * character, may be composed with dead key;
 * physical key name, as used in US hardware.

mw.libs
will show after loading and when defining a keymap the version information, current data structure and activity state.

This object won’t be examined by the gadget. A modification is not meaningful.

Internationalization
Not required for gadget itself, but support on maintenance page.

Further Information

 * KeyboardEvent code Values. W3C (names of function keys)
 * UI Events. W3C (background material)

Codes
A test page tells how to check for proper functionality.

de:User:PerfektesChaos/js/keyboardMapper