/*
 * Copyright 2011 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.animation.client;

import com.google.gwt.dom.client.Element;

/**
 * This class provides task scheduling for animations. Any exceptions thrown by
 * the command objects executed by the scheduler will be passed to the
 * {@link com.google.gwt.core.client.GWT.UncaughtExceptionHandler} if one is
 * installed.
 */
public abstract class AnimationScheduler {

  /**
   * The callback used when an animation frame becomes available.
   */
  public interface AnimationCallback {
    /**
     * Invokes the command.
     * 
     * @param timestamp the current timestamp
     */
    void execute(double timestamp);
  }

  /**
   * A handle to the requested animation frame created by
   * {@link #requestAnimationFrame(AnimationCallback, Element)}.
   */
  public abstract static class AnimationHandle {
    /**
     * Cancel the requested animation frame. If the animation frame is already
     * canceled, do nothing.
     */
    public abstract void cancel();
  }

  /**
   * Returns the default implementation of the AnimationScheduler API.
   */
  public static AnimationScheduler get() {
    return AnimationSchedulerImpl.INSTANCE;
  }

  /**
   * Schedule an animation, letting the browser decide when to trigger the next
   * step in the animation.
   * 
   * <p>
   * NOTE: If you are animating an element, use
   * {@link #requestAnimationFrame(AnimationCallback, Element)} instead so the
   * browser can optimize for the specified element.
   * </p>
   * 
   * <p>
   * Using this method instead of a timeout is preferred because the browser is
   * in the best position to decide how frequently to trigger the callback for
   * an animation of the specified element. The browser can balance multiple
   * animations and trigger callbacks at the optimal rate for smooth
   * performance.
   * </p>
   * 
   * @param callback the callback to fire
   * @return a handle to the requested animation frame
   * @see #requestAnimationFrame(AnimationCallback, Element)
   */
  public AnimationHandle requestAnimationFrame(AnimationCallback callback) {
    return requestAnimationFrame(callback, null);
  }

  /**
   * Schedule an animation, letting the browser decide when to trigger the next
   * step in the animation.
   * 
   * <p>
   * Using this method instead of a timeout is preferred because the browser is
   * in the best position to decide how frequently to trigger the callback for
   * an animation of the specified element. The browser can balance multiple
   * animations and trigger callbacks at the optimal rate for smooth
   * performance.
   * </p>
   * 
   * @param callback the callback to fire
   * @return a handle to the requested animation frame
   * @param element the element being animated
   */
  public abstract AnimationHandle requestAnimationFrame(AnimationCallback callback, Element element);
}