2.4/samples/expenses/src/main/java/com/google/gwt/mobile/client/TouchHandler.java

/*
 * Copyright 2010 Google Inc.
 * 
 * Licensed under the Apache License, Version 2.0 (the "License"); you may not
 * use this file except in compliance with the License. You may obtain a copy of
 * the License at
 * 
 * http://www.apache.org/licenses/LICENSE-2.0
 * 
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
 * License for the specific language governing permissions and limitations under
 * the License.
 */
package com.google.gwt.mobile.client;

import com.google.gwt.core.client.Duration;
import com.google.gwt.dom.client.Element;
import com.google.gwt.user.client.Event;
import com.google.gwt.user.client.EventListener;
import com.google.gwt.user.client.Timer;
import com.google.gwt.user.client.Window;

/**
 * Class that handles all touch events and uses them to interpret higher level
 * gestures and behaviors.
 * 
 * Examples of higher level gestures this class is intended to support - click,
 * double click, long click - dragging, swiping, zooming
 * 
 * Touch Behavior: Use this class to make your elements 'touchable' (see
 * touchable.js). Intended to work with all webkit browsers, tested only on
 * iPhone 3.x so far.
 * 
 * Drag Behavior: Use this class to make your elements 'draggable' (see
 * draggable.js). This behavior will handle all of the required events and
 * report the properties of the drag to you while the touch is happening and at
 * the end of the drag sequence. This behavior will NOT perform the actual
 * dragging (redrawing the element) for you, this responsibility is left to the
 * client code. This behavior contains a work around for a mobile safari but
 * where the 'touchend' event is not dispatched when the touch goes past the
 * bottom of the browser window. This is intended to work well in iframes.
 * Intended to work with all webkit browsers, tested only on iPhone 3.x so far.
 */
public class TouchHandler implements EventListener {

  /**
   * Delegate to receive drag events.
   */
  public interface DragDelegate {

    /**
     * The object's drag sequence is now complete.
     *
     * @param e The touchend event.
     */
    void onDragEnd(TouchEvent e);

    /**
     * The object has been dragged to a new position.
     *
     * @param e The touchmove event.
     */
    void onDragMove(TouchEvent e);

    /**
     * The object has started dragging.
     *
     * @param e The touchmove event.
     */
    void onDragStart(TouchEvent e);
  }

  /**
   * Delegate to receive touch events.
   */
  public interface TouchDelegate {

    /**
     * The object has received a touchend event.
     *
     * @param e The touchend event.
     */
    void onTouchEnd(TouchEvent e);

    /**
     * The object has received a touchstart event.
     *
     * @param e The touchstart event.
     * @return true if you want to allow a drag sequence to begin,
     *      false you want to disable dragging for the duration of this touch.
     */
    boolean onTouchStart(TouchEvent e);
  }

  /**
   * Whether or not the browser supports touches.
   */
  private static final boolean SUPPORTS_TOUCHES = supportsTouch();

  /**
   * Cancel event name.
   */
  private static final String CANCEL_EVENT = "touchcancel";

  /**
   * Threshold in pixels within which to bust clicks.
   */
  private static final int CLICK_BUST_THRESHOLD = 25;

  /**
   * End event name.
   */
  private static final String END_EVENT = SUPPORTS_TOUCHES ? "touchend"
      : "mouseup";

  /**
   * The number of ms to wait during a drag before updating the reported start
   * position of the drag.
   */
  private static final double MAX_TRACKING_TIME = 200;

  /**
   * Minimum movement of touch required to be considered a drag.
   */
  private static final double MIN_TRACKING_FOR_DRAG = 5;

  /**
   * Move event name.
   */
  private static final String MOVE_EVENT = SUPPORTS_TOUCHES ? "touchmove"
      : "mousemove";

  /**
   * Start event name.
   */
  private static final String START_EVENT = SUPPORTS_TOUCHES ? "touchstart"
      : "mousedown";

  /**
   * The threshold for when to start tracking whether a touch has left the
   * bottom of the browser window. Used to implement a workaround for a mobile
   * safari bug on the iPhone where a touchend event will never be fired if the
   * touch goes past the bottom of the window.
   */
  private static final double TOUCH_END_WORKAROUND_THRESHOLD = 20;

  /**
   * Get touch from event. Supports desktop events by returning the event that
   * is passed in as a parameter.
   * 
   * @param e the event
   * @return the touch object
   */
  public static Touch getTouchFromEvent(TouchEvent e) {
    if (SUPPORTS_TOUCHES) {
      return e.getOldTouchesUntilMyFriendFredSauerCleansUpTheSample().get(0);
    }

    // This is cheating a little bit, but it turns out that the Touch interface
    // overlays nicely on the regular NativeEvent interface.
    return e.cast();
  }

  /**
   * Determines whether the current platform supports touch events.
   * 
   * TODO(jgw): This should probably be implemented using deferred binding.
   */
  public static native boolean supportsTouch() /*-{
    // document.createTouch doesn't exist on Android, even though touch works.
    var android = navigator.userAgent.indexOf('Android') != -1;
    return android || !!('createTouch' in document);
  }-*/;

  /**
   * This would not be safe on all browsers, but none of the WebKit browsers
   * that actually support touch events have the kinds of memory leak problems
   * that this would trigger. And they all support event capture.
   */
  private static native void addEventListener(Element elem, String name,
      EventListener listener, boolean capture) /*-{
    elem.addEventListener(name, function(e) {
      listener.@com.google.gwt.user.client.EventListener::onBrowserEvent(Lcom/google/gwt/user/client/Event;)(e);
    }, capture);
  }-*/;

  private boolean bustNextClick;
  private DragDelegate dragDelegate;

  private Element element;

  /**
   * Start/end time of the touchstart event.
   */
  private double endTime;
  /**
   * The touch position of the last event before the touchend event.
   */
  private Point endTouchPosition;
  private TouchEvent lastEvent;

  private Point lastTouchPosition;

  /**
   * The time of the most recent relevant occurence. For most drag sequences
   * this will be the same as the startTime. If the touch gesture changes
   * direction significantly or pauses for a while this time will be updated to
   * the time of the last touchmove event.
   */
  private double recentTime;

  /**
   * The coordinate of the most recent relevant touch event. For most drag
   * sequences this will be the same as the startCoordinate. If the touch
   * gesture changes direction significantly or pauses for a while this
   * coordinate will be updated to the coordinate of the last touchmove event.
   */
  private Point recentTouchPosition;

  private Timer scrollOffTimer;

  private Point startTouchPosition;
  /**
   * The absolute sum of all touch x/y deltas.
   */
  private double totalMoveX, totalMoveY = 0;
  private TouchDelegate touchDelegate;
  private boolean touching, tracking, dragging;

  public TouchHandler(Element elem) {
    this.element = elem;
    this.totalMoveY = 0;
    this.totalMoveX = 0;
  }

  /**
   * Start listenting for events.
   */
  public void enable() {
    addEventListener(element, START_EVENT, this, false);
    addEventListener(element, MOVE_EVENT, this, false);
    addEventListener(element, CANCEL_EVENT, this, false);
    addEventListener(element, END_EVENT, this, false);

    // Capture click so we can properly bust it, no matter what order handlers
    // get fired in.
    addEventListener(element, "click", this, true);
  }

  /**
   * Get end velocity of the drag. This method is specific to drag behavior, so
   * if touch behavior and drag behavior is split then this should go with drag
   * behavior. End velocity is defined as deltaXY / deltaTime where deletaXY is
   * the difference between endPosition and recentPosition, and deltaTime is the
   * difference between endTime and recentTime.
   * 
   * @return The x and y velocity.
   */
  public Point getEndVelocity() {
    assert recentTouchPosition != null : "Recent position not set";
    assert endTouchPosition != null : "End position not set";

    double time = endTime - recentTime;
    return new Point(
        (endTouchPosition.x - recentTouchPosition.x) / time,
        (endTouchPosition.y - recentTouchPosition.y) / time);
  }

  /**
   * Is the touch manager currently tracking touch moves to detect a drag?
   * 
   * @return True if currently tracking.
   */
  public boolean isTracking() {
    return tracking;
  }

  public void onBrowserEvent(Event event) {
    TouchEvent e = event.cast();
    String type = e.getType();
    if (START_EVENT.equals(type)) {
      onStart(e);
    } else if (MOVE_EVENT.equals(type)) {
      onMove(e);
    } else if (END_EVENT.equals(type) || CANCEL_EVENT.equals(type)) {
      onEnd(e);
    } else if ("click".equals(type)) {
      if (bustNextClick) {
        event.stopPropagation();
        event.preventDefault();
        bustNextClick = false;
      }
    }
  }

  /**
   * Sets the delegate to receive drag events.
   */
  public void setDragDelegate(DragDelegate dragDelegate) {
    this.dragDelegate = dragDelegate;
  }

  /**
   * Sets the delegate to receive touch events.
   */
  public void setTouchDelegate(TouchDelegate touchDelegate) {
    this.touchDelegate = touchDelegate;
  }

  /**
   * Begin tracking the touchable element, it is eligible for dragging.
   */
  private void beginTracking() {
    tracking = true;
  }

  /**
   * Stop tracking the touchable element, it is no longer dragging.
   */
  private void endTracking() {
    tracking = false;
    dragging = false;
    totalMoveY = 0;
    totalMoveX = 0;
  }

  /**
   * Return the touch of the last event.
   * 
   * @return the touch.
   */
  private Touch getLastTouch() {
    assert lastEvent != null : "Last event not set";
    return getTouchFromEvent(lastEvent);
  }

  /**
   * Touch end handler.
   * 
   * @param e The touchend event.
   */
  private void onEnd(TouchEvent e) {
    touching = false;
    if (touchDelegate != null) {
      touchDelegate.onTouchEnd(e);
    }

    if (!tracking || dragDelegate == null) {
      return;
    }

    Touch touch = getLastTouch();
    Point touchCoordinate = new Point(touch.getPageX(),
        touch.getPageY());

    if (dragging) {
      endTime = e.getTimeStamp();
      endTouchPosition = touchCoordinate;
      dragDelegate.onDragEnd(e);

      if ((Math.abs(endTouchPosition.x - startTouchPosition.x) > CLICK_BUST_THRESHOLD)
          || (Math.abs(endTouchPosition.y - startTouchPosition.y) > CLICK_BUST_THRESHOLD)) {
        bustNextClick = true;
      }
    }

    endTracking();
  }

  /**
   * Touch move handler.
   * 
   * @param e The touchmove event.
   */
  private void onMove(final TouchEvent e) {
    if (!tracking || dragDelegate == null) {
      return;
    }

    // Prevent native scrolling.
    e.preventDefault();

    Touch touch = getTouchFromEvent(e);
    Point touchCoordinate = new Point(touch.getPageX(),
        touch.getPageY());

    double moveX = lastTouchPosition.x - touchCoordinate.x;
    double moveY = lastTouchPosition.y - touchCoordinate.y;
    totalMoveX += Math.abs(moveX);
    totalMoveY += Math.abs(moveY);
    lastTouchPosition.x = touchCoordinate.x;
    lastTouchPosition.y = touchCoordinate.y;

    // Handle case where they are getting close to leaving the window.
    // End events are unreliable when the touch is leaving the viewport area.
    // If they are close to the bottom or the right, and we don't get any other
    // touch events for another 100ms, assume they have left the screen. This
    // does not seem to be a problem for scrolling off the top or left of the
    // viewport area.
    if (scrollOffTimer != null) {
      scrollOffTimer.cancel();
    }
    if ((Window.getClientHeight() - touchCoordinate.y) < TOUCH_END_WORKAROUND_THRESHOLD
        || (Window.getClientWidth() - touchCoordinate.x) < TOUCH_END_WORKAROUND_THRESHOLD) {

      scrollOffTimer = new Timer() {
        @Override
        public void run() {
          e.setTimeStamp(Duration.currentTimeMillis());
          onEnd(e);
        }
      };
      scrollOffTimer.schedule(100);
    }

    if (!dragging) {
      if (totalMoveY > MIN_TRACKING_FOR_DRAG
          || totalMoveX > MIN_TRACKING_FOR_DRAG) {
        dragging = true;
        dragDelegate.onDragStart(e);
      }
    }

    if (dragging) {
      dragDelegate.onDragMove(e);

      lastEvent = e;

      // This happens when they are dragging slowly. If they are dragging slowly
      // then we should reset the start time and position to where they are now.
      // This will be important during the drag end when we report to the
      // draggable delegate what kind of drag just happened.
      if (e.getTimeStamp() - recentTime > MAX_TRACKING_TIME) {
        recentTime = e.getTimeStamp();
        recentTouchPosition = touchCoordinate;
      }
    }
  }

  /**
   * Touch start handler.
   * 
   * @param e The touchstart event.
   * @private
   */
  private void onStart(TouchEvent e) {
    // Ignore the touch if it is manufactured or if there is already a
    // touch happening.
    if (touching) {
      return;
    }

    touching = true;

    Touch touch = getTouchFromEvent(e);
    Point touchCoordinate = new Point(touch.getPageX(),
        touch.getPageY());

    // Do not start tracking if...
    // - we already are tracking
    // - the touchable delegate refuses to accept the start event at this time
    // - there is no draggable delegate
    if ((dragDelegate == null) ||
        ((touchDelegate != null) && !touchDelegate.onTouchStart(e))) {
      return;
    }

    startTouchPosition = touchCoordinate;
    recentTouchPosition = touchCoordinate;
    recentTime = e.getTimeStamp();
    lastEvent = e;
    lastTouchPosition = new Point(touchCoordinate);

    beginTracking();
  }
}