blockly 8.0.5 → 9.0.0-beta.0

package/core/marker_manager.ts

@@ -0,0 +1,181 @@
+/**
+ * @license
+ * Copyright 2019 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * @fileoverview Object in charge of managing markers and the cursor.
+ */
+
+/**
+ * Object in charge of managing markers and the cursor.
+ * @class
+ */
+import * as goog from '../closure/goog/goog.js';
+goog.declareModuleId('Blockly.MarkerManager');
+
+import type {Cursor} from './keyboard_nav/cursor.js';
+import type {Marker} from './keyboard_nav/marker.js';
+import type {WorkspaceSvg} from './workspace_svg.js';
+
+
+/**
+ * Class to manage the multiple markers and the cursor on a workspace.
+ * @alias Blockly.MarkerManager
+ */
+export class MarkerManager {
+  /** The name of the local marker. */
+  static readonly LOCAL_MARKER = 'local_marker_1';
+
+  /** The cursor. */
+  private cursor_: Cursor|null = null;
+
+  /** The cursor's SVG element. */
+  private cursorSvg_: SVGElement|null = null;
+
+  /** The map of markers for the workspace. */
+  private markers = new Map<string, Marker>();
+
+  /** The marker's SVG element. */
+  private markerSvg_: SVGElement|null = null;
+
+  /**
+   * @param workspace The workspace for the marker manager.
+   * @internal
+   */
+  constructor(private readonly workspace: WorkspaceSvg) {}
+
+  /**
+   * Register the marker by adding it to the map of markers.
+   * @param id A unique identifier for the marker.
+   * @param marker The marker to register.
+   */
+  registerMarker(id: string, marker: Marker) {
+    if (this.markers.has(id)) {
+      this.unregisterMarker(id);
+    }
+    marker.setDrawer(
+        this.workspace.getRenderer().makeMarkerDrawer(this.workspace, marker));
+    this.setMarkerSvg(marker.getDrawer().createDom());
+    this.markers.set(id, marker);
+  }
+
+  /**
+   * Unregister the marker by removing it from the map of markers.
+   * @param id The ID of the marker to unregister.
+   */
+  unregisterMarker(id: string) {
+    const marker = this.markers.get(id);
+    if (marker) {
+      marker.dispose();
+      this.markers.delete(id);
+    } else {
+      throw Error(
+          'Marker with ID ' + id + ' does not exist. ' +
+          'Can only unregister markers that exist.');
+    }
+  }
+
+  /**
+   * Get the cursor for the workspace.
+   * @return The cursor for this workspace.
+   */
+  getCursor(): Cursor|null {
+    return this.cursor_;
+  }
+
+  /**
+   * Get a single marker that corresponds to the given ID.
+   * @param id A unique identifier for the marker.
+   * @return The marker that corresponds to the given ID, or null if none
+   *     exists.
+   */
+  getMarker(id: string): Marker|null {
+    return this.markers.get(id) || null;
+  }
+
+  /**
+   * Sets the cursor and initializes the drawer for use with keyboard
+   * navigation.
+   * @param cursor The cursor used to move around this workspace.
+   */
+  setCursor(cursor: Cursor) {
+    if (this.cursor_ && this.cursor_.getDrawer()) {
+      this.cursor_.getDrawer().dispose();
+    }
+    this.cursor_ = cursor;
+    if (this.cursor_) {
+      const drawer = this.workspace.getRenderer().makeMarkerDrawer(
+          this.workspace, this.cursor_);
+      this.cursor_.setDrawer(drawer);
+      this.setCursorSvg(this.cursor_.getDrawer().createDom());
+    }
+  }
+
+  /**
+   * Add the cursor SVG to this workspace SVG group.
+   * @param cursorSvg The SVG root of the cursor to be added to the workspace
+   *     SVG group.
+   * @internal
+   */
+  setCursorSvg(cursorSvg: SVGElement|null) {
+    if (!cursorSvg) {
+      this.cursorSvg_ = null;
+      return;
+    }
+
+    this.workspace.getBlockCanvas()!.appendChild(cursorSvg);
+    this.cursorSvg_ = cursorSvg;
+  }
+
+  /**
+   * Add the marker SVG to this workspaces SVG group.
+   * @param markerSvg The SVG root of the marker to be added to the workspace
+   *     SVG group.
+   * @internal
+   */
+  setMarkerSvg(markerSvg: SVGElement|null) {
+    if (!markerSvg) {
+      this.markerSvg_ = null;
+      return;
+    }
+
+    if (this.workspace.getBlockCanvas()) {
+      if (this.cursorSvg_) {
+        this.workspace.getBlockCanvas()!.insertBefore(
+            markerSvg, this.cursorSvg_);
+      } else {
+        this.workspace.getBlockCanvas()!.appendChild(markerSvg);
+      }
+    }
+  }
+
+  /**
+   * Redraw the attached cursor SVG if needed.
+   * @internal
+   */
+  updateMarkers() {
+    if (this.workspace.keyboardAccessibilityMode && this.cursorSvg_) {
+      this.workspace.getCursor()!.draw();
+    }
+  }
+
+  /**
+   * Dispose of the marker manager.
+   * Go through and delete all markers associated with this marker manager.
+   * @suppress {checkTypes}
+   * @internal
+   */
+  dispose() {
+    const markerIds = Object.keys(this.markers);
+    for (let i = 0, markerId; markerId = markerIds[i]; i++) {
+      this.unregisterMarker(markerId);
+    }
+    this.markers.clear();
+    if (this.cursor_) {
+      this.cursor_.dispose();
+      this.cursor_ = null;
+    }
+  }
+}

package/core/menu.d.ts

@@ -0,0 +1,149 @@
+/**
+ * @license
+ * Copyright 2019 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { MenuItem } from './menuitem.js';
+import * as aria from './utils/aria.js';
+import { Coordinate } from './utils/coordinate.js';
+import type { Size } from './utils/size.js';
+/**
+ * A basic menu class.
+ * @alias Blockly.Menu
+ */
+export declare class Menu {
+    /**
+     * Array of menu items.
+     * (Nulls are never in the array, but typing the array as nullable prevents
+     * the compiler from objecting to .indexOf(null))
+     */
+    private readonly menuItems_;
+    /**
+     * Coordinates of the mousedown event that caused this menu to open. Used to
+     * prevent the consequent mouseup event due to a simple click from
+     * activating a menu item immediately.
+     */
+    openingCoords: Coordinate | null;
+    /**
+     * This is the element that we will listen to the real focus events on.
+     * A value of null means no menu item is highlighted.
+     */
+    private highlightedItem_;
+    /** Mouse over event data. */
+    private mouseOverHandler_;
+    /** Click event data. */
+    private clickHandler_;
+    /** Mouse enter event data. */
+    private mouseEnterHandler_;
+    /** Mouse leave event data. */
+    private mouseLeaveHandler_;
+    /** Key down event data. */
+    private onKeyDownHandler_;
+    /** The menu's root DOM element. */
+    private element_;
+    /** ARIA name for this menu. */
+    private roleName_;
+    /** Constructs a new Menu instance. */
+    constructor();
+    /**
+     * Add a new menu item to the bottom of this menu.
+     * @param menuItem Menu item to append.
+     * @internal
+     */
+    addChild(menuItem: MenuItem): void;
+    /**
+     * Creates the menu DOM.
+     * @param container Element upon which to append this menu.
+     */
+    render(container: Element): void;
+    /**
+     * Gets the menu's element.
+     * @return The DOM element.
+     * @internal
+     */
+    getElement(): Element | null;
+    /**
+     * Focus the menu element.
+     * @internal
+     */
+    focus(): void;
+    /** Blur the menu element. */
+    private blur_;
+    /**
+     * Set the menu accessibility role.
+     * @param roleName role name.
+     * @internal
+     */
+    setRole(roleName: aria.Role): void;
+    /** Dispose of this menu. */
+    dispose(): void;
+    /**
+     * Returns the child menu item that owns the given DOM element,
+     * or null if no such menu item is found.
+     * @param elem DOM element whose owner is to be returned.
+     * @return Menu item for which the DOM element belongs to.
+     */
+    private getMenuItem_;
+    /**
+     * Highlights the given menu item, or clears highlighting if null.
+     * @param item Item to highlight, or null.
+     * @internal
+     */
+    setHighlighted(item: MenuItem | null): void;
+    /**
+     * Highlights the next highlightable item (or the first if nothing is
+     * currently highlighted).
+     * @internal
+     */
+    highlightNext(): void;
+    /**
+     * Highlights the previous highlightable item (or the last if nothing is
+     * currently highlighted).
+     * @internal
+     */
+    highlightPrevious(): void;
+    /** Highlights the first highlightable item. */
+    private highlightFirst_;
+    /** Highlights the last highlightable item. */
+    private highlightLast_;
+    /**
+     * Helper function that manages the details of moving the highlight among
+     * child menuitems in response to keyboard events.
+     * @param startIndex Start index.
+     * @param delta Step direction: 1 to go down, -1 to go up.
+     */
+    private highlightHelper_;
+    /**
+     * Handles mouseover events. Highlight menuitems as the user hovers over them.
+     * @param e Mouse event to handle.
+     */
+    private handleMouseOver_;
+    /**
+     * Handles click events. Pass the event onto the child menuitem to handle.
+     * @param e Click event to handle.
+     */
+    private handleClick_;
+    /**
+     * Handles mouse enter events. Focus the element.
+     * @param _e Mouse event to handle.
+     */
+    private handleMouseEnter_;
+    /**
+     * Handles mouse leave events. Blur and clear highlight.
+     * @param _e Mouse event to handle.
+     */
+    private handleMouseLeave_;
+    /**
+     * Attempts to handle a keyboard event, if the menu item is enabled, by
+     * calling
+     * {@link handleKeyEventInternal_}.
+     * @param e Key event to handle.
+     */
+    private handleKeyEvent_;
+    /**
+     * Get the size of a rendered menu.
+     * @return Object with width and height properties.
+     * @internal
+     */
+    getSize(): Size;
+}