Events

Every change on the workspace triggers an event. These events fully describe the before and after state of each change.

Listening to Events

Workspaces have addChangeListener and removeChangeListener methods that can be used to listen to the event stream. One example is the real-time generation of code. Another example is the maximum block limit demo. As is often the case, neither of these two examples care what the triggering event was. They simply look at the current state of the workspace.

A more sophisticated event listener would look at the triggering event. The following example detects when the user creates their first comment, issues an alert, then stops listening so that no further alerts are triggered.

function onFirstComment(event) {
  if (event.type == Blockly.Events.CHANGE &&
      event.element == 'comment' &&
      !event.oldValue && event.newValue) {
    alert('Congratulations on creating your first comment!')
    workspace.removeChangeListener(onFirstComment);
  }
}
workspace.addChangeListener(onFirstComment);

In order to listen to any events that happen inside of a flyout a listener can be added to the flyout's workspace.

var flyoutWorkspace = yourWorkspace.getFlyout().getWorkspace();
flyoutWorkspace.addChangeListener(onFirstComment);

Blocks have another method of listening to the event stream. A block can define an onchange function or use setOnChange to set a function that will get called whenever a change occurs on the block's workspace.

Event Types

All events share the following common properties.

Name	Type	Description
`type`	string	One of Blockly.Events.CREATE, Blockly.Events.DELETE, Blockly.Events.CHANGE, Blockly.Events.MOVE, etc.
`isUiEvent`	boolean	Whether the event is a UI event (eg. scroll, click, select, block drag).
`workspaceId`	string	UUID of workspace. The workspace can be found with `Blockly.Workspace.getById(event.workspaceId)`.
`blockId`	string	UUID of block. The block can be found with `workspace.getBlockById(event.blockId)`.
`group`	string	UUID of group. Some events are part of an indivisible group, such as inserting a statement in a stack. This is used for grouping events together for undo/redo.

Workspace Events

Blockly.Events.FINISHED_LOADING

Finished loading events are not added to the undo stack. There are no additional properties for the Finished Loading event.

Block Events

Blockly.Events.BLOCK_CREATE

Block create events have two additional properties.

Name	Type	Description
`xml`	object	An XML tree defining the new block and any connected child blocks.
`ids`	array	An array containing the UUIDs of the new block and any connected child blocks.

Blockly.Events.BLOCK_DELETE

Block delete events have two additional properties.

Name	Type	Description
`oldXml`	object	An XML tree defining the deleted block and any connected child blocks.
`ids`	array	An array containing the UUIDs of the deleted block and any connected child blocks.

Blockly.Events.BLOCK_CHANGE

Block change events have four additional properties.

Name	Type	Description
`element`	string	One of 'field', 'comment', 'collapsed', 'disabled', 'inline', 'mutation'
`name`	string	Name of the field if this is a change to a field.
`oldValue`	value	Original value.
`newValue`	value	Changed value.

Blockly.Events.BLOCK_MOVE

Block move events have six additional properties.

Name	Type	Description
`oldParentId`	string	UUID of old parent block. Undefined if it was a top level block.
`oldInputName`	string	Name of input on old parent. Undefined if it was a top level block or parent's next block.
`oldCoordinate`	object	X and Y coordinates if it was a top level block. Undefined if it had a parent.
`newParentId`	string	UUID of new parent block. Undefined if it is a top level block.
`newInputName`	string	Name of input on new parent. Undefined if it is a top level block or parent's next block.
`newCoordinate`	object	X and Y coordinates if it is a top level block. Undefined if it has a parent.

Variable Events

Blockly.Events.VAR_CREATE

Variable create events have two additional properties.

Name	Type	Description
`varType`	string	The type of the variable like 'int' or 'string'. Does not need to be unique. This will default to "" which is a specific type.
`varName`	string	The name of the variable. This is unique across variables and procedures.
`varId`	string	The unique id of the variable.

Blockly.Events.VAR_DELETE

Variable delete events have two additional properties.

Name	Type	Description
`varType`	string	The type of the variable like 'int' or 'string'. Does not need to be unique. This will default to "" which is a specific type.
`varName`	string	The name of the variable. This is unique across variables and procedures.
`varId`	string	The unique id of the variable.

Blockly.Events.VAR_RENAME

Variable rename events have two additional properties.

Name	Type	Description
`oldName`	string	The current name of the variable. This is unique across variables and procedures.
`newName`	string	The new name of the variable. This is unique across variables and procedures.
`varId`	string	The unique id of the variable.

UI Events

UI events are events that don't necessarily need to be sent over the wire for multi-user editing to work (e.g. scrolling the workspace, zooming, opening toolbox categories). UI events are not added to the undo stack. The isUiEvent property for UI events is equal to true.

Blockly.Events.CLICK

Click events have one additional property.

Name	Type	Description
`targetType`	string	The type of element clicked. One of 'block', 'workspace', 'zoom_controls'.

Blockly.Events.SELECT

Select events have two additional properties.

Name	Type	Description
`oldElementId`	string	The id of the last selected element (can be either a block id or workspace comment id).
`newElementId`	string	The id of the selected element (can be either a block id or workspace comment id, null for de-select).

Blockly.Events.BLOCK_DRAG

Block drag events have two additional properties.

Name	Type	Description
`isStart`	boolean	Whether this is the start of a block drag.
`blocks`	!Array<!Blockly.Block>	The blocks affected by this drag event.

Blockly.Events.MARKER_MOVE

Marker move events have three additional properties.

Name	Type	Description
`oldNode`	?Blockly.ASTNode	The old node the marker used to be on (or null if there was none).
`newNode`	Blockly.ASTNode	The new node the marker is now on.
`isCursor`	boolean	Whether this is a cursor event.

Blockly.Events.BUBBLE_OPEN

Bubble open events have two additional properties.

Name	Type	Description
`isOpen`	boolean	True if the bubble is opening, false otherwise.
`bubbleType`	string	The type of bubble. One of 'mutator', 'comment', or 'warning'.

Blockly.Events.TRASHCAN_OPEN

Trashcan open events have one additional property.

Name	Type	Description
`isOpen`	boolean	Whether the trashcan flyout is opening (false if closing).

Blockly.Events.TOOLBOX_ITEM_SELECT

Toolbox item select events have two additional properties.

Name	Type	Description
`oldItem`	string	The previously selected toolbox item name.
`newItem`	string	The newly selected toolbox item name.

Blockly.Events.THEME_CHANGE

Theme change events have one additional property.

Name	Type	Description
`themeName`	string	The theme name.

Blockly.Events.VIEWPORT_CHANGE

Viewport change events have three additional properties.

Name	Type	Description
`viewTop`	number	Top-edge of the visible portion of the workspace, relative to the workspace origin.
`viewLeft`	number	Left-edge of the visible portion of the workspace, relative to the workspace origin.
`scale`	number	The scale of the workspace.

Here is a live demo of two Blockly instances using events to synchronize between them.