/** * @license * Copyright 2011 Google LLC * SPDX-License-Identifier: Apache-2.0 */ /** * The class representing one block. * * @class */ import * as goog from '../closure/goog/goog.js'; goog.declareModuleId('Blockly.Block'); // Unused import preserved for side-effects. Remove if unneeded. import './events/events_block_change.js'; // Unused import preserved for side-effects. Remove if unneeded. import './events/events_block_create.js'; // Unused import preserved for side-effects. Remove if unneeded. import './events/events_block_delete.js'; import {Blocks} from './blocks.js'; import type {Comment} from './comment.js'; import * as common from './common.js'; import {Connection} from './connection.js'; import {ConnectionType} from './connection_type.js'; import * as constants from './constants.js'; import type {Abstract} from './events/events_abstract.js'; import type {BlockMove} from './events/events_block_move.js'; import * as eventUtils from './events/utils.js'; import * as Extensions from './extensions.js'; import type {Field} from './field.js'; import * as fieldRegistry from './field_registry.js'; import {Align, Input} from './input.js'; import {inputTypes} from './input_types.js'; import type {IASTNodeLocation} from './interfaces/i_ast_node_location.js'; import type {IDeletable} from './interfaces/i_deletable.js'; import {ASTNode} from './keyboard_nav/ast_node.js'; import type {Mutator} from './mutator.js'; import * as Tooltip from './tooltip.js'; import * as arrayUtils from './utils/array.js'; import {Coordinate} from './utils/coordinate.js'; import * as idGenerator from './utils/idgenerator.js'; import * as parsing from './utils/parsing.js'; import {Size} from './utils/size.js'; import type {VariableModel} from './variable_model.js'; import type {Workspace} from './workspace.js'; /** * Class for one block. * Not normally called directly, workspace.newBlock() is preferred. * * @alias Blockly.Block */ export class Block implements IASTNodeLocation, IDeletable { /** * An optional callback method to use whenever the block's parent workspace * changes. This is usually only called from the constructor, the block type * initializer function, or an extension initializer function. */ onchange?: ((p1: Abstract) => AnyDuringMigration)|null; /** The language-neutral ID given to the collapsed input. */ static readonly COLLAPSED_INPUT_NAME: string = constants.COLLAPSED_INPUT_NAME; /** The language-neutral ID given to the collapsed field. */ static readonly COLLAPSED_FIELD_NAME: string = constants.COLLAPSED_FIELD_NAME; /** * Optional text data that round-trips between blocks and XML. * Has no effect. May be used by 3rd parties for meta information. */ data: string|null = null; /** * Has this block been disposed of? * * @internal */ disposed = false; /** * Colour of the block as HSV hue value (0-360) * This may be null if the block colour was not set via a hue number. */ private hue_: number|null = null; /** Colour of the block in '#RRGGBB' format. */ protected colour_ = '#000000'; /** Name of the block style. */ protected styleName_ = ''; /** An optional method called during initialization. */ init?: (() => AnyDuringMigration)|null = undefined; /** * An optional serialization method for defining how to serialize the * mutation state to XML. This must be coupled with defining * `domToMutation`. */ mutationToDom?: ((...p1: AnyDuringMigration[]) => Element)|null = undefined; /** * An optional deserialization method for defining how to deserialize the * mutation state from XML. This must be coupled with defining * `mutationToDom`. */ domToMutation?: ((p1: Element) => AnyDuringMigration)|null = undefined; /** * An optional serialization method for defining how to serialize the * block's extra state (eg mutation state) to something JSON compatible. * This must be coupled with defining `loadExtraState`. */ saveExtraState?: (() => AnyDuringMigration)|null = undefined; /** * An optional serialization method for defining how to deserialize the * block's extra state (eg mutation state) from something JSON compatible. * This must be coupled with defining `saveExtraState`. */ loadExtraState?: ((p1: AnyDuringMigration) => AnyDuringMigration)|null = undefined; /** * An optional property for suppressing adding STATEMENT_PREFIX and * STATEMENT_SUFFIX to generated code. */ suppressPrefixSuffix: boolean|null = false; /** * An optional property for declaring developer variables. Return a list of * variable names for use by generators. Developer variables are never * shown to the user, but are declared as global variables in the generated * code. */ getDeveloperVariables?: (() => string[]) = undefined; /** * An optional function that reconfigures the block based on the contents of * the mutator dialog. */ compose?: ((p1: Block) => void) = undefined; /** * An optional function that populates the mutator's dialog with * this block's components. */ decompose?: ((p1: Workspace) => Block) = undefined; id: string; // AnyDuringMigration because: Type 'null' is not assignable to type // 'Connection'. outputConnection: Connection = null as AnyDuringMigration; // AnyDuringMigration because: Type 'null' is not assignable to type // 'Connection'. nextConnection: Connection = null as AnyDuringMigration; // AnyDuringMigration because: Type 'null' is not assignable to type // 'Connection'. previousConnection: Connection = null as AnyDuringMigration; inputList: Input[] = []; inputsInline?: boolean = undefined; private disabled = false; tooltip: Tooltip.TipInfo = ''; contextMenu = true; protected parentBlock_: this|null = null; protected childBlocks_: this[] = []; private deletable_ = true; private movable_ = true; private editable_ = true; private isShadow_ = false; protected collapsed_ = false; protected outputShape_: number|null = null; /** * A string representing the comment attached to this block. * * @deprecated August 2019. Use getCommentText instead. */ comment: string|Comment|null = null; /** @internal */ commentModel: CommentModel; private readonly xy_: Coordinate; isInFlyout: boolean; isInMutator: boolean; RTL: boolean; /** True if this block is an insertion marker. */ protected isInsertionMarker_ = false; /** Name of the type of hat. */ hat?: string = undefined; rendered: boolean|null = null; /** * String for block help, or function that returns a URL. Null for no help. */ // AnyDuringMigration because: Type 'null' is not assignable to type 'string // | Function'. helpUrl: string|Function = null as AnyDuringMigration; /** A bound callback function to use when the parent workspace changes. */ private onchangeWrapper_: ((p1: Abstract) => AnyDuringMigration)|null = null; /** * A count of statement inputs on the block. * * @internal */ statementInputCount = 0; // TODO(b/109816955): remove '!', see go/strict-prop-init-fix. type!: string; // Record initial inline state. inputsInlineDefault?: boolean; workspace: Workspace; /** * @param workspace The block's workspace. * @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. * @throws When the prototypeName is not valid or not allowed. */ constructor(workspace: Workspace, prototypeName: string, opt_id?: string) { this.workspace = workspace; this.id = opt_id && !workspace.getBlockById(opt_id) ? opt_id : idGenerator.genUid(); workspace.setBlockById(this.id, this); /** A model of the comment attached to this block. */ this.commentModel = {text: null, pinned: false, size: new Size(160, 80)}; /** * The block's position in workspace units. (0, 0) is at the workspace's * origin; scale does not change this value. */ this.xy_ = new Coordinate(0, 0); this.isInFlyout = workspace.isFlyout; this.isInMutator = workspace.isMutator; this.RTL = workspace.RTL; // Copy the type-specific functions and data from the prototype. if (prototypeName) { this.type = prototypeName; const prototype = Blocks[prototypeName]; if (!prototype || typeof prototype !== 'object') { throw TypeError('Invalid block definition for type: ' + prototypeName); } Object.assign(this, prototype); } workspace.addTopBlock(this); workspace.addTypedBlock(this); if (new.target === Block) { this.doInit_(); } } /** Calls the init() function and handles associated event firing, etc. */ protected doInit_() { // All events fired should be part of the same group. // Any events fired during init should not be undoable, // so that block creation is atomic. const existingGroup = eventUtils.getGroup(); if (!existingGroup) { eventUtils.setGroup(true); } const initialUndoFlag = eventUtils.getRecordUndo(); try { // Call an initialization function, if it exists. if (typeof this.init === 'function') { eventUtils.setRecordUndo(false); this.init(); eventUtils.setRecordUndo(initialUndoFlag); } // Fire a create event. if (eventUtils.isEnabled()) { eventUtils.fire(new (eventUtils.get(eventUtils.BLOCK_CREATE))(this)); } } finally { if (!existingGroup) { eventUtils.setGroup(false); } // In case init threw, recordUndo flag should still be reset. eventUtils.setRecordUndo(initialUndoFlag); } this.inputsInlineDefault = this.inputsInline; // Bind an onchange function, if it exists. if (typeof this.onchange === 'function') { this.setOnChange(this.onchange); } } /** * Dispose of this block. * * @param healStack If true, then try to heal any gap by connecting the next * statement with the previous statement. Otherwise, dispose of all * children of this block. * @suppress {checkTypes} */ dispose(healStack: boolean) { if (this.disposed) { return; } this.unplug(healStack); if (eventUtils.isEnabled()) { eventUtils.fire(new (eventUtils.get(eventUtils.BLOCK_DELETE))(this)); } if (this.onchangeWrapper_) { this.workspace.removeChangeListener(this.onchangeWrapper_); } eventUtils.disable(); try { // This block is now at the top of the workspace. // Remove this block from the workspace's list of top-most blocks. this.workspace.removeTopBlock(this); this.workspace.removeTypedBlock(this); // Remove from block database. this.workspace.removeBlockById(this.id); // First, dispose of all my children. for (let i = this.childBlocks_.length - 1; i >= 0; i--) { this.childBlocks_[i].dispose(false); } // Then dispose of myself. // Dispose of all inputs and their fields. for (let i = 0, input; input = this.inputList[i]; i++) { input.dispose(); } this.inputList.length = 0; // Dispose of any remaining connections (next/previous/output). const connections = this.getConnections_(true); for (let i = 0, connection; connection = connections[i]; i++) { connection.dispose(); } } finally { eventUtils.enable(); this.disposed = true; } } /** * Call initModel on all fields on the block. * May be called more than once. * Either initModel or initSvg must be called after creating a block and * before the first interaction with it. Interactions include UI actions * (e.g. clicking and dragging) and firing events (e.g. create, delete, and * change). */ initModel() { for (let i = 0, input; input = this.inputList[i]; i++) { for (let j = 0, field; field = input.fieldRow[j]; j++) { if (field.initModel) { field.initModel(); } } } } /** * Unplug this block from its superior block. If this block is a statement, * optionally reconnect the block underneath with the block on top. * * @param opt_healStack Disconnect child statement and reconnect stack. * Defaults to false. */ unplug(opt_healStack?: boolean) { if (this.outputConnection) { this.unplugFromRow_(opt_healStack); } if (this.previousConnection) { this.unplugFromStack_(opt_healStack); } } /** * Unplug this block's output from an input on another block. Optionally * reconnect the block's parent to the only child block, if possible. * * @param opt_healStack Disconnect right-side block and connect to left-side * block. Defaults to false. */ private unplugFromRow_(opt_healStack?: boolean) { let parentConnection = null; if (this.outputConnection.isConnected()) { parentConnection = this.outputConnection.targetConnection; // Disconnect from any superior block. this.outputConnection.disconnect(); } // Return early in obvious cases. if (!parentConnection || !opt_healStack) { return; } const thisConnection = this.getOnlyValueConnection_(); if (!thisConnection || !thisConnection.isConnected() || thisConnection.targetBlock()!.isShadow()) { // Too many or too few possible connections on this block, or there's // nothing on the other side of this connection. return; } const childConnection = thisConnection.targetConnection; // Disconnect the child block. childConnection?.disconnect(); // Connect child to the parent if possible, otherwise bump away. if (this.workspace.connectionChecker.canConnect( childConnection, parentConnection, false)) { parentConnection.connect(childConnection!); } else { childConnection?.onFailedConnect(parentConnection); } } /** * Returns the connection on the value input that is connected to another * block. When an insertion marker is connected to a connection with a block * already attached, the connected block is attached to the insertion marker. * Since only one block can be displaced and attached to the insertion marker * this should only ever return one connection. * * @returns The connection on the value input, or null. */ private getOnlyValueConnection_(): Connection|null { let connection = null; for (let i = 0; i < this.inputList.length; i++) { const thisConnection = this.inputList[i].connection; if (thisConnection && thisConnection.type === ConnectionType.INPUT_VALUE && thisConnection.targetConnection) { if (connection) { return null; // More than one value input found. } connection = thisConnection; } } return connection; } /** * Unplug this statement block from its superior block. Optionally reconnect * the block underneath with the block on top. * * @param opt_healStack Disconnect child statement and reconnect stack. * Defaults to false. */ private unplugFromStack_(opt_healStack?: boolean) { let previousTarget = null; if (this.previousConnection.isConnected()) { // Remember the connection that any next statements need to connect to. previousTarget = this.previousConnection.targetConnection; // Detach this block from the parent's tree. this.previousConnection.disconnect(); } const nextBlock = this.getNextBlock(); if (opt_healStack && nextBlock && !nextBlock.isShadow()) { // Disconnect the next statement. const nextTarget = this.nextConnection.targetConnection; nextTarget?.disconnect(); if (previousTarget && this.workspace.connectionChecker.canConnect( previousTarget, nextTarget, false)) { // Attach the next statement to the previous statement. previousTarget.connect(nextTarget!); } } } /** * Returns all connections originating from this block. * * @param _all If true, return all connections even hidden ones. * @returns Array of connections. * @internal */ getConnections_(_all: boolean): Connection[] { const myConnections = []; if (this.outputConnection) { myConnections.push(this.outputConnection); } if (this.previousConnection) { myConnections.push(this.previousConnection); } if (this.nextConnection) { myConnections.push(this.nextConnection); } for (let i = 0, input; input = this.inputList[i]; i++) { if (input.connection) { myConnections.push(input.connection); } } return myConnections; } /** * Walks down a stack of blocks and finds the last next connection on the * stack. * * @param ignoreShadows If true,the last connection on a non-shadow block will * be returned. If false, this will follow shadows to find the last * connection. * @returns The last next connection on the stack, or null. * @internal */ lastConnectionInStack(ignoreShadows: boolean): Connection|null { let nextConnection = this.nextConnection; while (nextConnection) { const nextBlock = nextConnection.targetBlock(); if (!nextBlock || ignoreShadows && nextBlock.isShadow()) { return nextConnection; } nextConnection = nextBlock.nextConnection; } return null; } /** * Bump unconnected blocks out of alignment. Two blocks which aren't actually * connected should not coincidentally line up on screen. */ bumpNeighbours() {} // noop. /** * Return the parent block or null if this block is at the top level. The * parent block is either the block connected to the previous connection (for * a statement block) or the block connected to the output connection (for a * value block). * * @returns The block (if any) that holds the current block. */ getParent(): this|null { return this.parentBlock_; } /** * Return the input that connects to the specified block. * * @param block A block connected to an input on this block. * @returns The input (if any) that connects to the specified block. */ getInputWithBlock(block: Block): Input|null { for (let i = 0, input; input = this.inputList[i]; i++) { if (input.connection && input.connection.targetBlock() === block) { return input; } } return null; } /** * Return the parent block that surrounds the current block, or null if this * block has no surrounding block. A parent block might just be the previous * statement, whereas the surrounding block is an if statement, while loop, * etc. * * @returns The block (if any) that surrounds the current block. */ getSurroundParent(): this|null { /* eslint-disable-next-line @typescript-eslint/no-this-alias */ let block = this; let prevBlock; do { prevBlock = block; // AnyDuringMigration because: Type 'Block | null' is not assignable to // type 'this'. block = block.getParent() as AnyDuringMigration; if (!block) { // Ran off the top. return null; } } while (block.getNextBlock() === prevBlock); // This block is an enclosing parent, not just a statement in a stack. return block; } /** * Return the next statement block directly connected to this block. * * @returns The next statement block or null. */ getNextBlock(): Block|null { return this.nextConnection && this.nextConnection.targetBlock(); } /** * Returns the block connected to the previous connection. * * @returns The previous statement block or null. */ getPreviousBlock(): Block|null { return this.previousConnection && this.previousConnection.targetBlock(); } /** * Return the connection on the first statement input on this block, or null * if there are none. * * @returns The first statement connection or null. * @internal */ getFirstStatementConnection(): Connection|null { for (let i = 0, input; input = this.inputList[i]; i++) { if (input.connection && input.connection.type === ConnectionType.NEXT_STATEMENT) { return input.connection; } } return null; } /** * Return the top-most block in this block's tree. * This will return itself if this block is at the top level. * * @returns The root block. */ getRootBlock(): this { let rootBlock: this; /* eslint-disable-next-line @typescript-eslint/no-this-alias */ let block: this|null = this; do { rootBlock = block; block = rootBlock.parentBlock_; } while (block); return rootBlock; } /** * Walk up from the given block up through the stack of blocks to find * the top block of the sub stack. If we are nested in a statement input only * find the top-most nested block. Do not go all the way to the root block. * * @returns The top block in a stack. * @internal */ getTopStackBlock(): this { /* eslint-disable-next-line @typescript-eslint/no-this-alias */ let block = this; let previous; do { previous = block.getPreviousBlock(); // AnyDuringMigration because: Type 'Block' is not assignable to type // 'this'. } while (previous && previous.getNextBlock() === block && (block = previous as AnyDuringMigration)); return block; } /** * Find all the blocks that are directly nested inside this one. * Includes value and statement inputs, as well as any following statement. * Excludes any connection on an output tab or any preceding statement. * Blocks are optionally sorted by position; top to bottom. * * @param ordered Sort the list if true. * @returns Array of blocks. */ getChildren(ordered: boolean): Block[] { if (!ordered) { return this.childBlocks_; } const blocks = []; for (let i = 0, input; input = this.inputList[i]; i++) { if (input.connection) { const child = input.connection.targetBlock(); if (child) { blocks.push(child); } } } const next = this.getNextBlock(); if (next) { blocks.push(next); } return blocks; } /** * Set parent of this block to be a new block or null. * * @param newParent New parent block. * @internal */ setParent(newParent: this|null) { if (newParent === this.parentBlock_) { return; } // Check that block is connected to new parent if new parent is not null and // that block is not connected to superior one if new parent is null. const targetBlock = this.previousConnection && this.previousConnection.targetBlock() || this.outputConnection && this.outputConnection.targetBlock(); const isConnected = !!targetBlock; if (isConnected && newParent && targetBlock !== newParent) { throw Error('Block connected to superior one that is not new parent.'); } else if (!isConnected && newParent) { throw Error('Block not connected to new parent.'); } else if (isConnected && !newParent) { throw Error( 'Cannot set parent to null while block is still connected to' + ' superior block.'); } // This block hasn't actually moved on-screen, so there's no need to // update // its connection locations. if (this.parentBlock_) { // Remove this block from the old parent's child list. arrayUtils.removeElem(this.parentBlock_.childBlocks_, this); } else { // New parent must be non-null so remove this block from the workspace's // list of top-most blocks. this.workspace.removeTopBlock(this); } this.parentBlock_ = newParent; if (newParent) { // Add this block to the new parent's child list. newParent.childBlocks_.push(this); } else { this.workspace.addTopBlock(this); } } /** * Find all the blocks that are directly or indirectly nested inside this one. * Includes this block in the list. * Includes value and statement inputs, as well as any following statements. * Excludes any connection on an output tab or any preceding statements. * Blocks are optionally sorted by position; top to bottom. * * @param ordered Sort the list if true. * @returns Flattened array of blocks. */ getDescendants(ordered: boolean): this[] { const blocks = [this]; const childBlocks = this.getChildren(ordered); for (let child, i = 0; child = childBlocks[i]; i++) { // AnyDuringMigration because: Argument of type 'Block[]' is not // assignable to parameter of type 'this[]'. blocks.push(...child.getDescendants(ordered) as AnyDuringMigration); } return blocks; } /** * Get whether this block is deletable or not. * * @returns True if deletable. */ isDeletable(): boolean { return this.deletable_ && !this.isShadow_ && !this.disposed && !this.workspace.options.readOnly; } /** * Set whether this block is deletable or not. * * @param deletable True if deletable. */ setDeletable(deletable: boolean) { this.deletable_ = deletable; } /** * Get whether this block is movable or not. * * @returns True if movable. */ isMovable(): boolean { return this.movable_ && !this.isShadow_ && !this.disposed && !this.workspace.options.readOnly; } /** * Set whether this block is movable or not. * * @param movable True if movable. */ setMovable(movable: boolean) { this.movable_ = movable; } /** * Get whether is block is duplicatable or not. If duplicating this block and * descendants will put this block over the workspace's capacity this block is * not duplicatable. If duplicating this block and descendants will put any * type over their maxInstances this block is not duplicatable. * * @returns True if duplicatable. */ isDuplicatable(): boolean { if (!this.workspace.hasBlockLimits()) { return true; } return this.workspace.isCapacityAvailable( common.getBlockTypeCounts(this, true)); } /** * Get whether this block is a shadow block or not. * * @returns True if a shadow. */ isShadow(): boolean { return this.isShadow_; } /** * Set whether this block is a shadow block or not. * * @param shadow True if a shadow. * @internal */ setShadow(shadow: boolean) { this.isShadow_ = shadow; } /** * Get whether this block is an insertion marker block or not. * * @returns True if an insertion marker. */ isInsertionMarker(): boolean { return this.isInsertionMarker_; } /** * Set whether this block is an insertion marker block or not. * Once set this cannot be unset. * * @param insertionMarker True if an insertion marker. * @internal */ setInsertionMarker(insertionMarker: boolean) { this.isInsertionMarker_ = insertionMarker; } /** * Get whether this block is editable or not. * * @returns True if editable. */ isEditable(): boolean { return this.editable_ && !this.disposed && !this.workspace.options.readOnly; } /** * Set whether this block is editable or not. * * @param editable True if editable. */ setEditable(editable: boolean) { this.editable_ = editable; for (let i = 0, input; input = this.inputList[i]; i++) { for (let j = 0, field; field = input.fieldRow[j]; j++) { field.updateEditable(); } } } /** * Returns if this block has been disposed of / deleted. * * @returns True if this block has been disposed of / deleted. */ isDisposed(): boolean { return this.disposed; } /** * Find the connection on this block that corresponds to the given connection * on the other block. * Used to match connections between a block and its insertion marker. * * @param otherBlock The other block to match against. * @param conn The other connection to match. * @returns The matching connection on this block, or null. * @internal */ getMatchingConnection(otherBlock: Block, conn: Connection): Connection|null { const connections = this.getConnections_(true); const otherConnections = otherBlock.getConnections_(true); if (connections.length !== otherConnections.length) { throw Error('Connection lists did not match in length.'); } for (let i = 0; i < otherConnections.length; i++) { if (otherConnections[i] === conn) { return connections[i]; } } return null; } /** * Set the URL of this block's help page. * * @param url URL string for block help, or function that returns a URL. Null * for no help. */ setHelpUrl(url: string|Function) { this.helpUrl = url; } /** * Sets the tooltip for this block. * * @param newTip The text for the tooltip, a function that returns the text * for the tooltip, or a parent object whose tooltip will be used. To not * display a tooltip pass the empty string. */ setTooltip(newTip: Tooltip.TipInfo) { this.tooltip = newTip; } /** * Returns the tooltip text for this block. * * @returns The tooltip text for this block. */ getTooltip(): string { return Tooltip.getTooltipOfObject(this); } /** * Get the colour of a block. * * @returns #RRGGBB string. */ getColour(): string { return this.colour_; } /** * Get the name of the block style. * * @returns Name of the block style. */ getStyleName(): string { return this.styleName_; } /** * Get the HSV hue value of a block. Null if hue not set. * * @returns Hue value (0-360). */ getHue(): number|null { return this.hue_; } /** * Change the colour of a block. * * @param colour HSV hue value (0 to 360), #RRGGBB string, or a message * reference string pointing to one of those two values. */ setColour(colour: number|string) { const parsed = parsing.parseBlockColour(colour); this.hue_ = parsed.hue; this.colour_ = parsed.hex; } /** * Set the style and colour values of a block. * * @param blockStyleName Name of the block style. */ setStyle(blockStyleName: string) { this.styleName_ = blockStyleName; } /** * Sets a callback function to use whenever the block's parent workspace * changes, replacing any prior onchange handler. This is usually only called * from the constructor, the block type initializer function, or an extension * initializer function. * * @param onchangeFn The callback to call when the block's workspace changes. * @throws {Error} if onchangeFn is not falsey and not a function. */ setOnChange(onchangeFn: (p1: Abstract) => AnyDuringMigration) { if (onchangeFn && typeof onchangeFn !== 'function') { throw Error('onchange must be a function.'); } if (this.onchangeWrapper_) { this.workspace.removeChangeListener(this.onchangeWrapper_); } this.onchange = onchangeFn; this.onchangeWrapper_ = onchangeFn.bind(this); this.workspace.addChangeListener(this.onchangeWrapper_); } /** * Returns the named field from a block. * * @param name The name of the field. * @returns Named field, or null if field does not exist. */ getField(name: string): Field|null { if (typeof name !== 'string') { throw TypeError( 'Block.prototype.getField expects a string ' + 'with the field name but received ' + (name === undefined ? 'nothing' : name + ' of type ' + typeof name) + ' instead'); } for (let i = 0, input; input = this.inputList[i]; i++) { for (let j = 0, field; field = input.fieldRow[j]; j++) { if (field.name === name) { return field; } } } return null; } /** * Return all variables referenced by this block. * * @returns List of variable ids. */ getVars(): string[] { const vars = []; for (let i = 0, input; input = this.inputList[i]; i++) { for (let j = 0, field; field = input.fieldRow[j]; j++) { if (field.referencesVariables()) { vars.push(field.getValue()); } } } return vars; } /** * Return all variables referenced by this block. * * @returns List of variable models. * @internal */ getVarModels(): VariableModel[] { const vars = []; for (let i = 0, input; input = this.inputList[i]; i++) { for (let j = 0, field; field = input.fieldRow[j]; j++) { if (field.referencesVariables()) { const model = this.workspace.getVariableById(field.getValue() as string); // Check if the variable actually exists (and isn't just a potential // variable). if (model) { vars.push(model); } } } } return vars; } /** * Notification that a variable is renaming but keeping the same ID. If the * variable is in use on this block, rerender to show the new name. * * @param variable The variable being renamed. * @internal */ updateVarName(variable: VariableModel) { for (let i = 0, input; input = this.inputList[i]; i++) { for (let j = 0, field; field = input.fieldRow[j]; j++) { if (field.referencesVariables() && variable.getId() === field.getValue()) { field.refreshVariableName(); } } } } /** * Notification that a variable is renaming. * If the ID matches one of this block's variables, rename it. * * @param oldId ID of variable to rename. * @param newId ID of new variable. May be the same as oldId, but with an * updated name. */ renameVarById(oldId: string, newId: string) { for (let i = 0, input; input = this.inputList[i]; i++) { for (let j = 0, field; field = input.fieldRow[j]; j++) { if (field.referencesVariables() && oldId === field.getValue()) { field.setValue(newId); } } } } /** * Returns the language-neutral value of the given field. * * @param name The name of the field. * @returns Value of the field or null if field does not exist. */ getFieldValue(name: string): AnyDuringMigration { const field = this.getField(name); if (field) { return field.getValue(); } return null; } /** * Sets the value of the given field for this block. * * @param newValue The value to set. * @param name The name of the field to set the value of. */ setFieldValue(newValue: AnyDuringMigration, name: string) { const field = this.getField(name); if (!field) { throw Error('Field "' + name + '" not found.'); } field.setValue(newValue); } /** * Set whether this block can chain onto the bottom of another block. * * @param newBoolean True if there can be a previous statement. * @param opt_check Statement type or list of statement types. Null/undefined * if any type could be connected. */ setPreviousStatement(newBoolean: boolean, opt_check?: string|string[]|null) { if (newBoolean) { if (opt_check === undefined) { opt_check = null; } if (!this.previousConnection) { this.previousConnection = this.makeConnection_(ConnectionType.PREVIOUS_STATEMENT); } this.previousConnection.setCheck(opt_check); } else { if (this.previousConnection) { if (this.previousConnection.isConnected()) { throw Error( 'Must disconnect previous statement before removing ' + 'connection.'); } this.previousConnection.dispose(); // AnyDuringMigration because: Type 'null' is not assignable to type // 'Connection'. this.previousConnection = null as AnyDuringMigration; } } } /** * Set whether another block can chain onto the bottom of this block. * * @param newBoolean True if there can be a next statement. * @param opt_check Statement type or list of statement types. Null/undefined * if any type could be connected. */ setNextStatement(newBoolean: boolean, opt_check?: string|string[]|null) { if (newBoolean) { if (opt_check === undefined) { opt_check = null; } if (!this.nextConnection) { this.nextConnection = this.makeConnection_(ConnectionType.NEXT_STATEMENT); } this.nextConnection.setCheck(opt_check); } else { if (this.nextConnection) { if (this.nextConnection.isConnected()) { throw Error( 'Must disconnect next statement before removing ' + 'connection.'); } this.nextConnection.dispose(); // AnyDuringMigration because: Type 'null' is not assignable to type // 'Connection'. this.nextConnection = null as AnyDuringMigration; } } } /** * Set whether this block returns a value. * * @param newBoolean True if there is an output. * @param opt_check Returned type or list of returned types. Null or * undefined if any type could be returned (e.g. variable get). */ setOutput(newBoolean: boolean, opt_check?: string|string[]|null) { if (newBoolean) { if (opt_check === undefined) { opt_check = null; } if (!this.outputConnection) { this.outputConnection = this.makeConnection_(ConnectionType.OUTPUT_VALUE); } this.outputConnection.setCheck(opt_check); } else { if (this.outputConnection) { if (this.outputConnection.isConnected()) { throw Error( 'Must disconnect output value before removing connection.'); } this.outputConnection.dispose(); // AnyDuringMigration because: Type 'null' is not assignable to type // 'Connection'. this.outputConnection = null as AnyDuringMigration; } } } /** * Set whether value inputs are arranged horizontally or vertically. * * @param newBoolean True if inputs are horizontal. */ setInputsInline(newBoolean: boolean) { if (this.inputsInline !== newBoolean) { eventUtils.fire(new (eventUtils.get(eventUtils.BLOCK_CHANGE))( this, 'inline', null, this.inputsInline, newBoolean)); this.inputsInline = newBoolean; } } /** * Get whether value inputs are arranged horizontally or vertically. * * @returns True if inputs are horizontal. */ getInputsInline(): boolean { if (this.inputsInline !== undefined) { // Set explicitly. return this.inputsInline; } // Not defined explicitly. Figure out what would look best. for (let i = 1; i < this.inputList.length; i++) { if (this.inputList[i - 1].type === inputTypes.DUMMY && this.inputList[i].type === inputTypes.DUMMY) { // Two dummy inputs in a row. Don't inline them. return false; } } for (let i = 1; i < this.inputList.length; i++) { if (this.inputList[i - 1].type === inputTypes.VALUE && this.inputList[i].type === inputTypes.DUMMY) { // Dummy input after a value input. Inline them. return true; } } return false; } /** * Set the block's output shape. * * @param outputShape Value representing an output shape. */ setOutputShape(outputShape: number|null) { this.outputShape_ = outputShape; } /** * Get the block's output shape. * * @returns Value representing output shape if one exists. */ getOutputShape(): number|null { return this.outputShape_; } /** * Get whether this block is enabled or not. * * @returns True if enabled. */ isEnabled(): boolean { return !this.disabled; } /** * Set whether the block is enabled or not. * * @param enabled True if enabled. */ setEnabled(enabled: boolean) { if (this.isEnabled() !== enabled) { const oldValue = this.disabled; this.disabled = !enabled; eventUtils.fire(new (eventUtils.get(eventUtils.BLOCK_CHANGE))( this, 'disabled', null, oldValue, !enabled)); } } /** * Get whether the block is disabled or not due to parents. * The block's own disabled property is not considered. * * @returns True if disabled. */ getInheritedDisabled(): boolean { let ancestor = this.getSurroundParent(); while (ancestor) { if (ancestor.disabled) { return true; } ancestor = ancestor.getSurroundParent(); } // Ran off the top. return false; } /** * Get whether the block is collapsed or not. * * @returns True if collapsed. */ isCollapsed(): boolean { return this.collapsed_; } /** * Set whether the block is collapsed or not. * * @param collapsed True if collapsed. */ setCollapsed(collapsed: boolean) { if (this.collapsed_ !== collapsed) { eventUtils.fire(new (eventUtils.get(eventUtils.BLOCK_CHANGE))( this, 'collapsed', null, this.collapsed_, collapsed)); this.collapsed_ = collapsed; } } /** * Create a human-readable text representation of this block and any children. * * @param opt_maxLength Truncate the string to this length. * @param opt_emptyToken The placeholder string used to denote an empty field. * If not specified, '?' is used. * @returns Text of block. */ toString(opt_maxLength?: number, opt_emptyToken?: string): string { let text = []; const emptyFieldPlaceholder = opt_emptyToken || '?'; // Temporarily set flag to navigate to all fields. const prevNavigateFields = ASTNode.NAVIGATE_ALL_FIELDS; ASTNode.NAVIGATE_ALL_FIELDS = true; let node = ASTNode.createBlockNode(this); const rootNode = node; /** * Whether or not to add parentheses around an input. * * @param connection The connection. * @returns True if we should add parentheses around the input. */ function shouldAddParentheses(connection: Connection): boolean { let checks = connection.getCheck(); if (!checks && connection.targetConnection) { checks = connection.targetConnection.getCheck(); } return !!checks && (checks.indexOf('Boolean') !== -1 || checks.indexOf('Number') !== -1); } /** Check that we haven't circled back to the original root node. */ function checkRoot() { if (node && node.getType() === rootNode?.getType() && node.getLocation() === rootNode?.getLocation()) { node = null; } } // Traverse the AST building up our text string. while (node) { switch (node.getType()) { case ASTNode.types.INPUT: { const connection = node.getLocation() as Connection; if (!node.in()) { text.push(emptyFieldPlaceholder); } else if (shouldAddParentheses(connection)) { text.push('('); } break; } case ASTNode.types.FIELD: { const field = node.getLocation() as Field; if (field.name !== constants.COLLAPSED_FIELD_NAME) { text.push(field.getText()); } break; } } const current = node; node = current.in() || current.next(); if (!node) { // Can't go in or next, keep going out until we can go next. node = current.out(); checkRoot(); while (node && !node.next()) { node = node.out(); checkRoot(); // If we hit an input on the way up, possibly close out parentheses. if (node && node.getType() === ASTNode.types.INPUT && shouldAddParentheses(node.getLocation() as Connection)) { text.push(')'); } } if (node) { node = node.next(); } } } // Restore state of NAVIGATE_ALL_FIELDS. ASTNode.NAVIGATE_ALL_FIELDS = prevNavigateFields; // Run through our text array and simplify expression to remove parentheses // around single field blocks. // E.g. ['repeat', '(', '10', ')', 'times', 'do', '?'] for (let i = 2; i < text.length; i++) { if (text[i - 2] === '(' && text[i] === ')') { text[i - 2] = text[i - 1]; text.splice(i - 1, 2); } } // Join the text array, removing spaces around added parentheses. // AnyDuringMigration because: Type 'string' is not assignable to type // 'any[]'. text = text.reduce(function(acc, value) { return acc + (acc.substr(-1) === '(' || value === ')' ? '' : ' ') + value; }, '') as AnyDuringMigration; // AnyDuringMigration because: Property 'trim' does not exist on type // 'any[]'. text = (text as AnyDuringMigration).trim() || '???'; if (opt_maxLength) { // TODO: Improve truncation so that text from this block is given // priority. E.g. "1+2+3+4+5+6+7+8+9=0" should be "...6+7+8+9=0", not // "1+2+3+4+5...". E.g. "1+2+3+4+5=6+7+8+9+0" should be "...4+5=6+7...". if (text.length > opt_maxLength) { // AnyDuringMigration because: Type 'string' is not assignable to type // 'any[]'. text = (text.substring(0, opt_maxLength - 3) + '...') as AnyDuringMigration; } } return text; } /** * Shortcut for appending a value input row. * * @param name Language-neutral identifier which may used to find this input * again. Should be unique to this block. * @returns The input object created. */ appendValueInput(name: string): Input { return this.appendInput_(inputTypes.VALUE, name); } /** * Shortcut for appending a statement input row. * * @param name Language-neutral identifier which may used to find this input * again. Should be unique to this block. * @returns The input object created. */ appendStatementInput(name: string): Input { return this.appendInput_(inputTypes.STATEMENT, name); } /** * Shortcut for appending a dummy input row. * * @param opt_name Language-neutral identifier which may used to find this * input again. Should be unique to this block. * @returns The input object created. */ appendDummyInput(opt_name?: string): Input { return this.appendInput_(inputTypes.DUMMY, opt_name || ''); } /** * Initialize this block using a cross-platform, internationalization-friendly * JSON description. * * @param json Structured data describing the block. */ jsonInit(json: AnyDuringMigration) { const warningPrefix = json['type'] ? 'Block "' + json['type'] + '": ' : ''; // Validate inputs. if (json['output'] && json['previousStatement']) { throw Error( warningPrefix + 'Must not have both an output and a previousStatement.'); } // Set basic properties of block. // Makes styles backward compatible with old way of defining hat style. if (json['style'] && json['style'].hat) { this.hat = json['style'].hat; // Must set to null so it doesn't error when checking for style and // colour. json['style'] = null; } if (json['style'] && json['colour']) { throw Error(warningPrefix + 'Must not have both a colour and a style.'); } else if (json['style']) { this.jsonInitStyle_(json, warningPrefix); } else { this.jsonInitColour_(json, warningPrefix); } // Interpolate the message blocks. let i = 0; while (json['message' + i] !== undefined) { this.interpolate_( json['message' + i], json['args' + i] || [], json['lastDummyAlign' + i], warningPrefix); i++; } if (json['inputsInline'] !== undefined) { this.setInputsInline(json['inputsInline']); } // Set output and previous/next connections. if (json['output'] !== undefined) { this.setOutput(true, json['output']); } if (json['outputShape'] !== undefined) { this.setOutputShape(json['outputShape']); } if (json['previousStatement'] !== undefined) { this.setPreviousStatement(true, json['previousStatement']); } if (json['nextStatement'] !== undefined) { this.setNextStatement(true, json['nextStatement']); } if (json['tooltip'] !== undefined) { const rawValue = json['tooltip']; const localizedText = parsing.replaceMessageReferences(rawValue); this.setTooltip(localizedText); } if (json['enableContextMenu'] !== undefined) { this.contextMenu = !!json['enableContextMenu']; } if (json['suppressPrefixSuffix'] !== undefined) { this.suppressPrefixSuffix = !!json['suppressPrefixSuffix']; } if (json['helpUrl'] !== undefined) { const rawValue = json['helpUrl']; const localizedValue = parsing.replaceMessageReferences(rawValue); this.setHelpUrl(localizedValue); } if (typeof json['extensions'] === 'string') { console.warn( warningPrefix + 'JSON attribute \'extensions\' should be an array of' + ' strings. Found raw string in JSON for \'' + json['type'] + '\' block.'); json['extensions'] = [json['extensions']]; // Correct and continue. } // Add the mutator to the block. if (json['mutator'] !== undefined) { Extensions.apply(json['mutator'], this, true); } const extensionNames = json['extensions']; if (Array.isArray(extensionNames)) { for (let j = 0; j < extensionNames.length; j++) { Extensions.apply(extensionNames[j], this, false); } } } /** * Initialize the colour of this block from the JSON description. * * @param json Structured data describing the block. * @param warningPrefix Warning prefix string identifying block. */ private jsonInitColour_(json: AnyDuringMigration, warningPrefix: string) { if ('colour' in json) { if (json['colour'] === undefined) { console.warn(warningPrefix + 'Undefined colour value.'); } else { const rawValue = json['colour']; try { this.setColour(rawValue); } catch (e) { console.warn(warningPrefix + 'Illegal colour value: ', rawValue); } } } } /** * Initialize the style of this block from the JSON description. * * @param json Structured data describing the block. * @param warningPrefix Warning prefix string identifying block. */ private jsonInitStyle_(json: AnyDuringMigration, warningPrefix: string) { const blockStyleName = json['style']; try { this.setStyle(blockStyleName); } catch (styleError) { console.warn(warningPrefix + 'Style does not exist: ', blockStyleName); } } /** * Add key/values from mixinObj to this block object. By default, this method * will check that the keys in mixinObj will not overwrite existing values in * the block, including prototype values. This provides some insurance against * mixin / extension incompatibilities with future block features. This check * can be disabled by passing true as the second argument. * * @param mixinObj The key/values pairs to add to this block object. * @param opt_disableCheck Option flag to disable overwrite checks. */ mixin(mixinObj: AnyDuringMigration, opt_disableCheck?: boolean) { if (opt_disableCheck !== undefined && typeof opt_disableCheck !== 'boolean') { throw Error('opt_disableCheck must be a boolean if provided'); } if (!opt_disableCheck) { const overwrites = []; for (const key in mixinObj) { if ((this as AnyDuringMigration)[key] !== undefined) { overwrites.push(key); } } if (overwrites.length) { throw Error( 'Mixin will overwrite block members: ' + JSON.stringify(overwrites)); } } Object.assign(this, mixinObj); } /** * Interpolate a message description onto the block. * * @param message Text contains interpolation tokens (%1, %2, ...) that match * with fields or inputs defined in the args array. * @param args Array of arguments to be interpolated. * @param lastDummyAlign If a dummy input is added at the end, how should it * be aligned? * @param warningPrefix Warning prefix string identifying block. */ private interpolate_( message: string, args: AnyDuringMigration[], lastDummyAlign: string|undefined, warningPrefix: string) { const tokens = parsing.tokenizeInterpolation(message); this.validateTokens_(tokens, args.length); const elements = this.interpolateArguments_(tokens, args, lastDummyAlign); // An array of [field, fieldName] tuples. const fieldStack = []; for (let i = 0, element; element = elements[i]; i++) { if (this.isInputKeyword_(element['type'])) { const input = this.inputFromJson_(element, warningPrefix); // Should never be null, but just in case. if (input) { for (let j = 0, tuple; tuple = fieldStack[j]; j++) { input.appendField(tuple[0], tuple[1]); } fieldStack.length = 0; } } else { // All other types, including ones starting with 'input_' get routed // here. const field = this.fieldFromJson_(element); if (field) { fieldStack.push([field, element['name']]); } } } } /** * Validates that the tokens are within the correct bounds, with no * duplicates, and that all of the arguments are referred to. Throws errors if * any of these things are not true. * * @param tokens An array of tokens to validate * @param argsCount The number of args that need to be referred to. */ private validateTokens_(tokens: Array, argsCount: number) { const visitedArgsHash = []; let visitedArgsCount = 0; for (let i = 0; i < tokens.length; i++) { const token = tokens[i]; if (typeof token !== 'number') { continue; } if (token < 1 || token > argsCount) { throw Error( 'Block "' + this.type + '": ' + 'Message index %' + token + ' out of range.'); } if (visitedArgsHash[token]) { throw Error( 'Block "' + this.type + '": ' + 'Message index %' + token + ' duplicated.'); } visitedArgsHash[token] = true; visitedArgsCount++; } if (visitedArgsCount !== argsCount) { throw Error( 'Block "' + this.type + '": ' + 'Message does not reference all ' + argsCount + ' arg(s).'); } } /** * Inserts args in place of numerical tokens. String args are converted to * JSON that defines a label field. If necessary an extra dummy input is added * to the end of the elements. * * @param tokens The tokens to interpolate * @param args The arguments to insert. * @param lastDummyAlign The alignment the added dummy input should have, if * we are required to add one. * @returns The JSON definitions of field and inputs to add to the block. */ private interpolateArguments_( tokens: Array, args: Array, lastDummyAlign: string|undefined): AnyDuringMigration[] { const elements = []; for (let i = 0; i < tokens.length; i++) { let element = tokens[i]; if (typeof element === 'number') { element = args[element - 1]; } // Args can be strings, which is why this isn't elseif. if (typeof element === 'string') { // AnyDuringMigration because: Type '{ text: string; type: string; } | // null' is not assignable to type 'string | number'. element = this.stringToFieldJson_(element) as AnyDuringMigration; if (!element) { continue; } } elements.push(element); } const length = elements.length; if (length && !this.isInputKeyword_( (elements as AnyDuringMigration)[length - 1]['type'])) { const dummyInput = {'type': 'input_dummy'}; if (lastDummyAlign) { (dummyInput as AnyDuringMigration)['align'] = lastDummyAlign; } elements.push(dummyInput); } return elements; } /** * Creates a field from the JSON definition of a field. If a field with the * given type cannot be found, this attempts to create a different field using * the 'alt' property of the JSON definition (if it exists). * * @param element The element to try to turn into a field. * @returns The field defined by the JSON, or null if one couldn't be created. */ private fieldFromJson_(element: {alt?: string, type?: string, text?: string}): Field|null { const field = fieldRegistry.fromJson(element); if (!field && element['alt']) { if (typeof element['alt'] === 'string') { const json = this.stringToFieldJson_(element['alt']); return json ? this.fieldFromJson_(json) : null; } return this.fieldFromJson_(element['alt']); } return field; } /** * Creates an input from the JSON definition of an input. Sets the input's * check and alignment if they are provided. * * @param element The JSON to turn into an input. * @param warningPrefix The prefix to add to warnings to help the developer * debug. * @returns The input that has been created, or null if one could not be * created for some reason (should never happen). */ private inputFromJson_(element: AnyDuringMigration, warningPrefix: string): Input|null { const alignmentLookup = { 'LEFT': Align.LEFT, 'RIGHT': Align.RIGHT, 'CENTRE': Align.CENTRE, 'CENTER': Align.CENTRE, }; let input = null; switch (element['type']) { case 'input_value': input = this.appendValueInput(element['name']); break; case 'input_statement': input = this.appendStatementInput(element['name']); break; case 'input_dummy': input = this.appendDummyInput(element['name']); break; } // Should never be hit because of interpolate_'s checks, but just in case. if (!input) { return null; } if (element['check']) { input.setCheck(element['check']); } if (element['align']) { const alignment = (alignmentLookup as AnyDuringMigration)[element['align'].toUpperCase()]; if (alignment === undefined) { console.warn(warningPrefix + 'Illegal align value: ', element['align']); } else { input.setAlign(alignment); } } return input; } /** * Returns true if the given string matches one of the input keywords. * * @param str The string to check. * @returns True if the given string matches one of the input keywords, false * otherwise. */ private isInputKeyword_(str: string): boolean { return str === 'input_value' || str === 'input_statement' || str === 'input_dummy'; } /** * Turns a string into the JSON definition of a label field. If the string * becomes an empty string when trimmed, this returns null. * * @param str String to turn into the JSON definition of a label field. * @returns The JSON definition or null. */ private stringToFieldJson_(str: string): {text: string, type: string}|null { str = str.trim(); if (str) { return { 'type': 'field_label', 'text': str, }; } return null; } /** * Add a value input, statement input or local variable to this block. * * @param type One of Blockly.inputTypes. * @param name Language-neutral identifier which may used to find this input * again. Should be unique to this block. * @returns The input object created. */ protected appendInput_(type: number, name: string): Input { let connection = null; if (type === inputTypes.VALUE || type === inputTypes.STATEMENT) { connection = this.makeConnection_(type); } if (type === inputTypes.STATEMENT) { this.statementInputCount++; } // AnyDuringMigration because: Argument of type 'Connection | null' is not // assignable to parameter of type 'Connection'. const input = new Input(type, name, this, (connection as AnyDuringMigration)); // Append input to list. this.inputList.push(input); return input; } /** * Move a named input to a different location on this block. * * @param name The name of the input to move. * @param refName Name of input that should be after the moved input, or null * to be the input at the end. */ moveInputBefore(name: string, refName: string|null) { if (name === refName) { return; } // Find both inputs. let inputIndex = -1; let refIndex = refName ? -1 : this.inputList.length; for (let i = 0, input; input = this.inputList[i]; i++) { if (input.name === name) { inputIndex = i; if (refIndex !== -1) { break; } } else if (refName && input.name === refName) { refIndex = i; if (inputIndex !== -1) { break; } } } if (inputIndex === -1) { throw Error('Named input "' + name + '" not found.'); } if (refIndex === -1) { throw Error('Reference input "' + refName + '" not found.'); } this.moveNumberedInputBefore(inputIndex, refIndex); } /** * Move a numbered input to a different location on this block. * * @param inputIndex Index of the input to move. * @param refIndex Index of input that should be after the moved input. */ moveNumberedInputBefore(inputIndex: number, refIndex: number) { // Validate arguments. if (inputIndex === refIndex) { throw Error('Can\'t move input to itself.'); } if (inputIndex >= this.inputList.length) { throw RangeError('Input index ' + inputIndex + ' out of bounds.'); } if (refIndex > this.inputList.length) { throw RangeError('Reference input ' + refIndex + ' out of bounds.'); } // Remove input. const input = this.inputList[inputIndex]; this.inputList.splice(inputIndex, 1); if (inputIndex < refIndex) { refIndex--; } // Reinsert input. this.inputList.splice(refIndex, 0, input); } /** * Remove an input from this block. * * @param name The name of the input. * @param opt_quiet True to prevent an error if input is not present. * @returns True if operation succeeds, false if input is not present and * opt_quiet is true. * @throws {Error} if the input is not present and opt_quiet is not true. */ removeInput(name: string, opt_quiet?: boolean): boolean { for (let i = 0, input; input = this.inputList[i]; i++) { if (input.name === name) { if (input.type === inputTypes.STATEMENT) { this.statementInputCount--; } input.dispose(); this.inputList.splice(i, 1); return true; } } if (opt_quiet) { return false; } throw Error('Input not found: ' + name); } /** * Fetches the named input object. * * @param name The name of the input. * @returns The input object, or null if input does not exist. */ getInput(name: string): Input|null { for (let i = 0, input; input = this.inputList[i]; i++) { if (input.name === name) { return input; } } // This input does not exist. return null; } /** * Fetches the block attached to the named input. * * @param name The name of the input. * @returns The attached value block, or null if the input is either * disconnected or if the input does not exist. */ getInputTargetBlock(name: string): Block|null { const input = this.getInput(name); return input && input.connection && input.connection.targetBlock(); } /** * Returns the comment on this block (or null if there is no comment). * * @returns Block's comment. */ getCommentText(): string|null { return this.commentModel.text; } /** * Set this block's comment text. * * @param text The text, or null to delete. */ setCommentText(text: string|null) { if (this.commentModel.text === text) { return; } eventUtils.fire(new (eventUtils.get(eventUtils.BLOCK_CHANGE))( this, 'comment', null, this.commentModel.text, text)); this.commentModel.text = text; // AnyDuringMigration because: Type 'string | null' is not assignable to // type 'string | Comment'. this.comment = text as AnyDuringMigration; // For backwards compatibility. } /** * Set this block's warning text. * * @param _text The text, or null to delete. * @param _opt_id An optional ID for the warning text to be able to maintain * multiple warnings. */ setWarningText(_text: string|null, _opt_id?: string) {} // NOP. /** * Give this block a mutator dialog. * * @param _mutator A mutator dialog instance or null to remove. */ setMutator(_mutator: Mutator) {} // NOP. /** * Return the coordinates of the top-left corner of this block relative to the * drawing surface's origin (0,0), in workspace units. * * @returns Object with .x and .y properties. */ getRelativeToSurfaceXY(): Coordinate { return this.xy_; } /** * Move a block by a relative offset. * * @param dx Horizontal offset, in workspace units. * @param dy Vertical offset, in workspace units. */ moveBy(dx: number, dy: number) { if (this.parentBlock_) { throw Error('Block has parent.'); } const event = new (eventUtils.get(eventUtils.BLOCK_MOVE))(this) as BlockMove; this.xy_.translate(dx, dy); event.recordNew(); eventUtils.fire(event); } /** * Create a connection of the specified type. * * @param type The type of the connection to create. * @returns A new connection of the specified type. */ protected makeConnection_(type: number): Connection { return new Connection(this, type); } /** * Recursively checks whether all statement and value inputs are filled with * blocks. Also checks all following statement blocks in this stack. * * @param opt_shadowBlocksAreFilled An optional argument controlling whether * shadow blocks are counted as filled. Defaults to true. * @returns True if all inputs are filled, false otherwise. */ allInputsFilled(opt_shadowBlocksAreFilled?: boolean): boolean { // Account for the shadow block filledness toggle. if (opt_shadowBlocksAreFilled === undefined) { opt_shadowBlocksAreFilled = true; } if (!opt_shadowBlocksAreFilled && this.isShadow()) { return false; } // Recursively check each input block of the current block. for (let i = 0, input; input = this.inputList[i]; i++) { if (!input.connection) { continue; } const target = input.connection.targetBlock(); if (!target || !target.allInputsFilled(opt_shadowBlocksAreFilled)) { return false; } } // Recursively check the next block after the current block. const next = this.getNextBlock(); if (next) { return next.allInputsFilled(opt_shadowBlocksAreFilled); } return true; } /** * This method returns a string describing this Block in developer terms (type * name and ID; English only). * * Intended to on be used in console logs and errors. If you need a string * that uses the user's native language (including block text, field values, * and child blocks), use [toString()]{@link Block#toString}. * * @returns The description. */ toDevString(): string { let msg = this.type ? '"' + this.type + '" block' : 'Block'; if (this.id) { msg += ' (id="' + this.id + '")'; } return msg; } } export namespace Block { export interface CommentModel { text: string|null; pinned: boolean; size: Size; } } export type CommentModel = Block.CommentModel;