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