User:PerfektesChaos/js/keyboardMapper

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

Usage

edit
  • 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

edit

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

Keymap specification

edit

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

edit

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

edit

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

edit

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

edit

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

edit

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

edit

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

edit

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

Further Information

edit

Codes

edit
Source code
ResourceLoader
  • ext.gadget.keyboardMapper for mw:Extension:Gadgets
  • Dependencies:
    • None required (self-completing); 1. recommended, 2. when activated
      1. user
      2. 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.