GWT provides wrappers for all DOM-events and a unified interface for handling them. This article aims to provide a full listing of all relevant classes and points of interest for solving problems related to the DOM event cycle.
GWT event-handling is seperated from DOM events, which are wrapped with the NativeEvent class. The DomEvent class is a subclass of GwtEvent, which implements the flyweight pattern to wrap DOM-events and provide behaviour consistent with the GWT event-handling.
This makes it possible to handle DomEvents in the same way as regular GwtEvents, while the former are triggered by the browser itself.
The link to the browser is realized in the DOMImplStandard.sinkEventsImpl(Element, int) method. In this native method, DOM EventListeners are added to the DOM elements representing GWT Widgets. This method is ultimately executed when the addDomHandler() method is called. It effectively overrides all eventlisteners set by the browser with a method triggering the GWT event-cycle, so calling event.preventDefault() and event.stopPropagation() on a DomEvent are sure to have the desired effect.
Debugging in the Browser
When debugging issues with the DOM event-handling, a good point to start is to check the "Event Listeners" property of the DOM element. All DomEvents which have been added using addHandler() should be visible here - the most common reason for event-handling not working is that addHandler() was not called ;-).
In some browsers, stopping the propagation of "lower-level" events (such as click events) can prevent other DOM events (like the contextmenu event) from being triggered. This can be the source of near-endless frustration, especially with browsers like Chrome/Chromium, which implement major parts of their own user-interfaces in javascript/html.
Helpful Links
The following links provide essential information for understanding the DOM event-handling and associated problems:
- http://www.w3.org/TR/DOM-Level-3-Events/ - the official DOM3 Event specification
- http://www.w3.org/TR/DOM-Level-3-Events/images/eventflow.svg - The infamous DOM event-flow diagram (explains capture- and bubbling-phases)
- http://en.wikipedia.org/wiki/DOM_events - list of all DOM events, ordered by browser
- http://www.din.or.jp/~hagi3/JavaScript/JSTips/Mozilla/Samples/contextMenu.htm - An example for context-menu overriding, illustrates the different ways to add DOM event-listeners to DOM elements.
