blockly 8.0.4 → 8.0.5-beta.0

package/core/menuitem.ts

@@ -0,0 +1,240 @@
+/**
+ * @license
+ * Copyright 2019 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * @fileoverview Blockly menu item similar to Closure's goog.ui.MenuItem
+ */
+
+/**
+ * Blockly menu item similar to Closure's goog.ui.MenuItem
+ * @class
+ */
+import * as goog from '../closure/goog/goog.js';
+goog.declareModuleId('Blockly.MenuItem');
+
+import * as aria from './utils/aria.js';
+import * as dom from './utils/dom.js';
+import * as idGenerator from './utils/idgenerator.js';
+
+
+/**
+ * Class representing an item in a menu.
+ * @alias Blockly.MenuItem
+ */
+export class MenuItem {
+  /** Is the menu item clickable, as opposed to greyed-out. */
+  private enabled_ = true;
+
+  /** The DOM element for the menu item. */
+  private element_: HTMLDivElement|null = null;
+
+  /** Whether the menu item is rendered right-to-left. */
+  private rightToLeft_ = false;
+
+  /** ARIA name for this menu. */
+  private roleName_: aria.Role|null = null;
+
+  /** Is this menu item checkable. */
+  private checkable_ = false;
+
+  /** Is this menu item currently checked. */
+  private checked_ = false;
+
+  /** Is this menu item currently highlighted. */
+  private highlight_ = false;
+
+  /** Bound function to call when this menu item is clicked. */
+  private actionHandler_: Function|null = null;
+
+  /**
+   * @param content Text caption to display as the content of the item, or a
+   *     HTML element to display.
+   * @param opt_value Data/model associated with the menu item.
+   */
+  constructor(
+      private readonly content: string|HTMLElement,
+      private readonly opt_value?: string) {}
+
+  /**
+   * Creates the menuitem's DOM.
+   * @return Completed DOM.
+   */
+  createDom(): Element {
+    const element = (document.createElement('div'));
+    element.id = idGenerator.getNextUniqueId();
+    this.element_ = element;
+
+    // Set class and style
+    // goog-menuitem* is deprecated, use blocklyMenuItem*.  May 2020.
+    element.className = 'blocklyMenuItem goog-menuitem ' +
+        (this.enabled_ ? '' :
+                         'blocklyMenuItemDisabled goog-menuitem-disabled ') +
+        (this.checked_ ? 'blocklyMenuItemSelected goog-option-selected ' : '') +
+        (this.highlight_ ? 'blocklyMenuItemHighlight goog-menuitem-highlight ' :
+                           '') +
+        (this.rightToLeft_ ? 'blocklyMenuItemRtl goog-menuitem-rtl ' : '');
+
+    const content = (document.createElement('div'));
+    content.className = 'blocklyMenuItemContent goog-menuitem-content';
+    // Add a checkbox for checkable menu items.
+    if (this.checkable_) {
+      const checkbox = (document.createElement('div'));
+      checkbox.className = 'blocklyMenuItemCheckbox goog-menuitem-checkbox';
+      content.appendChild(checkbox);
+    }
+
+    let contentDom: Node = this.content as HTMLElement;
+    if (typeof this.content === 'string') {
+      contentDom = document.createTextNode(this.content);
+    }
+    content.appendChild(contentDom);
+    element.appendChild(content);
+
+    // Initialize ARIA role and state.
+    if (this.roleName_) {
+      aria.setRole(element, this.roleName_);
+    }
+    aria.setState(
+        element, aria.State.SELECTED,
+        this.checkable_ && this.checked_ || false);
+    aria.setState(element, aria.State.DISABLED, !this.enabled_);
+
+    return element;
+  }
+
+  /** Dispose of this menu item. */
+  dispose() {
+    this.element_ = null;
+  }
+
+  /**
+   * Gets the menu item's element.
+   * @return The DOM element.
+   * @internal
+   */
+  getElement(): Element|null {
+    return this.element_;
+  }
+
+  /**
+   * Gets the unique ID for this menu item.
+   * @return Unique component ID.
+   * @internal
+   */
+  getId(): string {
+    return this.element_!.id;
+  }
+
+  /**
+   * Gets the value associated with the menu item.
+   * @return value Value associated with the menu item.
+   * @internal
+   */
+  getValue(): AnyDuringMigration {
+    return this.opt_value;
+  }
+
+  /**
+   * Set menu item's rendering direction.
+   * @param rtl True if RTL, false if LTR.
+   * @internal
+   */
+  setRightToLeft(rtl: boolean) {
+    this.rightToLeft_ = rtl;
+  }
+
+  /**
+   * Set the menu item's accessibility role.
+   * @param roleName Role name.
+   * @internal
+   */
+  setRole(roleName: aria.Role) {
+    this.roleName_ = roleName;
+  }
+
+  /**
+   * Sets the menu item to be checkable or not. Set to true for menu items
+   * that represent checkable options.
+   * @param checkable Whether the menu item is checkable.
+   * @internal
+   */
+  setCheckable(checkable: boolean) {
+    this.checkable_ = checkable;
+  }
+
+  /**
+   * Checks or unchecks the component.
+   * @param checked Whether to check or uncheck the component.
+   * @internal
+   */
+  setChecked(checked: boolean) {
+    this.checked_ = checked;
+  }
+
+  /**
+   * Highlights or unhighlights the component.
+   * @param highlight Whether to highlight or unhighlight the component.
+   * @internal
+   */
+  setHighlighted(highlight: boolean) {
+    this.highlight_ = highlight;
+
+    const el = this.getElement();
+    if (el && this.isEnabled()) {
+      // goog-menuitem-highlight is deprecated, use blocklyMenuItemHighlight.
+      // May 2020.
+      const name = 'blocklyMenuItemHighlight';
+      const nameDep = 'goog-menuitem-highlight';
+      if (highlight) {
+        dom.addClass(el, name);
+        dom.addClass(el, nameDep);
+      } else {
+        dom.removeClass(el, name);
+        dom.removeClass(el, nameDep);
+      }
+    }
+  }
+
+  /**
+   * Returns true if the menu item is enabled, false otherwise.
+   * @return Whether the menu item is enabled.
+   * @internal
+   */
+  isEnabled(): boolean {
+    return this.enabled_;
+  }
+
+  /**
+   * Enables or disables the menu item.
+   * @param enabled Whether to enable or disable the menu item.
+   * @internal
+   */
+  setEnabled(enabled: boolean) {
+    this.enabled_ = enabled;
+  }
+
+  /**
+   * Performs the appropriate action when the menu item is activated
+   * by the user.
+   * @internal
+   */
+  performAction() {
+    if (this.isEnabled() && this.actionHandler_) {
+      this.actionHandler_(this);
+    }
+  }
+
+  /**
+   * Set the handler that's called when the menu item is activated by the user.
+   * `obj` will be used as the 'this' object in the function when called.
+   * @param fn The handler.
+   * @param obj Used as the 'this' object in fn when called.
+   * @internal
+   */
+  onAction(fn: (p1: MenuItem) => AnyDuringMigration, obj: AnyDuringMigration) {
+    this.actionHandler_ = fn.bind(obj);
+  }
+}

package/core/metrics_manager.d.ts

@@ -0,0 +1,201 @@
+/**
+ * @license
+ * Copyright 2021 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { IFlyout } from './interfaces/i_flyout.js';
+import type { IMetricsManager } from './interfaces/i_metrics_manager.js';
+import type { IToolbox } from './interfaces/i_toolbox.js';
+import type { Metrics } from './utils/metrics.js';
+import { Size } from './utils/size.js';
+import * as toolboxUtils from './utils/toolbox.js';
+import type { WorkspaceSvg } from './workspace_svg.js';
+/**
+ * The manager for all workspace metrics calculations.
+ * @alias Blockly.MetricsManager
+ */
+export declare class MetricsManager implements IMetricsManager {
+    /** The workspace to calculate metrics for. */
+    protected readonly workspace_: WorkspaceSvg;
+    /** @param workspace The workspace to calculate metrics for. */
+    constructor(workspace: WorkspaceSvg);
+    /**
+     * Gets the dimensions of the given workspace component, in pixel coordinates.
+     * @param elem The element to get the dimensions of, or null.  It should be a
+     *     toolbox or flyout, and should implement getWidth() and getHeight().
+     * @return An object containing width and height attributes, which will both
+     *     be zero if elem did not exist.
+     */
+    protected getDimensionsPx_(elem: IToolbox | null | IFlyout): Size;
+    /**
+     * Gets the width and the height of the flyout on the workspace in pixel
+     * coordinates. Returns 0 for the width and height if the workspace has a
+     * category toolbox instead of a simple toolbox.
+     * @param opt_own Whether to only return the workspace's own flyout.
+     * @return The width and height of the flyout.
+     */
+    getFlyoutMetrics(opt_own?: boolean): ToolboxMetrics;
+    /**
+     * Gets the width, height and position of the toolbox on the workspace in
+     * pixel coordinates. Returns 0 for the width and height if the workspace has
+     * a simple toolbox instead of a category toolbox. To get the width and height
+     * of a
+     * simple toolbox @see {@link getFlyoutMetrics}.
+     * @return The object with the width, height and position of the toolbox.
+     */
+    getToolboxMetrics(): ToolboxMetrics;
+    /**
+     * Gets the width and height of the workspace's parent SVG element in pixel
+     * coordinates. This area includes the toolbox and the visible workspace area.
+     * @return The width and height of the workspace's parent SVG element.
+     */
+    getSvgMetrics(): Size;
+    /**
+     * Gets the absolute left and absolute top in pixel coordinates.
+     * This is where the visible workspace starts in relation to the SVG
+     * container.
+     * @return The absolute metrics for the workspace.
+     */
+    getAbsoluteMetrics(): AbsoluteMetrics;
+    /**
+     * Gets the metrics for the visible workspace in either pixel or workspace
+     * coordinates. The visible workspace does not include the toolbox or flyout.
+     * @param opt_getWorkspaceCoordinates True to get the view metrics in
+     *     workspace coordinates, false to get them in pixel coordinates.
+     * @return The width, height, top and left of the viewport in either workspace
+     *     coordinates or pixel coordinates.
+     */
+    getViewMetrics(opt_getWorkspaceCoordinates?: boolean): ContainerRegion;
+    /**
+     * Gets content metrics in either pixel or workspace coordinates.
+     * The content area is a rectangle around all the top bounded elements on the
+     * workspace (workspace comments and blocks).
+     * @param opt_getWorkspaceCoordinates True to get the content metrics in
+     *     workspace coordinates, false to get them in pixel coordinates.
+     * @return The metrics for the content container.
+     */
+    getContentMetrics(opt_getWorkspaceCoordinates?: boolean): ContainerRegion;
+    /**
+     * Returns whether the scroll area has fixed edges.
+     * @return Whether the scroll area has fixed edges.
+     * @internal
+     */
+    hasFixedEdges(): boolean;
+    /**
+     * Computes the fixed edges of the scroll area.
+     * @param opt_viewMetrics The view metrics if they have been previously
+     *     computed. Passing in null may cause the view metrics to be computed
+     *     again, if it is needed.
+     * @return The fixed edges of the scroll area.
+     */
+    protected getComputedFixedEdges_(opt_viewMetrics?: ContainerRegion): FixedEdges;
+    /**
+     * Returns the content area with added padding.
+     * @param viewMetrics The view metrics.
+     * @param contentMetrics The content metrics.
+     * @return The padded content area.
+     */
+    protected getPaddedContent_(viewMetrics: ContainerRegion, contentMetrics: ContainerRegion): {
+        top: number;
+        bottom: number;
+        left: number;
+        right: number;
+    };
+    /**
+     * Returns the metrics for the scroll area of the workspace.
+     * @param opt_getWorkspaceCoordinates True to get the scroll metrics in
+     *     workspace coordinates, false to get them in pixel coordinates.
+     * @param opt_viewMetrics The view metrics if they have been previously
+     *     computed. Passing in null may cause the view metrics to be computed
+     *     again, if it is needed.
+     * @param opt_contentMetrics The content metrics if they have been previously
+     *     computed. Passing in null may cause the content metrics to be computed
+     *     again, if it is needed.
+     * @return The metrics for the scroll container.
+     */
+    getScrollMetrics(opt_getWorkspaceCoordinates?: boolean, opt_viewMetrics?: ContainerRegion, opt_contentMetrics?: ContainerRegion): ContainerRegion;
+    /**
+     * Returns common metrics used by UI elements.
+     * @return The UI metrics.
+     */
+    getUiMetrics(): UiMetrics;
+    /**
+     * Returns an object with all the metrics required to size scrollbars for a
+     * top level workspace.  The following properties are computed:
+     * Coordinate system: pixel coordinates, -left, -up, +right, +down
+     * .viewHeight: Height of the visible portion of the workspace.
+     * .viewWidth: Width of the visible portion of the workspace.
+     * .contentHeight: Height of the content.
+     * .contentWidth: Width of the content.
+     * .scrollHeight: Height of the scroll area.
+     * .scrollWidth: Width of the scroll area.
+     * .svgHeight: Height of the Blockly div (the view + the toolbox,
+     *    simple or otherwise),
+     * .svgWidth: Width of the Blockly div (the view + the toolbox,
+     *    simple or otherwise),
+     * .viewTop: Top-edge of the visible portion of the workspace, relative to
+     *     the workspace origin.
+     * .viewLeft: Left-edge of the visible portion of the workspace, relative to
+     *     the workspace origin.
+     * .contentTop: Top-edge of the content, relative to the workspace origin.
+     * .contentLeft: Left-edge of the content relative to the workspace origin.
+     * .scrollTop: Top-edge of the scroll area, relative to the workspace origin.
+     * .scrollLeft: Left-edge of the scroll area relative to the workspace origin.
+     * .absoluteTop: Top-edge of the visible portion of the workspace, relative
+     *     to the blocklyDiv.
+     * .absoluteLeft: Left-edge of the visible portion of the workspace, relative
+     *     to the blocklyDiv.
+     * .toolboxWidth: Width of the toolbox, if it exists.  Otherwise zero.
+     * .toolboxHeight: Height of the toolbox, if it exists.  Otherwise zero.
+     * .flyoutWidth: Width of the flyout if it is always open.  Otherwise zero.
+     * .flyoutHeight: Height of the flyout if it is always open.  Otherwise zero.
+     * .toolboxPosition: Top, bottom, left or right. Use TOOLBOX_AT constants to
+     *     compare.
+     * @return Contains size and position metrics of a top level workspace.
+     */
+    getMetrics(): Metrics;
+}
+export declare namespace MetricsManager {
+    /**
+     * Describes the width, height and location of the toolbox on the main
+     * workspace.
+     */
+    interface ToolboxMetrics {
+        width: number;
+        height: number;
+        position: toolboxUtils.Position;
+    }
+    /** Describes where the viewport starts in relation to the workspace SVG. */
+    interface AbsoluteMetrics {
+        left: number;
+        top: number;
+    }
+    /**
+     * All the measurements needed to describe the size and location of a
+     * container.
+     */
+    interface ContainerRegion {
+        height: number;
+        width: number;
+        top: number;
+        left: number;
+    }
+    /** Describes fixed edges of the workspace. */
+    interface FixedEdges {
+        top?: number;
+        bottom?: number;
+        left?: number;
+        right?: number;
+    }
+    /** Common metrics used for UI elements. */
+    interface UiMetrics {
+        viewMetrics: ContainerRegion;
+        absoluteMetrics: AbsoluteMetrics;
+        toolboxMetrics: ToolboxMetrics;
+    }
+}
+export declare type ToolboxMetrics = MetricsManager.ToolboxMetrics;
+export declare type AbsoluteMetrics = MetricsManager.AbsoluteMetrics;
+export declare type ContainerRegion = MetricsManager.ContainerRegion;
+export declare type FixedEdges = MetricsManager.FixedEdges;
+export declare type UiMetrics = MetricsManager.UiMetrics;