# Class Motion

java.lang.Object
com.codename1.ui.animations.Motion

public class Motion extends Object

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.

- ## Constructor Summary

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

- ## Method Summary

  Modifier and Type
  Method
  Description
  `int`
  `countAvailableVelocitySamplingPoints()`
  Gets the number of sampling points that can be used by `#getVelocity()`.
  `static Motion`
  `createCriticalDampedSpringMotion(int sourceValue, int destinationValue, int duration)`
  Creates a critically-damped spring motion from source to destination.
  `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.
  `static Motion`
  `createDecelerationMotion(int sourceValue, int destinationValue, int duration)`
  Creates a deceleration motion starting from source value all the way to destination value
  `static Motion`
  `createDecelerationMotionFrom(Motion motion, int maxDestinationValue, int maxDuration)`
  Creates a deceleration motion starting from the current position of another motion.
  `static Motion`
  `createEaseInMotion(int sourceValue, int destinationValue, int duration)`
  Equivalent to createCubicBezierMotion with 0f, 0.42f, 1f, 1f as arguments.
  `static Motion`
  `createEaseInOutMotion(int sourceValue, int destinationValue, int duration)`
  Equivalent to createCubicBezierMotion with 0, 0.42, 0.58, 1.0 as arguments.
  `static Motion`
  `createEaseMotion(int sourceValue, int destinationValue, int duration)`
  Equivalent to createCubicBezierMotion with 0f, 0.25f, 0.25f, 1 as arguments.
  `static Motion`
  `createEaseOutMotion(int sourceValue, int destinationValue, int duration)`
  Equivalent to createCubicBezierMotion with 0f, 0f, 0.58f, 1.0f as arguments.
  `static Motion`
  `createExponentialDecayMotion(int sourceValue, int maxValue, double initVelocity, double timeConstant)`
  `static Motion`
  `createFrictionMotion(int sourceValue, int maxValue, float initVelocity, float friction)`
  Creates a friction motion starting from source with initial speed and the friction
  `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.
  `static Motion`
  `createLinearMotion(int sourceValue, int destinationValue, int duration)`
  Creates a linear motion starting from source value all the way to destination value
  `static Motion`
  `createSplineMotion(int sourceValue, int destinationValue, int duration)`
  Creates a spline motion starting from source value all the way to destination value
  `void`
  `finish()`
  Sends the motion to the end time instantly which is useful for flushing an animation
  `long`
  `getCurrentMotionTime()`
  Returns the current time within the motion relative to start time
  `int`
  `getDestinationValue()`
  The number to which we will reach when the motion is finished
  `int`
  `getDuration()`
  Returns the animation duration
  `int`
  `getSourceValue()`
  The number from which we are starting (usually indicating animation start position)
  `protected long`
  `getStartTime()`
  The value of System.currentTimemillis() when motion was started
  `int`
  `getValue()`
  Returns the value for the motion for the current clock time.
  `double`
  `getVelocity()`
  Gets an approximation of the current velocity in pixels per millisecond.
  `boolean`
  `isDecayMotion()`
  `boolean`
  `isFinished()`
  Returns true if the motion has run its course and has finished meaning the current time is greater than startTime + duration.
  `static boolean`
  `isSlowMotion()`
  Allows debugging motion behavior by slowing motions down 50 fold, doesn't apply to friction motion
  `void`
  `setCurrentMotionTime(long currentMotionTime)`
  Allows overriding the getCurrentMotionTime method value with a manual value to provide full developer control over animation speed/position.
  `static void`
  `setSlowMotion(boolean aSlowMotion)`
  Allows debugging motion behavior by slowing motions down 50 fold, doesn't apply to friction motion
  `void`
  `setSourceValue(int sourceValue)`
  The number from which we are starting (usually indicating animation start position)
  `void`
  `setStartTime(long startTime)`
  Sets the start time of the motion
  `void`
  `start()`
  Sets the start time to the current time

  ### Methods inherited from class Object

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

- ## Constructor Details

  - ### Motion

    protected Motion(int sourceValue, int destinationValue, int duration)

    Construct a point/destination motion

    ###### Parameters

    - `sourceValue`: starting value

    - `destinationValue`: destination value

    - `duration`: motion duration

  - ### Motion

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

    Construct a velocity motion

    ###### Parameters

    - `sourceValue`: starting value

    - `initVelocity`: initial velocity

    - `friction`: 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`: 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`: starting value

    - `destinationValue`: destination value

    - `duration`: motion duration

    - `p0`: argument to the bezier function

    - `p1`: argument to the bezier function

    - `p2`: argument to the bezier function

    - `p3`: argument to the bezier function

    ###### 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`: starting value

    - `destinationValue`: destination value

    - `duration`: 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`: starting value

    - `destinationValue`: destination value

    - `duration`: 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`: starting value

    - `destinationValue`: destination value

    - `duration`: 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`: starting value

    - `destinationValue`: destination value

    - `duration`: 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`: the number from which we are starting (usually indicating animation start position)

    - `destinationValue`: the number to which we are heading (usually indicating animation destination)

    - `duration`: @param duration 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`: the color from which we are starting

    - `destinationValue`: the destination color

    - `duration`: @param duration 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`: the number from which we are starting (usually indicating animation start position)

    - `destinationValue`: the number to which we are heading (usually indicating animation destination)

    - `duration`: @param duration 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`: the number from which we are starting (usually indicating animation start position)

    - `destinationValue`: the number to which we are heading (usually indicating animation destination)

    - `duration`: @param duration 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`: the number from which we are starting

    - `destinationValue`: the number to which we are heading

    - `duration`: 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`: the number from which we are starting (usually indicating animation start position)

    - `maxDestinationValue`: The farthest position to allow motion to go.

    - `maxDuration`: 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`: the number from which we are starting (usually indicating animation start position)

    - `maxValue`: the maximum value for the friction

    - `initVelocity`: the starting velocity

    - `friction`: 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`: 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`: 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`: the starting time

  - ### getDuration

    public int getDuration()

    Returns the animation duration

    ###### Returns

    animation duration in milliseconds