blockly 8.0.5 → 9.0.0-beta.0

package/core/renderers/common/path_object.d.ts

@@ -0,0 +1,146 @@
+/**
+ * @license
+ * Copyright 2019 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { BlockSvg } from '../../block_svg.js';
+import type { Connection } from '../../connection.js';
+import type { BlockStyle } from '../../theme.js';
+import type { ConstantProvider } from './constants.js';
+import type { IPathObject } from './i_path_object.js';
+/**
+ * An object that handles creating and setting each of the SVG elements
+ * used by the renderer.
+ * @alias Blockly.blockRendering.PathObject
+ */
+export declare class PathObject implements IPathObject {
+    svgRoot: any;
+    /** @internal */
+    svgPath: SVGElement;
+    /**
+     * Holds the cursors svg element when the cursor is attached to the block.
+     * This is null if there is no cursor on the block.
+     * @internal
+     */
+    cursorSvg: SVGElement;
+    /**
+     * Holds the markers svg element when the marker is attached to the block.
+     * This is null if there is no marker on the block.
+     * @internal
+     */
+    markerSvg: SVGElement;
+    /** @internal */
+    constants: ConstantProvider;
+    /** @internal */
+    style: BlockStyle;
+    /**
+     * @param root The root SVG element.
+     * @param style The style object to use for colouring.
+     * @param constants The renderer's constants.
+     * @internal
+     */
+    constructor(root: SVGElement, style: BlockStyle, constants: ConstantProvider);
+    /**
+     * Set the path generated by the renderer onto the respective SVG element.
+     * @param pathString The path.
+     * @internal
+     */
+    setPath(pathString: string): void;
+    /**
+     * Flip the SVG paths in RTL.
+     * @internal
+     */
+    flipRTL(): void;
+    /**
+     * Add the cursor SVG to this block's SVG group.
+     * @param cursorSvg The SVG root of the cursor to be added to the block SVG
+     *     group.
+     * @internal
+     */
+    setCursorSvg(cursorSvg: SVGElement): void;
+    /**
+     * Add the marker SVG to this block's SVG group.
+     * @param markerSvg The SVG root of the marker to be added to the block SVG
+     *     group.
+     * @internal
+     */
+    setMarkerSvg(markerSvg: SVGElement): void;
+    /**
+     * Apply the stored colours to the block's path, taking into account whether
+     * the paths belong to a shadow block.
+     * @param block The source block.
+     * @internal
+     */
+    applyColour(block: BlockSvg): void;
+    /**
+     * Set the style.
+     * @param blockStyle The block style to use.
+     * @internal
+     */
+    setStyle(blockStyle: BlockStyle): void;
+    /**
+     * Add or remove the given CSS class on the path object's root SVG element.
+     * @param className The name of the class to add or remove
+     * @param add True if the class should be added.  False if it should be
+     *     removed.
+     */
+    protected setClass_(className: string, add: boolean): void;
+    /**
+     * Set whether the block shows a highlight or not.  Block highlighting is
+     * often used to visually mark blocks currently being executed.
+     * @param enable True if highlighted.
+     * @internal
+     */
+    updateHighlighted(enable: boolean): void;
+    /**
+     * Updates the look of the block to reflect a shadow state.
+     * @param shadow True if the block is a shadow block.
+     */
+    protected updateShadow_(shadow: boolean): void;
+    /**
+     * Updates the look of the block to reflect a disabled state.
+     * @param disabled True if disabled.
+     */
+    protected updateDisabled_(disabled: boolean): void;
+    /**
+     * Add or remove styling showing that a block is selected.
+     * @param enable True if selection is enabled, false otherwise.
+     * @internal
+     */
+    updateSelected(enable: boolean): void;
+    /**
+     * Add or remove styling showing that a block is dragged over a delete area.
+     * @param enable True if the block is being dragged over a delete area, false
+     *     otherwise.
+     * @internal
+     */
+    updateDraggingDelete(enable: boolean): void;
+    /**
+     * Add or remove styling showing that a block is an insertion marker.
+     * @param enable True if the block is an insertion marker, false otherwise.
+     * @internal
+     */
+    updateInsertionMarker(enable: boolean): void;
+    /**
+     * Add or remove styling showing that a block is movable.
+     * @param enable True if the block is movable, false otherwise.
+     * @internal
+     */
+    updateMovable(enable: boolean): void;
+    /**
+     * Add or remove styling that shows that if the dragging block is dropped,
+     * this block will be replaced.  If a shadow block, it will disappear.
+     * Otherwise it will bump.
+     * @param enable True if styling should be added.
+     * @internal
+     */
+    updateReplacementFade(enable: boolean): void;
+    /**
+     * Add or remove styling that shows that if the dragging block is dropped,
+     * this block will be connected to the input.
+     * @param _conn The connection on the input to highlight.
+     * @param _enable True if styling should be added.
+     * @internal
+     */
+    updateShapeForInputHighlight(_conn: Connection, _enable: boolean): void;
+}

package/core/renderers/common/path_object.ts

@@ -0,0 +1,272 @@
+/**
+ * @license
+ * Copyright 2019 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * @fileoverview An object that owns a block's rendering SVG elements.
+ */
+
+/**
+ * An object that owns a block's rendering SVG elements.
+ * @class
+ */
+import * as goog from '../../../closure/goog/goog.js';
+goog.declareModuleId('Blockly.blockRendering.PathObject');
+
+/* eslint-disable-next-line no-unused-vars */
+// Unused import preserved for side-effects. Remove if unneeded.
+// import '../../theme.js';
+
+import type {BlockSvg} from '../../block_svg.js';
+import type {Connection} from '../../connection.js';
+import type {BlockStyle} from '../../theme.js';
+import * as dom from '../../utils/dom.js';
+import {Svg} from '../../utils/svg.js';
+
+import type {ConstantProvider} from './constants.js';
+import type {IPathObject} from './i_path_object.js';
+
+
+/**
+ * An object that handles creating and setting each of the SVG elements
+ * used by the renderer.
+ * @alias Blockly.blockRendering.PathObject
+ */
+export class PathObject implements IPathObject {
+  svgRoot: AnyDuringMigration;
+  /** @internal */
+  svgPath: SVGElement;
+
+  /**
+   * Holds the cursors svg element when the cursor is attached to the block.
+   * This is null if there is no cursor on the block.
+   * @internal
+   */
+  // AnyDuringMigration because:  Type 'null' is not assignable to type
+  // 'SVGElement'.
+  cursorSvg: SVGElement = null as AnyDuringMigration;
+
+  /**
+   * Holds the markers svg element when the marker is attached to the block.
+   * This is null if there is no marker on the block.
+   * @internal
+   */
+  // AnyDuringMigration because:  Type 'null' is not assignable to type
+  // 'SVGElement'.
+  markerSvg: SVGElement = null as AnyDuringMigration;
+
+  /** @internal */
+  constants: ConstantProvider;
+  /** @internal */
+  style: BlockStyle;
+
+  /**
+   * @param root The root SVG element.
+   * @param style The style object to use for colouring.
+   * @param constants The renderer's constants.
+   * @internal
+   */
+  constructor(
+      root: SVGElement, style: BlockStyle, constants: ConstantProvider) {
+    this.constants = constants;
+    this.style = style;
+    this.svgRoot = root;
+
+    /** The primary path of the block. */
+    this.svgPath =
+        dom.createSvgElement(Svg.PATH, {'class': 'blocklyPath'}, this.svgRoot);
+  }
+
+  /**
+   * Set the path generated by the renderer onto the respective SVG element.
+   * @param pathString The path.
+   * @internal
+   */
+  setPath(pathString: string) {
+    this.svgPath.setAttribute('d', pathString);
+  }
+
+  /**
+   * Flip the SVG paths in RTL.
+   * @internal
+   */
+  flipRTL() {
+    // Mirror the block's path.
+    this.svgPath.setAttribute('transform', 'scale(-1 1)');
+  }
+
+  /**
+   * Add the cursor SVG to this block's SVG group.
+   * @param cursorSvg The SVG root of the cursor to be added to the block SVG
+   *     group.
+   * @internal
+   */
+  setCursorSvg(cursorSvg: SVGElement) {
+    if (!cursorSvg) {
+      // AnyDuringMigration because:  Type 'null' is not assignable to type
+      // 'SVGElement'.
+      this.cursorSvg = null as AnyDuringMigration;
+      return;
+    }
+
+    this.svgRoot.appendChild(cursorSvg);
+    this.cursorSvg = cursorSvg;
+  }
+
+  /**
+   * Add the marker SVG to this block's SVG group.
+   * @param markerSvg The SVG root of the marker to be added to the block SVG
+   *     group.
+   * @internal
+   */
+  setMarkerSvg(markerSvg: SVGElement) {
+    if (!markerSvg) {
+      // AnyDuringMigration because:  Type 'null' is not assignable to type
+      // 'SVGElement'.
+      this.markerSvg = null as AnyDuringMigration;
+      return;
+    }
+
+    if (this.cursorSvg) {
+      this.svgRoot.insertBefore(markerSvg, this.cursorSvg);
+    } else {
+      this.svgRoot.appendChild(markerSvg);
+    }
+    this.markerSvg = markerSvg;
+  }
+
+  /**
+   * Apply the stored colours to the block's path, taking into account whether
+   * the paths belong to a shadow block.
+   * @param block The source block.
+   * @internal
+   */
+  applyColour(block: BlockSvg) {
+    this.svgPath.setAttribute('stroke', this.style.colourTertiary);
+    this.svgPath.setAttribute('fill', this.style.colourPrimary);
+
+    this.updateShadow_(block.isShadow());
+    this.updateDisabled_(!block.isEnabled() || block.getInheritedDisabled());
+  }
+
+  /**
+   * Set the style.
+   * @param blockStyle The block style to use.
+   * @internal
+   */
+  setStyle(blockStyle: BlockStyle) {
+    this.style = blockStyle;
+  }
+
+  /**
+   * Add or remove the given CSS class on the path object's root SVG element.
+   * @param className The name of the class to add or remove
+   * @param add True if the class should be added.  False if it should be
+   *     removed.
+   */
+  protected setClass_(className: string, add: boolean) {
+    if (add) {
+      dom.addClass(this.svgRoot as Element, className);
+    } else {
+      dom.removeClass(this.svgRoot as Element, className);
+    }
+  }
+
+  /**
+   * Set whether the block shows a highlight or not.  Block highlighting is
+   * often used to visually mark blocks currently being executed.
+   * @param enable True if highlighted.
+   * @internal
+   */
+  updateHighlighted(enable: boolean) {
+    if (enable) {
+      this.svgPath.setAttribute(
+          'filter', 'url(#' + this.constants.embossFilterId + ')');
+    } else {
+      this.svgPath.setAttribute('filter', 'none');
+    }
+  }
+
+  /**
+   * Updates the look of the block to reflect a shadow state.
+   * @param shadow True if the block is a shadow block.
+   */
+  protected updateShadow_(shadow: boolean) {
+    if (shadow) {
+      this.svgPath.setAttribute('stroke', 'none');
+      this.svgPath.setAttribute('fill', this.style.colourSecondary);
+    }
+  }
+
+  /**
+   * Updates the look of the block to reflect a disabled state.
+   * @param disabled True if disabled.
+   */
+  protected updateDisabled_(disabled: boolean) {
+    this.setClass_('blocklyDisabled', disabled);
+    if (disabled) {
+      this.svgPath.setAttribute(
+          'fill', 'url(#' + this.constants.disabledPatternId + ')');
+    }
+  }
+
+  /**
+   * Add or remove styling showing that a block is selected.
+   * @param enable True if selection is enabled, false otherwise.
+   * @internal
+   */
+  updateSelected(enable: boolean) {
+    this.setClass_('blocklySelected', enable);
+  }
+
+  /**
+   * Add or remove styling showing that a block is dragged over a delete area.
+   * @param enable True if the block is being dragged over a delete area, false
+   *     otherwise.
+   * @internal
+   */
+  updateDraggingDelete(enable: boolean) {
+    this.setClass_('blocklyDraggingDelete', enable);
+  }
+
+  /**
+   * Add or remove styling showing that a block is an insertion marker.
+   * @param enable True if the block is an insertion marker, false otherwise.
+   * @internal
+   */
+  updateInsertionMarker(enable: boolean) {
+    this.setClass_('blocklyInsertionMarker', enable);
+  }
+
+  /**
+   * Add or remove styling showing that a block is movable.
+   * @param enable True if the block is movable, false otherwise.
+   * @internal
+   */
+  updateMovable(enable: boolean) {
+    this.setClass_('blocklyDraggable', enable);
+  }
+
+  /**
+   * Add or remove styling that shows that if the dragging block is dropped,
+   * this block will be replaced.  If a shadow block, it will disappear.
+   * Otherwise it will bump.
+   * @param enable True if styling should be added.
+   * @internal
+   */
+  updateReplacementFade(enable: boolean) {
+    this.setClass_('blocklyReplaceable', enable);
+  }
+
+  /**
+   * Add or remove styling that shows that if the dragging block is dropped,
+   * this block will be connected to the input.
+   * @param _conn The connection on the input to highlight.
+   * @param _enable True if styling should be added.
+   * @internal
+   */
+  updateShapeForInputHighlight(_conn: Connection, _enable: boolean) {}
+}
+// NOP

package/core/renderers/common/renderer.d.ts

@@ -0,0 +1,157 @@
+/**
+ * @license
+ * Copyright 2019 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { BlockSvg } from '../../block_svg.js';
+import { Connection } from '../../connection.js';
+import { PreviewType } from '../../insertion_marker_manager.js';
+import type { IRegistrable } from '../../interfaces/i_registrable.js';
+import type { Marker } from '../../keyboard_nav/marker.js';
+import type { RenderedConnection } from '../../rendered_connection.js';
+import type { BlockStyle, Theme } from '../../theme.js';
+import type { WorkspaceSvg } from '../../workspace_svg.js';
+import { ConstantProvider } from './constants.js';
+import { Debug } from './debugger.js';
+import { Drawer } from './drawer.js';
+import type { IPathObject } from './i_path_object.js';
+import { RenderInfo } from './info.js';
+import { MarkerSvg } from './marker_svg.js';
+/**
+ * The base class for a block renderer.
+ * @alias Blockly.blockRendering.Renderer
+ */
+export declare class Renderer implements IRegistrable {
+    /** The renderer's constant provider. */
+    protected constants_: ConstantProvider;
+    /** @internal */
+    name: string;
+    /**
+     * Rendering constant overrides, passed in through options.
+     * @internal
+     */
+    overrides: object | null;
+    /**
+     * @param name The renderer name.
+     * @internal
+     */
+    constructor(name: string);
+    /**
+     * Gets the class name that identifies this renderer.
+     * @return The CSS class name.
+     * @internal
+     */
+    getClassName(): string;
+    /**
+     * Initialize the renderer.
+     * @param theme The workspace theme object.
+     * @param opt_rendererOverrides Rendering constant overrides.
+     * @internal
+     */
+    init(theme: Theme, opt_rendererOverrides?: object): void;
+    /**
+     * Create any DOM elements that this renderer needs.
+     * @param svg The root of the workspace's SVG.
+     * @param theme The workspace theme object.
+     * @internal
+     */
+    createDom(svg: SVGElement, theme: Theme): void;
+    /**
+     * Refresh the renderer after a theme change.
+     * @param svg The root of the workspace's SVG.
+     * @param theme The workspace theme object.
+     * @internal
+     */
+    refreshDom(svg: SVGElement, theme: Theme): void;
+    /**
+     * Dispose of this renderer.
+     * Delete all DOM elements that this renderer and its constants created.
+     * @internal
+     */
+    dispose(): void;
+    /**
+     * Create a new instance of the renderer's constant provider.
+     * @return The constant provider.
+     */
+    protected makeConstants_(): ConstantProvider;
+    /**
+     * Create a new instance of the renderer's render info object.
+     * @param block The block to measure.
+     * @return The render info object.
+     */
+    protected makeRenderInfo_(block: BlockSvg): RenderInfo;
+    /**
+     * Create a new instance of the renderer's drawer.
+     * @param block The block to render.
+     * @param info An object containing all information needed to render this
+     *     block.
+     * @return The drawer.
+     */
+    protected makeDrawer_(block: BlockSvg, info: RenderInfo): Drawer;
+    /**
+     * Create a new instance of the renderer's debugger.
+     * @return The renderer debugger.
+     * @suppress {strictModuleDepCheck} Debug renderer only included in
+     * playground.
+     */
+    protected makeDebugger_(): Debug;
+    /**
+     * Create a new instance of the renderer's marker drawer.
+     * @param workspace The workspace the marker belongs to.
+     * @param marker The marker.
+     * @return The object in charge of drawing the marker.
+     * @internal
+     */
+    makeMarkerDrawer(workspace: WorkspaceSvg, marker: Marker): MarkerSvg;
+    /**
+     * Create a new instance of a renderer path object.
+     * @param root The root SVG element.
+     * @param style The style object to use for colouring.
+     * @return The renderer path object.
+     * @internal
+     */
+    makePathObject(root: SVGElement, style: BlockStyle): IPathObject;
+    /**
+     * Get the current renderer's constant provider.  We assume that when this is
+     * called, the renderer has already been initialized.
+     * @return The constant provider.
+     * @internal
+     */
+    getConstants(): ConstantProvider;
+    /**
+     * Determine whether or not to highlight a connection.
+     * @param _conn The connection to determine whether or not to highlight.
+     * @return True if we should highlight the connection.
+     * @internal
+     */
+    shouldHighlightConnection(_conn: Connection): boolean;
+    /**
+     * Checks if an orphaned block can connect to the "end" of the topBlock's
+     * block-clump. If the clump is a row the end is the last input. If the clump
+     * is a stack, the end is the last next connection. If the clump is neither,
+     * then this returns false.
+     * @param topBlock The top block of the block clump we want to try and connect
+     *     to.
+     * @param orphanBlock The orphan block that wants to find a home.
+     * @param localType The type of the connection being dragged.
+     * @return Whether there is a home for the orphan or not.
+     * @internal
+     */
+    orphanCanConnectAtEnd(topBlock: BlockSvg, orphanBlock: BlockSvg, localType: number): boolean;
+    /**
+     * Chooses a connection preview method based on the available connection, the
+     * current dragged connection, and the block being dragged.
+     * @param closest The available connection.
+     * @param local The connection currently being dragged.
+     * @param topBlock The block currently being dragged.
+     * @return The preview type to display.
+     * @internal
+     */
+    getConnectionPreviewMethod(closest: RenderedConnection, local: RenderedConnection, topBlock: BlockSvg): PreviewType;
+    /**
+     * Render the block.
+     * @param block The block to render.
+     * @internal
+     */
+    render(block: BlockSvg): void;
+}