Benutzer:PerfektesChaos/js/keyboardMapper

JavaScript Gadget – forme Tastendrücke zu anderen Textsequenzen um oder starte sonstige Aktivitäten.

Einbindung

Wenn das Projekt dieses Gadget bereits registriert haben sollte, genügt ein Häkchen auf der Seite Einstellungen („Helferlein“).
Sonst wären die folgenden Zeilen in die persönliche common.js, global.js etc. einzufügen:

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" );

Mehr JavaScript-Anweisungen werden aber ohnehin benötigt, die an einem der beschriebenen Orte einzufügen sind.

Konfiguration

Nach dem Laden macht das Gadget von sich aus noch nichts. Es muss spezifiziert werden, welche Tastendrücke welche Wirkung haben sollen.

Tastenzuordnung spezifizieren

Eine keymap (Tastenzuordnung) ist ein Array mit einer Anzahl einzelner Zuordnungen.

Die Reihenfolge der Elemente ist ohne Bedeutung, da nicht davon auszugehen ist, dass die gleiche Kombination zweimal zugeordnet wird.

Wenn definiert, wird das Array durch einen Aufruf von mw.hook kommuniziert:

mw.hook( "keyboardMapper.keymap" ).fire( meineTasten );
Das sollte optimal vor dem Laden geschehen, kann aber jederzeit und beliebig oft innerhalb der Wiki-Seite wiederholt werden.
Jeder wiederholte Aufruf ersetzt den bisherigen Zustand vollständig und sofort.
Wenn kein Array übermittelt wird, sondern false, ist keine Zuordnung mehr aktiv.

Einzelne Zuordnung

Jede einzelne Zuordnung ist ein object mit folgenden Komponenten:

Name	Typ	Bedeutung
`seek`	`string`	(Pflicht) Taste. Einzelnes Zeichen, oder Schlüsselwort wie `F1`, `F2` etc. Das einzelne Zeichen kann jedoch zuvor mittels Tottaste erzeugt worden sein.
`transfer`	`string` `number` `function` `boolean`	(Pflicht) Effekt eines Tastendrucks. eine Zeichenkette, die eingefügt werden soll eine Zahl wäre der Zeichencode eines einzelnen Zeichens, das eingefügt werden soll siehe auch benutzerdefinierte Funktion `true` bedeutet: Verschlucke den Tastendruck
`num`	`boolean`	`true` – nur im Ziffernblock. `false` – nur im alphanumerischen Tastenbereich.
`meta`	`boolean`	Nur mit „Meta“-Taste zusammen. Vorsicht: Viele Kombinationen werden vom Betriebssystem belegt.
`alt`	`boolean`	Nur mit `Alt` zusammen.
`ctrl`	`boolean`	Nur mit `Strg` zusammen.
`shift`	`boolean`	Nur mit `Umschalt ⇧` zusammen.
`learn`	`boolean`	Eingefügten Text selektiert belassen (Vorgabe: `true`). `false` – nicht selektieren
`leave`	`boolean`	Selektierten Text nie überschreiben.
`say`	`string` `object`	Beschreibung der Funktionalität (nur informativ).

Wenn die folgenden Komponenten gleichzeitig gesetzt sind, haben sie in der angegebenen Reihenfolge Vorrang vor den weiteren:

meta
alt
ctrl
shift

Nur eine dieser Modi ist wirksam.

Example

Der nachstehende Code zeigt die vollständige Sequenz, wie sie an einem geeigneten Ort zu hinterlegen wäre:

var meineTasten = [
   { seek:     " ",
     ctrl:     true,
     transfer: "&nbsp;",
     say:      "Kombination von [Leer] mit [Strg] ergibt Entity für geschütztes Leerzeichen."
   },
   { seek:     "-",
     ctrl:     true,
     transfer: 8211,
     say:      "[-] im alphanumerischen Segment mit [Strg] fügt Halbgeviertstrich ein."
   },
   { seek:     "F8",
     transfer: "--~~~~",
     leave:    true,
     say:      "[F8] fügt eine Signatur ein."
   },
   { seek:     ".",
     num:      true,
     alt:      true,
     transfer: ".",
     say:      { en: "Numpad decimal separator and [Alt] shifts to period if desirable",
                 de: "Ziffernblock-Dezimaltrenner mit [Alt] fügt Tausender-Punkt ein." }
   },
   { seek:     "*",
     num:      true,
     alt:      true,
     transfer: "×",
     say:      "Ziffernblock-[*] mit [Alt] fügt Malkreuz ein."
   },
   { seek:     "-",
     num:      true,
     alt:      true,
     transfer: 8722,
     say:      "Ziffernblock-[-] mit [Alt] fügt typografisches Minuszeichen ein."
   }
];

// Kommuniziere Tastenzuordnung:
mw.hook( "keyboardMapper.keymap" ).fire( meineTasten );

// Beschränke auf Quelltext-Bearbeitung:
mw.hook( "keyboardMapper.actions" ).fire( "edit" );

// Lade das eigentliche Gadget:
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" );

Seitenkontext

Das Gadget wird aktiviert, wenn die momentane Seite in einem Modus ist, von dem die Verarbeitung von Tastendrücken erwartet werden kann.

Vorgabe für den Modus ist edit ve – was bei Bearbeitung des Quelltextes oder mittels VisualEditor wirkt.

Die Spezifikation des Modus ist ein string von durch Leerzeichen getrennten Schlüsselwörtern oder ein einzelnes Sonderzeichen.

Wort	Bedeutung
`edit`	Klassische Quelltext-Bearbeitung (schließt `action=submit` ein).
`ve`	Bearbeitung unterstützt durch den VisualEditor.
`view`	Formulare auf Spezalseiten wie etwa zum Hochladen werden in diesem Modus angezeigt.
jeder Wert von `action=` in der URL der Seite	Wo immer benötigt.
`*`	Immer.
`-`	Nie.

Eine neue Zusammenstellung wird durch einen Aufruf von mw.hook kommuniziert:

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

Das ersetzt sofort die gesamte vorherige Spezifikation.

Benutzerdefinierte Funktion

Eine benutzerdefinierte Funktion erhält das DOM event object als Parameter.

Der Rückgabewert kann ein string sein, der in den momentan bearbeiteten Text eingefügt wird. Allerdings gibt es keine Notwendigkeit, dass solch ein Einfügungstext produziert werden muss, oder dass die Seite überhaupt in irgendeinem Bearbeitungsmodus sein muss. In diesen Fällen ist der Verzicht auf einen Rückgabewert möglich (oder explizit false, was zu empfehlen ist).

Funktionalitäten aller Art können ausgeführt werden, wenn durch eine Tastenzuordnung ausgelöst, namentlich:

Öffnen einer anderen Seite, insbesondere in einem anderen Browser-Tab, vor allem wenn ein Werkzeug Bezug auf die momentane Seite nimmt.
Darstellung der momentanen Seite ändern, in der Vorschau oder in der statischen Anzeige.

Die Komponente transfer kann solch eine Funktion spezifizieren.

Wartungsübersicht

Auf einer Wartungsseite wird der Effekt der momentanen Konfiguration angezeigt, sofern das Gadget aktiv ist.

Außerdem werden neben Versionsinformationen auch die Wirkungen von Tastendrücken angezeigt:

Das Zeichen, wie es für die Definitionen zu benennen ist.
Die auf US-amerikanischen Tastaturen beruhenden Hardware-Namen der Tasten.

Sollten hier keine Wirkungen gespiegelt werden, unterstützt der Browser eine wesentliche Komponente nicht.

Falls Definitionen fehlen sollten, war diese Spezifikation ungültig.

Browser

Von nachstehenden Browsern ist bekannt, dass sie das Gadget unterstützen oder auch nicht.

Browser	Version	Eignung
Chrome	(jede aktuelle)	Sollte funktionieren.
Firefox	(jede aktuelle)
Internet Explorer (Microsoft)	ab 9
Opera	ab 15
Vivaldi
Edge (Microsoft)		zu klären
Internet Explorer (Microsoft)	bis 8	Nicht einsetzbar.
Opera	bis 12
Opera	Mobile Emulator

Individuelle Konfigurationen oder eine Sicherheitsrichtlinie kann jedoch einen Browser an der Ausführung hindern.

mw.libs

mw.libs.keyboardMapper zeigt nach dem Laden und sobald eine Tastenzuordnung modifiziert wurde die Versionsinformation, momentane Datenstrukturen und Aktivitätsstatus.

Dieses object wird vom Gadget nicht gelesen. Eine Veränderung wäre nicht sinnvoll.

Hinweise

Die mit AltGr erreichbaren Tasten ~|\@ eignen sich nicht für die zusätzliche Belegung.
Die Meta-Taste (Windowstaste usw.) wird meist vom Betriebssystem abgefangen und ist bereits weitgehend belegt.
Tottasten wie `´^ sind ebenfalls ziemlich ungeeignet.
Browser haben bereits ein Sortiment an Tastaturbefehlen vordefiniert.
In Hilfe:Tastaturkombinationen ist dargestellt, was Wiki-Seiten bereits definiert haben; ggf. auch Hilfe:VisualEditor/Tastaturkombinationen.
Es kann nur innerhalb der Wiki-Seite eine Wirkung erzielt werden; der Browser allgemein kann nicht durch umdefinierte Tasten angesteuert werden.

Wie Tasten im Einzelnen wirken und welche unbelegt wären, muss im spezifischen Browser beim aktuellen Betriebssystem unter Berücksichtigung sonstiger individueller Einstellungen ausprobiert werden.

Weitere Informationen

KeyboardEvent code Values. W3C: Namen der Funktionstasten (englisch)
UI Events. W3C: Hintergrundmaterial (englisch)
Tastaturkürzel in Firefox. (deutsch)

Code und Stammseite

Die Stammseite ist en:User:PerfektesChaos/js/keyboardMapper mit:

Quellcode	(siehe dort)
ResourceLoader	`ext.gadget.keyboardMapper` für mw:Extension:Gadgets Dependencies (bei Bedarf selbstladend): `user`, (später) `jquery.textSelection`
Namensraum	alle
`mw.libs`	`keyboardMapper`
Cookies	keine
`mw.hook`	`keyboardMapper.ready` Wenn die Seite ausgestattet wurde. `keyboardMapper.keymap` Tastenzuordnung spezifizieren. `keyboardMapper.actions` Auslösekontext ändern. `keyboardMapper.updated` Wenn die Tastenzuordnung modifiziert wurde.
MediaWiki	1.23