TransitionManager.java revision c876cd8f9334e2423de00836009f3fd7a9566938 
1/*
2 * Copyright (C) 2016 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.support.transition;
18
19import android.os.Build;
20import android.support.annotation.NonNull;
21import android.view.ViewGroup;
22
23/**
24 * This class manages the set of transitions that fire when there is a
25 * change of {@link Scene}. To use the manager, add scenes along with
26 * transition objects with calls to {@link #setTransition(Scene, Transition)}
27 * or {@link #setTransition(Scene, Scene, Transition)}. Setting specific
28 * transitions for scene changes is not required; by default, a Scene change
29 * will use {@link AutoTransition} to do something reasonable for most
30 * situations. Specifying other transitions for particular scene changes is
31 * only necessary if the application wants different transition behavior
32 * in these situations.
33 *
34 * <p>Unlike the platform version, this does not support declaration by XML resources.</p>
35 */
36public class TransitionManager {
37
38    private static TransitionManagerStaticsImpl sImpl;
39
40    static {
41        if (Build.VERSION.SDK_INT < 19) {
42            sImpl = new TransitionManagerStaticsIcs();
43        } else {
44            sImpl = new TransitionManagerStaticsKitKat();
45        }
46    }
47
48    private TransitionManagerImpl mImpl;
49
50    public TransitionManager() {
51        if (Build.VERSION.SDK_INT < 19) {
52            mImpl = new TransitionManagerIcs();
53        } else {
54            mImpl = new TransitionManagerKitKat();
55        }
56    }
57
58    /**
59     * Convenience method to simply change to the given scene using
60     * the default transition for TransitionManager.
61     *
62     * @param scene The Scene to change to
63     */
64    public static void go(@NonNull Scene scene) {
65        sImpl.go(scene.mImpl);
66    }
67
68    /**
69     * Convenience method to simply change to the given scene using
70     * the given transition.
71     *
72     * <p>Passing in <code>null</code> for the transition parameter will
73     * result in the scene changing without any transition running, and is
74     * equivalent to calling {@link Scene#exit()} on the scene root's
75     * current scene, followed by {@link Scene#enter()} on the scene
76     * specified by the <code>scene</code> parameter.</p>
77     *
78     * @param scene      The Scene to change to
79     * @param transition The transition to use for this scene change. A
80     *                   value of null causes the scene change to happen with no transition.
81     */
82    public static void go(@NonNull Scene scene, Transition transition) {
83        sImpl.go(scene.mImpl, transition.mImpl);
84    }
85
86    /**
87     * Convenience method to animate, using the default transition,
88     * to a new scene defined by all changes within the given scene root between
89     * calling this method and the next rendering frame.
90     * Equivalent to calling {@link #beginDelayedTransition(ViewGroup, Transition)}
91     * with a value of <code>null</code> for the <code>transition</code> parameter.
92     *
93     * @param sceneRoot The root of the View hierarchy to run the transition on.
94     */
95    public static void beginDelayedTransition(final ViewGroup sceneRoot) {
96        sImpl.beginDelayedTransition(sceneRoot);
97    }
98
99    /**
100     * Convenience method to animate to a new scene defined by all changes within
101     * the given scene root between calling this method and the next rendering frame.
102     * Calling this method causes TransitionManager to capture current values in the
103     * scene root and then post a request to run a transition on the next frame.
104     * At that time, the new values in the scene root will be captured and changes
105     * will be animated. There is no need to create a Scene; it is implied by
106     * changes which take place between calling this method and the next frame when
107     * the transition begins.
108     *
109     * <p>Calling this method several times before the next frame (for example, if
110     * unrelated code also wants to make dynamic changes and run a transition on
111     * the same scene root), only the first call will trigger capturing values
112     * and exiting the current scene. Subsequent calls to the method with the
113     * same scene root during the same frame will be ignored.</p>
114     *
115     * <p>Passing in <code>null</code> for the transition parameter will
116     * cause the TransitionManager to use its default transition.</p>
117     *
118     * @param sceneRoot  The root of the View hierarchy to run the transition on.
119     * @param transition The transition to use for this change. A
120     *                   value of null causes the TransitionManager to use the default transition.
121     */
122    public static void beginDelayedTransition(final ViewGroup sceneRoot, Transition transition) {
123        sImpl.beginDelayedTransition(sceneRoot, transition.mImpl);
124    }
125
126    /**
127     * Sets a specific transition to occur when the given scene is entered.
128     *
129     * @param scene      The scene which, when applied, will cause the given
130     *                   transition to run.
131     * @param transition The transition that will play when the given scene is
132     *                   entered. A value of null will result in the default behavior of
133     *                   using the default transition instead.
134     */
135    public void setTransition(Scene scene, Transition transition) {
136        mImpl.setTransition(scene.mImpl, transition.mImpl);
137    }
138
139    /**
140     * Sets a specific transition to occur when the given pair of scenes is
141     * exited/entered.
142     *
143     * @param fromScene  The scene being exited when the given transition will
144     *                   be run
145     * @param toScene    The scene being entered when the given transition will
146     *                   be run
147     * @param transition The transition that will play when the given scene is
148     *                   entered. A value of null will result in the default behavior of
149     *                   using the default transition instead.
150     */
151    public void setTransition(Scene fromScene, Scene toScene, Transition transition) {
152        mImpl.setTransition(fromScene.mImpl, toScene.mImpl, transition.mImpl);
153    }
154
155    /**
156     * Change to the given scene, using the
157     * appropriate transition for this particular scene change
158     * (as specified to the TransitionManager, or the default
159     * if no such transition exists).
160     *
161     * @param scene The Scene to change to
162     */
163    public void transitionTo(Scene scene) {
164        mImpl.transitionTo(scene.mImpl);
165    }
166
167}
168