Class: Block

Blockly.Block

class   static

Constructor

Block

new Block(workspace, prototypeName, opt_id)

Class for one block. Not normally called directly, workspace.newBlock() is preferred.

Parameter
workspace	Blockly.Workspace The block's workspace. Value must not be null.
prototypeName	string Name of the language object containing type-specific functions for this block. Value may be null.
opt_id	Optional string Optional ID. Use this ID if provided, otherwise create a new ID.

Properties

childBlocks_

protected

non-null Array of non-null Blockly.Block

collapsed_

protected

boolean

comment

(string or Blockly.Comment)

contextMenu

boolean

data

nullable string

Optional text data that round-trips beween blocks and XML. Has no effect. May be used by 3rd parties for meta information.

hat

(string or undefined)

Name of the type of hat.

id

string

inputList

non-null Array of non-null Blockly.Input

inputsInline

(boolean or undefined)

inputsInlineDefault

(boolean or undefined)

isInFlyout

boolean

isInMutator

boolean

isInsertionMarker_

protected

boolean

True if this block is an insertion marker.

nextConnection

Blockly.Connection

outputConnection

Blockly.Connection

parentBlock_

protected

Blockly.Block

previousConnection

Blockly.Connection

RTL

boolean

tooltip

(string or non-null function())

type

string

workspace

non-null Blockly.Workspace

Methods

obtain

static

obtain(workspace, prototypeName) returns Blockly.Block

Obtain a newly created block.

Parameter
workspace	Blockly.Workspace The block's workspace. Value must not be null.
prototypeName	string Name of the language object containing type-specific functions for this block. Value may be null.

Deprecated

December 2015

Returns

non-null Blockly.Block The created block.

allInputsFilled

allInputsFilled(opt_shadowBlocksAreFilled) returns boolean

Recursively checks whether all statement and value inputs are filled with blocks. Also checks all following statement blocks in this stack.

Parameter
opt_shadowBlocksAreFilled	Optional boolean An optional argument controlling whether shadow blocks are counted as filled. Defaults to true.

Returns

boolean True if all inputs are filled, false otherwise.

appendDummyInput

appendDummyInput(opt_name) returns Blockly.Input

Shortcut for appending a dummy input row.

Parameter
opt_name	Optional string Language-neutral identifier which may used to find this input again. Should be unique to this block.

Returns

non-null Blockly.Input The input object created.

appendInput_

protected

appendInput_(type, name) returns Blockly.Input

Add a value input, statement input or local variable to this block.

Parameter
type	number Either Blockly.INPUT_VALUE or Blockly.NEXT_STATEMENT or Blockly.DUMMY_INPUT.
name	string Language-neutral identifier which may used to find this input again. Should be unique to this block.

Returns

non-null Blockly.Input The input object created.

appendStatementInput

appendStatementInput(name) returns Blockly.Input

Shortcut for appending a statement input row.

Parameter
name	string Language-neutral identifier which may used to find this input again. Should be unique to this block.

Returns

non-null Blockly.Input The input object created.

appendValueInput

appendValueInput(name) returns Blockly.Input

Shortcut for appending a value input row.

Parameter
name	string Language-neutral identifier which may used to find this input again. Should be unique to this block.

Returns

non-null Blockly.Input The input object created.

bumpNeighbours_

protected

bumpNeighbours_()

Bump unconnected blocks out of alignment. Two blocks which aren't actually connected should not coincidentally line up on screen.

dispose

dispose(healStack)

Dispose of this block.

Parameter
healStack	boolean 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.

getChildren

getChildren(ordered) returns Array of non-null Blockly.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.

Parameter
ordered	boolean Sort the list if true.

Returns

non-null Array of non-null Blockly.Block Array of blocks.

getColour

getColour() returns string

Get the colour of a block.

Returns

string #RRGGBB string.

getColourBorder

package

getColourBorder() returns Object

Get the border colour(s) of a block.

Returns

{colourDark, colourLight, colourBorder} An object containing colour values for the border(s) of the block. If the block is using a style the colourBorder will be defined and equal to the tertiary colour of the style (#RRGGBB string). Otherwise the colourDark and colourLight attributes will be defined (#RRGGBB strings).

getColourSecondary

getColourSecondary() returns string

Get the secondary colour of a block.

Returns

nullable string #RRGGBB string.

getColourShadow

getColourShadow() returns string

Get the shadow colour of a block.

Returns

nullable string #RRGGBB string.

getColourTertiary

getColourTertiary() returns string

Get the tertiary colour of a block.

Returns

nullable string #RRGGBB string.

getCommentText

getCommentText() returns string

Returns the comment on this block (or '' if none).

Returns

string Block's comment.

getDescendants

getDescendants(ordered) returns Array of non-null Blockly.Block

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.

Parameter
ordered	boolean Sort the list if true.

Returns

non-null Array of non-null Blockly.Block Flattened array of blocks.

getField

getField(name) returns Blockly.Field

Returns the named field from a block.

Parameter
name	string The name of the field.

Returns

Blockly.Field Named field, or null if field does not exist.

getFieldValue

getFieldValue(name) returns string

Returns the language-neutral value from the field of a block.

Parameter
name	string The name of the field.

Returns

nullable string Value from the field or null if field does not exist.

getFirstStatementConnection

package

getFirstStatementConnection() returns Blockly.Connection

Return the connection on the first statement input on this block, or null if there are none.

Returns

Blockly.Connection The first statement connection or null.

getHue

getHue() returns number

Get the HSV hue value of a block. Null if hue not set.

Returns

nullable number Hue value (0-360).

getInheritedDisabled

getInheritedDisabled() returns boolean

Get whether the block is disabled or not due to parents. The block's own disabled property is not considered.

Returns

boolean True if disabled.

getInput

getInput(name) returns Blockly.Input

Fetches the named input object.

Parameter
name	string The name of the input.

Returns

Blockly.Input The input object, or null if input does not exist.

getInputsInline

getInputsInline() returns boolean

Get whether value inputs are arranged horizontally or vertically.

Returns

boolean True if inputs are horizontal.

getInputTargetBlock

getInputTargetBlock(name) returns Blockly.Block

Fetches the block attached to the named input.

Parameter
name	string The name of the input.

Returns

Blockly.Block The attached value block, or null if the input is either disconnected or if the input does not exist.

getInputWithBlock

getInputWithBlock(block) returns Blockly.Input

Return the input that connects to the specified block.

Parameter
block	Blockly.Block A block connected to an input on this block. Value must not be null.

Returns

Blockly.Input The input that connects to the specified block.

getMatchingConnection

package

getMatchingConnection(otherBlock, conn) returns Blockly.Connection

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.

Parameter
otherBlock	Blockly.Block The other block to match against. Value must not be null.
conn	Blockly.Connection The other connection to match. Value must not be null.

Returns

Blockly.Connection The matching connection on this block, or null.

getNextBlock

getNextBlock() returns Blockly.Block

Return the next statement block directly connected to this block.

Returns

Blockly.Block The next statement block or null.

getParent

getParent() returns Blockly.Block

Return the parent block or null if this block is at the top level.

Returns

Blockly.Block The block that holds the current block.

getPreviousBlock

getPreviousBlock() returns Blockly.Block

Return the previous statement block directly connected to this block.

Returns

Blockly.Block The previous statement block or null.

getRelativeToSurfaceXY

getRelativeToSurfaceXY() returns Blockly.utils.Coordinate

Return the coordinates of the top-left corner of this block relative to the drawing surface's origin (0,0), in workspace units.

Returns

non-null Blockly.utils.Coordinate Object with .x and .y properties.

getRootBlock

getRootBlock() returns Blockly.Block

Return the top-most block in this block's tree. This will return itself if this block is at the top level.

Returns

non-null Blockly.Block The root block.

getStyleName

getStyleName() returns string

Get the name of the block style.

Returns

nullable string Name of the block style.

getSurroundParent

getSurroundParent() returns Blockly.Block

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

Blockly.Block The block that surrounds the current block.

getVarModels

package

getVarModels() returns Array of non-null Blockly.VariableModel

Return all variables referenced by this block.

Returns

non-null Array of non-null Blockly.VariableModel List of variable models.

getVars

package

getVars() returns Array of string

Return all variables referenced by this block.

Returns

non-null Array of string List of variable names.

initModel

public

initModel()

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).

isCollapsed

isCollapsed() returns boolean

Get whether the block is collapsed or not.

Returns

boolean True if collapsed.

isDeletable

isDeletable() returns boolean

Get whether this block is deletable or not.

Returns

boolean True if deletable.

isDuplicatable

isDuplicatable() returns boolean

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

boolean True if duplicatable.

isEditable

isEditable() returns boolean

Get whether this block is editable or not.

Returns

boolean True if editable.

isEnabled

isEnabled() returns boolean

Get whether this block is enabled or not.

Returns

boolean True if enabled.

isInsertionMarker

package

isInsertionMarker() returns boolean

Get whether this block is an insertion marker block or not.

Returns

boolean True if an insertion marker.

isMovable

isMovable() returns boolean

Get whether this block is movable or not.

Returns

boolean True if movable.

isShadow

isShadow() returns boolean

Get whether this block is a shadow block or not.

Returns

boolean True if a shadow.

jsonInit

jsonInit(json)

Initialize this block using a cross-platform, internationalization-friendly JSON description.

Parameter
json	Object Structured data describing the block. Value must not be null.

lastConnectionInStack

package

lastConnectionInStack() returns Blockly.Connection

Walks down a stack of blocks and finds the last next connection on the stack.

Returns

Blockly.Connection The last next connection on the stack, or null.

mixin

mixin(mixinObj, opt_disableCheck)

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.

Parameter
mixinObj	Object The key/values pairs to add to this block object. Value must not be null.
opt_disableCheck	Optional boolean Option flag to disable overwrite checks.

moveBy

moveBy(dx, dy)

Move a block by a relative offset.

Parameter
dx	number Horizontal offset, in workspace units.
dy	number Vertical offset, in workspace units.

moveInputBefore

moveInputBefore(name, refName)

Move a named input to a different location on this block.

Parameter
name	string The name of the input to move.
refName	string Name of input that should be after the moved input, or null to be the input at the end. Value may be null.

moveNumberedInputBefore

moveNumberedInputBefore(inputIndex, refIndex)

Move a numbered input to a different location on this block.

Parameter
inputIndex	number Index of the input to move.
refIndex	number Index of input that should be after the moved input.

removeInput

removeInput(name, opt_quiet)

Remove an input from this block.

Parameter
name	string The name of the input.
opt_quiet	Optional boolean True to prevent error if input is not present.

Throws

Error if the input is not present and opt_quiet is not true.

renameVarById

renameVarById(oldId, newId)

Notification that a variable is renaming. If the ID matches one of this block's variables, rename it.

Parameter
oldId	string ID of variable to rename.
newId	string ID of new variable. May be the same as oldId, but with an updated name.

setCollapsed

setCollapsed(collapsed)

Set whether the block is collapsed or not.

Parameter
collapsed	boolean True if collapsed.

setColour

setColour(colour)

Change the colour of a block.

Parameter
colour	(number or string) HSV hue value (0 to 360), #RRGGBB string, or a message reference string pointing to one of those two values.

setCommentText

setCommentText(text)

Set this block's comment text.

Parameter
text	string The text, or null to delete. Value may be null.

setConnectionsHidden

setConnectionsHidden(hidden)

Set whether the connections are hidden (not tracked in a database) or not. Recursively walk down all child blocks (except collapsed blocks).

Parameter
hidden	boolean True if connections are hidden.

setDeletable

setDeletable(deletable)

Set whether this block is deletable or not.

Parameter
deletable	boolean True if deletable.

setDisabled

setDisabled(disabled)

Set whether the block is disabled or not.

Parameter
disabled	boolean True if disabled.

Deprecated

May 2019

setEditable

setEditable(editable)

Set whether this block is editable or not.

Parameter
editable	boolean True if editable.

setEnabled

setEnabled(enabled)

Set whether the block is enabled or not.

Parameter
enabled	boolean True if enabled.

setFieldValue

setFieldValue(newValue, name)

Change the field value for a block (e.g. 'CHOOSE' or 'REMOVE').

Parameter
newValue	string Value to be the new field.
name	string The name of the field.

setHelpUrl

setHelpUrl(url)

Set the URL of this block's help page.

Parameter
url	(string or function()) URL string for block help, or function that returns a URL. Null for no help.

setInputsInline

setInputsInline(newBoolean)

Set whether value inputs are arranged horizontally or vertically.

Parameter
newBoolean	boolean True if inputs are horizontal.

setInsertionMarker

package

setInsertionMarker(insertionMarker)

Set whether this block is an insertion marker block or not. Once set this cannot be unset.

Parameter
insertionMarker	boolean True if an insertion marker.

setMovable

setMovable(movable)

Set whether this block is movable or not.

Parameter
movable	boolean True if movable.

setMutator

setMutator(_mutator)

Give this block a mutator dialog.

Parameter
_mutator	Blockly.Mutator A mutator dialog instance or null to remove.

setNextStatement

setNextStatement(newBoolean, opt_check)

Set whether another block can chain onto the bottom of this block.

Parameter
newBoolean	boolean True if there can be a next statement.
opt_check	Optional (string, Array of string, or null) Statement type or list of statement types. Null/undefined if any type could be connected.

setOnChange

setOnChange(onchangeFn)

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.

Parameter
onchangeFn	function(Blockly.Events.Abstract) The callback to call when the block's workspace changes.

Throws

Error if onchangeFn is not falsey or a function.

setOutput

setOutput(newBoolean, opt_check)

Set whether this block returns a value.

Parameter
newBoolean	boolean True if there is an output.
opt_check	Optional (string, Array of string, or null) Returned type or list of returned types. Null or undefined if any type could be returned (e.g. variable get).

setParent

setParent(newParent)

Set parent of this block to be a new block or null.

Parameter
newParent	Blockly.Block New parent block.

setPreviousStatement

setPreviousStatement(newBoolean, opt_check)

Set whether this block can chain onto the bottom of another block.

Parameter
newBoolean	boolean True if there can be a previous statement.
opt_check	Optional (string, Array of string, or null) Statement type or list of statement types. Null/undefined if any type could be connected.

setShadow

setShadow(shadow)

Set whether this block is a shadow block or not.

Parameter
shadow	boolean True if a shadow.

setStyle

setStyle(blockStyleName)

Set the style and colour values of a block.

Parameter
blockStyleName	string Name of the block style

Throws

Error if the block style does not exist.

setTooltip

setTooltip(newTip)

Change the tooltip text for a block.

Parameter
newTip	(string or non-null function()) Text for tooltip or a parent element to link to for its tooltip. May be a function that returns a string.

setWarningText

setWarningText(_text, _opt_id)

Set this block's warning text.

Parameter
_text	string The text, or null to delete. Value may be null.
_opt_id	Optional string An optional ID for the warning text to be able to maintain multiple warnings.

toDevString

toDevString() returns string

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().

Returns

string The description.

toString

toString(opt_maxLength, opt_emptyToken) returns string

Create a human-readable text representation of this block and any children.

Parameter
opt_maxLength	Optional number Truncate the string to this length.
opt_emptyToken	Optional string The placeholder string used to denote an empty field. If not specified, '?' is used.

Returns

string Text of block.

unplug

unplug(opt_healStack)

Unplug this block from its superior block. If this block is a statement, optionally reconnect the block underneath with the block on top.

Parameter
opt_healStack	Optional boolean Disconnect child statement and reconnect stack. Defaults to false.

updateVarName

package

updateVarName(variable)

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.

Parameter
variable	Blockly.VariableModel The variable being renamed. Value must not be null.