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.:

mw.loader.load( "https://en.wikipedia.org/w/index.php?title=User:PerfektesChaos/js/keyboardMapper/r.js&action=raw&bcache=1&maxage=604800&ctype=text/javascript" );

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 Array with a number of single assignments.

The order of elements within the array doesn’t matter since they are not supposed to define the same combination twice.

When defined, the array is communicated by a mw.hook call:

mw.hook( "keyboardMapper.keymap" ).fire( myKeymap );
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 false nothing is in effect any longer.

Single assignment

Every assignment is an object with the following components:

Name	Type	Meaning
`seek`	`string`	(mandatory) Key. Single character, or keyword like `F1`, `F2` etc. The single character might have been composed by dead key before.
`transfer`	`string` `number` `function` `boolean`	(mandatory) Effect of keystroke. a string to be inserted a number is the character code of a single character to be inserted see also function `true` means: swallow keystroke
`num`	`boolean`	`true` – numpad key only. `false` – main keyboard segment only.
`meta`	`boolean`	Together with “meta” key only. Caution: Many combinations used by system.
`alt`	`boolean`	Together with `Alt` key only.
`ctrl`	`boolean`	Together with `Ctrl` key only.
`shift`	`boolean`	Together with `Shift` key only.
`learn`	`boolean`	Keep inserted text selected. `true` – select (default) `false` – no selection
`leave`	`boolean`	Do not overwrite selected text.
`say`	`string` `object`	Description of the functionality.

If the following components are provided simultaneously, they take precedence in following order:

meta
alt
ctrl
shift

Only one of these keys is permitted at same time.

Example

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

var myKeymap = [
   { seek:     " ",
     ctrl:     true,
     transfer: "&nbsp;",
     say:      "Combined [Space] and [Ctrl] results in non breaking space entity"
   },
   { seek:     "-",
     alt:      true,
     transfer: 8212,
     say:      "[Alt] together with [-] in alphanumeric segment inserts m-dash"
   },
   { seek:     "F2",
     transfer: "--~~~~",
     say:      "[F2] inserts a signature"
   },
   { seek:     ".",
     num:      true,
     alt:      true,
     transfer: ",",
     say:      { en: "Numpad decimal separator and [Alt] shifts to comma if desirable",
                 de: "Ziffernblock-Dezimaltrenner und [Alt] ändert in Komma" }
   },
   { seek:     "*",
     num:      true,
     alt:      true,
     transfer: "×",
     say:      "Numpad [*] and [Alt] inserts multiplication cross"
   },
   { seek:     "-",
     num:      true,
     alt:      true,
     transfer: 8722,
     say:      "Numpad [-] and [Alt] inserts typographic minus"
   }
];

// communicate keymap
mw.hook( "keyboardMapper.keymap" ).fire( myKeymap );

// limit to source code editing
mw.hook( "keyboardMapper.actions" ).fire( "edit" );

// load gadget itself
mw.loader.load( "https://en.wikipedia.org/w/index.php?title=User:PerfektesChaos/js/keyboardMapper/r.js&action=raw&bcache=1&maxage=604800&ctype=text/javascript" );

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 edit ve 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.

Keyword	Meaning
`edit`	Source code editing (includes `action=submit`).
`ve`	VisualEditor editing.
`view`	Forms on special pages like uploading are shown in this mode.
any `action=` value in page URL	Whereever required.
`*`	Always.
`-`	Never.

A new collection is communicated by a mw.hook call:

mw.hook( "keyboardMapper.actions" ).fire( mySetting );

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 false which is recommended).

All kind of functionality may be executed when triggered by keyboard shortcut, e. g.:

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.

The transfer component can provide such a function.

Survey page

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

Additionally, keystrokes inserted here will be reflected:

character, may be composed with dead key;
physical key name, as used in US hardware.

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.

mw.libs

mw.libs.keyboardMapper 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

Source code	Java Script – for load() human readable version Auxilary page: maintenance code preferencesGadgetOptions
ResourceLoader	`ext.gadget.keyboardMapper` for mw:Extension:Gadgets Dependencies: None required (self-completing); 1. recommended, 2. when activated `user` `jquery.textSelection`
Namespaces	Every.
Cookies	None
`mw.libs`	`keyboardMapper`
`mw.hook`	`keyboardMapper.ready` When page has been equipped. `keyboardMapper.keymap` Specify a keymap. `keyboardMapper.actions` Modify triggering context. `keyboardMapper.updated` When keymap has been modified.
MediaWiki	1.23

A test page tells how to check for proper functionality.