Allow global keyboard shortcuts to override all other shortcuts by providing a special field (#6735)

* allow global keyboard shortcuts to override all other shortcuts by providing a special field

* rework the global shortcuts taking priority

* replace bool option with options object in KeyboardManager's keydown handler

* update keyboard shortcut documentation to add information about the new priority setting

* add support for priority global keyboard shortcuts to code mirror

* update the feature's docs to point out it was/will be introduced in 5.2.4

* rollback unnecessary change

core/modules/editor/engines/framed.js

@@ -87,7 +87,7 @@ function FramedEngine(options) {
 	$tw.utils.addEventListeners(this.domNode,[
 		{name: "click",handlerObject: this,handlerMethod: "handleClickEvent"},
 		{name: "input",handlerObject: this,handlerMethod: "handleInputEvent"},
-		{name: "keydown",handlerObject: this.widget,handlerMethod: "handleKeydownEvent"},
+		{name: "keydown",handlerObject: this,handlerMethod: "handleKeydownEvent"},
 		{name: "focus",handlerObject: this,handlerMethod: "handleFocusEvent"}
 	]);
 	// Add drag and drop event listeners if fileDrop is enabled
@@ -192,6 +192,17 @@ FramedEngine.prototype.handleFocusEvent = function(event) {
 	}
 };
 
+/*
+Handle a keydown event
+ */
+FramedEngine.prototype.handleKeydownEvent = function(event) {
+	if ($tw.keyboardManager.handleKeydownEvent(event, {onlyPriority: true})) {
+		return true;
+	}
+
+	return this.widget.handleKeydownEvent(event);
+};
+
 /*
 Handle a click
 */

core/modules/keyboard.js

@@ -141,6 +141,7 @@ function KeyboardManager(options) {
 	this.shortcutKeysList = [], // Stores the shortcut-key descriptors
 	this.shortcutActionList = [], // Stores the corresponding action strings
 	this.shortcutParsedList = []; // Stores the parsed key descriptors
+	this.shortcutPriorityList = []; // Stores the parsed shortcut priority
 	this.lookupNames = ["shortcuts"];
 	this.lookupNames.push($tw.platform.isMac ? "shortcuts-mac" : "shortcuts-not-mac")
 	this.lookupNames.push($tw.platform.isWindows ? "shortcuts-windows" : "shortcuts-not-windows");
@@ -318,12 +319,23 @@ KeyboardManager.prototype.updateShortcutLists = function(tiddlerList) {
 		this.shortcutKeysList[i] = tiddlerFields.key !== undefined ? tiddlerFields.key : undefined;
 		this.shortcutActionList[i] = tiddlerFields.text;
 		this.shortcutParsedList[i] = this.shortcutKeysList[i] !== undefined ? this.parseKeyDescriptors(this.shortcutKeysList[i]) : undefined;
+		this.shortcutPriorityList[i] = tiddlerFields.priority === "yes" ? true : false;
 	}
 };
 
-KeyboardManager.prototype.handleKeydownEvent = function(event) {
+/*
+event: the keyboard event object
+options:
+	onlyPriority: true if only priority global shortcuts should be invoked
+*/
+KeyboardManager.prototype.handleKeydownEvent = function(event, options) {
+	options = options || {};
 	var key, action;
 	for(var i=0; i<this.shortcutTiddlers.length; i++) {
+		if(options.onlyPriority && this.shortcutPriorityList[i] !== true) {
+			continue;
+		}
+
 		if(this.shortcutParsedList[i] !== undefined && this.checkKeyDescriptors(event,this.shortcutParsedList[i])) {
 			key = this.shortcutParsedList[i];
 			action = this.shortcutActionList[i];

core/modules/widgets/keyboard.js

@@ -53,6 +53,10 @@ KeyboardWidget.prototype.render = function(parent,nextSibling) {
 };
 
 KeyboardWidget.prototype.handleChangeEvent = function(event) {
+	if ($tw.keyboardManager.handleKeydownEvent(event, {onlyPriority: true})) {
+		return true;
+	}
+
 	var keyInfo = $tw.keyboardManager.getMatchingKeyDescriptor(event,this.keyInfoArray);
 	if(keyInfo) {
 		var handled = this.invokeActions(this,event);

editions/tw5.com/tiddlers/concepts/KeyboardShortcutTiddler.tid

@@ -7,6 +7,8 @@ A ''Keyboard Shortcut Tiddler'' is made of three parts:
 * The ''field'' `key` with a [[Keyboard Shortcut Descriptor]] as its ''value''
 * Actions in its ''text'' field
 
+<<.tip """<<.from-version "5.2.4">> By default <<.wlink KeyboardWidget>> and text editor shortcuts take priority, which can be circumvented by setting the ''field'' `priority` to `yes`.""">>
+
 If the [[Keyboard Shortcut Descriptor]] has the form `((my-shortcut))` it's a ''reference'' to a ''configuration Tiddler'' that stores the corresponding [[Keyboard Shortcut|KeyboardShortcuts]]
 
 In order to make a ''shortcut'' editable through the <<.controlpanel-tab KeyboardShortcuts>> Tab in the $:/ControlPanel it's sufficient to create a tiddler `$:/config/ShortcutInfo/my-shortcut`, where the ''suffix'' is the ''reference'' used for the [[Keyboard Shortcut|KeyboardShortcuts]]

editions/tw5.com/tiddlers/howtos/How to create keyboard shortcuts.tid

@@ -66,6 +66,8 @@ In the [[Keyboard Shortcuts Tab|$:/core/ui/ControlPanel/KeyboardShortcuts]] the
 
 !! Using global Keyboard Shortcuts
 
+> See [[Keyboard Shortcut Tiddler]] for detailed information about creating new global keyboard shortcuts.
+
 > The actions for ''global'' keyboard shortcuts are stored in the ''text'' field of tiddlers tagged with <<tag $:/tags/KeyboardShortcut>>
 
 > The ''key field'' connects an action-tiddler with the corresponding shortcut through the `((my-shortcut))` syntax, called [[Keyboard Shortcut Descriptor]]

plugins/tiddlywiki/codemirror/engine.js

@@ -186,6 +186,10 @@ function CodeMirrorEngine(options) {
 		return false;
 	});
 	this.cm.on("keydown",function(cm,event) {
+		if ($tw.keyboardManager.handleKeydownEvent(event, {onlyPriority: true})) {
+			return true;
+		}
+	
 		return self.widget.handleKeydownEvent.call(self.widget,event);
 	});
 	this.cm.on("focus",function(cm,event) {