Events & Handlers

The same handler pattern serves four different sources of events. Knowing which source an event comes from tells you who dispatches it, whether the browser can be told to ignore it, and how long a registration lives.

All four use the same two supertypes. com.google.web.bindery.event.shared.Event<H> is the base class of every event: it has an Event.Type<H> key, a source and a protected dispatch(H) method. com.google.gwt.event.shared.GwtEvent<H extends EventHandler> extends it and adds a liveness check; all the stock GWT events extend GwtEvent. The marker interface EventHandler (com.google.gwt.event.shared.EventHandler) is implemented by every stock handler interface.

The path of a DOM event through a widget is the one worth keeping in mind, because it explains the ordering of everything else on this page.

Source: GWT Developer Guide — Using the DOM

The element only sends an event to GWT if the widget has sunk it (sinkEvents for events that have a bit, sinkBitlessEvent for the others). The helper methods addClickHandler, addDomHandler and addBitlessDomHandler do the sinking for you. The bit constants and the lifecycle (what attach and detach do to a sunk event) are documented on the DOM & Elemental2 page; this page builds on them.

Every stock event comes as a pair: a handler interface with one method named on plus the event, and an event class with a static getType(). The interface for ClickEvent is ClickHandler with void onClick(ClickEvent event); for KeyDownEvent it is KeyDownHandler with void onKeyDown(KeyDownEvent event). A widget that can produce an event implements the matching Has...Handlers interface, whose single method is add...Handler (HasClickHandlers.addClickHandler(ClickHandler)), and the call returns a HandlerRegistration.

The Developer Guide builds on this pattern with two examples: an anonymous class per widget, and one handler instance shared by several widgets that tells them apart with event.getSource(). Because every stock handler interface has exactly one method, a lambda works as well (the Bookshelf module compiles with -sourceLevel 17), and the shared-handler form stays useful when many widgets need the same behaviour:

Source: GWT Developer Guide — Events and Handlers

The third dispatch printed nothing, and the second removeHandler() did not throw.

GWT wraps the browser events that matter for application widgets in com.google.gwt.event.dom.client. Each one has a native event name (the constants live in com.google.gwt.dom.client.BrowserEvents), a handler, an event class and, on FocusWidget and the other widgets that support them, an add...Handler method.

Source: GWT Javadoc — com.google.gwt.event.dom.client

Three things are missing from the table on purpose. There is no handler type for pointer events (pointerdown, pointermove) and none for input; the section "Events GWT does not know" shows how to add them. FocusWidget (buttons, text boxes, list boxes) supplies the click, double-click, key, mouse, focus, touch, gesture and drag-and-drop methods; other widgets implement the Has...Handlers interfaces that fit them, and a bare Widget supplies only addDomHandler and addHandler, which is what the next section uses. And the wheel row needs a remark: the 2.12.0 release notes say that the browser’s mousewheel event is deprecated and that GWT’s use of it was replaced by the standard wheel event, "transparent to applications", so MouseWheelHandler keeps working.

The helper interfaces make it easy to listen to a whole family with one object. HandlesAllKeyEvents, HandlesAllMouseEvents, HandlesAllFocusEvents and HandlesAllTouchEvents are abstract classes that implement all handlers of a family; you extend one and call addKeyHandlersTo(source) (or the equivalent method of the other classes). That method returns void: it registers the three handlers and drops their registrations, so it suits handlers that live as long as the source. When you need to remove them, add the three handlers yourself and combine the registrations with HandlerRegistrations.compose:

Source: GWT Javadoc — com.google.gwt.event.dom.client

The stock widgets call sinkEvents for you. A widget you build directly on a DOM element does it itself, then handles the events in onBrowserEvent(Event). The DOM & Elemental2 page shows the mechanism with a click counter; here the Bookshelf BookRow uses it the way a real widget does: it turns browser events into application events and still lets users add ordinary handlers.

Source: GWT Developer Guide — Using the DOM

The order in which things happen is the point of the example. The widget was attached to the page with two preview handlers registered, then a click and an Enter key were dispatched at its element. The preview handlers run first (the later one before the earlier one), then onBrowserEvent, and the handlers added with addDomHandler run last, from super.onBrowserEvent:

In headless Chrome 155 the same widget received a real mouse click and a real Enter key (sent through the DevTools protocol) and a synthetic dblclick dispatched at the element:

The first bus: line is the click, the second is the Enter key.

Event.addNativePreviewHandler(NativePreviewHandler) registers a global handler that sees every native event GWT dispatches, before the target widget does. It is the tool for application-wide behaviour that does not belong to any widget: keyboard shortcuts, "click outside closes the popup", logging, a busy overlay that swallows input. The Javadoc spells out its rules, and the probe confirmed them:

Source: GWT Javadoc — Event

The inner (later) handler ran first, the outer one saw the cancelled state, and the button never logged button received click: the click was cancelled before it reached the widget. The Developer Guide’s keyboard-shortcut example, which uses consume() to mark a shortcut as handled while letting it through, is quoted on the DOM & Elemental2 page; the older Event.addEventPreview(EventPreview) it replaced is deprecated in 2.13.1.

A shortcut for the Bookshelf catalogue ("press / to focus the search box", ignored while typing in a field) looks like this:

Source: GWT Developer Guide — Using the DOM

The shortcut must be removed when the view that installed it goes away (shortcut.removeHandler() in onUnload), or it keeps focusing a box that is no longer on the page.

com.google.gwt.user.client.Window keeps the handlers for the browser window. The first handler of each kind installs the native listener; the registration removes your handler.

Source: GWT Javadoc — Window

The old addWindowCloseListener, addWindowResizeListener and addWindowScrollListener are deprecated and are wrappers around the handler API. The 2.12.0 release notes record the reason for the close handler: the unload event is deprecated in browsers, so the calls that need it are deprecated and the notes of each deprecated method say what to use instead.

Source: GWT Javadoc — Window

The probe module registered a resize handler and a closing handler and drove headless Chrome 155 through the DevTools protocol. Resizing the viewport to 800x600 produced exactly one resize 800x600 line, although the size override was applied twice, and a synthetic resize event dispatched afterwards with the size unchanged produced nothing: GWT’s own filter (the source comment says that "on webkit and IE we sometimes get duplicate window resize events") drops events whose size did not change. Navigating away after real clicks opened the browser’s beforeunload dialog, and the closing handler had run (closing was logged), but the dialog’s message was the empty string: the text passed to setMessage is not shown by current browsers. MDN adds that browsers may skip the dialog for pages the user never interacted with. Use the handler to guard against losing unsaved work, and treat the message as a hint, not as UI.

A resize handler can run dozens of times per second while the user drags the window edge. Do cheap work in it, or debounce with a Timer or Scheduler.scheduleDeferred as the Delayed Logic & Scheduler page describes. Layout panels do not need a window handler: they resize their children through RequiresResize when the root layout panel resizes (see Panels & Layout).

Two different things can be stopped, and they are easy to confuse.

Source: MDN — Event.preventDefault()

The distinction shows in a panel that contains a button, with a click handler on each. The probe dispatched a click at the button, first with the two handlers, then after adding a second button handler that stops propagation:

Source: MDN — Event.stopPropagation()

The panel saw the click through bubbling, and getEventTarget() still named the button, so a handler on a container can tell which child was hit. After stopPropagation() the panel handler no longer ran. Note that stopPropagation() does not stop the other handlers registered on the same widget: button click ran before button stops it and would still run if it were registered after.

Do not use stopPropagation() to prevent a navigation or a form submit: that is preventDefault(). And do not call either on events that you only observe, such as the focus and blur of a form: cancelling them has no useful effect and hides the real behaviour from other handlers.

Browsers have a native drag-and-drop model (the HTML Standard’s "drag-and-drop processing model"), and GWT exposes it. It replaced the approach of the 2007 book, which had no native support to build on and therefore assembles dragging from mouse listeners and mouse capture. That technique still works with the mouse events above, but it cannot carry files, links or text between applications and does not use the data and effect model of the platform.

The pieces in GWT 2.13.1:

Source: GWT Javadoc — DragStartEvent

In headless Chrome 155 the probe intercepted a real drag started with the mouse (Input.setInterceptDrags), replayed it as dragEnter, dragOver and drop events at the zone, and printed:

The rule that surprises most newcomers is in the HTML Standard and on MDN: an element is a valid drop target only if its dragover (and dragenter) event is cancelled with preventDefault(). That is why the zone above has a DragOverEvent handler that does nothing but cancel. The probe replayed events through the DevTools protocol, which does not exercise that rule, so the "no preventDefault, no drop" behaviour is quoted from the standard and was not reproduced here.

Two more cautions. A drop delivers data from outside the page (another tab, a file manager): getData(...) must be treated like any other user input and shown with setText, never setHTML. And HtmlUnit does not model drag data: a synthetic dragstart created with Document.createHtmlEvent("dragstart", true, true) reaches the handler with a null DataTransfer, so a handler that calls setData fails in GWTTestCase with Cannot call method "setData" of null even though it works in a real browser. Test the data flow in a browser run, or put it behind an interface that a plain-JUnit presenter test can fake.

Application events are the same pattern with your own classes. You need an event class, a handler interface and a static Type, and then something to fire the event through: a widget (every Widget is a HasHandlers), a HandlerManager, or an event bus.

The Bookshelf catalogue shows each book as a BookRow, and a StockBadge next to it shows the copies left. Clicking a row (or pressing Enter on it) fires a BookSelectedEvent on the application bus. Borrowing or returning a copy fires a LoanChangedEvent; every badge that is on the page for that book updates, and a badge that has left the page does not.

Source: GWT Developer Guide — Activities and Places

The badge registers in onLoad and unregisters in onUnload, through a ResettableEventBus, so the lifetime of the registration is exactly the lifetime of the widget on the page:

Source: GWT Javadoc — Widget

The test drove the badge through three states: detached, attached, and detached again. Events for the badge’s book arrive only while it is attached:

Source: GWT Javadoc — SimpleEventBus.fireEvent

The detached badge ignored the first event, the attached one showed 2 copies and ignored book 8, and after onUnload the badge no longer reacted to the event that would have set 1 copy. The server stays authoritative: the event only updates what the user sees, and the real number of copies comes back from the RPC call (with its XSRF protection) that the activity makes before it fires the event.

A handler added to a widget or its child is released with the widget. A handler added to something that outlives the widget (an application event bus, Window, Event.addNativePreviewHandler, a Timer, an Elemental2 listener on document) is released only by you. The DOM & Elemental2 page measures the same effect for global DOM listeners; the version for the event bus is just as direct. A label registered on the application bus in its constructor and never unregistered:

Source: GWT article — DOM Events, Memory Leaks, and You

The label was removed from the page but is still alive and still handling events, because the bus holds the lambda and the lambda holds the label. The rules that keep applications clean:

Widget.addAttachHandler(AttachEvent.Handler) lets code outside the widget react to attach and detach when overriding onLoad is not an option.

The book (GWT 1.3 and 1.4, 2007) is built on listeners: interfaces with several methods, adapters, ListenerCollection helpers and addClickListener(...). Handlers replaced them in GWT 1.6, and the listener classes are still in gwt-user 2.13.1, all marked @Deprecated, so old code compiles with warnings. The advice of every @deprecated tag is to move to handlers, and the mapping is mechanical:

Source: GWT Javadoc — Widget

What changes besides names:

A before-and-after for a Bookshelf confirmation button:

Source: GWT Developer Guide — Events and Handlers

The messages below were printed by the 2.13.1 run of the probes described at the top of the page (HtmlUnit through GWTTestCase with assertions enabled, unless marked as Chrome).

Source: GWT — Release Notes