java.lang.Object | |
↳ | android.transition.Transition |
Known Direct Subclasses |
Known Indirect Subclasses |
A Transition holds information about animations that will be run on its
targets during a scene change. Subclasses of this abstract class may
choreograph several child transitions (
TransitionSet
or they may
perform custom animations themselves. Any Transition has two main jobs:
(1) capture property values, and (2) play animations based on changes to
captured property values. A custom transition knows what property values
on View objects are of interest to it, and also knows how to animate
changes to those values. For example, the
Fade
transition tracks
changes to visibility-related properties and is able to construct and run
animations that fade items in or out based on changes to those properties.
Note: Transitions may not work correctly with either
SurfaceView
or
TextureView
, due to the way that these views are displayed
on the screen. For SurfaceView, the problem is that the view is updated from
a non-UI thread, so changes to the view due to transitions (such as moving
and resizing the view) may be out of sync with the display inside those bounds.
TextureView is more compatible with transitions in general, but some
specific transitions (such as
Fade
) may not be compatible
with TextureView because they rely on
ViewOverlay
functionality,
which does not currently work with TextureView.
Transitions can be declared in XML resource files inside the
res/transition
directory. Transition resources consist of a tag name for one of the Transition
subclasses along with attributes to define some of the attributes of that transition.
For example, here is a minimal resource file that declares a
ChangeBounds
transition:
<changeBounds/>
Note that attributes for the transition are not required, just as they are
optional when declared in code; Transitions created from XML resources will use
the same defaults as their code-created equivalents. Here is a slightly more
elaborate example which declares a
TransitionSet
transition with
ChangeBounds
and
Fade
child transitions:
<transitionSet xmlns:android="http://schemas.android.com/apk/res/android" android:transitionOrdering="sequential"> <changeBounds/> <fade android:fadingMode="fade_out" > <targets> <target android:targetId="@id/grayscaleContainer" /> </targets> </fade> </transitionSet>
In this example, the transitionOrdering attribute is used on the TransitionSet
object to change from the default
ORDERING_TOGETHER
behavior
to be
ORDERING_SEQUENTIAL
instead. Also, the
Fade
transition uses a fadingMode of
OUT
instead of the default
out-in behavior. Finally, note the use of the
targets
sub-tag, which
takes a set of
target
tags, each
of which lists a specific
targetId
which this transition acts upon.
Use of targets is optional, but can be used to either limit the time spent checking
attributes on unchanging views, or limiting the types of animations run on specific views.
In this case, we know that only the
grayscaleContainer
will be
disappearing, so we choose to limit the
Fade
transition to only that view.
Transition
,
TransitionSet
,
TransitionTarget
, and
Fade
.
Nested Classes | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
|
Transition.TransitionListener | A transition listener receives notifications from a transition. |
XML Attributes | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
|
|
|
|||||||||
android:duration | setDuration(long) | Amount of time (in milliseconds) that the transition should run. | |||||||||
android:interpolator | setInterpolator(TimeInterpolator) | Interpolator to be used in the animations spawned by this transition. | |||||||||
android:startDelay | setStartDelay(long) | Delay in milliseconds before the transition starts. |
Public Constructors | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
|
Constructs a Transition object with no target objects.
|
Public Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
|
Adds a listener to the set of listeners that are sent events through the
life of an animation, such as start, repeat, and end.
|
||||||||||
|
Adds the id of a target view that this Transition is interested in
animating.
|
||||||||||
|
Sets the target view instances that this Transition is interested in
animating.
|
||||||||||
|
Captures the values in the end scene for the properties that this
transition monitors.
|
||||||||||
|
Captures the values in the start scene for the properties that this
transition monitors.
|
||||||||||
|
Creates and returns a copy of this
Object
.
|
||||||||||
|
This method creates an animation that will be run for this transition
given the information in the startValues and endValues structures captured
earlier for the start and end scenes.
|
||||||||||
|
Whether to add the children of given target to the list of target children
to exclude from this transition.
|
||||||||||
|
Whether to add the given type to the list of types whose children should
be excluded from this transition.
|
||||||||||
|
Whether to add the children of the given id to the list of targets to exclude
from this transition.
|
||||||||||
|
Whether to add the given id to the list of target ids to exclude from this
transition.
|
||||||||||
|
Whether to add the given type to the list of types to exclude from this
transition.
|
||||||||||
|
Whether to add the given target to the list of targets to exclude from this
transition.
|
||||||||||
|
Returns the duration set on this transition.
|
||||||||||
|
Returns the interpolator set on this transition.
|
||||||||||
|
Returns the name of this Transition.
|
||||||||||
|
Returns the startDelay set on this transition.
|
||||||||||
|
Returns the array of target IDs that this transition limits itself to
tracking and animating.
|
||||||||||
|
Returns the array of target views that this transition limits itself to
tracking and animating.
|
||||||||||
|
Returns the set of property names used stored in the
TransitionValues
object passed into
captureStartValues(TransitionValues)
that
this transition cares about for the purposes of canceling overlapping animations.
|
||||||||||
|
This method can be called by transitions to get the TransitionValues for
any particular view during the transition-playing process.
|
||||||||||
|
Removes a listener from the set listening to this animation.
|
||||||||||
|
Removes the given targetId from the list of ids that this Transition
is interested in animating.
|
||||||||||
|
Removes the given target from the list of targets that this Transition
is interested in animating.
|
||||||||||
|
Sets the duration of this transition.
|
||||||||||
|
Sets the interpolator of this transition.
|
||||||||||
|
Sets the startDelay of this transition.
|
||||||||||
|
Returns a string containing a concise, human-readable description of this
object.
|
[Expand]
Inherited Methods
|
|||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
From class
java.lang.Object
|
Amount of time (in milliseconds) that the transition should run.
Must be an integer value, such as "
100
".
This may also be a reference to a resource (in the form
"
@[
package
:]
type
:
name
") or
theme attribute (in the form
"
?[
package
:][
type
:]
name
")
containing a value of this type.
This corresponds to the global attribute
resource symbol
duration
.
Interpolator to be used in the animations spawned by this transition.
Must be a reference to another resource, in the form "
@[+][
package
:]
type
:
name
"
or to a theme attribute in the form "
?[
package
:][
type
:]
name
".
This corresponds to the global attribute
resource symbol
interpolator
.
Delay in milliseconds before the transition starts.
Must be an integer value, such as "
100
".
This may also be a reference to a resource (in the form
"
@[
package
:]
type
:
name
") or
theme attribute (in the form
"
?[
package
:][
type
:]
name
")
containing a value of this type.
This corresponds to the global attribute
resource symbol
startDelay
.
Constructs a Transition object with no target objects. A transition with no targets defaults to running on all target objects in the scene hierarchy (if the transition is not contained in a TransitionSet), or all target objects passed down from its parent (if it is in a TransitionSet).
Adds a listener to the set of listeners that are sent events through the life of an animation, such as start, repeat, and end.
listener | the listener to be added to the current set of listeners for this animation. |
---|
Adds the id of a target view that this Transition is interested in animating. By default, there are no targetIds, and a Transition will listen for changes on every view in the hierarchy below the sceneRoot of the Scene being transitioned into. Setting targetIds constrains the Transition to only listen for, and act on, views with these IDs. Views with different IDs, or no IDs whatsoever, will be ignored.
Note that using ids to specify targets implies that ids should be unique within the view hierarchy underneat the scene root.
targetId | The id of a target view, must be a positive number. |
---|
transitionSet.addTransitions(new Fade()).addTarget(someId);
Sets the target view instances that this Transition is interested in animating. By default, there are no targets, and a Transition will listen for changes on every view in the hierarchy below the sceneRoot of the Scene being transitioned into. Setting targets constrains the Transition to only listen for, and act on, these views. All other views will be ignored.
The target list is like the
targetId
list except this list specifies the actual View instances, not the ids
of the views. This is an important distinction when scene changes involve
view hierarchies which have been inflated separately; different views may
share the same id but not actually be the same instance. If the transition
should treat those views as the same, then
addTarget(int)
should be used
instead of
addTarget(View)
. If, on the other hand, scene changes involve
changes all within the same view hierarchy, among views which do not
necessarily have ids set on them, then the target list of views may be more
convenient.
target | A View on which the Transition will act, must be non-null. |
---|
transitionSet.addTransitions(new Fade()).addTarget(someView);
Captures the values in the end scene for the properties that this
transition monitors. These values are then passed as the endValues
structure in a later call to
createAnimator(ViewGroup, TransitionValues, TransitionValues)
.
The main concern for an implementation is what the
properties are that the transition cares about and what the values are
for all of those properties. The start and end values will be compared
later during the
createAnimator(android.view.ViewGroup, TransitionValues, TransitionValues)
method to determine what, if any, animations, should be run.
Subclasses must implement this method. The method should only be called by the transition system; it is not intended to be called from external classes.
transitionValues |
The holder for any values that the Transition
wishes to store. Values are stored in the
values
field
of this TransitionValues object and are keyed from
a String value. For example, to store a view's rotation value,
a transition might call
transitionValues.values.put("appname:transitionname:rotation",
view.getRotation())
. The target view will already be stored in
the transitionValues structure when this method is called.
|
---|
Captures the values in the start scene for the properties that this
transition monitors. These values are then passed as the startValues
structure in a later call to
createAnimator(ViewGroup, TransitionValues, TransitionValues)
.
The main concern for an implementation is what the
properties are that the transition cares about and what the values are
for all of those properties. The start and end values will be compared
later during the
createAnimator(android.view.ViewGroup, TransitionValues, TransitionValues)
method to determine what, if any, animations, should be run.
Subclasses must implement this method. The method should only be called by the transition system; it is not intended to be called from external classes.
transitionValues |
The holder for any values that the Transition
wishes to store. Values are stored in the
values
field
of this TransitionValues object and are keyed from
a String value. For example, to store a view's rotation value,
a transition might call
transitionValues.values.put("appname:transitionname:rotation",
view.getRotation())
. The target view will already be stored in
the transitionValues structure when this method is called.
|
---|
Creates and returns a copy of this
Object
. The default
implementation returns a so-called "shallow" copy: It creates a new
instance of the same class and then copies the field values (including
object references) from this instance to the new instance. A "deep" copy,
in contrast, would also recursively clone nested objects. A subclass that
needs to implement this kind of cloning should call
super.clone()
to create the new instance and then create deep copies of the nested,
mutable objects.
This method creates an animation that will be run for this transition given the information in the startValues and endValues structures captured earlier for the start and end scenes. Subclasses of Transition should override this method. The method should only be called by the transition system; it is not intended to be called from external classes.
This method is called by the transition's parent (all the way up to the
topmost Transition in the hierarchy) with the sceneRoot and start/end
values that the transition may need to set up initial target values
and construct an appropriate animation. For example, if an overall
Transition is a
TransitionSet
consisting of several
child transitions in sequence, then some of the child transitions may
want to set initial values on target views prior to the overall
Transition commencing, to put them in an appropriate state for the
delay between that start and the child Transition start time. For
example, a transition that fades an item in may wish to set the starting
alpha value to 0, to avoid it blinking in prior to the transition
actually starting the animation. This is necessary because the scene
change that triggers the Transition will automatically set the end-scene
on all target views, so a Transition that wants to animate from a
different value should set that value prior to returning from this method.
Additionally, a Transition can perform logic to determine whether the transition needs to run on the given target and start/end values. For example, a transition that resizes objects on the screen may wish to avoid running for views which are not present in either the start or end scenes.
If there is an animator created and returned from this method, the
transition mechanism will apply any applicable duration, startDelay,
and interpolator to that animation and start it. A return value of
null
indicates that no animation should run. The default
implementation returns null.
The method is called for every applicable target object, which is
stored in the
view
field.
sceneRoot | The root of the transition hierarchy. |
---|---|
startValues | The values for a specific target in the start scene. |
endValues | The values for the target in the end scene. |
Whether to add the children of given target to the list of target children
to exclude from this transition. The
exclude
parameter specifies
whether the target should be added to or removed from the excluded list.
Excluding targets is a general mechanism for allowing transitions to run on
a view hierarchy while skipping target views that should not be part of
the transition. For example, you may want to avoid animating children
of a specific ListView or Spinner. Views can be excluded either by their
id, or by their instance reference, or by the Class of that view
(eg,
Spinner
).
target | The target to ignore when running this transition. |
---|---|
exclude | Whether to add the target to or remove the target from the current list of excluded targets. |
Whether to add the given type to the list of types whose children should
be excluded from this transition. The
exclude
parameter
specifies whether the target type should be added to or removed from
the excluded list.
Excluding targets is a general mechanism for allowing transitions to run on
a view hierarchy while skipping target views that should not be part of
the transition. For example, you may want to avoid animating children
of a specific ListView or Spinner. Views can be excluded either by their
id, or by their instance reference, or by the Class of that view
(eg,
Spinner
).
type | The type to ignore when running this transition. |
---|---|
exclude | Whether to add the target type to or remove it from the current list of excluded target types. |
Whether to add the children of the given id to the list of targets to exclude
from this transition. The
exclude
parameter specifies whether
the children of the target should be added to or removed from the excluded list.
Excluding children in this way provides a simple mechanism for excluding all
children of specific targets, rather than individually excluding each
child individually.
Excluding targets is a general mechanism for allowing transitions to run on
a view hierarchy while skipping target views that should not be part of
the transition. For example, you may want to avoid animating children
of a specific ListView or Spinner. Views can be excluded either by their
id, or by their instance reference, or by the Class of that view
(eg,
Spinner
).
targetId | The id of a target whose children should be ignored when running this transition. |
---|---|
exclude | Whether to add the target to or remove the target from the current list of excluded-child targets. |
Whether to add the given id to the list of target ids to exclude from this
transition. The
exclude
parameter specifies whether the target
should be added to or removed from the excluded list.
Excluding targets is a general mechanism for allowing transitions to run on
a view hierarchy while skipping target views that should not be part of
the transition. For example, you may want to avoid animating children
of a specific ListView or Spinner. Views can be excluded either by their
id, or by their instance reference, or by the Class of that view
(eg,
Spinner
).
targetId | The id of a target to ignore when running this transition. |
---|---|
exclude | Whether to add the target to or remove the target from the current list of excluded targets. |
Whether to add the given type to the list of types to exclude from this
transition. The
exclude
parameter specifies whether the target
type should be added to or removed from the excluded list.
Excluding targets is a general mechanism for allowing transitions to run on
a view hierarchy while skipping target views that should not be part of
the transition. For example, you may want to avoid animating children
of a specific ListView or Spinner. Views can be excluded either by their
id, or by their instance reference, or by the Class of that view
(eg,
Spinner
).
type | The type to ignore when running this transition. |
---|---|
exclude | Whether to add the target type to or remove it from the current list of excluded target types. |
Whether to add the given target to the list of targets to exclude from this
transition. The
exclude
parameter specifies whether the target
should be added to or removed from the excluded list.
Excluding targets is a general mechanism for allowing transitions to run on
a view hierarchy while skipping target views that should not be part of
the transition. For example, you may want to avoid animating children
of a specific ListView or Spinner. Views can be excluded either by their
id, or by their instance reference, or by the Class of that view
(eg,
Spinner
).
target | The target to ignore when running this transition. |
---|---|
exclude | Whether to add the target to or remove the target from the current list of excluded targets. |
Returns the duration set on this transition. If no duration has been set, the returned value will be negative, indicating that resulting animators will retain their own durations.
Returns the interpolator set on this transition. If no interpolator has been set, the returned value will be null, indicating that resulting animators will retain their own interpolators.
Returns the name of this Transition. This name is used internally to distinguish between different transitions to determine when interrupting transitions overlap. For example, a ChangeBounds running on the same target view as another ChangeBounds should determine whether the old transition is animating to different end values and should be canceled in favor of the new transition.
By default, a Transition's name is simply the value of
getName()
,
but subclasses are free to override and return something different.
Returns the startDelay set on this transition. If no startDelay has been set, the returned value will be negative, indicating that resulting animators will retain their own startDelays.
Returns the array of target IDs that this transition limits itself to
tracking and animating. If the array is null for both this method and
getTargets()
, then this transition is
not limited to specific views, and will handle changes to any views
in the hierarchy of a scene change.
Returns the array of target views that this transition limits itself to
tracking and animating. If the array is null for both this method and
getTargetIds()
, then this transition is
not limited to specific views, and will handle changes to any views
in the hierarchy of a scene change.
Returns the set of property names used stored in the
TransitionValues
object passed into
captureStartValues(TransitionValues)
that
this transition cares about for the purposes of canceling overlapping animations.
When any transition is started on a given scene root, all transitions
currently running on that same scene root are checked to see whether the
properties on which they based their animations agree with the end values of
the same properties in the new transition. If the end values are not equal,
then the old animation is canceled since the new transition will start a new
animation to these new values. If the values are equal, the old animation is
allowed to continue and no new animation is started for that transition.
A transition does not need to override this method. However, not doing so will mean that the cancellation logic outlined in the previous paragraph will be skipped for that transition, possibly leading to artifacts as old transitions and new transitions on the same targets run in parallel, animating views toward potentially different end values.
TransitionValues
. The default implementation returns
null
.
This method can be called by transitions to get the TransitionValues for any particular view during the transition-playing process. This might be necessary, for example, to query the before/after state of related views for a given transition.
Removes a listener from the set listening to this animation.
listener | the listener to be removed from the current set of listeners for this transition. |
---|
Removes the given targetId from the list of ids that this Transition is interested in animating.
targetId | The id of a target view, must be a positive number. |
---|
transitionSet.addTransitions(new Fade()).removeTargetId(someId);
Removes the given target from the list of targets that this Transition is interested in animating.
target | The target view, must be non-null. |
---|
transitionSet.addTransitions(new Fade()).removeTarget(someView);
Sets the duration of this transition. By default, there is no duration (indicated by a negative number), which means that the Animator created by the transition will have its own specified duration. If the duration of a Transition is set, that duration will override the Animator duration.
duration | The length of the animation, in milliseconds. |
---|
Sets the interpolator of this transition. By default, the interpolator is null, which means that the Animator created by the transition will have its own specified interpolator. If the interpolator of a Transition is set, that interpolator will override the Animator interpolator.
interpolator | The time interpolator used by the transition |
---|
Sets the startDelay of this transition. By default, there is no delay (indicated by a negative number), which means that the Animator created by the transition will have its own specified startDelay. If the delay of a Transition is set, that delay will override the Animator delay.
startDelay | The length of the delay, in milliseconds. |
---|
Returns a string containing a concise, human-readable description of this object. Subclasses are encouraged to override this method and provide an implementation that takes into account the object's type and data. The default implementation is equivalent to the following expression:
getClass().getName() + '@' + Integer.toHexString(hashCode())
See
Writing a useful
toString
method
if you intend implementing your own
toString
method.