blockly 8.0.5 → 9.0.0-beta.0

package/core/{shortcut_items.js → shortcut_items.ts}

@@ -7,75 +7,72 @@
 /**
  * @fileoverview Registers default keyboard shortcuts.
  */
-'use strict';
 
 /**
  * Registers default keyboard shortcuts.
  * @namespace Blockly.ShortcutItems
  */
-goog.module('Blockly.ShortcutItems');
+import * as goog from '../closure/goog/goog.js';
+goog.declareModuleId('Blockly.ShortcutItems');
 
-const clipboard = goog.require('Blockly.clipboard');
-const common = goog.require('Blockly.common');
-/* eslint-disable-next-line no-unused-vars */
-const {BlockSvg} = goog.requireType('Blockly.BlockSvg');
-const {Gesture} = goog.require('Blockly.Gesture');
-/* eslint-disable-next-line no-unused-vars */
-const {ICopyable} = goog.requireType('Blockly.ICopyable');
-const {KeyCodes} = goog.require('Blockly.utils.KeyCodes');
-const {ShortcutRegistry} = goog.require('Blockly.ShortcutRegistry');
+import {BlockSvg} from './block_svg.js';
+import * as clipboard from './clipboard.js';
+import * as common from './common.js';
+import {Gesture} from './gesture.js';
+import type {ICopyable} from './interfaces/i_copyable.js';
+import {KeyboardShortcut, ShortcutRegistry} from './shortcut_registry.js';
+import {KeyCodes} from './utils/keycodes.js';
+import type {WorkspaceSvg} from './workspace_svg.js';
 
 
 /**
  * Object holding the names of the default shortcut items.
- * @enum {string}
  * @alias Blockly.ShortcutItems.names
  */
-const names = {
-  ESCAPE: 'escape',
-  DELETE: 'delete',
-  COPY: 'copy',
-  CUT: 'cut',
-  PASTE: 'paste',
-  UNDO: 'undo',
-  REDO: 'redo',
-};
-exports.names = names;
+export enum names {
+  ESCAPE = 'escape',
+  DELETE = 'delete',
+  COPY = 'copy',
+  CUT = 'cut',
+  PASTE = 'paste',
+  UNDO = 'undo',
+  REDO = 'redo'
+}
 
 /**
  * Keyboard shortcut to hide chaff on escape.
  * @alias Blockly.ShortcutItems.registerEscape
  */
-const registerEscape = function() {
-  /** @type {!ShortcutRegistry.KeyboardShortcut} */
-  const escapeAction = {
+export function registerEscape() {
+  const escapeAction: KeyboardShortcut = {
     name: names.ESCAPE,
-    preconditionFn: function(workspace) {
+    preconditionFn(workspace) {
       return !workspace.options.readOnly;
     },
-    callback: function(workspace) {
-      workspace.hideChaff();
+    callback(workspace) {
+      // AnyDuringMigration because:  Property 'hideChaff' does not exist on
+      // type 'Workspace'.
+      (workspace as AnyDuringMigration).hideChaff();
       return true;
     },
+    keyCodes: [KeyCodes.ESC],
   };
   ShortcutRegistry.registry.register(escapeAction);
-  ShortcutRegistry.registry.addKeyMapping(KeyCodes.ESC, escapeAction.name);
-};
-exports.registerEscape = registerEscape;
+}
 
 /**
  * Keyboard shortcut to delete a block on delete or backspace
  * @alias Blockly.ShortcutItems.registerDelete
  */
-const registerDelete = function() {
-  /** @type {!ShortcutRegistry.KeyboardShortcut} */
-  const deleteShortcut = {
+export function registerDelete() {
+  const deleteShortcut: KeyboardShortcut = {
     name: names.DELETE,
-    preconditionFn: function(workspace) {
+    preconditionFn(workspace) {
       const selected = common.getSelected();
-      return !workspace.options.readOnly && selected && selected.isDeletable();
+      return !workspace.options.readOnly && selected != null &&
+          selected.isDeletable();
     },
-    callback: function(workspace, e) {
+    callback(workspace, e) {
       // Delete or backspace.
       // Stop the browser from going back to the previous page.
       // Do this first to prevent an error in the delete code from resulting in
@@ -85,210 +82,178 @@ const registerDelete = function() {
       if (Gesture.inProgress()) {
         return false;
       }
-      (/** @type {!BlockSvg} */ (common.getSelected())).checkAndDelete();
+      (common.getSelected() as BlockSvg).checkAndDelete();
       return true;
     },
+    keyCodes: [KeyCodes.DELETE, KeyCodes.BACKSPACE],
   };
   ShortcutRegistry.registry.register(deleteShortcut);
-  ShortcutRegistry.registry.addKeyMapping(KeyCodes.DELETE, deleteShortcut.name);
-  ShortcutRegistry.registry.addKeyMapping(
-      KeyCodes.BACKSPACE, deleteShortcut.name);
-};
-exports.registerDelete = registerDelete;
+}
 
 /**
  * Keyboard shortcut to copy a block on ctrl+c, cmd+c, or alt+c.
  * @alias Blockly.ShortcutItems.registerCopy
  */
-const registerCopy = function() {
-  /** @type {!ShortcutRegistry.KeyboardShortcut} */
-  const copyShortcut = {
+export function registerCopy() {
+  const ctrlC = ShortcutRegistry.registry.createSerializedKey(
+      KeyCodes.C, [KeyCodes.CTRL]);
+  const altC =
+      ShortcutRegistry.registry.createSerializedKey(KeyCodes.C, [KeyCodes.ALT]);
+  const metaC = ShortcutRegistry.registry.createSerializedKey(
+      KeyCodes.C, [KeyCodes.META]);
+
+  const copyShortcut: KeyboardShortcut = {
     name: names.COPY,
-    preconditionFn: function(workspace) {
+    preconditionFn(workspace) {
       const selected = common.getSelected();
-      return !workspace.options.readOnly && !Gesture.inProgress() && selected &&
-          selected.isDeletable() && selected.isMovable();
+      return !workspace.options.readOnly && !Gesture.inProgress() &&
+          selected != null && selected.isDeletable() && selected.isMovable();
     },
-    callback: function(workspace, e) {
+    callback(workspace, e) {
       // Prevent the default copy behavior, which may beep or otherwise indicate
       // an error due to the lack of a selection.
       e.preventDefault();
-      workspace.hideChaff();
-      clipboard.copy(/** @type {!ICopyable} */ (common.getSelected()));
+      // AnyDuringMigration because:  Property 'hideChaff' does not exist on
+      // type 'Workspace'.
+      (workspace as AnyDuringMigration).hideChaff();
+      clipboard.copy(common.getSelected() as ICopyable);
       return true;
     },
+    keyCodes: [ctrlC, altC, metaC],
   };
   ShortcutRegistry.registry.register(copyShortcut);
-
-  const ctrlC = ShortcutRegistry.registry.createSerializedKey(
-      KeyCodes.C, [KeyCodes.CTRL]);
-  ShortcutRegistry.registry.addKeyMapping(ctrlC, copyShortcut.name);
-
-  const altC =
-      ShortcutRegistry.registry.createSerializedKey(KeyCodes.C, [KeyCodes.ALT]);
-  ShortcutRegistry.registry.addKeyMapping(altC, copyShortcut.name);
-
-  const metaC = ShortcutRegistry.registry.createSerializedKey(
-      KeyCodes.C, [KeyCodes.META]);
-  ShortcutRegistry.registry.addKeyMapping(metaC, copyShortcut.name);
-};
-exports.registerCopy = registerCopy;
+}
 
 /**
  * Keyboard shortcut to copy and delete a block on ctrl+x, cmd+x, or alt+x.
  * @alias Blockly.ShortcutItems.registerCut
  */
-const registerCut = function() {
-  /** @type {!ShortcutRegistry.KeyboardShortcut} */
-  const cutShortcut = {
+export function registerCut() {
+  const ctrlX = ShortcutRegistry.registry.createSerializedKey(
+      KeyCodes.X, [KeyCodes.CTRL]);
+  const altX =
+      ShortcutRegistry.registry.createSerializedKey(KeyCodes.X, [KeyCodes.ALT]);
+  const metaX = ShortcutRegistry.registry.createSerializedKey(
+      KeyCodes.X, [KeyCodes.META]);
+
+  const cutShortcut: KeyboardShortcut = {
     name: names.CUT,
-    preconditionFn: function(workspace) {
+    preconditionFn(workspace) {
       const selected = common.getSelected();
-      return !workspace.options.readOnly && !Gesture.inProgress() && selected &&
+      return !workspace.options.readOnly && !Gesture.inProgress() &&
+          selected != null && selected instanceof BlockSvg &&
           selected.isDeletable() && selected.isMovable() &&
-          !selected.workspace.isFlyout;
+          !selected.workspace!.isFlyout;
     },
-    callback: function() {
+    callback() {
       const selected = common.getSelected();
       if (!selected) {
         // Shouldn't happen but appeases the type system
         return false;
       }
       clipboard.copy(selected);
-      (/** @type {!BlockSvg} */ (selected)).checkAndDelete();
+      (selected as BlockSvg).checkAndDelete();
       return true;
     },
+    keyCodes: [ctrlX, altX, metaX],
   };
 
   ShortcutRegistry.registry.register(cutShortcut);
-
-  const ctrlX = ShortcutRegistry.registry.createSerializedKey(
-      KeyCodes.X, [KeyCodes.CTRL]);
-  ShortcutRegistry.registry.addKeyMapping(ctrlX, cutShortcut.name);
-
-  const altX =
-      ShortcutRegistry.registry.createSerializedKey(KeyCodes.X, [KeyCodes.ALT]);
-  ShortcutRegistry.registry.addKeyMapping(altX, cutShortcut.name);
-
-  const metaX = ShortcutRegistry.registry.createSerializedKey(
-      KeyCodes.X, [KeyCodes.META]);
-  ShortcutRegistry.registry.addKeyMapping(metaX, cutShortcut.name);
-};
-exports.registerCut = registerCut;
+}
 
 /**
  * Keyboard shortcut to paste a block on ctrl+v, cmd+v, or alt+v.
  * @alias Blockly.ShortcutItems.registerPaste
  */
-const registerPaste = function() {
-  /** @type {!ShortcutRegistry.KeyboardShortcut} */
-  const pasteShortcut = {
+export function registerPaste() {
+  const ctrlV = ShortcutRegistry.registry.createSerializedKey(
+      KeyCodes.V, [KeyCodes.CTRL]);
+  const altV =
+      ShortcutRegistry.registry.createSerializedKey(KeyCodes.V, [KeyCodes.ALT]);
+  const metaV = ShortcutRegistry.registry.createSerializedKey(
+      KeyCodes.V, [KeyCodes.META]);
+
+  const pasteShortcut: KeyboardShortcut = {
     name: names.PASTE,
-    preconditionFn: function(workspace) {
+    preconditionFn(workspace) {
       return !workspace.options.readOnly && !Gesture.inProgress();
     },
-    callback: function() {
-      return clipboard.paste();
+    callback() {
+      return !!(clipboard.paste());
     },
+    keyCodes: [ctrlV, altV, metaV],
   };
 
   ShortcutRegistry.registry.register(pasteShortcut);
-
-  const ctrlV = ShortcutRegistry.registry.createSerializedKey(
-      KeyCodes.V, [KeyCodes.CTRL]);
-  ShortcutRegistry.registry.addKeyMapping(ctrlV, pasteShortcut.name);
-
-  const altV =
-      ShortcutRegistry.registry.createSerializedKey(KeyCodes.V, [KeyCodes.ALT]);
-  ShortcutRegistry.registry.addKeyMapping(altV, pasteShortcut.name);
-
-  const metaV = ShortcutRegistry.registry.createSerializedKey(
-      KeyCodes.V, [KeyCodes.META]);
-  ShortcutRegistry.registry.addKeyMapping(metaV, pasteShortcut.name);
-};
-exports.registerPaste = registerPaste;
+}
 
 /**
  * Keyboard shortcut to undo the previous action on ctrl+z, cmd+z, or alt+z.
  * @alias Blockly.ShortcutItems.registerUndo
  */
-const registerUndo = function() {
-  /** @type {!ShortcutRegistry.KeyboardShortcut} */
-  const undoShortcut = {
+export function registerUndo() {
+  const ctrlZ = ShortcutRegistry.registry.createSerializedKey(
+      KeyCodes.Z, [KeyCodes.CTRL]);
+  const altZ =
+      ShortcutRegistry.registry.createSerializedKey(KeyCodes.Z, [KeyCodes.ALT]);
+  const metaZ = ShortcutRegistry.registry.createSerializedKey(
+      KeyCodes.Z, [KeyCodes.META]);
+
+  const undoShortcut: KeyboardShortcut = {
     name: names.UNDO,
-    preconditionFn: function(workspace) {
+    preconditionFn(workspace) {
       return !workspace.options.readOnly && !Gesture.inProgress();
     },
-    callback: function(workspace) {
+    callback(workspace) {
       // 'z' for undo 'Z' is for redo.
-      workspace.hideChaff();
+      (workspace as WorkspaceSvg).hideChaff();
       workspace.undo(false);
       return true;
     },
+    keyCodes: [ctrlZ, altZ, metaZ],
   };
   ShortcutRegistry.registry.register(undoShortcut);
-
-  const ctrlZ = ShortcutRegistry.registry.createSerializedKey(
-      KeyCodes.Z, [KeyCodes.CTRL]);
-  ShortcutRegistry.registry.addKeyMapping(ctrlZ, undoShortcut.name);
-
-  const altZ =
-      ShortcutRegistry.registry.createSerializedKey(KeyCodes.Z, [KeyCodes.ALT]);
-  ShortcutRegistry.registry.addKeyMapping(altZ, undoShortcut.name);
-
-  const metaZ = ShortcutRegistry.registry.createSerializedKey(
-      KeyCodes.Z, [KeyCodes.META]);
-  ShortcutRegistry.registry.addKeyMapping(metaZ, undoShortcut.name);
-};
-exports.registerUndo = registerUndo;
+}
 
 /**
  * Keyboard shortcut to redo the previous action on ctrl+shift+z, cmd+shift+z,
  * or alt+shift+z.
  * @alias Blockly.ShortcutItems.registerRedo
  */
-const registerRedo = function() {
-  /** @type {!ShortcutRegistry.KeyboardShortcut} */
-  const redoShortcut = {
-    name: names.REDO,
-    preconditionFn: function(workspace) {
-      return !Gesture.inProgress() && !workspace.options.readOnly;
-    },
-    callback: function(workspace) {
-      // 'z' for undo 'Z' is for redo.
-      workspace.hideChaff();
-      workspace.undo(true);
-      return true;
-    },
-  };
-  ShortcutRegistry.registry.register(redoShortcut);
-
+export function registerRedo() {
   const ctrlShiftZ = ShortcutRegistry.registry.createSerializedKey(
       KeyCodes.Z, [KeyCodes.SHIFT, KeyCodes.CTRL]);
-  ShortcutRegistry.registry.addKeyMapping(ctrlShiftZ, redoShortcut.name);
-
   const altShiftZ = ShortcutRegistry.registry.createSerializedKey(
       KeyCodes.Z, [KeyCodes.SHIFT, KeyCodes.ALT]);
-  ShortcutRegistry.registry.addKeyMapping(altShiftZ, redoShortcut.name);
-
   const metaShiftZ = ShortcutRegistry.registry.createSerializedKey(
       KeyCodes.Z, [KeyCodes.SHIFT, KeyCodes.META]);
-  ShortcutRegistry.registry.addKeyMapping(metaShiftZ, redoShortcut.name);
-
   // Ctrl-y is redo in Windows.  Command-y is never valid on Macs.
   const ctrlY = ShortcutRegistry.registry.createSerializedKey(
       KeyCodes.Y, [KeyCodes.CTRL]);
-  ShortcutRegistry.registry.addKeyMapping(ctrlY, redoShortcut.name);
-};
-exports.registerRedo = registerRedo;
+
+  const redoShortcut: KeyboardShortcut = {
+    name: names.REDO,
+    preconditionFn(workspace) {
+      return !Gesture.inProgress() && !workspace.options.readOnly;
+    },
+    callback(workspace) {
+      // 'z' for undo 'Z' is for redo.
+      (workspace as WorkspaceSvg).hideChaff();
+      workspace.undo(true);
+      return true;
+    },
+    keyCodes: [ctrlShiftZ, altShiftZ, metaShiftZ, ctrlY],
+  };
+  ShortcutRegistry.registry.register(redoShortcut);
+}
 
 /**
  * Registers all default keyboard shortcut item. This should be called once per
  * instance of KeyboardShortcutRegistry.
  * @alias Blockly.ShortcutItems.registerDefaultShortcuts
- * @package
+ * @internal
  */
-const registerDefaultShortcuts = function() {
+export function registerDefaultShortcuts() {
   registerEscape();
   registerDelete();
   registerCopy();
@@ -296,7 +261,6 @@ const registerDefaultShortcuts = function() {
   registerPaste();
   registerUndo();
   registerRedo();
-};
-exports.registerDefaultShortcuts = registerDefaultShortcuts;
+}
 
 registerDefaultShortcuts();

package/core/shortcut_registry.d.ts

@@ -0,0 +1,151 @@
+/**
+ * @license
+ * Copyright 2020 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { KeyCodes } from './utils/keycodes.js';
+import type { Workspace } from './workspace.js';
+/**
+ * Class for the registry of keyboard shortcuts. This is intended to be a
+ * singleton. You should not create a new instance, and only access this class
+ * from ShortcutRegistry.registry.
+ * @alias Blockly.ShortcutRegistry
+ */
+export declare class ShortcutRegistry {
+    static readonly registry: ShortcutRegistry;
+    /** Registry of all keyboard shortcuts, keyed by name of shortcut. */
+    private shortcuts;
+    /** Map of key codes to an array of shortcut names. */
+    private keyMap;
+    /** Resets the existing ShortcutRegistry singleton. */
+    private constructor();
+    /** Clear and recreate the registry and keyMap. */
+    reset(): void;
+    /**
+     * Registers a keyboard shortcut.
+     * @param shortcut The shortcut for this key code.
+     * @param opt_allowOverrides True to prevent a warning when overriding an
+     *     already registered item.
+     * @throws {Error} if a shortcut with the same name already exists.
+     */
+    register(shortcut: KeyboardShortcut, opt_allowOverrides?: boolean): void;
+    /**
+     * Unregisters a keyboard shortcut registered with the given key code. This
+     * will also remove any key mappings that reference this shortcut.
+     * @param shortcutName The name of the shortcut to unregister.
+     * @return True if an item was unregistered, false otherwise.
+     */
+    unregister(shortcutName: string): boolean;
+    /**
+     * Adds a mapping between a keycode and a keyboard shortcut.
+     * @param keyCode The key code for the keyboard shortcut. If registering a key
+     *     code with a modifier (ex: ctrl+c) use
+     *     ShortcutRegistry.registry.createSerializedKey;
+     * @param shortcutName The name of the shortcut to execute when the given
+     *     keycode is pressed.
+     * @param opt_allowCollision True to prevent an error when adding a shortcut
+     *     to a key that is already mapped to a shortcut.
+     * @throws {Error} if the given key code is already mapped to a shortcut.
+     */
+    addKeyMapping(keyCode: string | number | KeyCodes, shortcutName: string, opt_allowCollision?: boolean): void;
+    /**
+     * Removes a mapping between a keycode and a keyboard shortcut.
+     * @param keyCode The key code for the keyboard shortcut. If registering a key
+     *     code with a modifier (ex: ctrl+c) use
+     *     ShortcutRegistry.registry.createSerializedKey;
+     * @param shortcutName The name of the shortcut to execute when the given
+     *     keycode is pressed.
+     * @param opt_quiet True to not console warn when there is no shortcut to
+     *     remove.
+     * @return True if a key mapping was removed, false otherwise.
+     */
+    removeKeyMapping(keyCode: string, shortcutName: string, opt_quiet?: boolean): boolean;
+    /**
+     * Removes all the key mappings for a shortcut with the given name.
+     * Useful when changing the default key mappings and the key codes registered
+     * to the shortcut are unknown.
+     * @param shortcutName The name of the shortcut to remove from the key map.
+     */
+    removeAllKeyMappings(shortcutName: string): void;
+    /**
+     * Sets the key map. Setting the key map will override any default key
+     * mappings.
+     * @param newKeyMap The object with key code to shortcut names.
+     */
+    setKeyMap(newKeyMap: {
+        [key: string]: string[];
+    }): void;
+    /**
+     * Gets the current key map.
+     * @return The object holding key codes to ShortcutRegistry.KeyboardShortcut.
+     */
+    getKeyMap(): {
+        [key: string]: string[];
+    };
+    /**
+     * Gets the registry of keyboard shortcuts.
+     * @return The registry of keyboard shortcuts.
+     */
+    getRegistry(): {
+        [key: string]: KeyboardShortcut;
+    };
+    /**
+     * Handles key down events.
+     * @param workspace The main workspace where the event was captured.
+     * @param e The key down event.
+     * @return True if the event was handled, false otherwise.
+     */
+    onKeyDown(workspace: Workspace, e: KeyboardEvent): boolean;
+    /**
+     * Gets the shortcuts registered to the given key code.
+     * @param keyCode The serialized key code.
+     * @return The list of shortcuts to call when the given keyCode is used.
+     *     Undefined if no shortcuts exist.
+     */
+    getShortcutNamesByKeyCode(keyCode: string): string[] | undefined;
+    /**
+     * Gets the serialized key codes that the shortcut with the given name is
+     * registered under.
+     * @param shortcutName The name of the shortcut.
+     * @return An array with all the key codes the shortcut is registered under.
+     */
+    getKeyCodesByShortcutName(shortcutName: string): string[];
+    /**
+     * Serializes a key event.
+     * @param e A key down event.
+     * @return The serialized key code for the given event.
+     */
+    private serializeKeyEvent_;
+    /**
+     * Checks whether any of the given modifiers are not valid.
+     * @param modifiers List of modifiers to be used with the key.
+     * @throws {Error} if the modifier is not in the valid modifiers list.
+     */
+    private checkModifiers_;
+    /**
+     * Creates the serialized key code that will be used in the key map.
+     * @param keyCode Number code representing the key.
+     * @param modifiers List of modifier key codes to be used with the key. All
+     *     valid modifiers can be found in the ShortcutRegistry.modifierKeys.
+     * @return The serialized key code for the given modifiers and key.
+     */
+    createSerializedKey(keyCode: number, modifiers: KeyCodes[] | null): string;
+}
+export declare namespace ShortcutRegistry {
+    interface KeyboardShortcut {
+        callback?: ((p1: Workspace, p2: Event, p3: KeyboardShortcut) => boolean);
+        name: string;
+        preconditionFn?: ((p1: Workspace) => boolean);
+        metadata?: object;
+        keyCodes?: (number | string)[];
+        allowCollision?: boolean;
+    }
+    /** Supported modifiers. */
+    enum modifierKeys {
+        Shift = 16,
+        Control = 17,
+        Alt = 18,
+        Meta = 91
+    }
+}
+export declare type KeyboardShortcut = ShortcutRegistry.KeyboardShortcut;