com.google.gwt.animation.client.AnimationScheduler.java Source code

Introduction

Here is the source code for com.google.gwt.animation.client.AnimationScheduler.java

Source

/*
 * 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);
}