/*
 * 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.user.client.Timer;

/**
 * This class can be used to simulate the deceleration of an element within a
 * certain region. To use this behavior you need to provide a distance and time
 * that is meant to represent a gesture that is initiating this deceleration.
 * You also provide the bounds of the region that the element exists in, and the
 * current offset of the element within that region. This behavior will step
 * through all of the intermediate points necessary to decelerate the element
 * back to a velocity of zero. In doing so, the element may 'bounce' in and out
 * of the boundaries of the region, but will always come to rest within the
 * region.
 * 
 * This is primarily designed to solve the problem of slow scrolling in mobile
 * safari. You can use this along with the Scroller behavior
 * (wireless.fx.Scroller) to make a scrollable area scroll as well as it would
 * in a native application.
 * 
 * This class does not maintain any references to HTML elements, and therefore
 * cannot do any redrawing of elements. It only calculates where the element
 * should be on an interval. It is the delegate's responsibility to redraw the
 * element when the onDecelerate callback is invoked. It is recommended that you
 * move the element with a hardware accelerated method such as using
 * 'translate3d' on the element's -webkit-transform style property.
 */
class Momentum {

  /**
   * You are required to implement this interface in order to use the
   * {@link Momentum} behavior.
   */
  public interface Delegate {

    /**
     * Callback for a deceleration step. The delegate is responsible for redrawing
     * the element in its new position.
     *
     * @param floorX The new x offset
     * @param floorY The new y offset
     * @param velocity The current velocitiy
     */
    void onDecelerate(double floorX, double floorY, Point velocity);

    /**
     * Callback for end of deceleration.
     */
    void onDecelerationEnd();
  }

  /**
   * The constant factor applied to velocity at each frame to simulate
   * deceleration.
   */
  private static final double DECELERATION_FACTOR = 0.98;

  /**
   * The velocity threshold at which declereration will end.
   */
  private static final double DECELERATION_STOP_VELOCITY = 0.01;

  /**
   * The number of frames per second the animation should run at.
   */
  private static final double FRAMES_PER_SECOND = 60;

  /**
   * Boost the initial velocity by a certain factor before applying momentum.
   * This just gives the momentum a better feel.
   */
  private static final double INITIAL_VELOCITY_BOOST_FACTOR = 1.5;

  /**
   * Minimum velocity required to start deceleration.
   */
  private static final double MIN_START_VELOCITY = 0.3;

  /**
   * The number of milliseconds per animation frame.
   */
  private static final double MS_PER_FRAME = 1000 / FRAMES_PER_SECOND;

  /**
   * The spring coefficient for when the element is bouncing back from a
   * stretched offset to a min or max position. Each frame, the velocity will be
   * changed to x times this coefficient, where x is the current stretch value
   * of the element from its boundary. This will end when the stretch value
   * reaches 0.
   */
  private static final double POST_BOUNCE_COEFFICIENT = 9 / FRAMES_PER_SECOND;

  /**
   * The spring coefficient for when the element has passed a boundary and is
   * decelerating to change direction and bounce back. Each frame, the velocity
   * will be changed by x times this coefficient, where x is the current stretch
   * value of the element from its boundary. This will end when velocity reaches
   * zero.
   */
  private static final double PRE_BOUNCE_COEFFICIENT = 1.8 / FRAMES_PER_SECOND;

  /**
   * True when the momentum of has carried the position outside the allowable
   * range but before the velocity has changed directions.
   */
  private boolean bouncingX;

  /**
   * True when the momentum of has carried the position outside the allowable
   * range but before the velocity has changed directions.
   */
  private boolean bouncingY;

  /**
   * The current offset of the element. These x, y values can be decimal values.
   * It is necessary to store these values for the sake of precision.
   */
  private Point currentOffset;

  /**
   * Whether or not deceleration is currently in progress.
   */
  private boolean decelerating;

  private Delegate delegate;

  /**
   * The maximum boundary for the element.
   */
  private Point maxCoord;

  /**
   * The minimum boundary for the element.
   */
  private Point minCoord;

  /**
   * The previous offset of the element. These x, y values are whole numbers.
   * Their values are derived from rounding of the currentOffset_ member.
   */
  private Point previousOffset;

  /**
   * The start time of the deceleration.
   */
  private double startTime;

  private Timer stepFunction = new Timer() {
    @Override
    public void run() {
      step();
    }
  };

  /**
   * The step number of the deceleration.
   */
  private double stepNumber;

  /**
   * Current velocity of the element. In this class velocity is measured as
   * pixels per frame. That is, the number of pixels to move the element in the
   * next frame.
   */
  private Point velocity;

  /**
   * Creates a new Momentum object.
   * 
   * @param delegate The momentum delegate.
   */
  public Momentum(Delegate delegate) {
    this.delegate = delegate;
  }

  /**
   * Whether or not the element is currently bouncing. Bouncing is the behavior
   * of an element moving past an allowable boundary and decelerating to change
   * direction and snap back into place. Not to be confused with bouncing back.
   * 
   * @return True if the element is currently bouncing in either the x or y
   *         direction.
   */
  public boolean isBouncing() {
    return bouncingY || bouncingX;
  }

  /**
   * Start decelerating. Checks if the current velocity is above the minumum
   * threshold to start decelerating. If so then deceleration will begin, if not
   * then nothing happens.
   * 
   * @param velocity The initial velocity. The velocity passed here should be in
   *          terms of number of pixels / millisecond. initiating deceleration.
   * @param minCoord The content's scrollable boundary.
   * @param maxCoord The content's scrollable boundary.
   * @param initialOffset The current offset of the element within its
   *          boundaries.
   * @return True if deceleration has been initiated.
   */
  public boolean start(Point velocity, Point minCoord,
      Point maxCoord, Point initialOffset) {
    this.minCoord = minCoord;
    this.maxCoord = maxCoord;

    currentOffset = new Point(initialOffset);
    previousOffset = new Point(initialOffset);
    this.velocity = adjustInitialVelocity(velocity);

    if (isVelocityAboveThreshold(MIN_START_VELOCITY)) {
      decelerating = true;
      startTime = Duration.currentTimeMillis();
      stepNumber = 0;
      stepFunction.schedule((int) MS_PER_FRAME);
      return true;
    }

    return false;
  }

  /**
   * Stop decelerating.
   */
  public void stop() {
    decelerating = false;
    bouncingX = false;
    bouncingY = false;

    delegate.onDecelerationEnd();
  }

  /**
   * Helper method to calculate initial velocity.
   * 
   * @param velocity The initial velocity. The velocity passed here should be in
   *          terms of number of pixels / millisecond.
   * @return The adjusted x and y velocities.
   */
  private Point adjustInitialVelocity(Point velocity) {
    return new Point(adjustInitialVelocityForDirection(velocity.x,
        currentOffset.x, minCoord.x, maxCoord.x),
        adjustInitialVelocityForDirection(velocity.y, currentOffset.y,
            minCoord.y, maxCoord.y));
  }

  /**
   * Helper method to calculate the initial velocity for a specific direction.
   * 
   * @param originalVelocity The velocity we are adjusting.
   * @param offset The offset for this direction.
   * @param min The min coordinate for this direction.
   * @param max The max coordinate for this direction.
   * @return The calculated velocity.
   */
  private double adjustInitialVelocityForDirection(double originalVelocity,
      double offset, double min, double max) {
    // Convert from pixels/ms to pixels/frame
    double vel = originalVelocity * MS_PER_FRAME
        * INITIAL_VELOCITY_BOOST_FACTOR;

    // If the initial velocity is below the minimum threshold, it is possible
    // that we need to bounce back depending on where the element is.
    if (Math.abs(vel) < MIN_START_VELOCITY) {
      // If either of these cases are true, then the element is outside of its
      // allowable region and we need to apply a bounce back acceleration to
      // bring it back to rest in its defined area.
      if (offset < min) {
        vel = (min - offset) * POST_BOUNCE_COEFFICIENT;
        vel = Math.max(vel, MIN_START_VELOCITY);
      } else if (offset > max) {
        vel = (offset - max) * POST_BOUNCE_COEFFICIENT;
        vel = -Math.max(vel, MIN_START_VELOCITY);
      }
    }

    return vel;
  }

  /**
   * Decelerate the current velocity.
   */
  private void adjustVelocity() {
    adjustVelocityComponent(currentOffset.x, minCoord.x, maxCoord.x,
        velocity.x, bouncingX, false /* horizontal */
    );
    adjustVelocityComponent(currentOffset.y, minCoord.y, maxCoord.y,
        velocity.y, bouncingY, true /* vertical */
    );
  }

  /**
   * Apply deceleration to a specifc direction.
   * 
   * @param offset The offset for this direction.
   * @param min The min coordinate for this direction.
   * @param max The max coordinate for this direction.
   * @param velocity The velocity for this direction.
   * @param bouncing Whether this direction is bouncing.
   * @param vertical Whether or not the direction is vertical.
   */
  private void adjustVelocityComponent(double offset, double min, double max,
      double velocity, boolean bouncing, boolean vertical) {
    double speed = Math.abs(velocity);

    // Apply the deceleration factor several times as we get closer to stopping.
    int numTimes = speed < 15 ? (speed < 3 ? 3 : 2) : 1;
    velocity *= Math.pow(DECELERATION_FACTOR, numTimes);

    double stretchDistance = 0;

    // We make special adjustments to the velocity if the element is outside of
    // its region.
    if (offset < min) {
      stretchDistance = min - offset;
    } else if (offset > max) {
      stretchDistance = max - offset;
    }

    // If stretchDistance has a value then we are either bouncing or bouncing
    // back.
    if (stretchDistance != 0) {
      // If our adjustment is in the opposite direction of our velocity then we
      // are still trying to turn around. Else we are bouncing back.
      if (stretchDistance * velocity < 0) {
        bouncing = true;
        velocity += stretchDistance * PRE_BOUNCE_COEFFICIENT;
      } else {
        bouncing = false;
        velocity = stretchDistance * POST_BOUNCE_COEFFICIENT;
      }
    }

    if (vertical) {
      this.velocity.y = velocity;
      bouncingY = bouncing;
    } else {
      this.velocity.x = velocity;
      bouncingX = bouncing;
    }
  }

  /**
   * Checks whether or not an animation step is necessary or not. Animations
   * steps are not necessary when the velocity gets so low that in several
   * frames the offset is the same.
   * 
   * @return True if there is movement to be done in the next frame.
   */
  private boolean isStepNecessary() {
    return Math.abs(currentOffset.y + velocity.y - previousOffset.y) > 1
        || Math.abs(currentOffset.x + velocity.x - previousOffset.x) > 1;
  }

  /**
   * Whether or not the current velocity is above the threshold required to
   * continue decelerating. Once both the x and y velocity fall below the
   * threshold, the element should stop moving entirely.
   * 
   * @param threshold The threshold to measure against.
   * @return True if the x or y velocity is still above the threshold.
   */
  private boolean isVelocityAboveThreshold(double threshold) {
    return Math.abs(velocity.x) >= threshold
        || Math.abs(velocity.y) >= threshold;
  }

  /**
   * Calculate the next offset of the element and animate it to that position.
   */
  private void step() {
    // If deceleration is stopped between frames this is possible. Need to abort
    // the step if this happens.
    if (!decelerating) {
      return;
    }

    double now = Duration.currentTimeMillis();
    double framesExpected = Math.floor((now - startTime) / MS_PER_FRAME);

    // Do at least one step, and more if subsequent steps are not necessary or
    // if we are falling behind.
    do {
      stepWithoutAnimation();
    } while (isVelocityAboveThreshold(DECELERATION_STOP_VELOCITY)
        && (!isStepNecessary() || framesExpected > stepNumber));

    double floorY = currentOffset.y;
    double floorX = currentOffset.x;

    // If we have moved a whole integer then notify the delegate and update the
    // previous position.
    if (decelerating) {
      delegate.onDecelerate(floorX, floorY, velocity);
      previousOffset.y = floorY;
      previousOffset.x = floorX;
    }

    // This condition checks of deceleration is over.
    if (!isBouncing()
        && !isVelocityAboveThreshold(DECELERATION_STOP_VELOCITY)) {
      stop();
      return;
    }

    stepFunction.schedule((int) (MS_PER_FRAME * (1 + stepNumber - framesExpected)));
  }

  /**
   * Update the x, y values of the element offset without actually moving the
   * element. This is done because we store decimal values for x, y for
   * precision, but moving is only required when the offset is changed by at
   * least a whole integer.
   */
  private void stepWithoutAnimation() {
    stepNumber++;
    currentOffset.y += velocity.y;
    currentOffset.x += velocity.x;

    adjustVelocity();
  }
}