/** * @license * Copyright 2016 Google LLC * SPDX-License-Identifier: Apache-2.0 */ /** * @fileoverview Components for creating connections between blocks. */ /** * Components for creating connections between blocks. * @class */ import * as goog from '../closure/goog/goog.js'; goog.declareModuleId('Blockly.RenderedConnection'); import type {Block} from './block.js'; import type {BlockSvg} from './block_svg.js'; import * as common from './common.js'; import {config} from './config.js'; import {Connection} from './connection.js'; import type {ConnectionDB} from './connection_db.js'; import {ConnectionType} from './connection_type.js'; import * as eventUtils from './events/utils.js'; import * as internalConstants from './internal_constants.js'; import {Coordinate} from './utils/coordinate.js'; import * as dom from './utils/dom.js'; import {Svg} from './utils/svg.js'; import * as svgMath from './utils/svg_math.js'; import * as svgPaths from './utils/svg_paths.js'; /** A shape that has a pathDown property. */ interface PathDownShape { pathDown: string; } /** A shape that has a pathLeft property. */ interface PathLeftShape { pathLeft: string; } /** Maximum randomness in workspace units for bumping a block. */ const BUMP_RANDOMNESS = 10; /** * Class for a connection between blocks that may be rendered on screen. * @alias Blockly.RenderedConnection */ export class RenderedConnection extends Connection { // TODO(b/109816955): remove '!', see go/strict-prop-init-fix. sourceBlock_!: BlockSvg; private readonly db_: ConnectionDB; private readonly dbOpposite_: ConnectionDB; private readonly offsetInBlock_: Coordinate; private trackedState_: TrackedState; /** Connection this connection connects to. Null if not connected. */ override targetConnection: RenderedConnection|null = null; /** * @param source The block establishing this connection. * @param type The type of the connection. */ constructor(source: BlockSvg, type: number) { super(source, type); /** * Connection database for connections of this type on the current * workspace. */ this.db_ = source.workspace.connectionDBList[type]; /** * Connection database for connections compatible with this type on the * current workspace. */ this.dbOpposite_ = source.workspace .connectionDBList[internalConstants.OPPOSITE_TYPE[type]]; /** Workspace units, (0, 0) is top left of block. */ this.offsetInBlock_ = new Coordinate(0, 0); /** Describes the state of this connection's tracked-ness. */ this.trackedState_ = RenderedConnection.TrackedState.WILL_TRACK; } /** * Dispose of this connection. Remove it from the database (if it is * tracked) and call the super-function to deal with connected blocks. * @internal */ override dispose() { super.dispose(); if (this.trackedState_ === RenderedConnection.TrackedState.TRACKED) { this.db_.removeConnection(this, this.y); } } /** * Get the source block for this connection. * @return The source block. */ override getSourceBlock(): BlockSvg { return super.getSourceBlock() as BlockSvg; } /** * Returns the block that this connection connects to. * @return The connected block or null if none is connected. */ override targetBlock(): BlockSvg|null { return super.targetBlock() as BlockSvg; } /** * Returns the distance between this connection and another connection in * workspace units. * @param otherConnection The other connection to measure the distance to. * @return The distance between connections, in workspace units. */ distanceFrom(otherConnection: Connection): number { const xDiff = this.x - otherConnection.x; const yDiff = this.y - otherConnection.y; return Math.sqrt(xDiff * xDiff + yDiff * yDiff); } /** * Move the block(s) belonging to the connection to a point where they don't * visually interfere with the specified connection. * @param staticConnection The connection to move away from. * @internal */ bumpAwayFrom(staticConnection: RenderedConnection) { if (this.sourceBlock_.workspace.isDragging()) { // Don't move blocks around while the user is doing the same. return; } // Move the root block. let rootBlock = this.sourceBlock_.getRootBlock(); if (rootBlock.isInFlyout) { // Don't move blocks around in a flyout. return; } let reverse = false; if (!rootBlock.isMovable()) { // Can't bump an uneditable block away. // Check to see if the other block is movable. rootBlock = staticConnection.getSourceBlock().getRootBlock(); if (!rootBlock.isMovable()) { return; } // Swap the connections and move the 'static' connection instead. staticConnection = this; reverse = true; } // Raise it to the top for extra visibility. const selected = common.getSelected() == rootBlock; selected || rootBlock.addSelect(); let dx = staticConnection.x + config.snapRadius + Math.floor(Math.random() * BUMP_RANDOMNESS) - this.x; let dy = staticConnection.y + config.snapRadius + Math.floor(Math.random() * BUMP_RANDOMNESS) - this.y; if (reverse) { // When reversing a bump due to an uneditable block, bump up. dy = -dy; } if (rootBlock.RTL) { dx = staticConnection.x - config.snapRadius - Math.floor(Math.random() * BUMP_RANDOMNESS) - this.x; } rootBlock.moveBy(dx, dy); selected || rootBlock.removeSelect(); } /** * Change the connection's coordinates. * @param x New absolute x coordinate, in workspace coordinates. * @param y New absolute y coordinate, in workspace coordinates. */ moveTo(x: number, y: number) { if (this.trackedState_ === RenderedConnection.TrackedState.WILL_TRACK) { this.db_.addConnection(this, y); this.trackedState_ = RenderedConnection.TrackedState.TRACKED; } else if (this.trackedState_ === RenderedConnection.TrackedState.TRACKED) { this.db_.removeConnection(this, this.y); this.db_.addConnection(this, y); } this.x = x; this.y = y; } /** * Change the connection's coordinates. * @param dx Change to x coordinate, in workspace units. * @param dy Change to y coordinate, in workspace units. */ moveBy(dx: number, dy: number) { this.moveTo(this.x + dx, this.y + dy); } /** * Move this connection to the location given by its offset within the block * and the location of the block's top left corner. * @param blockTL The location of the top left corner of the block, in * workspace coordinates. */ moveToOffset(blockTL: Coordinate) { this.moveTo( blockTL.x + this.offsetInBlock_.x, blockTL.y + this.offsetInBlock_.y); } /** * Set the offset of this connection relative to the top left of its block. * @param x The new relative x, in workspace units. * @param y The new relative y, in workspace units. */ setOffsetInBlock(x: number, y: number) { this.offsetInBlock_.x = x; this.offsetInBlock_.y = y; } /** * Get the offset of this connection relative to the top left of its block. * @return The offset of the connection. * @internal */ getOffsetInBlock(): Coordinate { return this.offsetInBlock_; } /** * Move the blocks on either side of this connection right next to each other. * @internal */ tighten() { const dx = this.targetConnection!.x - this.x; const dy = this.targetConnection!.y - this.y; if (dx !== 0 || dy !== 0) { const block = this.targetBlock(); const svgRoot = block!.getSvgRoot(); if (!svgRoot) { throw Error('block is not rendered.'); } // Workspace coordinates. const xy = svgMath.getRelativeXY(svgRoot); block!.getSvgRoot().setAttribute( 'transform', 'translate(' + (xy.x - dx) + ',' + (xy.y - dy) + ')'); block!.moveConnections(-dx, -dy); } } /** * Find the closest compatible connection to this connection. * All parameters are in workspace units. * @param maxLimit The maximum radius to another connection. * @param dxy Offset between this connection's location in the database and * the current location (as a result of dragging). * @return Contains two properties: 'connection' which is either another * connection or null, and 'radius' which is the distance. */ closest(maxLimit: number, dxy: Coordinate): {connection: RenderedConnection|null, radius: number} { return this.dbOpposite_.searchForClosest(this, maxLimit, dxy); } /** Add highlighting around this connection. */ highlight() { let steps; const sourceBlockSvg = (this.sourceBlock_); const renderConstants = sourceBlockSvg.workspace.getRenderer().getConstants(); const shape = renderConstants.shapeFor(this); if (this.type === ConnectionType.INPUT_VALUE || this.type === ConnectionType.OUTPUT_VALUE) { // Vertical line, puzzle tab, vertical line. const yLen = renderConstants.TAB_OFFSET_FROM_TOP; steps = svgPaths.moveBy(0, -yLen) + svgPaths.lineOnAxis('v', yLen) + (shape as unknown as PathDownShape).pathDown + svgPaths.lineOnAxis('v', yLen); } else { const xLen = renderConstants.NOTCH_OFFSET_LEFT - renderConstants.CORNER_RADIUS; // Horizontal line, notch, horizontal line. steps = svgPaths.moveBy(-xLen, 0) + svgPaths.lineOnAxis('h', xLen) + (shape as unknown as PathLeftShape).pathLeft + svgPaths.lineOnAxis('h', xLen); } const xy = this.sourceBlock_.getRelativeToSurfaceXY(); const x = this.x - xy.x; const y = this.y - xy.y; // AnyDuringMigration because: Property 'highlightedPath_' does not exist // on type 'typeof Connection'. (Connection as AnyDuringMigration).highlightedPath_ = dom.createSvgElement( Svg.PATH, { 'class': 'blocklyHighlightedConnectionPath', 'd': steps, 'transform': 'translate(' + x + ',' + y + ')' + (this.sourceBlock_.RTL ? ' scale(-1 1)' : ''), }, this.sourceBlock_.getSvgRoot()); } /** Remove the highlighting around this connection. */ unhighlight() { // AnyDuringMigration because: Property 'highlightedPath_' does not exist // on type 'typeof Connection'. dom.removeNode((Connection as AnyDuringMigration).highlightedPath_); // AnyDuringMigration because: Property 'highlightedPath_' does not exist // on type 'typeof Connection'. delete (Connection as AnyDuringMigration).highlightedPath_; } /** * Set whether this connections is tracked in the database or not. * @param doTracking If true, start tracking. If false, stop tracking. * @internal */ setTracking(doTracking: boolean) { if (doTracking && this.trackedState_ === RenderedConnection.TrackedState.TRACKED || !doTracking && this.trackedState_ === RenderedConnection.TrackedState.UNTRACKED) { return; } if (this.sourceBlock_.isInFlyout) { // Don't bother maintaining a database of connections in a flyout. return; } if (doTracking) { this.db_.addConnection(this, this.y); this.trackedState_ = RenderedConnection.TrackedState.TRACKED; return; } if (this.trackedState_ === RenderedConnection.TrackedState.TRACKED) { this.db_.removeConnection(this, this.y); } this.trackedState_ = RenderedConnection.TrackedState.UNTRACKED; } /** * Stop tracking this connection, as well as all down-stream connections on * any block attached to this connection. This happens when a block is * collapsed. * * Also closes down-stream icons/bubbles. * @internal */ stopTrackingAll() { this.setTracking(false); if (this.targetConnection) { const blocks = this.targetBlock()!.getDescendants(false); for (let i = 0; i < blocks.length; i++) { const block = blocks[i]; // Stop tracking connections of all children. const connections = block.getConnections_(true); for (let j = 0; j < connections.length; j++) { (connections[j]).setTracking(false); } // Close all bubbles of all children. const icons = block.getIcons(); for (let j = 0; j < icons.length; j++) { icons[j].setVisible(false); } } } } /** * Start tracking this connection, as well as all down-stream connections on * any block attached to this connection. This happens when a block is * expanded. * @return List of blocks to render. */ startTrackingAll(): Block[] { this.setTracking(true); // All blocks that are not tracked must start tracking before any // rendering takes place, since rendering requires knowing the dimensions // of lower blocks. Also, since rendering a block renders all its parents, // we only need to render the leaf nodes. let renderList: AnyDuringMigration[] = []; if (this.type !== ConnectionType.INPUT_VALUE && this.type !== ConnectionType.NEXT_STATEMENT) { // Only spider down. return renderList; } const block = this.targetBlock(); if (block) { let connections; if (block.isCollapsed()) { // This block should only be partially revealed since it is collapsed. connections = []; block.outputConnection && connections.push(block.outputConnection); block.nextConnection && connections.push(block.nextConnection); block.previousConnection && connections.push(block.previousConnection); } else { // Show all connections of this block. connections = block.getConnections_(true); } for (let i = 0; i < connections.length; i++) { renderList.push.apply(renderList, connections[i].startTrackingAll()); } if (!renderList.length) { // Leaf block. renderList = [block]; } } return renderList; } /** * Behavior after a connection attempt fails. * Bumps this connection away from the other connection. Called when an * attempted connection fails. * @param otherConnection Connection that this connection failed to connect * to. * @internal */ override onFailedConnect(otherConnection: Connection) { const block = this.getSourceBlock(); if (eventUtils.getRecordUndo()) { const group = eventUtils.getGroup(); setTimeout(function(this: RenderedConnection) { if (!block.isDisposed() && !block.getParent()) { eventUtils.setGroup(group); this.bumpAwayFrom(otherConnection as RenderedConnection); eventUtils.setGroup(false); } }.bind(this), config.bumpDelay); } } /** * Disconnect two blocks that are connected by this connection. * @param parentBlock The superior block. * @param childBlock The inferior block. */ protected override disconnectInternal_( parentBlock: Block, childBlock: Block) { super.disconnectInternal_(parentBlock, childBlock); const renderedParent = parentBlock as BlockSvg; const renderedChild = childBlock as BlockSvg; // Rerender the parent so that it may reflow. if (renderedParent.rendered) { renderedParent.render(); } if (renderedChild.rendered) { renderedChild.updateDisabled(); renderedChild.render(); // Reset visibility, since the child is now a top block. renderedChild.getSvgRoot().style.display = 'block'; } } /** * Respawn the shadow block if there was one connected to the this connection. * Render/rerender blocks as needed. */ protected override respawnShadow_() { super.respawnShadow_(); const blockShadow = this.targetBlock(); if (!blockShadow) { return; } blockShadow.initSvg(); blockShadow.render(false); const parentBlock = this.getSourceBlock(); if (parentBlock.rendered) { parentBlock.render(); } } /** * Find all nearby compatible connections to this connection. * Type checking does not apply, since this function is used for bumping. * @param maxLimit The maximum radius to another connection, in workspace * units. * @return List of connections. * @internal */ override neighbours(maxLimit: number): Connection[] { return this.dbOpposite_.getNeighbours(this, maxLimit); } /** * Connect two connections together. This is the connection on the superior * block. Rerender blocks as needed. * @param childConnection Connection on inferior block. */ protected override connect_(childConnection: Connection) { super.connect_(childConnection); const renderedChildConnection = childConnection as RenderedConnection; const parentConnection = this; const parentBlock = parentConnection.getSourceBlock(); const childBlock = renderedChildConnection.getSourceBlock(); const parentRendered = parentBlock.rendered; const childRendered = childBlock.rendered; if (parentRendered) { parentBlock.updateDisabled(); } if (childRendered) { childBlock.updateDisabled(); } if (parentRendered && childRendered) { if (parentConnection.type === ConnectionType.NEXT_STATEMENT || parentConnection.type === ConnectionType.PREVIOUS_STATEMENT) { // Child block may need to square off its corners if it is in a stack. // Rendering a child will render its parent. childBlock.render(); } else { // Child block does not change shape. Rendering the parent node will // move its connected children into position. parentBlock.render(); } } // The input the child block is connected to (if any). const parentInput = parentBlock.getInputWithBlock(childBlock); if (parentInput) { const visible = parentInput.isVisible(); childBlock.getSvgRoot().style.display = visible ? 'block' : 'none'; } } /** * Function to be called when this connection's compatible types have changed. */ protected override onCheckChanged_() { // The new value type may not be compatible with the existing connection. if (this.isConnected() && (!this.targetConnection || !this.getConnectionChecker().canConnect( this, this.targetConnection, false))) { const child = this.isSuperior() ? this.targetBlock() : this.sourceBlock_; child!.unplug(); // Bump away. this.sourceBlock_.bumpNeighbours(); } } } export namespace RenderedConnection { /** * Enum for different kinds of tracked states. * * WILL_TRACK means that this connection will add itself to * the db on the next moveTo call it receives. * * UNTRACKED means that this connection will not add * itself to the database until setTracking(true) is explicitly called. * * TRACKED means that this connection is currently being tracked. */ export enum TrackedState { WILL_TRACK = -1, UNTRACKED = 0, TRACKED = 1, } } export type TrackedState = RenderedConnection.TrackedState; export const TrackedState = RenderedConnection.TrackedState;