/*

* GNU AGPL-3.0 License

*

* Copyright (c) 2021 - present core.ai . All rights reserved.

* Original work Copyright (c) 2012 - 2021 Adobe Systems Incorporated. All rights reserved.

*

* This program is free software: you can redistribute it and/or modify it

* under the terms of the GNU Affero General Public License as published by

* the Free Software Foundation, either version 3 of the License, or

* (at your option) any later version.

*

* This program is distributed in the hope that it will be useful, but WITHOUT

* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

* FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License

* for more details.

*

* You should have received a copy of the GNU Affero General Public License

* along with this program. If not, see https://opensource.org/licenses/AGPL-3.0.

*

*/

// @INCLUDE_IN_API_DOCS

/*globals path, logger*/

/*jslint regexp: true */

/*unittests: KeyBindingManager */

/**

* Manages the mapping of keyboard inputs to commands.

*/

define(function (require, exports, module) {

require("utils/Global");

let AppInit = require("utils/AppInit"),

Commands = require("command/Commands"),

CommandManager = require("command/CommandManager"),

DefaultDialogs = require("widgets/DefaultDialogs"),

EventDispatcher = require("utils/EventDispatcher"),

FileSystem = require("filesystem/FileSystem"),

FileSystemError = require("filesystem/FileSystemError"),

FileUtils = require("file/FileUtils"),

KeyEvent = require("utils/KeyEvent"),

Strings = require("strings"),

Keys = require("command/Keys"),

KeyboardOverlayMode = require("command/KeyboardOverlayMode"),

StringUtils = require("utils/StringUtils"),

Metrics = require("utils/Metrics"),

Dialogs = require("widgets/Dialogs"),

Mustache = require("thirdparty/mustache/mustache"),

UrlParams = require("utils/UrlParams").UrlParams,

_ = require("thirdparty/lodash");

let KeyboardPrefs = JSON.parse(require("text!base-config/keyboard.json"));

let KeyboardDialogTemplate = require("text!./ChangeShortcutTemplate.html");

let KEYMAP_FILENAME = "keymap.json",

_userKeyMapFilePath = path.normalize(brackets.app.getApplicationSupportDirectory() + "/" + KEYMAP_FILENAME);

/**

* key binding add event

*

* @const

* @type {string}

*/

const EVENT_KEY_BINDING_ADDED = "keyBindingAdded";

/**

* key binding remove event

*

* @const

* @type {string}

*/

const EVENT_KEY_BINDING_REMOVED = "keyBindingRemoved";

/**

* new preset event

*

* @const

* @type {string}

*/

const EVENT_NEW_PRESET = "newPreset";

/**

* preset change event

*

* @const

* @type {string}

*/

const EVENT_PRESET_CHANGED = "presetChanged";

/**

* @const

* @type {Object}

*/

const KEY = Keys.KEY;

const knownBindableCommands = new Set();

/**

* Forward declaration for JSLint.

*

* @private

* @type {Function}

*/

let _loadUserKeyMap = _.debounce(_loadUserKeyMapImmediate, 200);

let PreferencesManager;

let _customKeymapIDInUse;

const _registeredCustomKeyMaps = {};

const STATE_CUSTOM_KEY_MAP_ID = "customKeyMapID";

const PREF_TRIPLE_CTRL_KEY_PRESS_ENABLED = "tripleCtrlPalette";

/**

* Maps normalized shortcut descriptor to key binding info.

*

* @private

* @type {!Object.<string, {commandID: string, key: string, displayKey: string}>}

*/

let _keyMap = {}, // For the actual key bindings including user specified ones

// For the default factory key bindings, cloned from _keyMap after all extensions are loaded.

_defaultKeyMap = {};

/**

* @typedef {{shortcut: !string,

* commandID: ?string}} UserKeyBinding

*/

/**

* Maps shortcut descriptor to a command id.

*

* @private

* @type {UserKeyBinding}

*/

let _originalUserKeyMap = {},

_customKeyMap = {},

_customKeyMapCache = {};

/**

* Maps commandID to the list of shortcuts that are bound to it.

*

* @private

* @type {!Object.<string, Array.<{key: string, displayKey: string}>>}

*/

let _commandMap = {};

/**

* An array of command ID for all the available commands including the commands

* of installed extensions.

*

* @private

* @type {Array.<string>}

*/

let _allCommands = [];

/**

* Maps key names to the corresponding unicode symbols

*

* @private

* @type {{key: string, displayKey: string}}

*/

let _displayKeyMap = { "up": "\u2191",

"down": "\u2193",

"left": "\u2190",

"right": "\u2192",

"-": "\u2212" };

let _specialCommands = [Commands.EDIT_UNDO, Commands.EDIT_REDO, Commands.EDIT_SELECT_ALL,

Commands.EDIT_CUT, Commands.EDIT_COPY, Commands.EDIT_PASTE],

_reservedShortcuts = ["Ctrl-Z", "Ctrl-Y", "Ctrl-A", "Ctrl-X", "Ctrl-C", "Ctrl-V", "Ctrl-=", "Ctrl--"],

_macReservedShortcuts = ["Cmd-,", "Cmd-H", "Cmd-Alt-H", "Cmd-M", "Cmd-Shift-Z", "Cmd-Q", "Cmd-=", "Cmd--"],

_keyNames = ["Up", "Down", "Left", "Right", "Backspace", "Enter", "Space", "Tab",

"PageUp", "PageDown", "Home", "End", "Insert", "Delete"];

/**

* Flag to show key binding errors in the key map file. Default is true and

* it will be set to false when reloading without extensions. This flag is not

* used to suppress errors in loading or parsing the key map file. So if the key

* map file is corrupt, then the error dialog still shows up.

*

* @private

* @type {boolean}

*/

let _showErrors = true;

/**

* Allow clients to toggle key binding

*

* @private

* @type {boolean}

*/

let _enabled = true;

/**

* Stack of registered global keydown hooks.

*

* @private

* @type {Array.<function(Event): boolean>}

*/

let _globalKeydownHooks = [];

/**

* States of Ctrl key down detection

*

* @private

* @enum {number}

*/

let CtrlDownStates = {

"NOT_YET_DETECTED": 0,

"DETECTED": 1,

"DETECTED_AND_IGNORED": 2 // For consecutive ctrl keydown events while a Ctrl key is being hold down

};

/**

* Flags used to determine whether right Alt key is pressed. When it is pressed,

* the following two keydown events are triggered in that specific order.

*

* 1. _ctrlDown - flag used to record { ctrlKey: true, keyIdentifier: "Control", ... } keydown event

* 2. _altGrDown - flag used to record { ctrlKey: true, altKey: true, keyIdentifier: "Alt", ... } keydown event

*

* @private

* @type {CtrlDownStates|boolean}

*/

let _ctrlDown = CtrlDownStates.NOT_YET_DETECTED,

_altGrDown = false;

/**

* Used to record the timeStamp property of the last keydown event.

*

* @private

* @type {number}

*/

let _lastTimeStamp;

/**

* Used to record the keyIdentifier property of the last keydown event.

*

* @private

* @type {string}

*/

let _lastKeyIdentifier;

/**

* Constant used for checking the interval between Control keydown event and Alt keydown event.

* If the right Alt key is down we get Control keydown followed by Alt keydown within 30 ms. if

* the user is pressing Control key and then Alt key, the interval will be larger than 30 ms.

*

* @private

* @type {number}

*/

let MAX_INTERVAL_FOR_CTRL_ALT_KEYS = 30;

/**

* Forward declaration for JSLint.

*

* @private

* @type {Function}

*/

let _onCtrlUp;

/**

* Resets all the flags and removes _onCtrlUp event listener.

*

* @private

*/

function _quitAltGrMode() {

_enabled = true;

_ctrlDown = CtrlDownStates.NOT_YET_DETECTED;

_altGrDown = false;

_lastTimeStamp = null;

_lastKeyIdentifier = null;

$(window).off("keyup", _onCtrlUp);

}

/**

* Detects the release of AltGr key by checking all keyup events

* until we receive one with ctrl key code. Once detected, reset

* all the flags and also remove this event listener.

*

* @private

* @param {!KeyboardEvent} e keyboard event object

*/

_onCtrlUp = function (e) {

let key = e.keyCode || e.which;

if (_altGrDown && key === KeyEvent.DOM_VK_CONTROL) {

_quitAltGrMode();

}

};

/**

* Detects whether AltGr key is pressed. When it is pressed, the first keydown event has

* ctrlKey === true with keyIdentifier === "Control". The next keydown event with

* altKey === true, ctrlKey === true and keyIdentifier === "Alt" is sent within 30 ms. Then

* the next keydown event with altKey === true, ctrlKey === true and keyIdentifier === "Control"

* is sent. If the user keep holding AltGr key down, then the second and third

* keydown events are repeatedly sent out alternately. If the user is also holding down Ctrl

* key, then either keyIdentifier === "Control" or keyIdentifier === "Alt" is repeatedly sent

* but not alternately.

*

* Once we detect the AltGr key down, then disable KeyBindingManager and set up a keyup

* event listener to detect the release of the altGr key so that we can re-enable KeyBindingManager.

* When we detect the addition of Ctrl key besides AltGr key, we also quit AltGr mode and re-enable

* KeyBindingManager.

*

* @private

* @param {!KeyboardEvent} e keyboard event object

*/

function _detectAltGrKeyDown(e) {

if (brackets.platform !== "win") {

return;

}

if (!_altGrDown) {

if (_ctrlDown !== CtrlDownStates.DETECTED_AND_IGNORED && e.ctrlKey && e.key === "Control") {

_ctrlDown = CtrlDownStates.DETECTED;

} else if (e.repeat && e.ctrlKey && e.key === "Control") {

// We get here if the user is holding down left/right Control key. Set it to false

// so that we don't misidentify the combination of Ctrl and Alt keys as AltGr key.

_ctrlDown = CtrlDownStates.DETECTED_AND_IGNORED;

} else if (_ctrlDown === CtrlDownStates.DETECTED && e.altKey && e.ctrlKey && e.key === "Alt" &&

(e.timeStamp - _lastTimeStamp) < MAX_INTERVAL_FOR_CTRL_ALT_KEYS) {

_altGrDown = true;

_lastKeyIdentifier = "Alt";

_enabled = false;

$(window).on("keyup", _onCtrlUp);

} else {

// Reset _ctrlDown so that we can start over in detecting the two key events

// required for AltGr key.

_ctrlDown = CtrlDownStates.NOT_YET_DETECTED;

}

_lastTimeStamp = e.timeStamp;

} else if (e.key === "Control" || e.key === "Alt") {

// If the user is NOT holding down AltGr key or is also pressing Ctrl key,

// then _lastKeyIdentifier will be the same as keyIdentifier in the current

// key event. So we need to quit AltGr mode to re-enable KBM.

if (e.altKey && e.ctrlKey && e.key === _lastKeyIdentifier) {

_quitAltGrMode();

} else {

_lastKeyIdentifier = e.key;

}

}

}

/**

* @private

*/

function _reset() {

_keyMap = {};

_defaultKeyMap = {};

_customKeyMap = {};

_customKeyMapCache = {};

_commandMap = {};

_globalKeydownHooks = [];

_userKeyMapFilePath = path.normalize(brackets.app.getApplicationSupportDirectory() + "/" + KEYMAP_FILENAME);

}

/**

* Initialize an empty keymap as the current keymap. It overwrites the current keymap if there is one.

* builds the keyDescriptor string from the given parts

*

* @private

* @param {boolean} hasCtrl Is Ctrl key enabled

* @param {boolean} hasAlt Is Alt key enabled

* @param {boolean} hasShift Is Shift key enabled

* @param {string} key The key that's pressed

* @return {string} The normalized key descriptor

*/

function _buildKeyDescriptor(hasMacCtrl, hasCtrl, hasAlt, hasShift, key) {

if (!key) {

console.log("KeyBindingManager _buildKeyDescriptor() - No key provided!");

return "";

}

let keyDescriptor = [];

if (hasMacCtrl) {

keyDescriptor.push("Ctrl");

}

if (hasAlt) {

keyDescriptor.push("Alt");

}

if (hasShift) {

keyDescriptor.push("Shift");

}

if (hasCtrl) {

// Windows display Ctrl first, Mac displays Command symbol last

if (brackets.platform === "mac") {

keyDescriptor.push("Cmd");

} else {

keyDescriptor.unshift("Ctrl");

}

}

keyDescriptor.push(key);

return keyDescriptor.join("-");

}

/**

* normalizes the incoming key descriptor so the modifier keys are always specified in the correct order

*

* @private

* @param {string} origDescriptor The string for a key descriptor, can be in any order, the result will be Ctrl-Alt-Shift-<Key>

* @return {string} The normalized key descriptor or null if the descriptor invalid

*/

function normalizeKeyDescriptorString(origDescriptor) {

let hasMacCtrl = false,

hasCtrl = false,

hasAlt = false,

hasShift = false,

key = "",

error = false;

function _compareModifierString(left, right) {

if (!left || !right) {

return false;

}

left = left.trim().toLowerCase();

right = right.trim().toLowerCase();

return (left.length > 0 && left === right);

}

origDescriptor.split("-").forEach(function parseDescriptor(ele, i, arr) {

if (_compareModifierString("ctrl", ele)) {

if (brackets.platform === "mac") {

hasMacCtrl = true;

} else {

hasCtrl = true;

}

} else if (_compareModifierString("cmd", ele)) {

if (brackets.platform === "mac") {

hasCtrl = true;

} else {

error = true;

}

} else if (_compareModifierString("alt", ele)) {

hasAlt = true;

} else if (_compareModifierString("opt", ele)) {

if (brackets.platform === "mac") {

hasAlt = true;

} else {

error = true;

}

} else if (_compareModifierString("shift", ele)) {

hasShift = true;

} else if (key.length > 0) {

console.log("KeyBindingManager normalizeKeyDescriptorString() - Multiple keys defined. Using key: " + key + " from: " + origDescriptor);

error = true;

} else {

key = ele;

}

});

if (error) {

return null;

}

// Check to see if the binding is for "-".

if (key === "" && origDescriptor.search(/^.+--$/) !== -1) {

key = "-";

}

// Check if it is a shift key only press

if (key === "" && origDescriptor.toLowerCase() === 'shift-shift') {

key = "Shift";

}

// '+' char is valid if it's the only key. Keyboard shortcut strings should use

// unicode characters (unescaped). Keyboard shortcut display strings may use

// unicode escape sequences (e.g. \u20AC euro sign)

if ((key.indexOf("+")) >= 0 && (key.length > 1)) {

return null;

}

// Ensure that the first letter of the key name is in upper case and the rest are

// in lower case. i.e. 'a' => 'A' and 'up' => 'Up'

if (/^[a-z]/i.test(key)) {

key = _.capitalize(key.toLowerCase());

}

// Also make sure that the second word of PageUp/PageDown has the first letter in upper case.

if (/^Page/.test(key)) {

key = key.replace(/(up|down)$/, function (match, p1) {

return _.capitalize(p1);

});

}

// No restriction on single character key yet, but other key names are restricted to either

// Function keys or those listed in _keyNames array.

if (key.length > 1 && !/F\d+/.test(key) &&

_keyNames.indexOf(key) === -1) {

return null;

}

return _buildKeyDescriptor(hasMacCtrl, hasCtrl, hasAlt, hasShift, key);

}

function _mapKeycodeToKeyLegacy(keycode) {

// https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/keyCode

// keycode is deprecated. We only use this in one edge case in mac listed in the caller.

// If keycode represents one of the digit keys (0-9), then return the corresponding digit

// by subtracting KeyEvent.DOM_VK_0 from keycode. ie. [48-57] --> [0-9]

if ((keycode >= KeyEvent.DOM_VK_0 && keycode <= KeyEvent.DOM_VK_9) ||

(keycode >= KeyEvent.DOM_VK_A && keycode <= KeyEvent.DOM_VK_Z)){

return String.fromCharCode(keycode);

// Do the same with the numpad numbers

// by subtracting KeyEvent.DOM_VK_NUMPAD0 from keycode. ie. [96-105] --> [0-9]

} else if (keycode >= KeyEvent.DOM_VK_NUMPAD0 && keycode <= KeyEvent.DOM_VK_NUMPAD9) {

return String.fromCharCode(keycode - KeyEvent.DOM_VK_NUMPAD0 + KeyEvent.DOM_VK_0);

}

switch (keycode) {

case KeyEvent.DOM_VK_SEMICOLON:

return ";";

case KeyEvent.DOM_VK_EQUALS:

return "=";

case KeyEvent.DOM_VK_COMMA:

return ",";

case KeyEvent.DOM_VK_SUBTRACT:

case KeyEvent.DOM_VK_DASH:

return "-";

case KeyEvent.DOM_VK_ADD:

return "+";

case KeyEvent.DOM_VK_DECIMAL:

case KeyEvent.DOM_VK_PERIOD:

return ".";

case KeyEvent.DOM_VK_DIVIDE:

case KeyEvent.DOM_VK_SLASH:

return "/";

case KeyEvent.DOM_VK_BACK_QUOTE:

return "`";

case KeyEvent.DOM_VK_OPEN_BRACKET:

return "[";

case KeyEvent.DOM_VK_BACK_SLASH:

return "\\";

case KeyEvent.DOM_VK_CLOSE_BRACKET:

return "]";

case KeyEvent.DOM_VK_QUOTE:

return "'";

default:

return null;

}

}

/**

* Looks for keycodes that have os-inconsistent keys and fixes them.

*

* @private

* @return {string} If the key is OS-inconsistent, the correct key; otherwise, the original key.

**/

// Maps a physical key code (event.code, which is keyboard-layout and input-method independent)

// to the key name used in keymaps. Used as a fallback when event.key is unusable.

const _CODE_TO_KEY = {

"Space": "Space",

"Enter": "Enter",

"NumpadEnter": "Enter",

"Tab": "Tab",

"Backspace": "Backspace",

"Delete": "Delete",

"Escape": "Esc",

"ArrowUp": "Up",

"ArrowDown": "Down",

"ArrowLeft": "Left",

"ArrowRight": "Right",

"Home": "Home",

"End": "End",

"PageUp": "PageUp",

"PageDown": "PageDown",

"Minus": "-",

"Equal": "=",

"BracketLeft": "[",

"BracketRight": "]",

"Backslash": "\\",

"Semicolon": ";",

"Quote": "'",

"Comma": ",",

"Period": ".",

"Slash": "/",

"Backquote": "`"

};

function _mapCodeToKey(code) {

if (!code) {

return null;

}

if (/^Key[A-Z]$/.test(code)) { // KeyA -> A

return code.slice(3);

}

if (/^Digit[0-9]$/.test(code)) { // Digit1 -> 1

return code.slice(5);

}

if (/^Numpad[0-9]$/.test(code)) { // Numpad1 -> 1

return code.slice(6);

}

return _CODE_TO_KEY[code] || null;

}

function _mapKeycodeToKey(event) {

// key code mapping https://developer.mozilla.org/en-US/docs/Web/API/UI_Events/Keyboard_event_code_values

if((event.ctrlKey || event.metaKey) && event.altKey && brackets.platform === "mac"){

// in mac, Cmd-alt-<shift?>-key are valid. But alt-key will trigger international keyboard typing and

// hence instead of Cmd-Alt-O, mac will get event Cmd-alt-Φ which is not what we want. So we will

// fallback to the deprecated keyCode event in the case

const key = _mapKeycodeToKeyLegacy(event.keyCode);

if(key){

return key;

}

}

const key = event.key;

// Some input methods (e.g. IBus/fcitx on Linux intercepting Ctrl-Space) deliver the event

// with key === "Unidentified"/"Dead". Fall back to the physical key code so shortcuts like

// Ctrl-Space still resolve correctly.

if (key === "Unidentified" || key === "Dead" || !key) {

const fromCode = _mapCodeToKey(event.code);

if (fromCode) {

return fromCode;

}

}

let codes = {

"ArrowUp": "Up",

"ArrowDown": "Down",

"ArrowLeft": "Left",

"ArrowRight": "Right",

" ": "Space"

};

if(codes[key]){

return codes[key];

}

return key;

}

/**

* Takes a keyboard event and translates it into a key in a key map

*

* @private

*/

function _translateKeyboardEvent(event) {

let hasMacCtrl = (brackets.platform === "mac") ? (event.ctrlKey) : false,

hasCtrl = (brackets.platform !== "mac") ? (event.ctrlKey) : (event.metaKey),

hasAlt = (event.altKey),

hasShift = (event.shiftKey),

key = _mapKeycodeToKey(event);

return normalizeKeyDescriptorString(_buildKeyDescriptor(hasMacCtrl, hasCtrl, hasAlt, hasShift, key));

}

/**

* Convert normalized key representation to display appropriate for platform.

*

* @param {!string} descriptor Normalized key descriptor.

* @return {!string} Display/Operating system appropriate string

*/

function formatKeyDescriptor(descriptor) {

let displayStr;

if (brackets.platform === "mac") {

displayStr = descriptor.replace(/-(?!$)/g, ""); // remove dashes

displayStr = displayStr.replace("Ctrl", "\u2303"); // Ctrl > control symbol

displayStr = displayStr.replace("Cmd", "\u2318"); // Cmd > command symbol

displayStr = displayStr.replace("Shift", "\u21E7"); // Shift > shift symbol

displayStr = displayStr.replace("Alt", "\u2325"); // Alt > option symbol

} else {

displayStr = descriptor.replace("Ctrl", Strings.KEYBOARD_CTRL);

displayStr = displayStr.replace("Shift", Strings.KEYBOARD_SHIFT);

displayStr = displayStr.replace(/-(?!$)/g, "+");

}

displayStr = displayStr.replace("Space", Strings.KEYBOARD_SPACE);

displayStr = displayStr.replace("PageUp", Strings.KEYBOARD_PAGE_UP);

displayStr = displayStr.replace("PageDown", Strings.KEYBOARD_PAGE_DOWN);

displayStr = displayStr.replace("Home", Strings.KEYBOARD_HOME);

displayStr = displayStr.replace("End", Strings.KEYBOARD_END);

displayStr = displayStr.replace("Ins", Strings.KEYBOARD_INSERT);

displayStr = displayStr.replace("Del", Strings.KEYBOARD_DELETE);

return displayStr;

}

/**

* @private

* @param {string} A normalized key-description string.

* @return {boolean} true if the key is already assigned, false otherwise.

*/

function _isKeyAssigned(key) {

return (_keyMap[key] !== undefined);

}

/**

* Remove a key binding from _keymap

*

* @param {!string} key - a key-description string that may or may not be normalized.

* @param {?string} [platform] - OS from which to remove the binding (all platforms if unspecified)

*/

function removeBinding(key, platform) {

if (!key || ((platform !== null) && (platform !== undefined) && (platform !== brackets.platform))) {

return;

}

let normalizedKey = normalizeKeyDescriptorString(key);

if (!normalizedKey) {

console.log("Failed to normalize " + key);

} else if (_isKeyAssigned(normalizedKey)) {

let binding = _keyMap[normalizedKey],

command = CommandManager.get(binding.commandID),

bindings = _commandMap[binding.commandID];

// delete key binding record

delete _keyMap[normalizedKey];

if (bindings) {

// delete mapping from command to key binding

_commandMap[binding.commandID] = bindings.filter(function (b) {

return (b.key !== normalizedKey);

});

if (command) {

command.trigger(EVENT_KEY_BINDING_REMOVED, {key: normalizedKey, displayKey: binding.displayKey});

exports.trigger(EVENT_KEY_BINDING_REMOVED, {

commandID: command.getID(),

key: normalizedKey,

displayKey: binding.displayKey

});

}

}

}

}

/**

* Updates _allCommands array and _defaultKeyMap with the new key binding

* if it is not yet in the _allCommands array. _allCommands array is initialized

* only in extensionsLoaded event. So any new commands or key bindings added after

* that will be updated here.

*

* @private

* @param {{commandID: string, key: string, displayKey:string, explicitPlatform: string}} newBinding

*/

function _updateCommandAndKeyMaps(newBinding) {

if (_allCommands.length === 0) {

return;

}

if (newBinding && newBinding.commandID && _allCommands.indexOf(newBinding.commandID) === -1) {

_defaultKeyMap[newBinding.commandID] = _.cloneDeep(newBinding);

// Process user key map again to catch any reassignment to all new key bindings added from extensions.

_loadUserKeyMap();

}

}

/**

* @private

*

* @param {string} commandID

* @param {string|{{key: string, displayKey: string}}} keyBinding - a single shortcut.

* @param {string?} platform

* - "all" indicates all platforms, not overridable

* - undefined indicates all platforms, overridden by platform-specific binding

* @param {boolean?} userBindings true if adding a user key binding or undefined otherwise.

* @param {boolean?} isMenuShortcut

* @return {?{key: string, displayKey:String}} Returns a record for valid key bindings.

* Returns null when key binding platform does not match, binding does not normalize,

* or is already assigned.

*/

function _addBinding(commandID, keyBinding, {platform, userBindings, isMenuShortcut}) {

knownBindableCommands.add(commandID);

let key,

result = null,

normalized,

normalizedDisplay,

explicitPlatform = keyBinding.platform || platform,

explicitBrowserOnly = keyBinding.browserOnly,

explicitNativeOnly = keyBinding.nativeOnly,

targetPlatform,

command,

bindingsToDelete = [],

existing;

if(Phoenix.isNativeApp && explicitBrowserOnly) {

return null;

}

if(!Phoenix.isNativeApp && explicitNativeOnly) {

return null;

}

// For platform: "all", use explicit current platform

if (explicitPlatform && explicitPlatform !== "all") {

targetPlatform = explicitPlatform;

} else {

targetPlatform = brackets.platform;

}

// Skip if the key binding is not for this platform.

if (explicitPlatform === "mac" && brackets.platform !== "mac") {

return null;

}

// if the request does not specify an explicit platform, and we're

// currently on a mac, then replace Ctrl with Cmd.

key = (keyBinding.key) || keyBinding;

if (brackets.platform === "mac" && (explicitPlatform === undefined || explicitPlatform === "all")) {

key = key.replace("Ctrl", "Cmd");

if (keyBinding.displayKey !== undefined) {

keyBinding.displayKey = keyBinding.displayKey.replace("Ctrl", "Cmd");

}

}

normalized = normalizeKeyDescriptorString(key);

// skip if the key binding is invalid

if (!normalized) {

console.error(`Unable to parse key binding '${key}' for command '${commandID}'. Permitted modifiers: Ctrl, Cmd, Alt, Opt, Shift; separated by '-' (not '+').`);

return null;

}

function isSingleCharAZ(str) {

return /^[A-Z]$/i.test(str);

}

const keySplit = normalized.split("-");

if(!isMenuShortcut && ((keySplit.length ===2 && keySplit[0] === 'Alt' && isSingleCharAZ(keySplit[1])) ||

(keySplit.length ===3 && keySplit[0] === 'Alt' && keySplit[1] === 'Shift' && isSingleCharAZ(keySplit[2])))){

console.error(`Key binding '${normalized}' for command '${commandID}' may cause issues. The key combinations starting with 'Alt-<letter>' and 'Alt-Shift-<letter>' are reserved. On macOS, they are used for AltGr internationalization, and on Windows/Linux, they are used for menu navigation shortcuts. If this is a menu shortcut, use 'isMenuShortcut' option.`);

}

// ctrl-alt-<key> events are allowed in all platforms. In windows ctrl-alt-<key> events are treated as altGr

// and used for international keyboards. But we have special handling for detecting alt gr key press that

// accounts for this and disables keybinding manager inwindows on detecting altGr key press.

// See _detectAltGrKeyDown function in this file.

// check for duplicate key bindings

existing = _keyMap[normalized];

// for cross-platform compatibility

if (exports.useWindowsCompatibleBindings) {

// windows-only key bindings are used as the default binding

// only if a default binding wasn't already defined

if (explicitPlatform === "win") {

// search for a generic or platform-specific binding if it

// already exists

if (existing && (!existing.explicitPlatform ||

existing.explicitPlatform === brackets.platform ||

existing.explicitPlatform === "all")) {

// do not clobber existing binding with windows-only binding

return null;

}

// target this windows binding for the current platform

targetPlatform = brackets.platform;

}

}

// skip if this binding doesn't match the current platform

if (targetPlatform !== brackets.platform) {

return null;

}

// skip if the key is already assigned

if (existing) {

if (!existing.explicitPlatform && explicitPlatform) {

// remove the the generic binding to replace with this new platform-specific binding

removeBinding(normalized);

existing = false;

}

}

// delete existing bindings when

// (1) replacing a windows-compatible binding with a generic or

// platform-specific binding

// (2) replacing a generic binding with a platform-specific binding

let existingBindings = _commandMap[commandID] || [],

isWindowsCompatible,

isReplaceGeneric,

ignoreGeneric;

existingBindings.forEach(function (binding) {

// remove windows-only bindings in _commandMap

isWindowsCompatible = exports.useWindowsCompatibleBindings &&

binding.explicitPlatform === "win";

// remove existing generic binding

isReplaceGeneric = !binding.explicitPlatform &&

explicitPlatform;

if (isWindowsCompatible || isReplaceGeneric) {

bindingsToDelete.push(binding);

} else {

// existing binding is platform-specific and the requested binding is generic

ignoreGeneric = binding.explicitPlatform && !explicitPlatform;

}

});

if (ignoreGeneric) {

// explicit command binding overrides this one

return null;

}

if (existing) {

// do not re-assign a key binding

if(commandID !== _keyMap[normalized].commandID) {

console.error("Cannot assign " + normalized + " to " + commandID + ". It is already assigned to " + _keyMap[normalized].commandID);

}// else the same shortcut is already there, do nothing

return null;

}

// remove generic or windows-compatible bindings

bindingsToDelete.forEach(function (binding) {

removeBinding(binding.key);

});

// optional display-friendly string (e.g. CMD-+ instead of CMD-=)

normalizedDisplay = (keyBinding.displayKey) ? normalizeKeyDescriptorString(keyBinding.displayKey) : normalized;

// 1-to-many commandID mapping to key binding

if (!_commandMap[commandID]) {

_commandMap[commandID] = [];

}

result = {

key: normalized,

displayKey: normalizedDisplay,

explicitPlatform: explicitPlatform

};

_commandMap[commandID].push(result);

// 1-to-1 key binding to commandID

_keyMap[normalized] = {

commandID: commandID,

key: normalized,

displayKey: normalizedDisplay,

explicitPlatform: explicitPlatform

};

if (!userBindings) {

_updateCommandAndKeyMaps(_keyMap[normalized]);

}

// notify listeners

command = CommandManager.get(commandID);

if (command) {

command.trigger(EVENT_KEY_BINDING_ADDED, result, commandID);

exports.trigger(EVENT_KEY_BINDING_ADDED, result, commandID);

}

return result;

}

/**

* Returns a copy of the current key map. If the optional 'defaults' parameter is true,

* then a copy of the default key map is returned.

* In the default keymap each key is associated with an object containing `commandID`, `key`, and `displayKey`.

*

* @param {boolean=} defaults true if the caller wants a copy of the default key map. Otherwise, the current active key map is returned.

* @return {Object}

*/

function getKeymap(defaults) {

return $.extend({}, defaults ? _defaultKeyMap : _keyMap);

}

function _makeMapFromArray(map, arr){

for(let item of arr) {

map[item] = true;

}

return map;

}

/**

* If there is a registered and enabled key event, we always mark the event as processed

* except the ones in UN_SWALLOWED_EVENTS.

*

* @private

* @type {Array.<string>}

*/

const UN_SWALLOWED_EVENTS = _makeMapFromArray({}, [

Commands.EDIT_SELECT_ALL,

Commands.EDIT_UNDO,

Commands.EDIT_REDO,

Commands.EDIT_CUT,

Commands.EDIT_COPY,

Commands.EDIT_PASTE

]);

// single keys except function keys and key combinations are never swallowed. Áka we want default behavior

// for the below keys if the command handler for the registered key didnt do anything.

let UN_SWALLOWED_KEYS = _makeMapFromArray({},

_keyNames.concat(_reservedShortcuts)

.concat(_macReservedShortcuts));

function _isUnSwallowedKeys(key) {

return UN_SWALLOWED_KEYS[key] || key.length === 1; // keys like a-z, 0-9 etc

}

/**

* Process the keybinding for the current key.

*

* @private

* @param {string} key A key-description string.