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.BLOCK_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.BLOCK_CREATE, Blockly.Events.BLOCK_DELETE, Blockly.Events.BLOCK_CHANGE, Blockly.Events.BLOCK_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 |
Element | An XML tree defining the new block and any connected child blocks. |
json |
object | A JS object 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 |
Element | An XML tree defining the deleted block and any connected child blocks. |
oldJson |
object | A JS object 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. |
wasShadow |
boolean | Whether the deleted block was a shadow block or not. |
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. |
Workspace Comment Events
Blockly.Events.COMMENT_CREATE
Workspace comment create events have two additional properties.
Name | Type | Description |
---|---|---|
commentId |
string | The UUID of the newly created comment. |
xml |
object | An XML tree defining the new comment. |
Blockly.Events.COMMENT_DELETE
Workspace comment delete events have two additional properties.
Name | Type | Description |
---|---|---|
commentId |
string | The UUID of the deleted comment. |
xml |
object | An XML tree defining the deleted comment. |
Blockly.Events.COMMENT_CHANGE
Workspace comment change events have four additional properties.
Name | Type | Description |
---|---|---|
commentId |
string | The UUID of the comment that is being changed. |
oldContents |
string | Previous contents of the comment. |
newContents |
string | New contents of the comment. |
Blockly.Events.COMMENT_MOVE
Workspace comment move events have six additional properties.
Name | Type | Description |
---|---|---|
commentId |
string | The UUID of the comment that is being moved. |
oldCoordinate |
string | The location before the move, in workspace coordinates. |
newCoordinate |
string | The location after the move, in workspace coordinates. |
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.SELECTED
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.