UI event API changes in December release

154 views
Skip to first unread message

Monica Kozbial

unread,
Dec 8, 2020, 12:36:42 PM12/8/20
to blo...@googlegroups.com

Hello everyone, 

The upcoming December 2020 release includes API changes to Blockly UI Events. This change makes it easier to differentiate between UI events and creates better typing and property names.

Instead of firing Blockly.Events.Ui, we now fire more specific subclasses that inherit from Blockly.Events.BaseUi. For compatibility with developers who have extended Blockly.Events.Ui we have kept Blockly.Events.Ui with only minor changes. It now inherits  from Blockly.Events.BaseUi.

After release, we will publish updates to Events documentation with more detail on each new property’s type and description. Additionally, the issue tracking this change is #4203.

If you have any questions, feel free to respond to this thread.


If you don’t do a lot with events, you can stop reading now. Otherwise, as part of upgrading to the newest release, you should expect to need to make the following changes anywhere that you listen to (or use) UI events:

  1. You will need to change how you check for if an event is a Ui event.

As a result of this change, the type of all UI events are no longer ‘ui’ (with exception of deprecated Blockly.Events.Ui) and in order to check if an event is a UI event, you must use a new property on all events isUiEvent to check. 

before release

after release

if (event.type == ui’)
or
if (event.type == Blockly.Events.UI)

or

if (event instanceof Blockly.Events.Ui)

if (event.isUiEvent)    [recommended]

or

if (event instanceof Blockly.Events.BaseUi)


  1. You will need to change the properties you access on UI events emitted from Blockly.

Additionally, the property names on UI Events have changed, to be more specific to what value they hold. Prior to this refactor, these events had the properties: element, oldValue, and newValue, where element held information on the more specific type of UI event. Now, the type property details the type of UI event and each event has its own set of properties.

Here is a detailed table of conversions for new events and properties:

old element property

new class

new type

old property → new property

dragStart

Blockly.Events.BlockDrag

drag

oldValue → null

newValue → blocks

(new property) isStart=true

dragStop

Blockly.Events.BlockDrag

drag

oldValue → blocks

newValue → null

(new property) isStart=false

selected

Blockly.Events.Selected

selected

oldValue → oldElementId

newValue → newElementId

click

Blockly.Events.Click

click

newValue → targetType

cursorMove

Blockly.Events.MarkerMove

marker_move

oldValue → oldNode

newValue → newNode

(new property) isCursor=true

markerMove

Blockly.Events.MarkerMove

marker_move

oldValue → oldNode

newValue → newNode

(new property) isCursor=false

commentOpen

Blockly.Events.BubbleOpen

bubble_open

newValue → isOpen

(new property) bubbleType=’comment’

mutatorOpen

Blockly.Events.BubbleOpen

bubble_open

newValue → isOpen

(new property) bubbleType=’mutator’

warningOpen

Blockly.Events.BubbleOpen

bubble_open

newValue → isOpen

(new property) bubbleType=’warning’

trashcanOpen

Blockly.Events.TrashcanOpen

trashcan_open

newValue → isOpen

category

Blockly.Events.ToolboxItemSelect

toolbox_item_select

oldValue → oldItem

newValue → newItem

theme

Blockly.Events.ThemeChange

themeChange

(new property) themeName

(new event)

Blockly.Events.ViewportChange

viewportChange

(new property) viewTop

(new property) viewLeft

(new property) scale


~ Monica


koz...@google.com

unread,
Dec 11, 2020, 7:27:38 PM12/11/20
to Blockly
Minor typos in the table for "new type" column.
themeChange -> theme_change
viewportChange -> viewport_change

Reply all
Reply to author
Forward
0 new messages