Skip to main content

New site for Dart news and articles

For the latest Dart news, visit our new blog at  https://medium.com/dartlang .

New DOM Event Streams API makes it Easier to Listen to and Capture Events

A new API is on the way for dealing with DOM events in Dart. Google engineer Peter Bois gives us the details:
One of our goals for exposing DOM events in Dart is to have them follow the 'best practices' for events- particularly events which are exposed in places such as your application data model.

The current plan is that DOM events would be exposed as:
class Element {
  static const HtmlStreamProvider<MouseEvent> clickEvent = 
    const HtmlStreamProvider<MouseEvent>('click');

  Stream<MouseEvent> get onClick => clickEvent.forTarget(this);
}

The HtmlStreamProvider class is:
class HtmlStreamProvider<T extends Event> {
  const HtmlStreamProvider(String eventType);
  Stream<T> forTarget(EventTarget e, {bool useCapture: false})
}

There's basically two parts- 
  1. The static declaration of the event as an HtmlStreamProvider which provides a Stream for a DOM event on a specific target. This is only really used for bubbling DOM events.
  2. A Stream<> getter on the object instance to allow easy access to the event stream.
NOTE: we will not remove the old APIs until the new APIs have been in & baked for a while.

Examples of old vs new syntax:

Listening to an event
Old:
element.on.click.add((e) {
});
New:
element.onClick.listen((e) {
});

Capturing an event
Old:
element.on.click.add((e) {  
}, true);
New:
Element.clickEvent.forTarget(element, useCapture:true).listen((e) {
});

Listening to a bubbled event
Old (not really supported):
document.body.$dom_addEventListener('canPlay', (e) {}, false);
New:
MediaElement.canPlayEvent.forTarget(document.body).listen((e) {
});


QUESTIONS:
  1. Are you planning on exposing all model events as Streams? By this I mean something like backbone.js-style events. Our goal for DOM events is to be consistent with the dominant data event model.
  2. Any opinions on naming? Currently the events are exposed as onEventName, but it's often common to use this naming style for virtual methods. Using just eventName has a number of conflicts with members. We aren't entirely thrilled with onEventName.
If you're interested in taking a peek, the CL with the changes is at:

As always, we invite you to join our Dart mailing list, ask questions on Stack Overflow, or file feature requests on dartbug.com.