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

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, Blockly.Events.UI.
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.

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', 'mutate'
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.

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.

Blockly.Events.UI

UI events have three additional properties.

Name	Type	Description
element	string	One of 'selected', 'category', 'click', 'commentOpen', 'mutatorOpen', 'warningOpen', 'theme'
oldValue	value	Original value.
newValue	value	Changed value.

It is expected that the list of UI actions represented by UI events will become more comprehensive over time. For instance events for scrolling, zooming, dragging bubbles, etc.

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