Supporting multi-touch events with GWT on mobile Safari

March 28th, 2010 Alex Moffat Posted in GWT | 13 Comments »

The goal is to be able to handle the touchstart, touchmove, touchend and touchcancel events provided by mobile Safari by writing standard GWT code like the example below for touchstart.

        touchable.addTouchStartHandler(new TouchStartHandler() {
            public void onTouchStart(TouchStartEvent event) {
                event.preventDefault();
                addStyleDependentName("touched");
                Touch t = event.touches().get(0);
                offsetX = t.pageX() - getAbsoluteLeft();
                offsetY = t.pageY() - getAbsoluteTop();
            }
        });

I’ll walk through the steps needed to get this working, concentrating on the implementation needed for the touchstart event.

The easiest place to start is by building the EventHandler and Event subclasses. The code below is the TouchStartHandler. It’s just extends EventHandler.

public interface TouchStartHandler extends EventHandler {

    void onTouchStart(TouchStartEvent event);
}

The TouchStartEvent class is also simple. It implements the abstract methods getAssociatedType and dispatch defined by GWTEvent. I chose to implement a TouchEvent abstract superclass for the TouchStart, TouchMove, TouchEnd and TouchCancel classes following the pattern of the MouseDown, MouseUp etc events provided by GWT. The start of the TouchStartEvent class looks like

public class TouchStartEvent extends TouchEvent<TouchStartHandler> {

    private static final Type<TouchStartHandler> TYPE =
        new Type<TouchStartHandler>("touchstart", new TouchStartEvent());

    public static Type<TouchStartHandler> getType() {
        return TYPE;
    }

    // getAssociatedType and dispatch
}

Notice the value “touchstart” provided as the value of the eventName parameter to the DomEvent.Type constructor. This is used when hooking up the handlers so that they are called when touchstart events are fired by the browser. It does not have to be the native event name but things are less confusing if you follow the convention that it is.

A basic implementation of the TouchEvent superclass just provides access to the touches array of touch objects provided by the native JavaScript.

public abstract class TouchEvent<H extends EventHandler> extends DomEvent<H> {

    public JsArray<Touch> touches() {
        return touches(getNativeEvent());
    }

    private native JsArray<Touch> touches(NativeEvent nativeEvent) /*-{
      return nativeEvent.touches;
    }-*/;
}

I used overlay types to implement Touch so there’s no overhead. The fragment below just shows access to the pageX value.

public class Touch extends JavaScriptObject {

    protected Touch() {
    }

    public final native int pageX() /*-{
      return this.pageX;
    }-*/;

Now all these pieces are in place it possible to write the code that will add support for touch events to a GWT widget. For example you would be able to extend SimplePanel to create TouchPanel and add this method.

    public HandlerRegistration addTouchStartHandler(TouchStartHandler handler) {
        return addDomHandler(handler, TouchStartEvent.getType());
    }

As you probably expect this doesn’t work. To see why we need to take a look at the implementation of addDomHandler in the Widget class and understand a little about how GWT handles events. The critical line in addDomHandler is

  sinkEvents(Event.getTypeInt(type.getName()));

This is what eventually sets the ontouchstart property of the widget’s element.

Each different type of event supported by GWT has a corresponding integer code returned by Event.getTypeInt. Each code is a single bit so that the codes can be combined with an or operation as a bit field. The bit field is used when event handlers are added or removed to know which handlers are currently set on an element. Adding a new type of event requires that Event.getTypeInt return a new unique value for that type which works with the bit field mechanism and the values used for all the existing types. If you trace through Event.getTypeInt you end up at the implementation in eventGetTypeInt in DOMImpl. It’s just a large switch statement with case statements for each type value. For example

    case "load": return 0x08000;
    case "losecapture": return 0x02000;
    case "mousedown": return 0x00004;

The correct subclass of DOMImpl is chosen at compile time using deferred binding so to support these new events you need a subclass appropriate for mobile Safari. My post “The right way to add support for a new browser to GWT” explains how to do this.

I copied the code for eventGetTypeInt from DOMImpl into my DOMImplMobileSafari class and added new case statements for the new touch* event type values.

    case "touchstart": return 0x100000;
    case "touchmove": return 0x200000;
    case "touchcancel": return 0x400000;
    case "touchend": return 0x800000;

An alternative I experimented with was to override eventGetTypeInt with a non-native method, detect whether the native method returned an undefined value, which indicates no case statement matched, and use an extra switch statement to deal with the touch events. In my opinion the extra complexity wasn’t worth it, if GWT adds extra event types the overridden code will have to be investigated anyway to ensure the int values I’m using are still unique.

Next you need to look at the call to sinkEvents in Widget.addDomHandler. This is where the bit pattern returned from Event.getTypeInt is combined with the patterns from other events already being listened for by the widget to determine which event dispatch handlers should be registered. Tracing through the code leads to sinkEventsImpl in DOMImplStandard. This is the method that needs to be overridden in DOMImplMobileSafari. Each separate event has a corresponding if statement that checks whether the current call to sinkEventsImpl is targeting that event and if it is whether the dispatcher function should be added or removed.

    if (chMask & 0x00020) elem.onmouseout    = (bits & 0x00020) ?
        @com.google.gwt.user.client.impl.DOMImplStandard::dispatchEvent : null;

As with the eventGetTypeInt method I just copied the existing code and added new statements to the end for the touch* bit patterns, for instance

    if (chMask & 0x100000) elem.ontouchstart = (bits & 0x100000) ?
        @com.google.gwt.user.client.impl.DOMImplStandard::dispatchEvent : null;

With this change the solution is complete and the addTouchStartHandler presented earlier works correctly.