Generalizing Events

This page discuss proposed improvements to how bokeh handles various types of event. At a high level, the idea is to offer a unified layer that process a generic event type consisting of an event type and payload.

General features

1. Want a generic event type in bokeh that is not tied to Backbone. It can be something like a JSON dict with a type and a payload.
2. The idea is that there is a generic event layer that abstracts away the existing event types (hammer events, backbone related events, maybe events relating to tools).
3. This generic event layer should be able to trigger Python or JS callbacks.
4. This system should help deprecate ToolEvents as well as the various callback methods (these can be replaced by the new, centralized way of registering JS callbacks).
5. There should be a mechanism to state what events are being listened for. This can inform the components emitting events so they only emit the events that are of interest.

Open questions:

1. What types of events should be available? Some examples of interest - click, double click, mouse position, selection events. You can imagine low level events such as mouse down or more sophisticated events such as drag & drop events.
2. What payloads should be associated with these events? For instance, the mouse position can have an x,y position but also a position in data space. This could have more than 2 coordinates e.g. when using twin axes.
3. Where does this layer belong? At the level of the Document or something more granular?

Proposed events:

Here is a list of the events that may be of interest to users. The following suggestions are (roughly) ordered by how useful they might be to users.

UI events

UI Event	Possible payload
click/tap	xpos, ypos, data coordinates
doubleclick	xpos, ypos, data coordinates
keypress	char pressed
key up	char pressed
key down	char pressed
drag motion	start pos (x,y), end pos (x,y), start data coords, end data coords
mousewheel	wheel delta, wheel delta x, wheel delta y

Tool events

Tool Event	Possible payload
boxselect	(x1,y1,x2,y2), selection indices
lasso select	[(x1,y1),(x2,y2),...], selection indices
x_range	(data x-start, data x-end)
y_range	(data y-start, data y-end)
pan	(dx,dy), delta in data coords.
reset	[no payload]
crosshair	(x,y), (data x, data y)

Low level events

Low level events	Possible payload
mouse down	xpos, ypos, data coordinates
mouse up	[(x1,y1),(x2,y2),...], selection indices

Relevant links:

PR 5276 (closed) - Offers similar functionality but is not unified in the same way as the current proposal PR 5491.