ViewPropertyAnimator.java revision a0b13bddb282b6b177c7756dcc8ff006eb8fc971
1/*
2 * Copyright (C) 2011 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 *      http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17package android.view;
18
19import android.animation.Animator;
20import android.animation.ValueAnimator;
21import android.animation.TimeInterpolator;
22import android.os.Build;
23
24import java.util.ArrayList;
25import java.util.HashMap;
26import java.util.Set;
27
28/**
29 * This class enables automatic and optimized animation of select properties on View objects.
30 * If only one or two properties on a View object are being animated, then using an
31 * {@link android.animation.ObjectAnimator} is fine; the property setters called by ObjectAnimator
32 * are well equipped to do the right thing to set the property and invalidate the view
33 * appropriately. But if several properties are animated simultaneously, or if you just want a
34 * more convenient syntax to animate a specific property, then ViewPropertyAnimator might be
35 * more well-suited to the task.
36 *
37 * <p>This class may provide better performance for several simultaneous animations, because
38 * it will optimize invalidate calls to take place only once for several properties instead of each
39 * animated property independently causing its own invalidation. Also, the syntax of using this
40 * class could be easier to use because the caller need only tell the View object which
41 * property to animate, and the value to animate either to or by, and this class handles the
42 * details of configuring the underlying Animator class and starting it.</p>
43 *
44 * <p>This class is not constructed by the caller, but rather by the View whose properties
45 * it will animate. Calls to {@link android.view.View#animate()} will return a reference
46 * to the appropriate ViewPropertyAnimator object for that View.</p>
47 *
48 */
49public class ViewPropertyAnimator {
50
51    /**
52     * The View whose properties are being animated by this class. This is set at
53     * construction time.
54     */
55    final View mView;
56
57    /**
58     * The duration of the underlying Animator object. By default, we don't set the duration
59     * on the Animator and just use its default duration. If the duration is ever set on this
60     * Animator, then we use the duration that it was set to.
61     */
62    private long mDuration;
63
64    /**
65     * A flag indicating whether the duration has been set on this object. If not, we don't set
66     * the duration on the underlying Animator, but instead just use its default duration.
67     */
68    private boolean mDurationSet = false;
69
70    /**
71     * The startDelay of the underlying Animator object. By default, we don't set the startDelay
72     * on the Animator and just use its default startDelay. If the startDelay is ever set on this
73     * Animator, then we use the startDelay that it was set to.
74     */
75    private long mStartDelay = 0;
76
77    /**
78     * A flag indicating whether the startDelay has been set on this object. If not, we don't set
79     * the startDelay on the underlying Animator, but instead just use its default startDelay.
80     */
81    private boolean mStartDelaySet = false;
82
83    /**
84     * The interpolator of the underlying Animator object. By default, we don't set the interpolator
85     * on the Animator and just use its default interpolator. If the interpolator is ever set on
86     * this Animator, then we use the interpolator that it was set to.
87     */
88    private TimeInterpolator mInterpolator;
89
90    /**
91     * A flag indicating whether the interpolator has been set on this object. If not, we don't set
92     * the interpolator on the underlying Animator, but instead just use its default interpolator.
93     */
94    private boolean mInterpolatorSet = false;
95
96    /**
97     * Listener for the lifecycle events of the underlying ValueAnimator object.
98     */
99    private Animator.AnimatorListener mListener = null;
100
101    /**
102     * Listener for the update events of the underlying ValueAnimator object.
103     */
104    private ValueAnimator.AnimatorUpdateListener mUpdateListener = null;
105
106    /**
107     * A lazily-created ValueAnimator used in order to get some default animator properties
108     * (duration, start delay, interpolator, etc.).
109     */
110    private ValueAnimator mTempValueAnimator;
111
112    /**
113     * A RenderThread-driven backend that may intercept startAnimation
114     */
115    private ViewPropertyAnimatorRT mRTBackend;
116
117    /**
118     * This listener is the mechanism by which the underlying Animator causes changes to the
119     * properties currently being animated, as well as the cleanup after an animation is
120     * complete.
121     */
122    private AnimatorEventListener mAnimatorEventListener = new AnimatorEventListener();
123
124    /**
125     * This list holds the properties that have been asked to animate. We allow the caller to
126     * request several animations prior to actually starting the underlying animator. This
127     * enables us to run one single animator to handle several properties in parallel. Each
128     * property is tossed onto the pending list until the animation actually starts (which is
129     * done by posting it onto mView), at which time the pending list is cleared and the properties
130     * on that list are added to the list of properties associated with that animator.
131     */
132    ArrayList<NameValuesHolder> mPendingAnimations = new ArrayList<NameValuesHolder>();
133    private Runnable mPendingSetupAction;
134    private Runnable mPendingCleanupAction;
135    private Runnable mPendingOnStartAction;
136    private Runnable mPendingOnEndAction;
137
138    /**
139     * Constants used to associate a property being requested and the mechanism used to set
140     * the property (this class calls directly into View to set the properties in question).
141     */
142    static final int NONE           = 0x0000;
143    static final int TRANSLATION_X  = 0x0001;
144    static final int TRANSLATION_Y  = 0x0002;
145    static final int TRANSLATION_Z  = 0x0004;
146    static final int SCALE_X        = 0x0008;
147    static final int SCALE_Y        = 0x0010;
148    static final int ROTATION       = 0x0020;
149    static final int ROTATION_X     = 0x0040;
150    static final int ROTATION_Y     = 0x0080;
151    static final int X              = 0x0100;
152    static final int Y              = 0x0200;
153    static final int Z              = 0x0400;
154    static final int ALPHA          = 0x0800;
155
156    private static final int TRANSFORM_MASK = TRANSLATION_X | TRANSLATION_Y | TRANSLATION_Z |
157            SCALE_X | SCALE_Y | ROTATION | ROTATION_X | ROTATION_Y | X | Y | Z;
158
159    /**
160     * The mechanism by which the user can request several properties that are then animated
161     * together works by posting this Runnable to start the underlying Animator. Every time
162     * a property animation is requested, we cancel any previous postings of the Runnable
163     * and re-post it. This means that we will only ever run the Runnable (and thus start the
164     * underlying animator) after the caller is done setting the properties that should be
165     * animated together.
166     */
167    private Runnable mAnimationStarter = new Runnable() {
168        @Override
169        public void run() {
170            startAnimation();
171        }
172    };
173
174    /**
175     * This class holds information about the overall animation being run on the set of
176     * properties. The mask describes which properties are being animated and the
177     * values holder is the list of all property/value objects.
178     */
179    private static class PropertyBundle {
180        int mPropertyMask;
181        ArrayList<NameValuesHolder> mNameValuesHolder;
182
183        PropertyBundle(int propertyMask, ArrayList<NameValuesHolder> nameValuesHolder) {
184            mPropertyMask = propertyMask;
185            mNameValuesHolder = nameValuesHolder;
186        }
187
188        /**
189         * Removes the given property from being animated as a part of this
190         * PropertyBundle. If the property was a part of this bundle, it returns
191         * true to indicate that it was, in fact, canceled. This is an indication
192         * to the caller that a cancellation actually occurred.
193         *
194         * @param propertyConstant The property whose cancellation is requested.
195         * @return true if the given property is a part of this bundle and if it
196         * has therefore been canceled.
197         */
198        boolean cancel(int propertyConstant) {
199            if ((mPropertyMask & propertyConstant) != 0 && mNameValuesHolder != null) {
200                int count = mNameValuesHolder.size();
201                for (int i = 0; i < count; ++i) {
202                    NameValuesHolder nameValuesHolder = mNameValuesHolder.get(i);
203                    if (nameValuesHolder.mNameConstant == propertyConstant) {
204                        mNameValuesHolder.remove(i);
205                        mPropertyMask &= ~propertyConstant;
206                        return true;
207                    }
208                }
209            }
210            return false;
211        }
212    }
213
214    /**
215     * This list tracks the list of properties being animated by any particular animator.
216     * In most situations, there would only ever be one animator running at a time. But it is
217     * possible to request some properties to animate together, then while those properties
218     * are animating, to request some other properties to animate together. The way that
219     * works is by having this map associate the group of properties being animated with the
220     * animator handling the animation. On every update event for an Animator, we ask the
221     * map for the associated properties and set them accordingly.
222     */
223    private HashMap<Animator, PropertyBundle> mAnimatorMap =
224            new HashMap<Animator, PropertyBundle>();
225    private HashMap<Animator, Runnable> mAnimatorSetupMap;
226    private HashMap<Animator, Runnable> mAnimatorCleanupMap;
227    private HashMap<Animator, Runnable> mAnimatorOnStartMap;
228    private HashMap<Animator, Runnable> mAnimatorOnEndMap;
229
230    /**
231     * This is the information we need to set each property during the animation.
232     * mNameConstant is used to set the appropriate field in View, and the from/delta
233     * values are used to calculate the animated value for a given animation fraction
234     * during the animation.
235     */
236    static class NameValuesHolder {
237        int mNameConstant;
238        float mFromValue;
239        float mDeltaValue;
240        NameValuesHolder(int nameConstant, float fromValue, float deltaValue) {
241            mNameConstant = nameConstant;
242            mFromValue = fromValue;
243            mDeltaValue = deltaValue;
244        }
245    }
246
247    /**
248     * Constructor, called by View. This is private by design, as the user should only
249     * get a ViewPropertyAnimator by calling View.animate().
250     *
251     * @param view The View associated with this ViewPropertyAnimator
252     */
253    ViewPropertyAnimator(View view) {
254        mView = view;
255        view.ensureTransformationInfo();
256        if (view.getContext().getApplicationInfo().targetSdkVersion >= Build.VERSION_CODES.L) {
257            mRTBackend = new ViewPropertyAnimatorRT(view);
258        }
259    }
260
261    /**
262     * Sets the duration for the underlying animator that animates the requested properties.
263     * By default, the animator uses the default value for ValueAnimator. Calling this method
264     * will cause the declared value to be used instead.
265     * @param duration The length of ensuing property animations, in milliseconds. The value
266     * cannot be negative.
267     * @return This object, allowing calls to methods in this class to be chained.
268     */
269    public ViewPropertyAnimator setDuration(long duration) {
270        if (duration < 0) {
271            throw new IllegalArgumentException("Animators cannot have negative duration: " +
272                    duration);
273        }
274        mDurationSet = true;
275        mDuration = duration;
276        return this;
277    }
278
279    /**
280     * Returns the current duration of property animations. If the duration was set on this
281     * object, that value is returned. Otherwise, the default value of the underlying Animator
282     * is returned.
283     *
284     * @see #setDuration(long)
285     * @return The duration of animations, in milliseconds.
286     */
287    public long getDuration() {
288        if (mDurationSet) {
289            return mDuration;
290        } else {
291            // Just return the default from ValueAnimator, since that's what we'd get if
292            // the value has not been set otherwise
293            if (mTempValueAnimator == null) {
294                mTempValueAnimator = new ValueAnimator();
295            }
296            return mTempValueAnimator.getDuration();
297        }
298    }
299
300    /**
301     * Returns the current startDelay of property animations. If the startDelay was set on this
302     * object, that value is returned. Otherwise, the default value of the underlying Animator
303     * is returned.
304     *
305     * @see #setStartDelay(long)
306     * @return The startDelay of animations, in milliseconds.
307     */
308    public long getStartDelay() {
309        if (mStartDelaySet) {
310            return mStartDelay;
311        } else {
312            // Just return the default from ValueAnimator (0), since that's what we'd get if
313            // the value has not been set otherwise
314            return 0;
315        }
316    }
317
318    /**
319     * Sets the startDelay for the underlying animator that animates the requested properties.
320     * By default, the animator uses the default value for ValueAnimator. Calling this method
321     * will cause the declared value to be used instead.
322     * @param startDelay The delay of ensuing property animations, in milliseconds. The value
323     * cannot be negative.
324     * @return This object, allowing calls to methods in this class to be chained.
325     */
326    public ViewPropertyAnimator setStartDelay(long startDelay) {
327        if (startDelay < 0) {
328            throw new IllegalArgumentException("Animators cannot have negative duration: " +
329                    startDelay);
330        }
331        mStartDelaySet = true;
332        mStartDelay = startDelay;
333        return this;
334    }
335
336    /**
337     * Sets the interpolator for the underlying animator that animates the requested properties.
338     * By default, the animator uses the default interpolator for ValueAnimator. Calling this method
339     * will cause the declared object to be used instead.
340     *
341     * @param interpolator The TimeInterpolator to be used for ensuing property animations. A value
342     * of <code>null</code> will result in linear interpolation.
343     * @return This object, allowing calls to methods in this class to be chained.
344     */
345    public ViewPropertyAnimator setInterpolator(TimeInterpolator interpolator) {
346        mInterpolatorSet = true;
347        mInterpolator = interpolator;
348        return this;
349    }
350
351    /**
352     * Returns the timing interpolator that this animation uses.
353     *
354     * @return The timing interpolator for this animation.
355     */
356    public TimeInterpolator getInterpolator() {
357        if (mInterpolatorSet) {
358            return mInterpolator;
359        } else {
360            // Just return the default from ValueAnimator, since that's what we'd get if
361            // the value has not been set otherwise
362            if (mTempValueAnimator == null) {
363                mTempValueAnimator = new ValueAnimator();
364            }
365            return mTempValueAnimator.getInterpolator();
366        }
367    }
368
369    /**
370     * Sets a listener for events in the underlying Animators that run the property
371     * animations.
372     *
373     * @see Animator.AnimatorListener
374     *
375     * @param listener The listener to be called with AnimatorListener events. A value of
376     * <code>null</code> removes any existing listener.
377     * @return This object, allowing calls to methods in this class to be chained.
378     */
379    public ViewPropertyAnimator setListener(Animator.AnimatorListener listener) {
380        mListener = listener;
381        return this;
382    }
383
384    Animator.AnimatorListener getListener() {
385        return mListener;
386    }
387
388    /**
389     * Sets a listener for update events in the underlying ValueAnimator that runs
390     * the property animations. Note that the underlying animator is animating between
391     * 0 and 1 (these values are then turned into the actual property values internally
392     * by ViewPropertyAnimator). So the animator cannot give information on the current
393     * values of the properties being animated by this ViewPropertyAnimator, although
394     * the view object itself can be queried to get the current values.
395     *
396     * @see android.animation.ValueAnimator.AnimatorUpdateListener
397     *
398     * @param listener The listener to be called with update events. A value of
399     * <code>null</code> removes any existing listener.
400     * @return This object, allowing calls to methods in this class to be chained.
401     */
402    public ViewPropertyAnimator setUpdateListener(ValueAnimator.AnimatorUpdateListener listener) {
403        mUpdateListener = listener;
404        return this;
405    }
406
407    ValueAnimator.AnimatorUpdateListener getUpdateListener() {
408        return mUpdateListener;
409    }
410
411    /**
412     * Starts the currently pending property animations immediately. Calling <code>start()</code>
413     * is optional because all animations start automatically at the next opportunity. However,
414     * if the animations are needed to start immediately and synchronously (not at the time when
415     * the next event is processed by the hierarchy, which is when the animations would begin
416     * otherwise), then this method can be used.
417     */
418    public void start() {
419        mView.removeCallbacks(mAnimationStarter);
420        startAnimation();
421    }
422
423    /**
424     * Cancels all property animations that are currently running or pending.
425     */
426    public void cancel() {
427        if (mAnimatorMap.size() > 0) {
428            HashMap<Animator, PropertyBundle> mAnimatorMapCopy =
429                    (HashMap<Animator, PropertyBundle>)mAnimatorMap.clone();
430            Set<Animator> animatorSet = mAnimatorMapCopy.keySet();
431            for (Animator runningAnim : animatorSet) {
432                runningAnim.cancel();
433            }
434        }
435        mPendingAnimations.clear();
436        mView.removeCallbacks(mAnimationStarter);
437        if (mRTBackend != null) {
438            mRTBackend.cancelAll();
439        }
440    }
441
442    /**
443     * This method will cause the View's <code>x</code> property to be animated to the
444     * specified value. Animations already running on the property will be canceled.
445     *
446     * @param value The value to be animated to.
447     * @see View#setX(float)
448     * @return This object, allowing calls to methods in this class to be chained.
449     */
450    public ViewPropertyAnimator x(float value) {
451        animateProperty(X, value);
452        return this;
453    }
454
455    /**
456     * This method will cause the View's <code>x</code> property to be animated by the
457     * specified value. Animations already running on the property will be canceled.
458     *
459     * @param value The amount to be animated by, as an offset from the current value.
460     * @see View#setX(float)
461     * @return This object, allowing calls to methods in this class to be chained.
462     */
463    public ViewPropertyAnimator xBy(float value) {
464        animatePropertyBy(X, value);
465        return this;
466    }
467
468    /**
469     * This method will cause the View's <code>y</code> property to be animated to the
470     * specified value. Animations already running on the property will be canceled.
471     *
472     * @param value The value to be animated to.
473     * @see View#setY(float)
474     * @return This object, allowing calls to methods in this class to be chained.
475     */
476    public ViewPropertyAnimator y(float value) {
477        animateProperty(Y, value);
478        return this;
479    }
480
481    /**
482     * This method will cause the View's <code>y</code> property to be animated by the
483     * specified value. Animations already running on the property will be canceled.
484     *
485     * @param value The amount to be animated by, as an offset from the current value.
486     * @see View#setY(float)
487     * @return This object, allowing calls to methods in this class to be chained.
488     */
489    public ViewPropertyAnimator yBy(float value) {
490        animatePropertyBy(Y, value);
491        return this;
492    }
493
494    /**
495     * This method will cause the View's <code>z</code> property to be animated to the
496     * specified value. Animations already running on the property will be canceled.
497     *
498     * @param value The value to be animated to.
499     * @see View#setZ(float)
500     * @return This object, allowing calls to methods in this class to be chained.
501     */
502    public ViewPropertyAnimator z(float value) {
503        animateProperty(Z, value);
504        return this;
505    }
506
507    /**
508     * This method will cause the View's <code>z</code> property to be animated by the
509     * specified value. Animations already running on the property will be canceled.
510     *
511     * @param value The amount to be animated by, as an offset from the current value.
512     * @see View#setZ(float)
513     * @return This object, allowing calls to methods in this class to be chained.
514     */
515    public ViewPropertyAnimator zBy(float value) {
516        animatePropertyBy(Z, value);
517        return this;
518    }
519
520    /**
521     * This method will cause the View's <code>rotation</code> property to be animated to the
522     * specified value. Animations already running on the property will be canceled.
523     *
524     * @param value The value to be animated to.
525     * @see View#setRotation(float)
526     * @return This object, allowing calls to methods in this class to be chained.
527     */
528    public ViewPropertyAnimator rotation(float value) {
529        animateProperty(ROTATION, value);
530        return this;
531    }
532
533    /**
534     * This method will cause the View's <code>rotation</code> property to be animated by the
535     * specified value. Animations already running on the property will be canceled.
536     *
537     * @param value The amount to be animated by, as an offset from the current value.
538     * @see View#setRotation(float)
539     * @return This object, allowing calls to methods in this class to be chained.
540     */
541    public ViewPropertyAnimator rotationBy(float value) {
542        animatePropertyBy(ROTATION, value);
543        return this;
544    }
545
546    /**
547     * This method will cause the View's <code>rotationX</code> property to be animated to the
548     * specified value. Animations already running on the property will be canceled.
549     *
550     * @param value The value to be animated to.
551     * @see View#setRotationX(float)
552     * @return This object, allowing calls to methods in this class to be chained.
553     */
554    public ViewPropertyAnimator rotationX(float value) {
555        animateProperty(ROTATION_X, value);
556        return this;
557    }
558
559    /**
560     * This method will cause the View's <code>rotationX</code> property to be animated by the
561     * specified value. Animations already running on the property will be canceled.
562     *
563     * @param value The amount to be animated by, as an offset from the current value.
564     * @see View#setRotationX(float)
565     * @return This object, allowing calls to methods in this class to be chained.
566     */
567    public ViewPropertyAnimator rotationXBy(float value) {
568        animatePropertyBy(ROTATION_X, value);
569        return this;
570    }
571
572    /**
573     * This method will cause the View's <code>rotationY</code> property to be animated to the
574     * specified value. Animations already running on the property will be canceled.
575     *
576     * @param value The value to be animated to.
577     * @see View#setRotationY(float)
578     * @return This object, allowing calls to methods in this class to be chained.
579     */
580    public ViewPropertyAnimator rotationY(float value) {
581        animateProperty(ROTATION_Y, value);
582        return this;
583    }
584
585    /**
586     * This method will cause the View's <code>rotationY</code> property to be animated by the
587     * specified value. Animations already running on the property will be canceled.
588     *
589     * @param value The amount to be animated by, as an offset from the current value.
590     * @see View#setRotationY(float)
591     * @return This object, allowing calls to methods in this class to be chained.
592     */
593    public ViewPropertyAnimator rotationYBy(float value) {
594        animatePropertyBy(ROTATION_Y, value);
595        return this;
596    }
597
598    /**
599     * This method will cause the View's <code>translationX</code> property to be animated to the
600     * specified value. Animations already running on the property will be canceled.
601     *
602     * @param value The value to be animated to.
603     * @see View#setTranslationX(float)
604     * @return This object, allowing calls to methods in this class to be chained.
605     */
606    public ViewPropertyAnimator translationX(float value) {
607        animateProperty(TRANSLATION_X, value);
608        return this;
609    }
610
611    /**
612     * This method will cause the View's <code>translationX</code> property to be animated by the
613     * specified value. Animations already running on the property will be canceled.
614     *
615     * @param value The amount to be animated by, as an offset from the current value.
616     * @see View#setTranslationX(float)
617     * @return This object, allowing calls to methods in this class to be chained.
618     */
619    public ViewPropertyAnimator translationXBy(float value) {
620        animatePropertyBy(TRANSLATION_X, value);
621        return this;
622    }
623
624    /**
625     * This method will cause the View's <code>translationY</code> property to be animated to the
626     * specified value. Animations already running on the property will be canceled.
627     *
628     * @param value The value to be animated to.
629     * @see View#setTranslationY(float)
630     * @return This object, allowing calls to methods in this class to be chained.
631     */
632    public ViewPropertyAnimator translationY(float value) {
633        animateProperty(TRANSLATION_Y, value);
634        return this;
635    }
636
637    /**
638     * This method will cause the View's <code>translationY</code> property to be animated by the
639     * specified value. Animations already running on the property will be canceled.
640     *
641     * @param value The amount to be animated by, as an offset from the current value.
642     * @see View#setTranslationY(float)
643     * @return This object, allowing calls to methods in this class to be chained.
644     */
645    public ViewPropertyAnimator translationYBy(float value) {
646        animatePropertyBy(TRANSLATION_Y, value);
647        return this;
648    }
649
650    /**
651     * This method will cause the View's <code>translationZ</code> property to be animated to the
652     * specified value. Animations already running on the property will be canceled.
653     *
654     * @param value The value to be animated to.
655     * @see View#setTranslationZ(float)
656     * @return This object, allowing calls to methods in this class to be chained.
657     */
658    public ViewPropertyAnimator translationZ(float value) {
659        animateProperty(TRANSLATION_Z, value);
660        return this;
661    }
662
663    /**
664     * This method will cause the View's <code>translationZ</code> property to be animated by the
665     * specified value. Animations already running on the property will be canceled.
666     *
667     * @param value The amount to be animated by, as an offset from the current value.
668     * @see View#setTranslationZ(float)
669     * @return This object, allowing calls to methods in this class to be chained.
670     */
671    public ViewPropertyAnimator translationZBy(float value) {
672        animatePropertyBy(TRANSLATION_Z, value);
673        return this;
674    }
675    /**
676     * This method will cause the View's <code>scaleX</code> property to be animated to the
677     * specified value. Animations already running on the property will be canceled.
678     *
679     * @param value The value to be animated to.
680     * @see View#setScaleX(float)
681     * @return This object, allowing calls to methods in this class to be chained.
682     */
683    public ViewPropertyAnimator scaleX(float value) {
684        animateProperty(SCALE_X, value);
685        return this;
686    }
687
688    /**
689     * This method will cause the View's <code>scaleX</code> property to be animated by the
690     * specified value. Animations already running on the property will be canceled.
691     *
692     * @param value The amount to be animated by, as an offset from the current value.
693     * @see View#setScaleX(float)
694     * @return This object, allowing calls to methods in this class to be chained.
695     */
696    public ViewPropertyAnimator scaleXBy(float value) {
697        animatePropertyBy(SCALE_X, value);
698        return this;
699    }
700
701    /**
702     * This method will cause the View's <code>scaleY</code> property to be animated to the
703     * specified value. Animations already running on the property will be canceled.
704     *
705     * @param value The value to be animated to.
706     * @see View#setScaleY(float)
707     * @return This object, allowing calls to methods in this class to be chained.
708     */
709    public ViewPropertyAnimator scaleY(float value) {
710        animateProperty(SCALE_Y, value);
711        return this;
712    }
713
714    /**
715     * This method will cause the View's <code>scaleY</code> property to be animated by the
716     * specified value. Animations already running on the property will be canceled.
717     *
718     * @param value The amount to be animated by, as an offset from the current value.
719     * @see View#setScaleY(float)
720     * @return This object, allowing calls to methods in this class to be chained.
721     */
722    public ViewPropertyAnimator scaleYBy(float value) {
723        animatePropertyBy(SCALE_Y, value);
724        return this;
725    }
726
727    /**
728     * This method will cause the View's <code>alpha</code> property to be animated to the
729     * specified value. Animations already running on the property will be canceled.
730     *
731     * @param value The value to be animated to.
732     * @see View#setAlpha(float)
733     * @return This object, allowing calls to methods in this class to be chained.
734     */
735    public ViewPropertyAnimator alpha(float value) {
736        animateProperty(ALPHA, value);
737        return this;
738    }
739
740    /**
741     * This method will cause the View's <code>alpha</code> property to be animated by the
742     * specified value. Animations already running on the property will be canceled.
743     *
744     * @param value The amount to be animated by, as an offset from the current value.
745     * @see View#setAlpha(float)
746     * @return This object, allowing calls to methods in this class to be chained.
747     */
748    public ViewPropertyAnimator alphaBy(float value) {
749        animatePropertyBy(ALPHA, value);
750        return this;
751    }
752
753    /**
754     * The View associated with this ViewPropertyAnimator will have its
755     * {@link View#setLayerType(int, android.graphics.Paint) layer type} set to
756     * {@link View#LAYER_TYPE_HARDWARE} for the duration of the next animation.
757     * As stated in the documentation for {@link View#LAYER_TYPE_HARDWARE},
758     * the actual type of layer used internally depends on the runtime situation of the
759     * view. If the activity and this view are hardware-accelerated, then the layer will be
760     * accelerated as well. If the activity or the view is not accelerated, then the layer will
761     * effectively be the same as {@link View#LAYER_TYPE_SOFTWARE}.
762     *
763     * <p>This state is not persistent, either on the View or on this ViewPropertyAnimator: the
764     * layer type of the View will be restored when the animation ends to what it was when this
765     * method was called, and this setting on ViewPropertyAnimator is only valid for the next
766     * animation. Note that calling this method and then independently setting the layer type of
767     * the View (by a direct call to {@link View#setLayerType(int, android.graphics.Paint)}) will
768     * result in some inconsistency, including having the layer type restored to its pre-withLayer()
769     * value when the animation ends.</p>
770     *
771     * @see View#setLayerType(int, android.graphics.Paint)
772     * @return This object, allowing calls to methods in this class to be chained.
773     */
774    public ViewPropertyAnimator withLayer() {
775         mPendingSetupAction= new Runnable() {
776            @Override
777            public void run() {
778                mView.setLayerType(View.LAYER_TYPE_HARDWARE, null);
779                if (mView.isAttachedToWindow()) {
780                    mView.buildLayer();
781                }
782            }
783        };
784        final int currentLayerType = mView.getLayerType();
785        mPendingCleanupAction = new Runnable() {
786            @Override
787            public void run() {
788                mView.setLayerType(currentLayerType, null);
789            }
790        };
791        if (mAnimatorSetupMap == null) {
792            mAnimatorSetupMap = new HashMap<Animator, Runnable>();
793        }
794        if (mAnimatorCleanupMap == null) {
795            mAnimatorCleanupMap = new HashMap<Animator, Runnable>();
796        }
797
798        return this;
799    }
800
801    /**
802     * Specifies an action to take place when the next animation runs. If there is a
803     * {@link #setStartDelay(long) startDelay} set on this ViewPropertyAnimator, then the
804     * action will run after that startDelay expires, when the actual animation begins.
805     * This method, along with {@link #withEndAction(Runnable)}, is intended to help facilitate
806     * choreographing ViewPropertyAnimator animations with other animations or actions
807     * in the application.
808     *
809     * @param runnable The action to run when the next animation starts.
810     * @return This object, allowing calls to methods in this class to be chained.
811     */
812    public ViewPropertyAnimator withStartAction(Runnable runnable) {
813        mPendingOnStartAction = runnable;
814        if (runnable != null && mAnimatorOnStartMap == null) {
815            mAnimatorOnStartMap = new HashMap<Animator, Runnable>();
816        }
817        return this;
818    }
819
820    /**
821     * Specifies an action to take place when the next animation ends. The action is only
822     * run if the animation ends normally; if the ViewPropertyAnimator is canceled during
823     * that animation, the runnable will not run.
824     * This method, along with {@link #withStartAction(Runnable)}, is intended to help facilitate
825     * choreographing ViewPropertyAnimator animations with other animations or actions
826     * in the application.
827     *
828     * <p>For example, the following code animates a view to x=200 and then back to 0:</p>
829     * <pre>
830     *     Runnable endAction = new Runnable() {
831     *         public void run() {
832     *             view.animate().x(0);
833     *         }
834     *     };
835     *     view.animate().x(200).withEndAction(endAction);
836     * </pre>
837     *
838     * @param runnable The action to run when the next animation ends.
839     * @return This object, allowing calls to methods in this class to be chained.
840     */
841    public ViewPropertyAnimator withEndAction(Runnable runnable) {
842        mPendingOnEndAction = runnable;
843        if (runnable != null && mAnimatorOnEndMap == null) {
844            mAnimatorOnEndMap = new HashMap<Animator, Runnable>();
845        }
846        return this;
847    }
848
849    boolean hasActions() {
850        return mPendingSetupAction != null
851                || mPendingCleanupAction != null
852                || mPendingOnStartAction != null
853                || mPendingOnEndAction != null;
854    }
855
856    /**
857     * Starts the underlying Animator for a set of properties. We use a single animator that
858     * simply runs from 0 to 1, and then use that fractional value to set each property
859     * value accordingly.
860     */
861    private void startAnimation() {
862        if (mRTBackend != null && mRTBackend.startAnimation(this)) {
863            return;
864        }
865        mView.setHasTransientState(true);
866        ValueAnimator animator = ValueAnimator.ofFloat(1.0f);
867        ArrayList<NameValuesHolder> nameValueList =
868                (ArrayList<NameValuesHolder>) mPendingAnimations.clone();
869        mPendingAnimations.clear();
870        int propertyMask = 0;
871        int propertyCount = nameValueList.size();
872        for (int i = 0; i < propertyCount; ++i) {
873            NameValuesHolder nameValuesHolder = nameValueList.get(i);
874            propertyMask |= nameValuesHolder.mNameConstant;
875        }
876        mAnimatorMap.put(animator, new PropertyBundle(propertyMask, nameValueList));
877        if (mPendingSetupAction != null) {
878            mAnimatorSetupMap.put(animator, mPendingSetupAction);
879            mPendingSetupAction = null;
880        }
881        if (mPendingCleanupAction != null) {
882            mAnimatorCleanupMap.put(animator, mPendingCleanupAction);
883            mPendingCleanupAction = null;
884        }
885        if (mPendingOnStartAction != null) {
886            mAnimatorOnStartMap.put(animator, mPendingOnStartAction);
887            mPendingOnStartAction = null;
888        }
889        if (mPendingOnEndAction != null) {
890            mAnimatorOnEndMap.put(animator, mPendingOnEndAction);
891            mPendingOnEndAction = null;
892        }
893        animator.addUpdateListener(mAnimatorEventListener);
894        animator.addListener(mAnimatorEventListener);
895        if (mStartDelaySet) {
896            animator.setStartDelay(mStartDelay);
897        }
898        if (mDurationSet) {
899            animator.setDuration(mDuration);
900        }
901        if (mInterpolatorSet) {
902            animator.setInterpolator(mInterpolator);
903        }
904        animator.start();
905    }
906
907    /**
908     * Utility function, called by the various x(), y(), etc. methods. This stores the
909     * constant name for the property along with the from/delta values that will be used to
910     * calculate and set the property during the animation. This structure is added to the
911     * pending animations, awaiting the eventual start() of the underlying animator. A
912     * Runnable is posted to start the animation, and any pending such Runnable is canceled
913     * (which enables us to end up starting just one animator for all of the properties
914     * specified at one time).
915     *
916     * @param constantName The specifier for the property being animated
917     * @param toValue The value to which the property will animate
918     */
919    private void animateProperty(int constantName, float toValue) {
920        float fromValue = getValue(constantName);
921        float deltaValue = toValue - fromValue;
922        animatePropertyBy(constantName, fromValue, deltaValue);
923    }
924
925    /**
926     * Utility function, called by the various xBy(), yBy(), etc. methods. This method is
927     * just like animateProperty(), except the value is an offset from the property's
928     * current value, instead of an absolute "to" value.
929     *
930     * @param constantName The specifier for the property being animated
931     * @param byValue The amount by which the property will change
932     */
933    private void animatePropertyBy(int constantName, float byValue) {
934        float fromValue = getValue(constantName);
935        animatePropertyBy(constantName, fromValue, byValue);
936    }
937
938    /**
939     * Utility function, called by animateProperty() and animatePropertyBy(), which handles the
940     * details of adding a pending animation and posting the request to start the animation.
941     *
942     * @param constantName The specifier for the property being animated
943     * @param startValue The starting value of the property
944     * @param byValue The amount by which the property will change
945     */
946    private void animatePropertyBy(int constantName, float startValue, float byValue) {
947        // First, cancel any existing animations on this property
948        if (mAnimatorMap.size() > 0) {
949            Animator animatorToCancel = null;
950            Set<Animator> animatorSet = mAnimatorMap.keySet();
951            for (Animator runningAnim : animatorSet) {
952                PropertyBundle bundle = mAnimatorMap.get(runningAnim);
953                if (bundle.cancel(constantName)) {
954                    // property was canceled - cancel the animation if it's now empty
955                    // Note that it's safe to break out here because every new animation
956                    // on a property will cancel a previous animation on that property, so
957                    // there can only ever be one such animation running.
958                    if (bundle.mPropertyMask == NONE) {
959                        // the animation is no longer changing anything - cancel it
960                        animatorToCancel = runningAnim;
961                        break;
962                    }
963                }
964            }
965            if (animatorToCancel != null) {
966                animatorToCancel.cancel();
967            }
968        }
969
970        NameValuesHolder nameValuePair = new NameValuesHolder(constantName, startValue, byValue);
971        mPendingAnimations.add(nameValuePair);
972        mView.removeCallbacks(mAnimationStarter);
973        mView.postOnAnimation(mAnimationStarter);
974    }
975
976    /**
977     * This method handles setting the property values directly in the View object's fields.
978     * propertyConstant tells it which property should be set, value is the value to set
979     * the property to.
980     *
981     * @param propertyConstant The property to be set
982     * @param value The value to set the property to
983     */
984    private void setValue(int propertyConstant, float value) {
985        final View.TransformationInfo info = mView.mTransformationInfo;
986        final RenderNode renderNode = mView.mRenderNode;
987        switch (propertyConstant) {
988            case TRANSLATION_X:
989                renderNode.setTranslationX(value);
990                break;
991            case TRANSLATION_Y:
992                renderNode.setTranslationY(value);
993                break;
994            case TRANSLATION_Z:
995                renderNode.setTranslationZ(value);
996                break;
997            case ROTATION:
998                renderNode.setRotation(value);
999                break;
1000            case ROTATION_X:
1001                renderNode.setRotationX(value);
1002                break;
1003            case ROTATION_Y:
1004                renderNode.setRotationY(value);
1005                break;
1006            case SCALE_X:
1007                renderNode.setScaleX(value);
1008                break;
1009            case SCALE_Y:
1010                renderNode.setScaleY(value);
1011                break;
1012            case X:
1013                renderNode.setTranslationX(value - mView.mLeft);
1014                break;
1015            case Y:
1016                renderNode.setTranslationY(value - mView.mTop);
1017                break;
1018            case Z:
1019                renderNode.setTranslationZ(value - renderNode.getElevation());
1020                break;
1021            case ALPHA:
1022                info.mAlpha = value;
1023                renderNode.setAlpha(value);
1024                break;
1025        }
1026    }
1027
1028    /**
1029     * This method gets the value of the named property from the View object.
1030     *
1031     * @param propertyConstant The property whose value should be returned
1032     * @return float The value of the named property
1033     */
1034    private float getValue(int propertyConstant) {
1035        final RenderNode node = mView.mRenderNode;
1036        switch (propertyConstant) {
1037            case TRANSLATION_X:
1038                return node.getTranslationX();
1039            case TRANSLATION_Y:
1040                return node.getTranslationY();
1041            case TRANSLATION_Z:
1042                return node.getTranslationZ();
1043            case ROTATION:
1044                return node.getRotation();
1045            case ROTATION_X:
1046                return node.getRotationX();
1047            case ROTATION_Y:
1048                return node.getRotationY();
1049            case SCALE_X:
1050                return node.getScaleX();
1051            case SCALE_Y:
1052                return node.getScaleY();
1053            case X:
1054                return mView.mLeft + node.getTranslationX();
1055            case Y:
1056                return mView.mTop + node.getTranslationY();
1057            case Z:
1058                return node.getElevation() + node.getTranslationZ();
1059            case ALPHA:
1060                return mView.mTransformationInfo.mAlpha;
1061        }
1062        return 0;
1063    }
1064
1065    /**
1066     * Utility class that handles the various Animator events. The only ones we care
1067     * about are the end event (which we use to clean up the animator map when an animator
1068     * finishes) and the update event (which we use to calculate the current value of each
1069     * property and then set it on the view object).
1070     */
1071    private class AnimatorEventListener
1072            implements Animator.AnimatorListener, ValueAnimator.AnimatorUpdateListener {
1073        @Override
1074        public void onAnimationStart(Animator animation) {
1075            if (mAnimatorSetupMap != null) {
1076                Runnable r = mAnimatorSetupMap.get(animation);
1077                if (r != null) {
1078                    r.run();
1079                }
1080                mAnimatorSetupMap.remove(animation);
1081            }
1082            if (mAnimatorOnStartMap != null) {
1083                Runnable r = mAnimatorOnStartMap.get(animation);
1084                if (r != null) {
1085                    r.run();
1086                }
1087                mAnimatorOnStartMap.remove(animation);
1088            }
1089            if (mListener != null) {
1090                mListener.onAnimationStart(animation);
1091            }
1092        }
1093
1094        @Override
1095        public void onAnimationCancel(Animator animation) {
1096            if (mListener != null) {
1097                mListener.onAnimationCancel(animation);
1098            }
1099            if (mAnimatorOnEndMap != null) {
1100                mAnimatorOnEndMap.remove(animation);
1101            }
1102        }
1103
1104        @Override
1105        public void onAnimationRepeat(Animator animation) {
1106            if (mListener != null) {
1107                mListener.onAnimationRepeat(animation);
1108            }
1109        }
1110
1111        @Override
1112        public void onAnimationEnd(Animator animation) {
1113            mView.setHasTransientState(false);
1114            if (mListener != null) {
1115                mListener.onAnimationEnd(animation);
1116            }
1117            if (mAnimatorOnEndMap != null) {
1118                Runnable r = mAnimatorOnEndMap.get(animation);
1119                if (r != null) {
1120                    r.run();
1121                }
1122                mAnimatorOnEndMap.remove(animation);
1123            }
1124            if (mAnimatorCleanupMap != null) {
1125                Runnable r = mAnimatorCleanupMap.get(animation);
1126                if (r != null) {
1127                    r.run();
1128                }
1129                mAnimatorCleanupMap.remove(animation);
1130            }
1131            mAnimatorMap.remove(animation);
1132        }
1133
1134        /**
1135         * Calculate the current value for each property and set it on the view. Invalidate
1136         * the view object appropriately, depending on which properties are being animated.
1137         *
1138         * @param animation The animator associated with the properties that need to be
1139         * set. This animator holds the animation fraction which we will use to calculate
1140         * the current value of each property.
1141         */
1142        @Override
1143        public void onAnimationUpdate(ValueAnimator animation) {
1144            PropertyBundle propertyBundle = mAnimatorMap.get(animation);
1145            if (propertyBundle == null) {
1146                // Shouldn't happen, but just to play it safe
1147                return;
1148            }
1149
1150            boolean hardwareAccelerated = mView.isHardwareAccelerated();
1151
1152            // alpha requires slightly different treatment than the other (transform) properties.
1153            // The logic in setAlpha() is not simply setting mAlpha, plus the invalidation
1154            // logic is dependent on how the view handles an internal call to onSetAlpha().
1155            // We track what kinds of properties are set, and how alpha is handled when it is
1156            // set, and perform the invalidation steps appropriately.
1157            boolean alphaHandled = false;
1158            if (!hardwareAccelerated) {
1159                mView.invalidateParentCaches();
1160            }
1161            float fraction = animation.getAnimatedFraction();
1162            int propertyMask = propertyBundle.mPropertyMask;
1163            if ((propertyMask & TRANSFORM_MASK) != 0) {
1164                mView.invalidateViewProperty(hardwareAccelerated, false);
1165            }
1166            ArrayList<NameValuesHolder> valueList = propertyBundle.mNameValuesHolder;
1167            if (valueList != null) {
1168                int count = valueList.size();
1169                for (int i = 0; i < count; ++i) {
1170                    NameValuesHolder values = valueList.get(i);
1171                    float value = values.mFromValue + fraction * values.mDeltaValue;
1172                    if (values.mNameConstant == ALPHA) {
1173                        alphaHandled = mView.setAlphaNoInvalidation(value);
1174                    } else {
1175                        setValue(values.mNameConstant, value);
1176                    }
1177                }
1178            }
1179            if ((propertyMask & TRANSFORM_MASK) != 0) {
1180                if (!hardwareAccelerated) {
1181                    mView.mPrivateFlags |= View.PFLAG_DRAWN; // force another invalidation
1182                }
1183            }
1184            // invalidate(false) in all cases except if alphaHandled gets set to true
1185            // via the call to setAlphaNoInvalidation(), above
1186            if (alphaHandled) {
1187                mView.invalidate(true);
1188            } else {
1189                mView.invalidateViewProperty(false, false);
1190            }
1191            if (mUpdateListener != null) {
1192                mUpdateListener.onAnimationUpdate(animation);
1193            }
1194        }
1195    }
1196}
1197