/* * Copyright (C) 2010 The Android Open Source Project * * 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 android.animation; import android.view.View; import android.view.ViewGroup; import android.view.ViewTreeObserver; import android.view.animation.AccelerateDecelerateInterpolator; import android.view.animation.DecelerateInterpolator; import java.util.ArrayList; import java.util.HashMap; import java.util.List; /** * This class enables automatic animations on layout changes in ViewGroup objects. To enable * transitions for a layout container, create a LayoutTransition object and set it on any * ViewGroup by calling {@link ViewGroup#setLayoutTransition(LayoutTransition)}. This will cause * default animations to run whenever items are added to or removed from that container. To specify * custom animations, use the {@link LayoutTransition#setAnimator(int, Animator) * setAnimator()} method. * *
One of the core concepts of these transition animations is that there are two core * changes that cause the transition and four different animations that run because of * those changes. The changes that trigger the transition are items being added to a container * (referred to as an "appearing" transition) or removed from a container (also known as * "disappearing"). The animations that run due to those events are one that animates * items being added, one that animates items being removed, and two that animate the other * items in the container that change due to the add/remove occurrence. Users of * the transition may want different animations for the changing items depending on whether * they are changing due to anappearing or disappearing event, so there is one animation for * each of these variations of the changing event. Most of the API of this class is concerned * with setting up the basic properties of the animations used in these four situations, * or with setting up custom animations for any or all of the four.
* *The animations specified for the transition, both the defaults and any custom animations
* set on the transition object, are templates only. That is, these animations exist to hold the
* basic animation properties, such as the duration, start delay, and properties being animated.
* But the actual target object, as well as the start and end values for those properties, are
* set automatically in the process of setting up the transition each time it runs. Each of the
* animations is cloned from the original copy and the clone is then populated with the dynamic
* values of the target being animated (such as one of the items in a layout container that is
* moving as a result of the layout event) as well as the values that are changing (such as the
* position and size of that object). The actual values that are pushed to each animation
* depends on what properties are specified for the animation. For example, the default
* CHANGE_APPEARING animation animates left
, top
, right
,
* and bottom
. Values for these properties are updated with the pre- and post-layout
* values when the transition begins. Custom animations will be similarly populated with
* the target and values being animated, assuming they use ObjectAnimator objects with
* property names that are known on the target object.
transitionType
parameter determines the animation whose start delay
* is being set.
*
* @param transitionType one of {@link #CHANGE_APPEARING}, {@link #CHANGE_DISAPPEARING},
* {@link #APPEARING}, or {@link #DISAPPEARING}, which determines the animation whose start
* delay is being set.
* @param delay The length of time, in milliseconds, to delay before starting the animation.
* @see Animator#setStartDelay(long)
*/
public void setStartDelay(int transitionType, long delay) {
switch (transitionType) {
case CHANGE_APPEARING:
mChangingAppearingDelay = delay;
break;
case CHANGE_DISAPPEARING:
mChangingDisappearingDelay = delay;
break;
case APPEARING:
mAppearingDelay = delay;
break;
case DISAPPEARING:
mDisappearingDelay = delay;
break;
}
}
/**
* Gets the start delay on one of the animation objects used by this transition. The
* transitionType
parameter determines the animation whose start delay
* is returned.
*
* @param transitionType one of {@link #CHANGE_APPEARING}, {@link #CHANGE_DISAPPEARING},
* {@link #APPEARING}, or {@link #DISAPPEARING}, which determines the animation whose start
* delay is returned.
* @return long The start delay of the specified animation.
* @see Animator#getStartDelay()
*/
public long getStartDelay(int transitionType) {
switch (transitionType) {
case CHANGE_APPEARING:
return mChangingAppearingDuration;
case CHANGE_DISAPPEARING:
return mChangingDisappearingDuration;
case APPEARING:
return mAppearingDuration;
case DISAPPEARING:
return mDisappearingDuration;
}
// shouldn't reach here
return 0;
}
/**
* Sets the duration on one of the animation objects used by this transition. The
* transitionType
parameter determines the animation whose duration
* is being set.
*
* @param transitionType one of {@link #CHANGE_APPEARING}, {@link #CHANGE_DISAPPEARING},
* {@link #APPEARING}, or {@link #DISAPPEARING}, which determines the animation whose
* duration is being set.
* @param duration The length of time, in milliseconds, that the specified animation should run.
* @see Animator#setDuration(long)
*/
public void setDuration(int transitionType, long duration) {
switch (transitionType) {
case CHANGE_APPEARING:
mChangingAppearingDuration = duration;
break;
case CHANGE_DISAPPEARING:
mChangingDisappearingDuration = duration;
break;
case APPEARING:
mAppearingDuration = duration;
break;
case DISAPPEARING:
mDisappearingDuration = duration;
break;
}
}
/**
* Gets the duration on one of the animation objects used by this transition. The
* transitionType
parameter determines the animation whose duration
* is returned.
*
* @param transitionType one of {@link #CHANGE_APPEARING}, {@link #CHANGE_DISAPPEARING},
* {@link #APPEARING}, or {@link #DISAPPEARING}, which determines the animation whose
* duration is returned.
* @return long The duration of the specified animation.
* @see Animator#getDuration()
*/
public long getDuration(int transitionType) {
switch (transitionType) {
case CHANGE_APPEARING:
return mChangingAppearingDuration;
case CHANGE_DISAPPEARING:
return mChangingDisappearingDuration;
case APPEARING:
return mAppearingDuration;
case DISAPPEARING:
return mDisappearingDuration;
}
// shouldn't reach here
return 0;
}
/**
* Sets the length of time to delay between starting each animation during one of the
* CHANGE animations.
*
* @param transitionType A value of {@link #CHANGE_APPEARING} or @link #CHANGE_DISAPPEARING}.
* @param duration The length of time, in milliseconds, to delay before launching the next
* animation in the sequence.
*/
public void setStagger(int transitionType, long duration) {
switch (transitionType) {
case CHANGE_APPEARING:
mChangingAppearingStagger = duration;
break;
case CHANGE_DISAPPEARING:
mChangingDisappearingStagger = duration;
break;
// noop other cases
}
}
/**
* Tets the length of time to delay between starting each animation during one of the
* CHANGE animations.
*
* @param transitionType A value of {@link #CHANGE_APPEARING} or @link #CHANGE_DISAPPEARING}.
* @return long The length of time, in milliseconds, to delay before launching the next
* animation in the sequence.
*/
public long getStagger(int transitionType) {
switch (transitionType) {
case CHANGE_APPEARING:
return mChangingAppearingStagger;
case CHANGE_DISAPPEARING:
return mChangingDisappearingStagger;
}
// shouldn't reach here
return 0;
}
/**
* Sets the interpolator on one of the animation objects used by this transition. The
* transitionType
parameter determines the animation whose interpolator
* is being set.
*
* @param transitionType one of {@link #CHANGE_APPEARING}, {@link #CHANGE_DISAPPEARING},
* {@link #APPEARING}, or {@link #DISAPPEARING}, which determines the animation whose
* duration is being set.
* @param interpolator The interpolator that the specified animation should use.
* @see Animator#setInterpolator(TimeInterpolator)
*/
public void setInterpolator(int transitionType, TimeInterpolator interpolator) {
switch (transitionType) {
case CHANGE_APPEARING:
mChangingAppearingInterpolator = interpolator;
break;
case CHANGE_DISAPPEARING:
mChangingDisappearingInterpolator = interpolator;
break;
case APPEARING:
mAppearingInterpolator = interpolator;
break;
case DISAPPEARING:
mDisappearingInterpolator = interpolator;
break;
}
}
/**
* Gets the interpolator on one of the animation objects used by this transition. The
* transitionType
parameter determines the animation whose interpolator
* is returned.
*
* @param transitionType one of {@link #CHANGE_APPEARING}, {@link #CHANGE_DISAPPEARING},
* {@link #APPEARING}, or {@link #DISAPPEARING}, which determines the animation whose
* duration is being set.
* @return TimeInterpolator The interpolator that the specified animation uses.
* @see Animator#setInterpolator(TimeInterpolator)
*/
public TimeInterpolator getInterpolator(int transitionType) {
switch (transitionType) {
case CHANGE_APPEARING:
return mChangingAppearingInterpolator;
case CHANGE_DISAPPEARING:
return mChangingDisappearingInterpolator;
case APPEARING:
return mAppearingInterpolator;
case DISAPPEARING:
return mDisappearingInterpolator;
}
// shouldn't reach here
return null;
}
/**
* Sets the animation used during one of the transition types that may run. Any
* Animator object can be used, but to be most useful in the context of layout
* transitions, the animation should either be a ObjectAnimator or a AnimatorSet
* of animations including PropertyAnimators. Also, these ObjectAnimator objects
* should be able to get and set values on their target objects automatically. For
* example, a ObjectAnimator that animates the property "left" is able to set and get the
* left
property from the View objects being animated by the layout
* transition. The transition works by setting target objects and properties
* dynamically, according to the pre- and post-layoout values of those objects, so
* having animations that can handle those properties appropriately will work best
* for custom animation. The dynamic setting of values is only the case for the
* CHANGE animations; the APPEARING and DISAPPEARING animations are simply run with
* the values they have.
*
* It is also worth noting that any and all animations (and their underlying * PropertyValuesHolder objects) will have their start and end values set according * to the pre- and post-layout values. So, for example, a custom animation on "alpha" * as the CHANGE_APPEARING animation will inherit the real value of alpha on the target * object (presumably 1) as its starting and ending value when the animation begins. * Animations which need to use values at the beginning and end that may not match the * values queried when the transition begins may need to use a different mechanism * than a standard ObjectAnimator object.
* * @param transitionType one of {@link #CHANGE_APPEARING}, {@link #CHANGE_DISAPPEARING}, * {@link #APPEARING}, or {@link #DISAPPEARING}, which determines the animation whose * duration is being set. * @param animator The animation being assigned. A value ofnull
means that no
* animation will be run for the specified transitionType.
*/
public void setAnimator(int transitionType, Animator animator) {
switch (transitionType) {
case CHANGE_APPEARING:
mChangingAppearingAnim = animator;
break;
case CHANGE_DISAPPEARING:
mChangingDisappearingAnim = animator;
break;
case APPEARING:
mAppearingAnim = animator;
break;
case DISAPPEARING:
mDisappearingAnim = animator;
break;
}
}
/**
* Gets the animation used during one of the transition types that may run.
*
* @param transitionType one of {@link #CHANGE_APPEARING}, {@link #CHANGE_DISAPPEARING},
* {@link #APPEARING}, or {@link #DISAPPEARING}, which determines the animation whose
* duration is being set.
* @return Animator The animation being used for the given transition type.
* @see #setAnimator(int, Animator)
*/
public Animator getAnimator(int transitionType) {
switch (transitionType) {
case CHANGE_APPEARING:
return mChangingAppearingAnim;
case CHANGE_DISAPPEARING:
return mChangingDisappearingAnim;
case APPEARING:
return mAppearingAnim;
case DISAPPEARING:
return mDisappearingAnim;
}
// shouldn't reach here
return null;
}
/**
* This function sets up runs animations on all of the views that change during layout.
* For every child in the parent, we create a change animation of the appropriate
* type (appearing or disappearing) and ask it to populate its start values from its
* target view. We add layout listeners to all child views and listen for changes. For
* those views that change, we populate the end values for those animations and start them.
* Animations are not run on unchanging views.
*
* @param parent The container which is undergoing an appearing or disappearing change.
* @param newView The view being added to or removed from the parent.
* @param changeReason A value of APPEARING or DISAPPEARING, indicating whether the
* transition is occuring because an item is being added to or removed from the parent.
*/
private void runChangeTransition(final ViewGroup parent, View newView, final int changeReason) {
Animator baseAnimator = (changeReason == APPEARING) ?
mChangingAppearingAnim : mChangingDisappearingAnim;
// If the animation is null, there's nothing to do
if (baseAnimator == null) {
return;
}
// reset the inter-animation delay, in case we use it later
staggerDelay = 0;
final ViewTreeObserver observer = parent.getViewTreeObserver(); // used for later cleanup
if (!observer.isAlive()) {
// If the observer's not in a good state, skip the transition
return;
}
int numChildren = parent.getChildCount();
for (int i = 0; i < numChildren; ++i) {
final View child = parent.getChildAt(i);
// only animate the views not being added or removed
if (child != newView) {
// If there's an animation running on this view already, cancel it
Animator currentAnimation = currentChangingAnimations.get(child);
if (currentAnimation != null) {
currentAnimation.cancel();
currentChangingAnimations.remove(child);
}
// Make a copy of the appropriate animation
final Animator anim = baseAnimator.clone();
// Cache the animation in case we need to cancel it later
currentChangingAnimations.put(child, anim);
// Set the target object for the animation
anim.setTarget(child);
// A ObjectAnimator (or AnimatorSet of them) can extract start values from
// its target object
anim.setupStartValues();
// Add a listener to track layout changes on this view. If we don't get a callback,
// then there's nothing to animate.
final View.OnLayoutChangeListener listener = new View.OnLayoutChangeListener() {
public void onLayoutChange(View v, int left, int top, int right, int bottom,
int oldLeft, int oldTop, int oldRight, int oldBottom) {
// Tell the animation to extract end values from the changed object
anim.setupEndValues();
long startDelay;
long duration;
if (changeReason == APPEARING) {
startDelay = mChangingAppearingDelay + staggerDelay;
staggerDelay += mChangingAppearingStagger;
duration = mChangingAppearingDuration;
} else {
startDelay = mChangingDisappearingDelay + staggerDelay;
staggerDelay += mChangingDisappearingStagger;
duration = mChangingDisappearingDuration;
}
anim.setStartDelay(startDelay);
anim.setDuration(duration);
if (anim instanceof ObjectAnimator) {
((ObjectAnimator) anim).setCurrentPlayTime(0);
}
anim.start();
// this only removes listeners whose views changed - must clear the
// other listeners later
child.removeOnLayoutChangeListener(this);
layoutChangeListenerMap.remove(child);
}
};
// Remove the animation from the cache when it ends
anim.addListener(new AnimatorListenerAdapter() {
private boolean canceled = false;
public void onAnimationCancel(Animator animator) {
// we remove canceled animations immediately, not here
canceled = true;
child.removeOnLayoutChangeListener(listener);
layoutChangeListenerMap.remove(child);
}
public void onAnimationEnd(Animator animator) {
if (!canceled) {
currentChangingAnimations.remove(child);
}
}
});
child.addOnLayoutChangeListener(listener);
// cache the listener for later removal
layoutChangeListenerMap.put(child, listener);
}
}
// This is the cleanup step. When we get this rendering event, we know that all of
// the appropriate animations have been set up and run. Now we can clear out the
// layout listeners.
observer.addOnPreDrawListener(new ViewTreeObserver.OnPreDrawListener() {
public boolean onPreDraw() {
parent.getViewTreeObserver().removeOnPreDrawListener(this);
int numChildren = parent.getChildCount();
for (int i = 0; i < numChildren; ++i) {
final View child = parent.getChildAt(i);
child.removeOnLayoutChangeListener(layoutChangeListenerMap.get(child));
}
layoutChangeListenerMap.clear();
return true;
}
});
}
/**
* This method runs the animation that makes an added item appear.
*
* @param parent The ViewGroup to which the View is being added.
* @param child The View being added to the ViewGroup.
*/
private void runAppearingTransition(final ViewGroup parent, final View child) {
Animator currentAnimation = currentVisibilityAnimations.get(child);
if (currentAnimation != null) {
currentAnimation.cancel();
}
if (mAppearingAnim == null) {
if (mListeners != null) {
for (TransitionListener listener : mListeners) {
listener.endTransition(LayoutTransition.this, parent, child, APPEARING);
}
}
return;
}
Animator anim = mAppearingAnim.clone();
anim.setTarget(child);
anim.setStartDelay(mAppearingDelay);
anim.setDuration(mAppearingDuration);
if (anim instanceof ObjectAnimator) {
((ObjectAnimator) anim).setCurrentPlayTime(0);
}
if (mListeners != null) {
anim.addListener(new AnimatorListenerAdapter() {
public void onAnimationEnd() {
currentVisibilityAnimations.remove(child);
for (TransitionListener listener : mListeners) {
listener.endTransition(LayoutTransition.this, parent, child, APPEARING);
}
}
});
}
currentVisibilityAnimations.put(child, anim);
anim.start();
}
/**
* This method runs the animation that makes a removed item disappear.
*
* @param parent The ViewGroup from which the View is being removed.
* @param child The View being removed from the ViewGroup.
*/
private void runDisappearingTransition(final ViewGroup parent, final View child) {
Animator currentAnimation = currentVisibilityAnimations.get(child);
if (currentAnimation != null) {
currentAnimation.cancel();
}
if (mDisappearingAnim == null) {
if (mListeners != null) {
for (TransitionListener listener : mListeners) {
listener.endTransition(LayoutTransition.this, parent, child, DISAPPEARING);
}
}
return;
}
Animator anim = mDisappearingAnim.clone();
anim.setStartDelay(mDisappearingDelay);
anim.setDuration(mDisappearingDuration);
anim.setTarget(child);
if (mListeners != null) {
anim.addListener(new AnimatorListenerAdapter() {
@Override
public void onAnimationEnd(Animator anim) {
currentVisibilityAnimations.remove(child);
for (TransitionListener listener : mListeners) {
listener.endTransition(LayoutTransition.this, parent, child, DISAPPEARING);
}
}
});
}
if (anim instanceof ObjectAnimator) {
((ObjectAnimator) anim).setCurrentPlayTime(0);
}
currentVisibilityAnimations.put(child, anim);
anim.start();
}
/**
* This method is called by ViewGroup when a child view is about to be added to the
* container. This callback starts the process of a transition; we grab the starting
* values, listen for changes to all of the children of the container, and start appropriate
* animations.
*
* @param parent The ViewGroup to which the View is being added.
* @param child The View being added to the ViewGroup.
*/
public void addChild(ViewGroup parent, View child) {
if (mListeners != null) {
for (TransitionListener listener : mListeners) {
listener.startTransition(this, parent, child, APPEARING);
}
}
runChangeTransition(parent, child, APPEARING);
runAppearingTransition(parent, child);
}
/**
* This method is called by ViewGroup when a child view is about to be added to the
* container. This callback starts the process of a transition; we grab the starting
* values, listen for changes to all of the children of the container, and start appropriate
* animations.
*
* @param parent The ViewGroup to which the View is being added.
* @param child The View being added to the ViewGroup.
*/
public void showChild(ViewGroup parent, View child) {
addChild(parent, child);
}
/**
* This method is called by ViewGroup when a child view is about to be removed from the
* container. This callback starts the process of a transition; we grab the starting
* values, listen for changes to all of the children of the container, and start appropriate
* animations.
*
* @param parent The ViewGroup from which the View is being removed.
* @param child The View being removed from the ViewGroup.
*/
public void removeChild(ViewGroup parent, View child) {
if (mListeners != null) {
for (TransitionListener listener : mListeners) {
listener.startTransition(this, parent, child, DISAPPEARING);
}
}
runChangeTransition(parent, child, DISAPPEARING);
runDisappearingTransition(parent, child);
}
/**
* This method is called by ViewGroup when a child view is about to be removed from the
* container. This callback starts the process of a transition; we grab the starting
* values, listen for changes to all of the children of the container, and start appropriate
* animations.
*
* @param parent The ViewGroup from which the View is being removed.
* @param child The View being removed from the ViewGroup.
*/
public void hideChild(ViewGroup parent, View child) {
removeChild(parent, child);
}
/**
* Add a listener that will be called when the bounds of the view change due to
* layout processing.
*
* @param listener The listener that will be called when layout bounds change.
*/
public void addTransitionListener(TransitionListener listener) {
if (mListeners == null) {
mListeners = new ArrayList