bm-core-ui 2.9.5 → 2.10.1

package/build/BMWindow/BMKeyboardShortcut.js

@@ -1,6 +1,27 @@
 // @ts-check
 
-import { NO } from "../Core/BMCoreUI";
+import { BMHTMLEntity, NO } from "../Core/BMCoreUI";
+
+/**
+ * A dictionary that contains the mapping between key codes and the character
+ * symbols that represent them.
+ */
+const _BMKeyboardShortcutCharacterMap = {
+    Backquote: '`',
+    Minus: '-',
+    Equal: '=',
+    BracketLeft: '[',
+    BracketRight: ']',
+    Backslash: '\\',
+    Semicolon: ';',
+    Quote: '\'',
+    Comma: ',',
+    Period: '.',
+    Slash: '/',
+    Enter: BMHTMLEntity.Return,
+    Escape: BMHTMLEntity.Escape,
+    Backspace: BMHTMLEntity.Delete,
+};
 
 // @type BMKeyboardShortcutModifier
 
@@ -10,44 +31,44 @@ import { NO } from "../Core/BMCoreUI";
  */
 export const BMKeyboardShortcutModifier = Object.freeze({ // <enum>
 
-	/**
-	 * Represents the command key on macOS and iOS, windows key on Windows and meta key on Linux.
-	 */
-	Command: {key: 'metaKey', value: 1}, // <enum>
+    /**
+     * Represents the command key on macOS and iOS, windows key on Windows and meta key on Linux.
+     */
+    Command: {key: 'metaKey', value: 1}, // <enum>
 
-	/**
-	 * Represents the option key on macOS and alt on other systems.
-	 */
-	Option: {key: 'altKey', value: 2}, // <enum>
+    /**
+     * Represents the option key on macOS and alt on other systems.
+     */
+    Option: {key: 'altKey', value: 2}, // <enum>
 
-	/**
-	 * Represents the shit key.
-	 */
-	Shift: {key: 'shiftKey', value: 4}, // <enum>
+    /**
+     * Represents the shit key.
+     */
+    Shift: {key: 'shiftKey', value: 4}, // <enum>
 
-	/**
-	 * Represents the control key.
-	 */
-	Control: {key: 'ctrlKey', value: 8}, // <enum>
+    /**
+     * Represents the control key.
+     */
+    Control: {key: 'ctrlKey', value: 8}, // <enum>
 
-	/**
-	 * Represents the command key on macOS and iOS and control key on other systems.
-	 */
-	System: {key: 'systemKey', value: (navigator.platform.startsWith('Mac') || /iPhone|iPad|iPod/.test(navigator.platform)) ? 1 : 8}, // <enum>
+    /**
+     * Represents the command key on macOS and iOS and control key on other systems.
+     */
+    System: {key: 'systemKey', value: (navigator.platform.startsWith('Mac') || /iPhone|iPad|iPod/.test(navigator.platform)) ? 1 : 8}, // <enum>
 
 });
 
 // @endtype
 
-// @type BMKeyboardShortcut
+// @type BMKeySequence
 
 /**
- * A keyboard shortcut object describes the keys that must be pressed for a keyboard shortcut to trigger as
- * well as what should happen when that shortcut is triggered.
+ * A class whose instances describe sequences of keys on a keyboard that must be
+ * pressed for an action to take place.
  */
-export function BMKeyboardShortcut() {} // <constructor>
+export function BMKeySequence() {} // <constructor>
 
-BMKeyboardShortcut.prototype = {
+BMKeySequence.prototype = {
 
     /**
      * The key that should be pressed for this keyboard shortcut.
@@ -58,7 +79,7 @@ BMKeyboardShortcut.prototype = {
     },
 
     /**
-     * An optional array of keyboard modifiers that must be pressed
+     * An array of keyboard modifiers that must be pressed
      * together with the key in order to trigger the shortcut.
      */
     _modifiers: undefined, // <[BMKeyboardShortcutModifier]>
@@ -66,6 +87,196 @@ BMKeyboardShortcut.prototype = {
         if (this._modifiers) return this._modifiers.slice();
     },
 
+    /**
+     * Designated initializer. Initializes this key sequence with the specified key and optional modifiers.
+     * @param key <String>                                              The key that should be pressed for this key sequence.
+     *                                                                  This maps to the `code` property of keyboard events.
+     * {
+     * 	@param modifiers <[BMKeyboardShortcutModifier], nullable>		Defaults to an empty array. An optional array of modifiers
+     *                                                                  that must be pressed together with the target key.
+     * }
+     * @return <BMKeySequence>                                          This key sequence.
+     */
+    initWithKeyCode(key, {modifiers} = {modifiers: []}) {
+        this._key = key;
+        this._modifiers = modifiers?.slice() ?? [];
+
+        for (const modifier of this._modifiers) {
+            this._modifierBitmap = this._modifierBitmap | modifier.value;
+        }
+
+        return this;
+    },
+
+    /**
+     * Initializes this key sequence with the specified keyboard event, using the event's key code
+     * and any active modifier keys. If the event includes the control or command keys, these may be converted
+     * into a system key modifier based on the current platform.
+     * @param event <KeyboardEvent>         The keyboard event from which this key sequence should be initialized.
+     * @return <BMKeySequence>              This key sequence.
+     */
+    initWithKeyboardEvent(event) {
+        const modifiers = [];
+        if (event.shiftKey) {
+            modifiers.push(BMKeyboardShortcutModifier.Shift);
+        }
+        if (event.altKey) {
+            modifiers.push(BMKeyboardShortcutModifier.Option);
+        }
+        if (event.metaKey) {
+            if (BMKeyboardShortcutModifier.System.value == BMKeyboardShortcutModifier.Command.value) {
+                modifiers.push(BMKeyboardShortcutModifier.System);
+            }
+            else {
+                modifiers.push(BMKeyboardShortcutModifier.Command);
+            }
+        }
+        if (event.ctrlKey) {
+            if (BMKeyboardShortcutModifier.System.value == BMKeyboardShortcutModifier.Control.value) {
+                modifiers.push(BMKeyboardShortcutModifier.System);
+            }
+            else {
+                modifiers.push(BMKeyboardShortcutModifier.Control);
+            }
+        }
+
+        return this.initWithKeyCode(event.code, {modifiers});
+    },
+
+    /**
+     * A string description of this key sequence, intended to be displayed to end-users.
+     * Its format depends on the current platform.
+     */
+    get HTMLDescription() { // <String>
+        let representation = '';
+        const code = this.keyCode || '';
+
+        if (code.startsWith('Key')) {
+            // Alphanumeric keys can be extracted from the key code
+            representation = code.substring(3);
+        }
+        else if (code.startsWith('Digit')) {
+            // Digit keys can also be extracted from the key code
+            representation = code.substring(5);
+        }
+        else {
+            // Otherwise use the character code map, defaulting to showing the code otherwise
+            representation = _BMKeyboardShortcutCharacterMap[code] || code;
+        }
+
+        const isAppleSystem = (navigator.platform.startsWith('Mac') || /iPhone|iPad|iPod/.test(navigator.platform));
+
+        // Add the modifier keys
+        if (this.modifiers.includes(BMKeyboardShortcutModifier.System)) {
+            if (isAppleSystem) {
+                representation = BMHTMLEntity.Command + representation;
+            }
+            else {
+                representation = 'Ctrl + ' + representation;
+            }
+        }
+
+        if (this.modifiers.includes(BMKeyboardShortcutModifier.Command)) {
+            if (isAppleSystem) {
+                representation = BMHTMLEntity.Command + representation;
+            }
+            else {
+                representation = 'Win + ' + representation;
+            }
+        }
+
+        if (this.modifiers.includes(BMKeyboardShortcutModifier.Shift)) {
+            if (isAppleSystem) {
+                representation = BMHTMLEntity.Shift + representation;
+            }
+            else {
+                representation = 'Shift + ' + representation;
+            }
+        }
+        
+        if (this.modifiers.includes(BMKeyboardShortcutModifier.Option)) {
+            if (isAppleSystem) {
+                representation = BMHTMLEntity.Option + representation;
+            }
+            else {
+                representation = 'Alt + ' + representation;
+            }
+        }
+
+        if (this.modifiers.includes(BMKeyboardShortcutModifier.Control)) {
+            if (isAppleSystem) {
+                representation = BMHTMLEntity.Control + representation;
+            }
+            else {
+                representation = 'Ctrl + ' + representation;
+            }
+        }
+
+        return representation;
+    }
+};
+
+/**
+ * Creates and returns a key sequence initialized with the specified key and optional modifiers.
+ * @param key <String>                                              The key that should be pressed for this key sequence.
+ *                                                                  This maps to the `code` property of keyboard events.
+ * {
+ * 	@param modifiers <[BMKeyboardShortcutModifier], nullable>		Defaults to an empty array. An optional array of modifiers
+ *                                                                  that must be pressed together with the target key.
+ * }
+ * @return <BMKeySequence>                                          This key sequence.
+ */
+BMKeySequence.keySequenceWithKeyCode = function (key, args) {
+    return new this().initWithKeyCode(key, args);
+};
+
+/**
+ * Creates and returns a key sequence initialized with the specified keyboard event, using the event's key code
+ * and any active modifier keys. If the event includes the control or command keys, these may be converted
+ * into a system key modifier based on the current platform.
+ * @param event <KeyboardEvent>         The keyboard event from which this key sequence should be initialized.
+ * @return <BMKeySequence>              This key sequence.
+ */
+BMKeySequence.keySequenceWithKeyboardEvent = function (event) {
+    return new this().initWithKeyboardEvent(event);
+}
+
+// @endtype
+
+// @type BMKeyboardShortcut
+
+/**
+ * A keyboard shortcut object describes the keys that must be pressed for a keyboard shortcut to trigger as
+ * well as what should happen when that shortcut is triggered.
+ */
+export function BMKeyboardShortcut() {} // <constructor>
+
+BMKeyboardShortcut.prototype = {
+
+    /**
+     * The key sequence that should be pressed to trigger this keyboard shortcut.
+     */
+    _keySequence: undefined, // <BMKeySequence>
+    get keySequence() {
+        return this._keySequence;
+    },
+
+    /**
+     * The key that should be pressed for this keyboard shortcut.
+     */
+    get keyCode() { // <String>
+        return this._keySequence._key;
+    },
+
+    /**
+     * An array of keyboard modifiers that must be pressed
+     * together with the key in order to trigger the shortcut.
+     */
+    get modifiers() { // <[BMKeyboardShortcutModifier]>
+        if (this._keySequence._modifiers) return this._keySequence._modifiers.slice();
+        return [];
+    },
+
     /**
      * A bitmap describing the modifiers that should be active.
      */
@@ -101,7 +312,38 @@ BMKeyboardShortcut.prototype = {
     preventsDefault: NO, // <Boolean>
 
     /**
-     * Designated initializer. Initializes this keyboard shortcut with the given key and optional modifiers, as well as
+     * Designated Initializer. Initializes this keyboard shortcut with the specified key sequence and the action that the
+     * keyboard shortcut should trigger.
+     * @param keySequence <BMKeySequence>               The key sequence describing the keyboard buttons that
+     *                                                  should be pressed to trigger this keyboard shortcut.
+     * {
+     * 	@param target <AnyObject>						The object that will handle this keyboard shortcut action.
+     * 	@param action <String>							The name of a method on the target object that will be invoked when this 
+     * 													keyboard shortcut is triggered. That method will receive the following arguments:
+     * 
+     *  - `event`: {@link KeyboardEvent} The keyboard event that triggered the keyboard shortcut
+     *  - `{forKeyboardShortcut}`: {@link BMKeyboardShortcut} The associated keyboard shortcut
+     *  @param preventsDefault <Boolean, nullable>      Defaults to `NO`. When set to `YES`, the default action of the event that triggers
+     *                                                  normally as a result of the key sequence will be prevented.
+     * }
+     * @return <BMKeyboardShortcut>                     This keyboard shortcut.
+     */
+    initWithKeySequence(keySequence, {target, action, preventsDefault} = {}) {
+        this._keySequence = keySequence;
+
+        this._target = target;
+        this._action = action;
+        this.preventsDefault = preventsDefault || NO;
+
+        for (const modifier of this.modifiers) {
+            this._modifierBitmap = this._modifierBitmap | modifier.value;
+        }
+
+        return this;
+    },
+
+    /**
+     * Initializes this keyboard shortcut with the given key and optional modifiers, as well as
      * the target and action that will handle it.
      * 
      * In order to be triggered, this keyboard shortcut must be registered with an event handler such as a window
@@ -110,65 +352,44 @@ BMKeyboardShortcut.prototype = {
      * {
      * 	@param modifiers <[BMKeyboardShortcutModifier], nullable>		Defaults to an empty array. An optional array of keyboard modifiers that must be active.
      * 																	for the keyboard shortcut to fire.
-     * 	@param target <AnyObject>										The object that will handle this keyboard shortcut action.
-     * 	@param action <String>											The name of a method on the target object that will be invoked when this 
-     * 																	keyboard shortcut is triggered. That method will receive the keyboard event as its single parameter.
-     *  @param preventsDefault <Boolean, nullable>                      Defaults to `NO`. When set to `YES`, the default action of the event that triggers this keyboard shortcut will be prevented.
+     * 	@param target <AnyObject>						                The object that will handle this keyboard shortcut action.
+     * 	@param action <String>							                The name of a method on the target object that will be invoked when this 
+     * 													                keyboard shortcut is triggered. That method will receive the following arguments:
+     * 
+     *  - `event`: {@link KeyboardEvent} The keyboard event that triggered the keyboard shortcut
+     *  - `{forKeyboardShortcut}`: {@link BMKeyboardShortcut} The associated keyboard shortcut
+     *  @param preventsDefault <Boolean, nullable>                      Defaults to `NO`. When set to `YES`, the default action of the event that triggers
+     *                                                                  normally as a result of the key sequence will be prevented.
      * }
      * @return <BMKeyboardShortcut>                                     This keyboard shortcut.
      */
     initWithKeyCode(key, {modifiers, target, action, preventsDefault} = {modifiers: []}) {
-        this._key = key;
-        this._modifiers = modifiers || [];
-        this._target = target;
-        this._action = action;
-        this.preventsDefault = preventsDefault || NO;
+        const keySequence = new BMKeySequence().initWithKeyCode(key, {modifiers});
+        this._keySequence = keySequence;
 
-        for (const modifier of this._modifiers) {
-            this._modifierBitmap = this._modifierBitmap | modifier.value;
-        }
-
-        return this;
+        return this.initWithKeySequence(keySequence, {target, action, preventsDefault});
     },
 
     /**
      * Initializes this keyboard shortcut with the given keyboard event. If the event includes the control or command keys, these may be converted
      * into a system key modifier based on the current platform.
-     * @param event <KeyboardEvent>                                     The keyboard event from which this keyboard shortcut should be initialized.
+     * @param event <KeyboardEvent>                     The keyboard event from which this keyboard shortcut should be initialized.
      * {
-     * 	@param target <AnyObject>										The object that will handle this keyboard shortcut action.
-     * 	@param action <String>											The name of a method on the target object that will be invoked when this 
-     * 																	keyboard shortcut is triggered. That method will receive the keyboard event as its single parameter.
-     *  @param preventsDefault <Boolean, nullable>                      Defaults to `NO`. When set to `YES`, the default action of the event that triggers this keyboard shortcut will be prevented.
-     * }
+     * 	@param target <AnyObject>						The object that will handle this keyboard shortcut action.
+     * 	@param action <String>							The name of a method on the target object that will be invoked when this 
+     * 													keyboard shortcut is triggered. That method will receive the following arguments:
      * 
+     *  - `event`: {@link KeyboardEvent} The keyboard event that triggered the keyboard shortcut
+     *  - `{forKeyboardShortcut}`: {@link BMKeyboardShortcut} The associated keyboard shortcut
+     *  @param preventsDefault <Boolean, nullable>      Defaults to `NO`. When set to `YES`, the default action of the event that triggers
+     *                                                  normally as a result of the key sequence will be prevented.
+     * }
+     * @return <BMKeyboardShortcut>                                     This keyboard shortcut.
      */
     initWithKeyboardEvent(event, {target, action, preventsDefault} = {}) {
-        const modifiers = [];
-        if (event.shiftKey) {
-            modifiers.push(BMKeyboardShortcutModifier.Shift);
-        }
-        if (event.altKey) {
-            modifiers.push(BMKeyboardShortcutModifier.Option);
-        }
-        if (event.metaKey) {
-            if (BMKeyboardShortcutModifier.System.value == BMKeyboardShortcutModifier.Command.value) {
-                modifiers.push(BMKeyboardShortcutModifier.System);
-            }
-            else {
-                modifiers.push(BMKeyboardShortcutModifier.Command);
-            }
-        }
-        if (event.ctrlKey) {
-            if (BMKeyboardShortcutModifier.System.value == BMKeyboardShortcutModifier.Control.value) {
-                modifiers.push(BMKeyboardShortcutModifier.System);
-            }
-            else {
-                modifiers.push(BMKeyboardShortcutModifier.Control);
-            }
-        }
+        const keySequence = new BMKeySequence().initWithKeyboardEvent(event);
 
-        return this.initWithKeyCode(event.code, {modifiers, target, action, preventsDefault});
+        return this.initWithKeySequence(keySequence, {target, action, preventsDefault});
     },
 
     /**
@@ -179,7 +400,7 @@ BMKeyboardShortcut.prototype = {
      *  @param targetID <Object ^(String)>      A callback that is invoked with the target ID and should return
      *                                          the target object which will handle the keyboard shortcut.
      * }
-     * @returns <Object>                        This keyboard shortcut.
+     * @returns <BMKeyboardShortcut>            This keyboard shortcut.
      */
     initWithSerializedKeyboardShortcut(shortcut, {targetID: resolver}) {
         if (shortcut._class != 'BMKeyboardShortcut') {
@@ -188,8 +409,9 @@ BMKeyboardShortcut.prototype = {
 
         const target = resolver(shortcut._targetID);
 
+        const modifierValues = Object.values(BMKeyboardShortcutModifier);
         const modifiers = shortcut._modifiers.map(modifier => {
-            return Object.values(BMKeyboardShortcutModifier).find(m => m.key == modifier)
+            return modifierValues.find(m => m.key == modifier)
         });
 
         return this.initWithKeyCode(shortcut._key, {modifiers, target, action: shortcut._action, preventsDefault: shortcut._preventsDefault});
@@ -205,8 +427,8 @@ BMKeyboardShortcut.prototype = {
     serializedKeyboardShortcutWithTargetID(ID) {
         return {
             _class: `BMKeyboardShortcut`,
-            _key: this._key,
-            _modifiers: this._modifiers.map(m => m.key),
+            _key: this.keyCode,
+            _modifiers: this.modifiers.map(m => m.key),
             _targetID: ID,
             _action: this._action,
             _preventsDefault: this.preventsDefault,
@@ -215,6 +437,27 @@ BMKeyboardShortcut.prototype = {
 
 };
 
+/**
+ * Constructs and returns a keyboard shortcut with the specified key sequence and action that will be triggered
+ * by the keyboard shortcut.
+ * @param keySequence <BMKeySequence>                   The key sequence describing the keys that should be pressed to
+ *                                                      trigger this shortcut.s
+ * {
+ * 	@param target <AnyObject>						    The object that will handle this keyboard shortcut action.
+ * 	@param action <String>							    The name of a method on the target object that will be invoked when this 
+ * 													    keyboard shortcut is triggered. That method will receive the following arguments:
+ * 
+ *  - `event`: {@link KeyboardEvent} The keyboard event that triggered the keyboard shortcut
+ *  - `{forKeyboardShortcut}`: {@link BMKeyboardShortcut} The associated keyboard shortcut
+ *  @param preventsDefault <Boolean, nullable>          Defaults to `NO`. When set to `YES`, the default action of the event that triggers
+ *                                                      normally as a result of the key sequence will be prevented.
+ * }
+ * @return <BMKeyboardShortcut>                         A keyboard shortcut.
+ */
+BMKeyboardShortcut.keyboardShortcutWithKeySequence = function (event, args) {
+    return (new BMKeyboardShortcut).initWithKeySequence(event, args);
+};
+
 /**
  * Constructs and returns a keyboard shortcut with the given key and optional modifiers, as well as
  * the target and action that will handle it.
@@ -225,10 +468,14 @@ BMKeyboardShortcut.prototype = {
  * {
  * 	@param modifiers <[BMKeyboardShortcutModifier], nullable>		Defaults to an empty array. An optional array of keyboard modifiers that must be active.
  * 																	for the keyboard shortcut to fire.
- * 	@param target <AnyObject>										The object that will handle this keyboard shortcut action.
- * 	@param action <String>											The name of a method on the target object that will be invoked when this 
- * 																	keyboard shortcut is triggered. That method will receive the keyboard event as its single parameter.
- *  @param preventsDefault <Boolean, nullable>                      Defaults to `NO`. When set to `YES`, the default action of the event that triggers this keyboard shortcut will be prevented.
+ * 	@param target <AnyObject>						                The object that will handle this keyboard shortcut action.
+ * 	@param action <String>							                The name of a method on the target object that will be invoked when this 
+ * 													                keyboard shortcut is triggered. That method will receive the following arguments:
+ * 
+ *  - `event`: {@link KeyboardEvent} The keyboard event that triggered the keyboard shortcut
+ *  - `{forKeyboardShortcut}`: {@link BMKeyboardShortcut} The associated keyboard shortcut
+ *  @param preventsDefault <Boolean, nullable>                      Defaults to `NO`. When set to `YES`, the default action of the event that triggers
+ *                                                                  normally as a result of the key sequence will be prevented.
  * }
  * @return <BMKeyboardShortcut>                                     A keyboard shortcut.
  */
@@ -236,18 +483,21 @@ BMKeyboardShortcut.keyboardShortcutWithKeyCode = function (key, args) {
     return (new BMKeyboardShortcut).initWithKeyCode(key, args);
 };
 
-
 /**
  * Constructs and returns a keyboard shortcut with the given keyboard event. If the event includes the control or command keys, these may be converted
  * into a system key modifier based on the current platform.
- * @param event <KeyboardEvent>                                     The keyboard event from which this keyboard shortcut should be initialized.
+ * @param event <KeyboardEvent>                         The keyboard event from which this keyboard shortcut should be initialized.
  * {
- * 	@param target <AnyObject>										The object that will handle this keyboard shortcut action.
- * 	@param action <String>											The name of a method on the target object that will be invoked when this 
- * 																	keyboard shortcut is triggered. That method will receive the keyboard event as its single parameter.
- *  @param preventsDefault <Boolean, nullable>                      Defaults to `NO`. When set to `YES`, the default action of the event that triggers this keyboard shortcut will be prevented.
- * }
+ * 	@param target <AnyObject>						    The object that will handle this keyboard shortcut action.
+ * 	@param action <String>							    The name of a method on the target object that will be invoked when this 
+ * 													    keyboard shortcut is triggered. That method will receive the following arguments:
  * 
+ *  - `event`: {@link KeyboardEvent} The keyboard event that triggered the keyboard shortcut
+ *  - `{forKeyboardShortcut}`: {@link BMKeyboardShortcut} The associated keyboard shortcut
+ *  @param preventsDefault <Boolean, nullable>          Defaults to `NO`. When set to `YES`, the default action of the event that triggers
+ *                                                      normally as a result of the key sequence will be prevented.
+ * }
+ * @return <BMKeyboardShortcut>                         A keyboard shortcut.
  */
 BMKeyboardShortcut.keyboardShortcutWithKeyboardEvent = function (event, args) {
     return (new BMKeyboardShortcut).initWithKeyboardEvent(event, args);
@@ -261,7 +511,7 @@ BMKeyboardShortcut.keyboardShortcutWithKeyboardEvent = function (event, args) {
  *  @param targetID <Object ^(String)>      A callback that is invoked with the target ID and should return
  *                                          the target object which will handle the keyboard shortcut.
  * }
- * @returns <Object>                        A keyboard shortcut.
+ * @returns <BMKeyboardShortcut, nullable>  A keyboard shortcut.
  */
 BMKeyboardShortcut.keyboardShortcutWithSerializedKeyboardShortcut = function (shortcut, args) {
     return (new BMKeyboardShortcut).initWithSerializedKeyboardShortcut(shortcut, args);