blockly 8.0.4 → 8.0.5-beta.0

package/core/widgetdiv.ts

@@ -0,0 +1,257 @@
+/**
+ * @license
+ * Copyright 2013 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * @fileoverview A div that floats on top of Blockly.  This singleton contains
+ *     temporary HTML UI widgets that the user is currently interacting with.
+ *     E.g. text input areas, colour pickers, context menus.
+ */
+
+/**
+ * A div that floats on top of Blockly.  This singleton contains
+ *     temporary HTML UI widgets that the user is currently interacting with.
+ *     E.g. text input areas, colour pickers, context menus.
+ * @namespace Blockly.WidgetDiv
+ */
+import * as goog from '../closure/goog/goog.js';
+goog.declareModuleId('Blockly.WidgetDiv');
+
+import * as common from './common.js';
+import * as dom from './utils/dom.js';
+import type {Rect} from './utils/rect.js';
+import type {Size} from './utils/size.js';
+import type {WorkspaceSvg} from './workspace_svg.js';
+
+
+/** The object currently using this container. */
+let owner: AnyDuringMigration = null;
+
+/** Optional cleanup function set by whichever object uses the widget. */
+// AnyDuringMigration because:  Type 'null' is not assignable to type
+// 'Function'.
+let dispose: Function = null as AnyDuringMigration;
+
+/** A class name representing the current owner's workspace renderer. */
+let rendererClassName = '';
+
+/** A class name representing the current owner's workspace theme. */
+let themeClassName = '';
+
+/** The HTML container for popup overlays (e.g. editor widgets). */
+let containerDiv: HTMLDivElement|null;
+
+/**
+ * Returns the HTML container for editor widgets.
+ * @return The editor widget container.
+ * @alias Blockly.WidgetDiv.getDiv
+ */
+export function getDiv(): HTMLDivElement|null {
+  return containerDiv;
+}
+
+/**
+ * Allows unit tests to reset the div.
+ * @param newDiv The new value for the DIV field.
+ * @alias Blockly.WidgetDiv.testOnly_setDiv
+ * @ignore
+ */
+export function testOnly_setDiv(newDiv: HTMLDivElement|null) {
+  containerDiv = newDiv;
+}
+
+/**
+ * Create the widget div and inject it onto the page.
+ * @alias Blockly.WidgetDiv.createDom
+ */
+export function createDom() {
+  if (containerDiv) {
+    return;  // Already created.
+  }
+
+  containerDiv = document.createElement('div') as HTMLDivElement;
+  containerDiv.className = 'blocklyWidgetDiv';
+  const container = common.getParentContainer() || document.body;
+  container.appendChild(containerDiv);
+}
+
+/**
+ * Initialize and display the widget div.  Close the old one if needed.
+ * @param newOwner The object that will be using this container.
+ * @param rtl Right-to-left (true) or left-to-right (false).
+ * @param newDispose Optional cleanup function to be run when the widget is
+ *     closed.
+ * @alias Blockly.WidgetDiv.show
+ */
+export function show(
+    newOwner: AnyDuringMigration, rtl: boolean, newDispose: Function) {
+  hide();
+  owner = newOwner;
+  dispose = newDispose;
+  const div = containerDiv;
+  div!.style.direction = rtl ? 'rtl' : 'ltr';
+  div!.style.display = 'block';
+  const mainWorkspace = common.getMainWorkspace() as WorkspaceSvg;
+  rendererClassName = mainWorkspace.getRenderer().getClassName();
+  themeClassName = mainWorkspace.getTheme().getClassName();
+  // AnyDuringMigration because:  Argument of type 'HTMLDivElement | null' is
+  // not assignable to parameter of type 'Element'.
+  dom.addClass(div as AnyDuringMigration, rendererClassName);
+  // AnyDuringMigration because:  Argument of type 'HTMLDivElement | null' is
+  // not assignable to parameter of type 'Element'.
+  dom.addClass(div as AnyDuringMigration, themeClassName);
+}
+
+/**
+ * Destroy the widget and hide the div.
+ * @alias Blockly.WidgetDiv.hide
+ */
+export function hide() {
+  if (!isVisible()) {
+    return;
+  }
+  owner = null;
+
+  const div = containerDiv;
+  div!.style.display = 'none';
+  div!.style.left = '';
+  div!.style.top = '';
+  dispose && dispose();
+  // AnyDuringMigration because:  Type 'null' is not assignable to type
+  // 'Function'.
+  dispose = null as AnyDuringMigration;
+  div!.textContent = '';
+
+  if (rendererClassName) {
+    // AnyDuringMigration because:  Argument of type 'HTMLDivElement | null' is
+    // not assignable to parameter of type 'Element'.
+    dom.removeClass(div as AnyDuringMigration, rendererClassName);
+    rendererClassName = '';
+  }
+  if (themeClassName) {
+    // AnyDuringMigration because:  Argument of type 'HTMLDivElement | null' is
+    // not assignable to parameter of type 'Element'.
+    dom.removeClass(div as AnyDuringMigration, themeClassName);
+    themeClassName = '';
+  }
+  (common.getMainWorkspace() as WorkspaceSvg).markFocused();
+}
+
+/**
+ * Is the container visible?
+ * @return True if visible.
+ * @alias Blockly.WidgetDiv.isVisible
+ */
+export function isVisible(): boolean {
+  return !!owner;
+}
+
+/**
+ * Destroy the widget and hide the div if it is being used by the specified
+ * object.
+ * @param oldOwner The object that was using this container.
+ * @alias Blockly.WidgetDiv.hideIfOwner
+ */
+export function hideIfOwner(oldOwner: AnyDuringMigration) {
+  if (owner === oldOwner) {
+    hide();
+  }
+}
+/**
+ * Set the widget div's position and height.  This function does nothing clever:
+ * it will not ensure that your widget div ends up in the visible window.
+ * @param x Horizontal location (window coordinates, not body).
+ * @param y Vertical location (window coordinates, not body).
+ * @param height The height of the widget div (pixels).
+ */
+function positionInternal(x: number, y: number, height: number) {
+  containerDiv!.style.left = x + 'px';
+  containerDiv!.style.top = y + 'px';
+  containerDiv!.style.height = height + 'px';
+}
+
+/**
+ * Position the widget div based on an anchor rectangle.
+ * The widget should be placed adjacent to but not overlapping the anchor
+ * rectangle.  The preferred position is directly below and aligned to the left
+ * (LTR) or right (RTL) side of the anchor.
+ * @param viewportBBox The bounding rectangle of the current viewport, in window
+ *     coordinates.
+ * @param anchorBBox The bounding rectangle of the anchor, in window
+ *     coordinates.
+ * @param widgetSize The size of the widget that is inside the widget div, in
+ *     window coordinates.
+ * @param rtl Whether the workspace is in RTL mode.  This determines horizontal
+ *     alignment.
+ * @alias Blockly.WidgetDiv.positionWithAnchor
+ * @internal
+ */
+export function positionWithAnchor(
+    viewportBBox: Rect, anchorBBox: Rect, widgetSize: Size, rtl: boolean) {
+  const y = calculateY(viewportBBox, anchorBBox, widgetSize);
+  const x = calculateX(viewportBBox, anchorBBox, widgetSize, rtl);
+
+  if (y < 0) {
+    positionInternal(x, 0, widgetSize.height + y);
+  } else {
+    positionInternal(x, y, widgetSize.height);
+  }
+}
+
+/**
+ * Calculate an x position (in window coordinates) such that the widget will not
+ * be offscreen on the right or left.
+ * @param viewportBBox The bounding rectangle of the current viewport, in window
+ *     coordinates.
+ * @param anchorBBox The bounding rectangle of the anchor, in window
+ *     coordinates.
+ * @param widgetSize The dimensions of the widget inside the widget div.
+ * @param rtl Whether the Blockly workspace is in RTL mode.
+ * @return A valid x-coordinate for the top left corner of the widget div, in
+ *     window coordinates.
+ */
+function calculateX(
+    viewportBBox: Rect, anchorBBox: Rect, widgetSize: Size,
+    rtl: boolean): number {
+  if (rtl) {
+    // Try to align the right side of the field and the right side of widget.
+    const widgetLeft = anchorBBox.right - widgetSize.width;
+    // Don't go offscreen left.
+    const x = Math.max(widgetLeft, viewportBBox.left);
+    // But really don't go offscreen right:
+    return Math.min(x, viewportBBox.right - widgetSize.width);
+  } else {
+    // Try to align the left side of the field and the left side of widget.
+    // Don't go offscreen right.
+    const x = Math.min(anchorBBox.left, viewportBBox.right - widgetSize.width);
+    // But left is more important, because that's where the text is.
+    return Math.max(x, viewportBBox.left);
+  }
+}
+
+/**
+ * Calculate a y position (in window coordinates) such that the widget will not
+ * be offscreen on the top or bottom.
+ * @param viewportBBox The bounding rectangle of the current viewport, in window
+ *     coordinates.
+ * @param anchorBBox The bounding rectangle of the anchor, in window
+ *     coordinates.
+ * @param widgetSize The dimensions of the widget inside the widget div.
+ * @return A valid y-coordinate for the top left corner of the widget div, in
+ *     window coordinates.
+ */
+function calculateY(
+    viewportBBox: Rect, anchorBBox: Rect, widgetSize: Size): number {
+  // Flip the widget vertically if off the bottom.
+  // The widget could go off the top of the window, but it would also go off
+  // the bottom.  The window is just too small.
+  if (anchorBBox.bottom + widgetSize.height >= viewportBBox.bottom) {
+    // The bottom of the widget is at the top of the field.
+    return anchorBBox.top - widgetSize.height;
+  } else {
+    // The top of the widget is at the bottom of the field.
+    return anchorBBox.bottom;
+  }
+}

package/core/workspace.d.ts

@@ -0,0 +1,386 @@
+/**
+ * @license
+ * Copyright 2012 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import './connection_checker.js';
+import type { Block } from './block.js';
+import type { ConnectionDB } from './connection_db.js';
+import type { Abstract } from './events/events_abstract.js';
+import type { IASTNodeLocation } from './interfaces/i_ast_node_location.js';
+import type { IConnectionChecker } from './interfaces/i_connection_checker.js';
+import { Options } from './options.js';
+import type * as toolbox from './utils/toolbox.js';
+import { VariableMap } from './variable_map.js';
+import type { VariableModel } from './variable_model.js';
+import type { WorkspaceComment } from './workspace_comment.js';
+/**
+ * Class for a workspace.  This is a data structure that contains blocks.
+ * There is no UI, and can be created headlessly.
+ * @alias Blockly.Workspace
+ */
+export declare class Workspace implements IASTNodeLocation {
+    /**
+     * Angle away from the horizontal to sweep for blocks.  Order of execution is
+     * generally top to bottom, but a small angle changes the scan to give a bit
+     * of a left to right bias (reversed in RTL).  Units are in degrees. See:
+     * https://tvtropes.org/pmwiki/pmwiki.php/Main/DiagonalBilling
+     */
+    static SCAN_ANGLE: number;
+    id: string;
+    options: Options;
+    RTL: boolean;
+    horizontalLayout: boolean;
+    toolboxPosition: toolbox.Position;
+    /**
+     * Returns `true` if the workspace is visible and `false` if it's headless.
+     */
+    rendered: boolean;
+    /**
+     * Is this workspace the surface for a flyout?
+     * @internal
+     */
+    internalIsFlyout: boolean;
+    /** Is this workspace the surface for a flyout? */
+    get isFlyout(): boolean;
+    /**
+     * Is this workspace the surface for a mutator?
+     * @internal
+     */
+    internalIsMutator: boolean;
+    /** Is this workspace the surface for a mutator? */
+    get isMutator(): boolean;
+    /**
+     * Returns `true` if the workspace is currently in the process of a bulk
+     * clear.
+     * @internal
+     */
+    isClearing: boolean;
+    /**
+     * Maximum number of undo events in stack. `0` turns off undo, `Infinity`
+     * sets it to unlimited.
+     */
+    MAX_UNDO: number;
+    /** Set of databases for rapid lookup of connection locations. */
+    connectionDBList: ConnectionDB[];
+    connectionChecker: IConnectionChecker;
+    private readonly topBlocks_;
+    private readonly topComments_;
+    private readonly commentDB;
+    private readonly listeners_;
+    protected undoStack_: Abstract[];
+    protected redoStack_: Abstract[];
+    private readonly blockDB;
+    private readonly typedBlocksDB;
+    private variableMap_;
+    /**
+     * Blocks in the flyout can refer to variables that don't exist in the main
+     * workspace.  For instance, the "get item in list" block refers to an
+     * "item" variable regardless of whether the variable has been created yet.
+     * A FieldVariable must always refer to a VariableModel.  We reconcile
+     * these by tracking "potential" variables in the flyout.  These variables
+     * become real when references to them are dragged into the main workspace.
+     */
+    private potentialVariableMap_;
+    /** @param opt_options Dictionary of options. */
+    constructor(opt_options?: Options);
+    /**
+     * Dispose of this workspace.
+     * Unlink from all DOM elements to prevent memory leaks.
+     * @suppress {checkTypes}
+     */
+    dispose(): void;
+    /**
+     * Compare function for sorting objects (blocks, comments, etc) by position;
+     *    top to bottom (with slight LTR or RTL bias).
+     * @param a The first object to compare.
+     * @param b The second object to compare.
+     * @return The comparison value. This tells Array.sort() how to change object
+     *     a's index.
+     */
+    private sortObjects_;
+    /**
+     * Adds a block to the list of top blocks.
+     * @param block Block to add.
+     */
+    addTopBlock(block: Block): void;
+    /**
+     * Removes a block from the list of top blocks.
+     * @param block Block to remove.
+     */
+    removeTopBlock(block: Block): void;
+    /**
+     * Finds the top-level blocks and returns them.  Blocks are optionally sorted
+     * by position; top to bottom (with slight LTR or RTL bias).
+     * @param ordered Sort the list if true.
+     * @return The top-level block objects.
+     */
+    getTopBlocks(ordered: boolean): Block[];
+    /**
+     * Add a block to the list of blocks keyed by type.
+     * @param block Block to add.
+     */
+    addTypedBlock(block: Block): void;
+    /**
+     * Remove a block from the list of blocks keyed by type.
+     * @param block Block to remove.
+     */
+    removeTypedBlock(block: Block): void;
+    /**
+     * Finds the blocks with the associated type and returns them. Blocks are
+     * optionally sorted by position; top to bottom (with slight LTR or RTL bias).
+     * @param type The type of block to search for.
+     * @param ordered Sort the list if true.
+     * @return The blocks of the given type.
+     */
+    getBlocksByType(type: string, ordered: boolean): Block[];
+    /**
+     * Adds a comment to the list of top comments.
+     * @param comment comment to add.
+     * @internal
+     */
+    addTopComment(comment: WorkspaceComment): void;
+    /**
+     * Removes a comment from the list of top comments.
+     * @param comment comment to remove.
+     * @internal
+     */
+    removeTopComment(comment: WorkspaceComment): void;
+    /**
+     * Finds the top-level comments and returns them.  Comments are optionally
+     * sorted by position; top to bottom (with slight LTR or RTL bias).
+     * @param ordered Sort the list if true.
+     * @return The top-level comment objects.
+     * @internal
+     */
+    getTopComments(ordered: boolean): WorkspaceComment[];
+    /**
+     * Find all blocks in workspace.  Blocks are optionally sorted
+     * by position; top to bottom (with slight LTR or RTL bias).
+     * @param ordered Sort the list if true.
+     * @return Array of blocks.
+     */
+    getAllBlocks(ordered: boolean): Block[];
+    /** Dispose of all blocks and comments in workspace. */
+    clear(): void;
+    /**
+     * Rename a variable by updating its name in the variable map. Identify the
+     * variable to rename with the given ID.
+     * @param id ID of the variable to rename.
+     * @param newName New variable name.
+     */
+    renameVariableById(id: string, newName: string): void;
+    /**
+     * Create a variable with a given name, optional type, and optional ID.
+     * @param name The name of the variable. This must be unique across variables
+     *     and procedures.
+     * @param opt_type The type of the variable like 'int' or 'string'.
+     *     Does not need to be unique. Field_variable can filter variables based
+     * on their type. This will default to '' which is a specific type.
+     * @param opt_id The unique ID of the variable. This will default to a UUID.
+     * @return The newly created variable.
+     */
+    createVariable(name: string, opt_type?: string | null, opt_id?: string | null): VariableModel;
+    /**
+     * Find all the uses of the given variable, which is identified by ID.
+     * @param id ID of the variable to find.
+     * @return Array of block usages.
+     */
+    getVariableUsesById(id: string): Block[];
+    /**
+     * Delete a variables by the passed in ID and all of its uses from this
+     * workspace. May prompt the user for confirmation.
+     * @param id ID of variable to delete.
+     */
+    deleteVariableById(id: string): void;
+    /**
+     * Find the variable by the given name and return it. Return null if not
+     * found.
+     * @param name The name to check for.
+     * @param opt_type The type of the variable.  If not provided it defaults to
+     *     the empty string, which is a specific type.
+     * @return The variable with the given name.
+     */
+    getVariable(name: string, opt_type?: string): VariableModel | null;
+    /**
+     * Find the variable by the given ID and return it. Return null if not found.
+     * @param id The ID to check for.
+     * @return The variable with the given ID.
+     */
+    getVariableById(id: string): VariableModel | null;
+    /**
+     * Find the variable with the specified type. If type is null, return list of
+     *     variables with empty string type.
+     * @param type Type of the variables to find.
+     * @return The sought after variables of the passed in type. An empty array if
+     *     none are found.
+     */
+    getVariablesOfType(type: string | null): VariableModel[];
+    /**
+     * Return all variable types.
+     * @return List of variable types.
+     * @internal
+     */
+    getVariableTypes(): string[];
+    /**
+     * Return all variables of all types.
+     * @return List of variable models.
+     */
+    getAllVariables(): VariableModel[];
+    /**
+     * Returns all variable names of all types.
+     * @return List of all variable names of all types.
+     */
+    getAllVariableNames(): string[];
+    /**
+     * Returns the horizontal offset of the workspace.
+     * Intended for LTR/RTL compatibility in XML.
+     * Not relevant for a headless workspace.
+     * @return Width.
+     */
+    getWidth(): number;
+    /**
+     * Obtain a newly created block.
+     * @param prototypeName Name of the language object containing type-specific
+     *     functions for this block.
+     * @param opt_id Optional ID.  Use this ID if provided, otherwise create a new
+     *     ID.
+     * @return The created block.
+     */
+    newBlock(prototypeName: string, opt_id?: string): Block;
+    /**
+     * The number of blocks that may be added to the workspace before reaching
+     *     the maxBlocks.
+     * @return Number of blocks left.
+     */
+    remainingCapacity(): number;
+    /**
+     * The number of blocks of the given type that may be added to the workspace
+     *    before reaching the maxInstances allowed for that type.
+     * @param type Type of block to return capacity for.
+     * @return Number of blocks of type left.
+     */
+    remainingCapacityOfType(type: string): number;
+    /**
+     * Check if there is remaining capacity for blocks of the given counts to be
+     *    created. If the total number of blocks represented by the map is more
+     * than the total remaining capacity, it returns false. If a type count is
+     * more than the remaining capacity for that type, it returns false.
+     * @param typeCountsMap A map of types to counts (usually representing blocks
+     *     to be created).
+     * @return True if there is capacity for the given map, false otherwise.
+     */
+    isCapacityAvailable(typeCountsMap: any): boolean;
+    /**
+     * Checks if the workspace has any limits on the maximum number of blocks,
+     *    or the maximum number of blocks of specific types.
+     * @return True if it has block limits, false otherwise.
+     */
+    hasBlockLimits(): boolean;
+    /**
+     * Gets the undo stack for workplace.
+     * @return undo stack
+     * @internal
+     */
+    getUndoStack(): Abstract[];
+    /**
+     * Gets the redo stack for workplace.
+     * @return redo stack
+     * @internal
+     */
+    getRedoStack(): Abstract[];
+    /**
+     * Undo or redo the previous action.
+     * @param redo False if undo, true if redo.
+     */
+    undo(redo: boolean): void;
+    /** Clear the undo/redo stacks. */
+    clearUndo(): void;
+    /**
+     * When something in this workspace changes, call a function.
+     * Note that there may be a few recent events already on the stack.  Thus the
+     * new change listener might be called with events that occurred a few
+     * milliseconds before the change listener was added.
+     * @param func Function to call.
+     * @return Obsolete return value, ignore.
+     */
+    addChangeListener(func: Function): Function;
+    /**
+     * Stop listening for this workspace's changes.
+     * @param func Function to stop calling.
+     */
+    removeChangeListener(func: Function): void;
+    /**
+     * Fire a change event.
+     * @param event Event to fire.
+     */
+    fireChangeListener(event: Abstract): void;
+    /**
+     * Find the block on this workspace with the specified ID.
+     * @param id ID of block to find.
+     * @return The sought after block, or null if not found.
+     */
+    getBlockById(id: string): Block | null;
+    /**
+     * Set a block on this workspace with the specified ID.
+     * @param id ID of block to set.
+     * @param block The block to set.
+     * @internal
+     */
+    setBlockById(id: string, block: Block): void;
+    /**
+     * Delete a block off this workspace with the specified ID.
+     * @param id ID of block to delete.
+     * @internal
+     */
+    removeBlockById(id: string): void;
+    /**
+     * Find the comment on this workspace with the specified ID.
+     * @param id ID of comment to find.
+     * @return The sought after comment, or null if not found.
+     * @internal
+     */
+    getCommentById(id: string): WorkspaceComment | null;
+    /**
+     * Checks whether all value and statement inputs in the workspace are filled
+     * with blocks.
+     * @param opt_shadowBlocksAreFilled An optional argument controlling whether
+     *     shadow blocks are counted as filled. Defaults to true.
+     * @return True if all inputs are filled, false otherwise.
+     */
+    allInputsFilled(opt_shadowBlocksAreFilled?: boolean): boolean;
+    /**
+     * Return the variable map that contains "potential" variables.
+     * These exist in the flyout but not in the workspace.
+     * @return The potential variable map.
+     * @internal
+     */
+    getPotentialVariableMap(): VariableMap | null;
+    /**
+     * Create and store the potential variable map for this workspace.
+     * @internal
+     */
+    createPotentialVariableMap(): void;
+    /**
+     * Return the map of all variables on the workspace.
+     * @return The variable map.
+     */
+    getVariableMap(): VariableMap;
+    /**
+     * Set the map of all variables on the workspace.
+     * @param variableMap The variable map.
+     * @internal
+     */
+    setVariableMap(variableMap: VariableMap): void;
+    /**
+     * Find the workspace with the specified ID.
+     * @param id ID of workspace to find.
+     * @return The sought after workspace or null if not found.
+     */
+    static getById(id: string): Workspace | null;
+    /**
+     * Find all workspaces.
+     * @return Array of workspaces.
+     */
+    static getAll(): Workspace[];
+}