public class Motion

  1. Object
  2. Motion

Abstracts the notion of physical motion over time from a numeric location to another. This class can be subclassed to implement any motion equation for appropriate physics effects.

This class relies on AnimationTime.now() to provide transitions between coordinates, allowing the underlying clock to be overridden for deterministic playback or custom animation pacing. The motion can be subclassed to provide every type of motion feel from parabolic motion to spline and linear motion. The default implementation provides a simple algorithm giving the feel of acceleration and deceleration.

Constructors

protected Motion(int sourceValue, int destinationValue, int duration)Construct a point/destination motion
protected Motion(int sourceValue, float initVelocity, float friction)Construct a velocity motion
protected Motion(int sourceValue, double initVelocity, double friction)

Methods

public static boolean isSlowMotion()Allows debugging motion behavior by slowing motions down 50 fold, doesn’t apply to friction motion
public static void setSlowMotion(boolean aSlowMotion)Allows debugging motion behavior by slowing motions down 50 fold, doesn’t apply to friction motion
public static Motion createCubicBezierMotion(int sourceValue, int destinationValue, int duration, float p0, float p1, float p2, float p3)Creates a standard Cubic Bezier motion to implement functions such as ease-in/out etc.
public static Motion createThreePointCubicMotion(int sourceValue, int destinationValue, int duration, float a1X, float a1Y, float b1X, float b1Y, float midX, float midY, float a2X, float a2Y, float b2X, float b2Y)A curve made of TWO cubic beziers joined at a point, which a single cubic cannot express.
public static Motion createEaseInOutMotion(int sourceValue, int destinationValue, int duration)Equivalent to createCubicBezierMotion with 0, 0.42, 0.58, 1.0 as arguments.
public static Motion createEaseMotion(int sourceValue, int destinationValue, int duration)Equivalent to createCubicBezierMotion with 0f, 0.25f, 0.25f, 1 as arguments.
public static Motion createEaseInMotion(int sourceValue, int destinationValue, int duration)Equivalent to createCubicBezierMotion with 0f, 0.42f, 1f, 1f as arguments.
public static Motion createEaseOutMotion(int sourceValue, int destinationValue, int duration)Equivalent to createCubicBezierMotion with 0f, 0f, 0.58f, 1.0f as arguments.
public static Motion createLinearMotion(int sourceValue, int destinationValue, int duration)Creates a linear motion starting from source value all the way to destination value
public static Motion createLinearColorMotion(int sourceValue, int destinationValue, int duration)Creates a linear motion starting from source value all the way to destination value for a color value.
public static Motion createSplineMotion(int sourceValue, int destinationValue, int duration)Creates a spline motion starting from source value all the way to destination value
public static Motion createDecelerationMotion(int sourceValue, int destinationValue, int duration)Creates a deceleration motion starting from source value all the way to destination value
public static Motion createCriticalDampedSpringMotion(int sourceValue, int destinationValue, int duration)Creates a critically-damped spring motion from source to destination.
public static Motion createDecelerationMotionFrom(Motion motion, int maxDestinationValue, int maxDuration)Creates a deceleration motion starting from the current position of another motion.
public static Motion createFrictionMotion(int sourceValue, int maxValue, float initVelocity, float friction)Creates a friction motion starting from source with initial speed and the friction
public static Motion createExponentialDecayMotion(int sourceValue, int maxValue, double initVelocity, double timeConstant)
public void finish()Sends the motion to the end time instantly which is useful for flushing an animation
public void start()Sets the start time to the current time
public long getCurrentMotionTime()Returns the current time within the motion relative to start time
public void setCurrentMotionTime(long currentMotionTime)Allows overriding the getCurrentMotionTime method value with a manual value to provide full developer control over animation speed/position.
public boolean isDecayMotion()
public boolean isFinished()Returns true if the motion has run its course and has finished meaning the current time is greater than startTime + duration.
public int getValue()Returns the value for the motion for the current clock time.
public double getVelocity()Gets an approximation of the current velocity in pixels per millisecond.
public int countAvailableVelocitySamplingPoints()Gets the number of sampling points that can be used by #getVelocity().
public int getSourceValue()The number from which we are starting (usually indicating animation start position)
public void setSourceValue(int sourceValue)The number from which we are starting (usually indicating animation start position)
public int getDestinationValue()The number to which we will reach when the motion is finished
protected long getStartTime()The value of System.currentTimemillis() when motion was started
public void setStartTime(long startTime)Sets the start time of the motion
public int getDuration()Returns the animation duration

Inherited methods

From Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait, clone

Constructor details

Motion

protected Motion(int sourceValue, int destinationValue, int duration)
Construct a point/destination motion

Parameters

sourceValue int
starting value
destinationValue int
destination value
duration int
motion duration

Motion

protected Motion(int sourceValue, float initVelocity, float friction)
Construct a velocity motion

Parameters

sourceValue int
starting value
initVelocity float
initial velocity
friction float
degree of friction

Motion

protected Motion(int sourceValue, double initVelocity, double friction)

Method details

isSlowMotion

public static boolean isSlowMotion()
Allows debugging motion behavior by slowing motions down 50 fold, doesn’t apply to friction motion

Returns

the slowMotion

setSlowMotion

public static void setSlowMotion(boolean aSlowMotion)
Allows debugging motion behavior by slowing motions down 50 fold, doesn’t apply to friction motion

Parameters

aSlowMotion boolean
the slowMotion to set

createCubicBezierMotion

public static Motion createCubicBezierMotion(int sourceValue, int destinationValue, int duration, float p0, float p1, float p2, float p3)
Creates a standard Cubic Bezier motion to implement functions such as ease-in/out etc.

Parameters

sourceValue int
starting value
destinationValue int
destination value
duration int
motion duration
p0 float
argument to the bezier function
p1 float
argument to the bezier function
p2 float
argument to the bezier function
p3 float
argument to the bezier function

Returns

Motion instance

createThreePointCubicMotion

public static Motion createThreePointCubicMotion(int sourceValue, int destinationValue, int duration, float a1X, float a1Y, float b1X, float b1Y, float midX, float midY, float a2X, float a2Y, float b2X, float b2Y)

A curve made of TWO cubic beziers joined at a point, which a single cubic cannot express.

A plain cubic-bezier is monotonic in a way some motion is not: it cannot accelerate hard, ease, and then ease out again, because it has only two control points to spend. Curves that do this are specified as a pair of beziers meeting at a midpoint, each with its own controls, and the joint is where the character of the motion changes.

The segments are evaluated in their own normalized space and rescaled, so each half is an ordinary CSS cubic-bezier and the two meet exactly at the midpoint.

Parameters

sourceValue int
the initial value
destinationValue int
the value at the end of the motion
duration int
the motion duration in milliseconds
a1X float
, a1Y, b1X, b1Y: control points of the first segment
a1Y float
Not documented.
b1X float
Not documented.
b1Y float
Not documented.
midX float
, midY: the point the two segments meet at
midY float
Not documented.
a2X float
, a2Y, b2X, b2Y: control points of the second segment
a2Y float
Not documented.
b2X float
Not documented.
b2Y float
Not documented.

Returns

Motion instance

createEaseInOutMotion

public static Motion createEaseInOutMotion(int sourceValue, int destinationValue, int duration)
Equivalent to createCubicBezierMotion with 0, 0.42, 0.58, 1.0 as arguments.

Parameters

sourceValue int
starting value
destinationValue int
destination value
duration int
motion duration

Returns

Motion instance

createEaseMotion

public static Motion createEaseMotion(int sourceValue, int destinationValue, int duration)
Equivalent to createCubicBezierMotion with 0f, 0.25f, 0.25f, 1 as arguments.

Parameters

sourceValue int
starting value
destinationValue int
destination value
duration int
motion duration

Returns

Motion instance

createEaseInMotion

public static Motion createEaseInMotion(int sourceValue, int destinationValue, int duration)
Equivalent to createCubicBezierMotion with 0f, 0.42f, 1f, 1f as arguments.

Parameters

sourceValue int
starting value
destinationValue int
destination value
duration int
motion duration

Returns

Motion instance

createEaseOutMotion

public static Motion createEaseOutMotion(int sourceValue, int destinationValue, int duration)
Equivalent to createCubicBezierMotion with 0f, 0f, 0.58f, 1.0f as arguments.

Parameters

sourceValue int
starting value
destinationValue int
destination value
duration int
motion duration

Returns

Motion instance

createLinearMotion

public static Motion createLinearMotion(int sourceValue, int destinationValue, int duration)
Creates a linear motion starting from source value all the way to destination value

Parameters

sourceValue int
the number from which we are starting (usually indicating animation start position)
destinationValue int
the number to which we are heading (usually indicating animation destination)
duration int
the length in milliseconds of the motion (time it takes to get from sourceValue to destinationValue)

Returns

new motion object

createLinearColorMotion

public static Motion createLinearColorMotion(int sourceValue, int destinationValue, int duration)
Creates a linear motion starting from source value all the way to destination value for a color value. Unlike a regular linear motion a color linear motion is shifted based on channels where red, green & blue get shifted separately.

Parameters

sourceValue int
the color from which we are starting
destinationValue int
the destination color
duration int
the length in milliseconds of the motion (time it takes to get from sourceValue to destinationValue)

Returns

new motion object

createSplineMotion

public static Motion createSplineMotion(int sourceValue, int destinationValue, int duration)
Creates a spline motion starting from source value all the way to destination value

Parameters

sourceValue int
the number from which we are starting (usually indicating animation start position)
destinationValue int
the number to which we are heading (usually indicating animation destination)
duration int
the length in milliseconds of the motion (time it takes to get from sourceValue to destinationValue)

Returns

new motion object

createDecelerationMotion

public static Motion createDecelerationMotion(int sourceValue, int destinationValue, int duration)
Creates a deceleration motion starting from source value all the way to destination value

Parameters

sourceValue int
the number from which we are starting (usually indicating animation start position)
destinationValue int
the number to which we are heading (usually indicating animation destination)
duration int
the length in milliseconds of the motion (time it takes to get from sourceValue to destinationValue)

Returns

new motion object

createCriticalDampedSpringMotion

public static Motion createCriticalDampedSpringMotion(int sourceValue, int destinationValue, int duration)
Creates a critically-damped spring motion from source to destination. This is the envelope of a second-order critically damped system step response: x(t) = dst - (dst - src) * (1 + w*t) * e^(-w*t) where w is chosen so the residual at t=duration is about 2%. Produces a quick initial approach with a soft settling tail, closer in feel to the iOS rubber-band snap-back than the quadratic createDecelerationMotion curve.

Parameters

sourceValue int
the number from which we are starting
destinationValue int
the number to which we are heading
duration int
the length in milliseconds of the motion

Returns

new motion object

createDecelerationMotionFrom

public static Motion createDecelerationMotionFrom(Motion motion, int maxDestinationValue, int maxDuration)
Creates a deceleration motion starting from the current position of another motion.

Parameters

motion Motion
the number from which we are starting (usually indicating animation start position)
maxDestinationValue int
The farthest position to allow motion to go.
maxDuration int
The longest that the duration is allowed to proceed for.

Returns

new motion object

createFrictionMotion

public static Motion createFrictionMotion(int sourceValue, int maxValue, float initVelocity, float friction)
Creates a friction motion starting from source with initial speed and the friction

Parameters

sourceValue int
the number from which we are starting (usually indicating animation start position)
maxValue int
the maximum value for the friction
initVelocity float
the starting velocity
friction float
the motion friction

Returns

new motion object

createExponentialDecayMotion

public static Motion createExponentialDecayMotion(int sourceValue, int maxValue, double initVelocity, double timeConstant)

finish

public void finish()
Sends the motion to the end time instantly which is useful for flushing an animation

start

public void start()
Sets the start time to the current time

getCurrentMotionTime

public long getCurrentMotionTime()
Returns the current time within the motion relative to start time

Returns

long value representing AnimationTime.now() - startTime

setCurrentMotionTime

public void setCurrentMotionTime(long currentMotionTime)
Allows overriding the getCurrentMotionTime method value with a manual value to provide full developer control over animation speed/position.

Parameters

currentMotionTime long
the time in milliseconds for the motion.

isDecayMotion

public boolean isDecayMotion()

isFinished

public boolean isFinished()
Returns true if the motion has run its course and has finished meaning the current time is greater than startTime + duration.

Returns

true if AnimationTime.now() > duration + startTime or the last returned value is the destination value

getValue

public int getValue()
Returns the value for the motion for the current clock time. The value is dependent on the Motion type.

Returns

a value that is relative to the source value

getVelocity

public double getVelocity()

Gets an approximation of the current velocity in pixels per millisecond.

NOTE: If #countAvailableVelocitySamplingPoints() 0

Returns

Current velocity in pixels per millisecond.

countAvailableVelocitySamplingPoints

public int countAvailableVelocitySamplingPoints()
Gets the number of sampling points that can be used by #getVelocity(). A minimum of 2 sampling points are required for the result of #getVelocity() to have any meaning.

Returns

The number of sampling points that can be used by #getVelocity().

getSourceValue

public int getSourceValue()
The number from which we are starting (usually indicating animation start position)

Returns

the source value

setSourceValue

public void setSourceValue(int sourceValue)
The number from which we are starting (usually indicating animation start position)

Parameters

sourceValue int
the source value

getDestinationValue

public int getDestinationValue()
The number to which we will reach when the motion is finished

Returns

the source value

getStartTime

protected long getStartTime()
The value of System.currentTimemillis() when motion was started

Returns

the start time

setStartTime

public void setStartTime(long startTime)
Sets the start time of the motion

Parameters

startTime long
the starting time

getDuration

public int getDuration()
Returns the animation duration

Returns

animation duration in milliseconds