blockly 9.0.0-beta.0 → 9.0.0-beta.1

package/core/block.d.ts

@@ -22,7 +22,7 @@ import type { Workspace } from './workspace.js';
 /**
  * Class for one block.
  * Not normally called directly, workspace.newBlock() is preferred.
- * @unrestricted
+ *
  * @alias Blockly.Block
  */
 export declare class Block implements IASTNodeLocation, IDeletable {
@@ -43,6 +43,7 @@ export declare class Block implements IASTNodeLocation, IDeletable {
     data: string | null;
     /**
      * Has this block been disposed of?
+     *
      * @internal
      */
     disposed: boolean;
@@ -122,6 +123,7 @@ export declare class Block implements IASTNodeLocation, IDeletable {
     protected outputShape_: number | null;
     /**
      * A string representing the comment attached to this block.
+     *
      * @deprecated August 2019. Use getCommentText instead.
      */
     comment: string | Comment | null;
@@ -144,6 +146,7 @@ export declare class Block implements IASTNodeLocation, IDeletable {
     private onchangeWrapper_;
     /**
      * A count of statement inputs on the block.
+     *
      * @internal
      */
     statementInputCount: number;
@@ -163,6 +166,7 @@ export declare class Block implements IASTNodeLocation, IDeletable {
     protected doInit_(): void;
     /**
      * 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.
@@ -181,6 +185,7 @@ export declare class Block implements IASTNodeLocation, IDeletable {
     /**
      * 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.
      */
@@ -188,6 +193,7 @@ export declare class Block implements IASTNodeLocation, IDeletable {
     /**
      * 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.
      */
@@ -199,30 +205,33 @@ export declare class Block implements IASTNodeLocation, IDeletable {
      * Since only one block can be displaced and attached to the insertion marker
      * this should only ever return one connection.
      *
-     * @return The connection on the value input, or null.
+     * @returns The connection on the value input, or null.
      */
     private getOnlyValueConnection_;
     /**
      * 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_;
     /**
      * Returns all connections originating from this block.
+     *
      * @param _all If true, return all connections even hidden ones.
-     * @return Array of connections.
+     * @returns Array of connections.
      * @internal
      */
     getConnections_(_all: boolean): Connection[];
     /**
      * 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.
-     * @return The last next connection on the stack, or null.
+     * @returns The last next connection on the stack, or null.
      * @internal
      */
     lastConnectionInStack(ignoreShadows: boolean): Connection | null;
@@ -236,13 +245,15 @@ export declare class Block implements IASTNodeLocation, IDeletable {
      * 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).
-     * @return The block (if any) that holds the current block.
+     *
+     * @returns The block (if any) that holds the current block.
      */
     getParent(): this | null;
     /**
      * Return the input that connects to the specified block.
+     *
      * @param block A block connected to an input on this block.
-     * @return The input (if any) that connects to the specified block.
+     * @returns The input (if any) that connects to the specified block.
      */
     getInputWithBlock(block: Block): Input | null;
     /**
@@ -250,37 +261,43 @@ export declare class Block implements IASTNodeLocation, IDeletable {
      * 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.
-     * @return The block (if any) that surrounds the current block.
+     *
+     * @returns The block (if any) that surrounds the current block.
      */
     getSurroundParent(): this | null;
     /**
      * Return the next statement block directly connected to this block.
-     * @return The next statement block or null.
+     *
+     * @returns The next statement block or null.
      */
     getNextBlock(): Block | null;
     /**
      * Returns the block connected to the previous connection.
-     * @return The previous statement block or null.
+     *
+     * @returns The previous statement block or null.
      */
     getPreviousBlock(): Block | null;
     /**
      * Return the connection on the first statement input on this block, or null
      * if there are none.
-     * @return The first statement connection or null.
+     *
+     * @returns The first statement connection or null.
      * @internal
      */
     getFirstStatementConnection(): Connection | null;
     /**
      * Return the top-most block in this block's tree.
      * This will return itself if this block is at the top level.
-     * @return The root block.
+     *
+     * @returns The root block.
      */
     getRootBlock(): this;
     /**
      * 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.
-     * @return The top block in a stack.
+     *
+     * @returns The top block in a stack.
      * @internal
      */
     getTopStackBlock(): this;
@@ -289,12 +306,14 @@ export declare class Block implements IASTNodeLocation, IDeletable {
      * 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.
-     * @return Array of blocks.
+     * @returns Array of blocks.
      */
     getChildren(ordered: boolean): Block[];
     /**
      * Set parent of this block to be a new block or null.
+     *
      * @param newParent New parent block.
      * @internal
      */
@@ -305,27 +324,32 @@ export declare class Block implements IASTNodeLocation, IDeletable {
      * 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.
-     * @return Flattened array of blocks.
+     * @returns Flattened array of blocks.
      */
     getDescendants(ordered: boolean): this[];
     /**
      * Get whether this block is deletable or not.
-     * @return True if deletable.
+     *
+     * @returns True if deletable.
      */
     isDeletable(): boolean;
     /**
      * Set whether this block is deletable or not.
+     *
      * @param deletable True if deletable.
      */
     setDeletable(deletable: boolean): void;
     /**
      * Get whether this block is movable or not.
-     * @return True if movable.
+     *
+     * @returns True if movable.
      */
     isMovable(): boolean;
     /**
      * Set whether this block is movable or not.
+     *
      * @param movable True if movable.
      */
     setMovable(movable: boolean): void;
@@ -334,65 +358,76 @@ export declare class Block implements IASTNodeLocation, IDeletable {
      * 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.
-     * @return True if duplicatable.
+     *
+     * @returns True if duplicatable.
      */
     isDuplicatable(): boolean;
     /**
      * Get whether this block is a shadow block or not.
-     * @return True if a shadow.
+     *
+     * @returns True if a shadow.
      */
     isShadow(): boolean;
     /**
      * Set whether this block is a shadow block or not.
+     *
      * @param shadow True if a shadow.
      * @internal
      */
     setShadow(shadow: boolean): void;
     /**
      * Get whether this block is an insertion marker block or not.
-     * @return True if an insertion marker.
+     *
+     * @returns True if an insertion marker.
      */
     isInsertionMarker(): boolean;
     /**
      * 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): void;
     /**
      * Get whether this block is editable or not.
-     * @return True if editable.
+     *
+     * @returns True if editable.
      */
     isEditable(): boolean;
     /**
      * Set whether this block is editable or not.
+     *
      * @param editable True if editable.
      */
     setEditable(editable: boolean): void;
     /**
      * Returns if this block has been disposed of / deleted.
-     * @return True if this block has been disposed of / deleted.
+     *
+     * @returns True if this block has been disposed of / deleted.
      */
     isDisposed(): boolean;
     /**
      * 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.
-     * @return The matching connection on this block, or null.
+     * @returns The matching connection on this block, or null.
      * @internal
      */
     getMatchingConnection(otherBlock: Block, conn: Connection): Connection | 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): void;
     /**
      * 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.
@@ -400,32 +435,38 @@ export declare class Block implements IASTNodeLocation, IDeletable {
     setTooltip(newTip: Tooltip.TipInfo): void;
     /**
      * Returns the tooltip text for this block.
-     * @return The tooltip text for this block.
+     *
+     * @returns The tooltip text for this block.
      */
     getTooltip(): string;
     /**
      * Get the colour of a block.
-     * @return #RRGGBB string.
+     *
+     * @returns #RRGGBB string.
      */
     getColour(): string;
     /**
      * Get the name of the block style.
-     * @return Name of the block style.
+     *
+     * @returns Name of the block style.
      */
     getStyleName(): string;
     /**
      * Get the HSV hue value of a block.  Null if hue not set.
-     * @return Hue value (0-360).
+     *
+     * @returns Hue value (0-360).
      */
     getHue(): number | null;
     /**
      * 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): void;
     /**
      * Set the style and colour values of a block.
+     *
      * @param blockStyleName Name of the block style.
      */
     setStyle(blockStyleName: string): void;
@@ -434,30 +475,35 @@ export declare class Block implements IASTNodeLocation, IDeletable {
      * 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) => any): void;
     /**
      * Returns the named field from a block.
+     *
      * @param name The name of the field.
-     * @return Named field, or null if field does not exist.
+     * @returns Named field, or null if field does not exist.
      */
     getField(name: string): Field | null;
     /**
      * Return all variables referenced by this block.
-     * @return List of variable ids.
+     *
+     * @returns List of variable ids.
      */
     getVars(): string[];
     /**
      * Return all variables referenced by this block.
-     * @return List of variable models.
+     *
+     * @returns List of variable models.
      * @internal
      */
     getVarModels(): VariableModel[];
     /**
      * 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
      */
@@ -465,6 +511,7 @@ export declare class Block implements IASTNodeLocation, IDeletable {
     /**
      * 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.
@@ -472,18 +519,21 @@ export declare class Block implements IASTNodeLocation, IDeletable {
     renameVarById(oldId: string, newId: string): void;
     /**
      * Returns the language-neutral value of the given field.
+     *
      * @param name The name of the field.
-     * @return Value of the field or null if field does not exist.
+     * @returns Value of the field or null if field does not exist.
      */
     getFieldValue(name: string): any;
     /**
      * 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: any, name: string): void;
     /**
      * 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.
@@ -491,6 +541,7 @@ export declare class Block implements IASTNodeLocation, IDeletable {
     setPreviousStatement(newBoolean: boolean, opt_check?: string | string[] | null): void;
     /**
      * 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.
@@ -498,6 +549,7 @@ export declare class Block implements IASTNodeLocation, IDeletable {
     setNextStatement(newBoolean: boolean, opt_check?: string | string[] | null): void;
     /**
      * 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).
@@ -505,93 +557,109 @@ export declare class Block implements IASTNodeLocation, IDeletable {
     setOutput(newBoolean: boolean, opt_check?: string | string[] | null): void;
     /**
      * Set whether value inputs are arranged horizontally or vertically.
+     *
      * @param newBoolean True if inputs are horizontal.
      */
     setInputsInline(newBoolean: boolean): void;
     /**
      * Get whether value inputs are arranged horizontally or vertically.
-     * @return True if inputs are horizontal.
+     *
+     * @returns True if inputs are horizontal.
      */
     getInputsInline(): boolean;
     /**
      * Set the block's output shape.
+     *
      * @param outputShape Value representing an output shape.
      */
     setOutputShape(outputShape: number | null): void;
     /**
      * Get the block's output shape.
-     * @return Value representing output shape if one exists.
+     *
+     * @returns Value representing output shape if one exists.
      */
     getOutputShape(): number | null;
     /**
      * Get whether this block is enabled or not.
-     * @return True if enabled.
+     *
+     * @returns True if enabled.
      */
     isEnabled(): boolean;
     /**
      * Set whether the block is enabled or not.
+     *
      * @param enabled True if enabled.
      */
     setEnabled(enabled: boolean): void;
     /**
      * Get whether the block is disabled or not due to parents.
      * The block's own disabled property is not considered.
-     * @return True if disabled.
+     *
+     * @returns True if disabled.
      */
     getInheritedDisabled(): boolean;
     /**
      * Get whether the block is collapsed or not.
-     * @return True if collapsed.
+     *
+     * @returns True if collapsed.
      */
     isCollapsed(): boolean;
     /**
      * Set whether the block is collapsed or not.
+     *
      * @param collapsed True if collapsed.
      */
     setCollapsed(collapsed: boolean): void;
     /**
      * 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.
-     * @return Text of block.
+     * @returns Text of block.
      */
     toString(opt_maxLength?: number, opt_emptyToken?: string): string;
     /**
      * 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.
-     * @return The input object created.
+     * @returns The input object created.
      */
     appendValueInput(name: string): Input;
     /**
      * 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.
-     * @return The input object created.
+     * @returns The input object created.
      */
     appendStatementInput(name: string): Input;
     /**
      * 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.
-     * @return The input object created.
+     * @returns The input object created.
      */
     appendDummyInput(opt_name?: string): Input;
     /**
      * Initialize this block using a cross-platform, internationalization-friendly
      * JSON description.
+     *
      * @param json Structured data describing the block.
      */
     jsonInit(json: any): void;
     /**
      * 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_;
     /**
      * Initialize the style of this block from the JSON description.
+     *
      * @param json Structured data describing the block.
      * @param warningPrefix Warning prefix string identifying block.
      */
@@ -602,12 +670,14 @@ export declare class Block implements IASTNodeLocation, IDeletable {
      * 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: any, opt_disableCheck?: boolean): void;
     /**
      * 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.
@@ -620,6 +690,7 @@ export declare class Block implements IASTNodeLocation, IDeletable {
      * 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.
      */
@@ -628,55 +699,62 @@ export declare class Block implements IASTNodeLocation, IDeletable {
      * 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.
-     * @return The JSON definitions of field and inputs to add to the block.
+     * @returns The JSON definitions of field and inputs to add to the block.
      */
     private interpolateArguments_;
     /**
      * 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.
-     * @return The field defined by the JSON, or null if one couldn't be created.
+     * @returns The field defined by the JSON, or null if one couldn't be created.
      */
     private fieldFromJson_;
     /**
      * 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.
-     * @return The input that has been created, or null if one could not be
+     * @returns The input that has been created, or null if one could not be
      *     created for some reason (should never happen).
      */
     private inputFromJson_;
     /**
      * Returns true if the given string matches one of the input keywords.
+     *
      * @param str The string to check.
-     * @return True if the given string matches one of the input keywords, false
+     * @returns True if the given string matches one of the input keywords, false
      *     otherwise.
      */
     private isInputKeyword_;
     /**
      * 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.
-     * @return The JSON definition or null.
+     * @returns The JSON definition or null.
      */
     private stringToFieldJson_;
     /**
      * 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.
-     * @return The input object created.
+     * @returns The input object created.
      */
     protected appendInput_(type: number, name: string): 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.
@@ -684,44 +762,51 @@ export declare class Block implements IASTNodeLocation, IDeletable {
     moveInputBefore(name: string, refName: string | null): void;
     /**
      * 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): void;
     /**
      * 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.
-     * @return True if operation succeeds, false if input is not present and
+     * @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;
     /**
      * Fetches the named input object.
+     *
      * @param name The name of the input.
-     * @return The input object, or null if input does not exist.
+     * @returns The input object, or null if input does not exist.
      */
     getInput(name: string): Input | null;
     /**
      * Fetches the block attached to the named input.
+     *
      * @param name The name of the input.
-     * @return The attached value block, or null if the input is either
+     * @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;
     /**
      * Returns the comment on this block (or null if there is no comment).
-     * @return Block's comment.
+     *
+     * @returns Block's comment.
      */
     getCommentText(): string | null;
     /**
      * Set this block's comment text.
+     *
      * @param text The text, or null to delete.
      */
     setCommentText(text: string | null): void;
     /**
      * 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.
@@ -729,33 +814,38 @@ export declare class Block implements IASTNodeLocation, IDeletable {
     setWarningText(_text: string | null, _opt_id?: string): void;
     /**
      * Give this block a mutator dialog.
+     *
      * @param _mutator A mutator dialog instance or null to remove.
      */
     setMutator(_mutator: Mutator): void;
     /**
      * Return the coordinates of the top-left corner of this block relative to the
      * drawing surface's origin (0,0), in workspace units.
-     * @return Object with .x and .y properties.
+     *
+     * @returns Object with .x and .y properties.
      */
     getRelativeToSurfaceXY(): Coordinate;
     /**
      * 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): void;
     /**
      * Create a connection of the specified type.
+     *
      * @param type The type of the connection to create.
-     * @return A new connection of the specified type.
+     * @returns A new connection of the specified type.
      */
     protected makeConnection_(type: number): Connection;
     /**
      * 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.
-     * @return True if all inputs are filled, false otherwise.
+     * @returns True if all inputs are filled, false otherwise.
      */
     allInputsFilled(opt_shadowBlocksAreFilled?: boolean): boolean;
     /**
@@ -765,7 +855,8 @@ export declare class Block implements IASTNodeLocation, IDeletable {
      * 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}.
-     * @return The description.
+     *
+     * @returns The description.
      */
     toDevString(): string;
 }
@@ -777,3 +868,4 @@ export declare namespace Block {
     }
 }
 export declare type CommentModel = Block.CommentModel;
+//# sourceMappingURL=block.d.ts.map