UI event API changes in December release

[Monica Kozbial]

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)

2. 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]

Minor typos in the table for "new type" column.

themeChange -> theme_change

viewportChange -> viewport_change