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:

1. meta
2. alt
3. ctrl
4. 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: " ",
     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.