Class MorphTransition

java.lang.Object
com.codename1.ui.animations.Transition
com.codename1.ui.animations.MorphTransition
All Implemented Interfaces:
Animation
public final class MorphTransition extends Transition

A transition inspired by the Android L release morph activity effect allowing a set of components in one form/container to morph into another in a different container/form.

Beyond the original position / size morph, this transition can also tween the opacity, rotation and scale of each morphed target and can morph arbitrary rendered elements (an Image, a rendered SVG, a snapshot of any Component, ...) that don't have to be named components living in a Form -- see #morph(MorphElement).

The transition is also scrubbable: instead of letting the framework drive it from the animation clock you can step it to an arbitrary normalized position t in [0, 1] with #setProgress(double). Scrubbing is deterministic (it never reads the wall clock), is repeatable, and can move backwards, which makes it compose cleanly with a frame-export loop that renders the same animation at a set of progress fractions.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static final class 
    MorphTransition.MorphElement
    Describes an arbitrary rendered element that the morph tweens between two states: position, size, opacity, rotation and scale.

  • Method Summary

    Modifier and Type
    Method
    Description
    boolean
    animate()
    Allows the animation to reduce "repaint" calls when it returns false.
    void
    cleanup()
    Optional operation to cleanup the garbage left over by a running transition
    Transition
    copy(boolean reverse)
    Create a copy of the transition, usually the transition used is a copy.
    static MorphTransition
    create(int duration)
    Creates a transition with the given duration, this transition should be modified with the builder methods such as morph
    float
    getCurrentOpacity(String sourceName)
    The interpolated opacity (0..1) of a named morph target at the current progress, or 1 when no opacity tween is registered for that name.
    float
    getCurrentRotation(String sourceName)
    The interpolated rotation (degrees) of a named morph target at the current progress, or 0 when no rotation tween is registered for that name.
    float
    getCurrentScale(String sourceName)
    The interpolated scale multiplier of a named morph target at the current progress, or 1 when no scale tween is registered for that name.
    double
    getProgress()
    Returns the last normalized progress requested through #setProgress(double) (0 until the first call).
    void
    initTransition()
    Callback thats invoked before a transition begins, the source form may be null for the first form in the application.
    boolean
    isScrubbing()
    Returns true once #setProgress(double) has been used to drive this transition manually.
    boolean
    isSnapshotMode()
    Returns the current snapshot-mode setting.
    MorphTransition
    morph(MorphTransition.MorphElement element)
    Morphs an arbitrary rendered element (an Image, a rendered SVG, a snapshot of any Component) between two states.
    MorphTransition
    morph(String cmp)
    Morphs the component with the given source name in the source container hierarchy to the component with the same name in the destination hierarchy
    MorphTransition
    morph(String source, String to)
    Morphs the component with the given source name in the source container hierarchy to the component with the given name in the destination hierarchy
    MorphTransition
    opacity(String sourceName, float fromOpacity, float toOpacity)
    Tweens the opacity of a named morph target from fromOpacity to toOpacity (both in the [0, 1] range) over the course of the transition.
    void
    paint(Graphics g)
    Draws the animation, within a component the standard paint method would be invoked since it bares the exact same signature.
    MorphTransition
    rotation(String sourceName, float fromDegrees, float toDegrees)
    Tweens the rotation of a named morph target from fromDegrees to toDegrees about its center.
    MorphTransition
    scale(String sourceName, float fromScale, float toScale)
    Tweens an extra scale multiplier (about the target center, on top of the interpolated bounds) of a named morph target from fromScale to toScale.
    MorphTransition
    setProgress(double t)
    Steps the transition to a normalized progress t in [0, 1] without reading the animation clock.
    MorphTransition
    snapshotMode(boolean enabled)
    Enables the image-snapshot path.

    Methods inherited from class Transition

    cleanSource, getDestination, getSource, hideInterformContainers, init, paintInterformContainers, showInterformContainers

    Methods inherited from class Object

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

  • Method Details

    • snapshotMode

      public MorphTransition snapshotMode(boolean enabled)

      Enables the image-snapshot path. Each (source, dest) pair is rendered once into an Image at initTransition() (clipped to the component's own bounds; off-viewport children do not contribute pixels), then the tween draws those images at the interpolated (x, y, w, h).

      Use this when:

      • The source lives inside a scrolling container whose scrollX/scrollY would otherwise leak off-viewport child pixels into the morph (the cross-form morph clipping artifact).
      • The source has children with dynamic content (a BrowserComponent, a video frame, a custom-painted background) that should be frozen visually for the duration of the animation.
      • The source's parent applies a clip that the layered pane wouldn't replicate.

      Snapshot mode is also required for the per-named-target #rotation, #scale and #opacity tweens to have a visible effect, since those transforms are applied while drawing the captured image.

      Default is off to preserve back-compat with the legacy live-paint path. Always pair with a screenshot regression test (see scripts/hellocodenameone/.../MorphTransitionTest).

      Parameters
      • enabled: true to snapshot, false for the legacy live-paint mode
      Returns

      this transition (for chaining with #morph(String) etc.)

    • isSnapshotMode

      public boolean isSnapshotMode()
      Returns the current snapshot-mode setting. See #snapshotMode(boolean).

    • create

      public static MorphTransition create(int duration)

      Creates a transition with the given duration, this transition should be modified with the builder methods such as morph

      Parameters
      • duration: the duration of the transition
      Returns

      a new Morph transition instance

    • copy

      public Transition copy(boolean reverse)

      Create a copy of the transition, usually the transition used is a copy.

      Parameters
      • reverse: @param reverse creates a new transition instance with "reverse" behavior useful for signifying "back" operations
      Returns

      new transition instance

      Overrides:
      copy in class Transition

    • morph

      public MorphTransition morph(String cmp)

      Morphs the component with the given source name in the source container hierarchy to the component with the same name in the destination hierarchy

      Parameters
      • cmp: the compoennt name
      Returns

      this so morph operations can be chained as MorphTransition t = MorphTransition.create(300).morph("a").("c");

    • morph

      public MorphTransition morph(String source, String to)

      Morphs the component with the given source name in the source container hierarchy to the component with the given name in the destination hierarchy

      Parameters

      • source

      • to

      Returns

      this so morph operations can be chained as MorphTransition t = MorphTransition.create(300).morph("a", "b").("c", "d");

    • opacity

      public MorphTransition opacity(String sourceName, float fromOpacity, float toOpacity)

      Tweens the opacity of a named morph target from fromOpacity to toOpacity (both in the [0, 1] range) over the course of the transition. The named target must also be registered with #morph(String) / #morph(String, String). The opacity is applied while drawing the captured snapshot, so this requires #snapshotMode(boolean) to be on to have a visible effect.

      Parameters
      • sourceName: the source-side name passed to #morph(String)
      • fromOpacity: the opacity at t = 0, 0 (transparent) to 1 (opaque)
      • toOpacity: the opacity at t = 1
      Returns

      this transition for chaining

    • rotation

      public MorphTransition rotation(String sourceName, float fromDegrees, float toDegrees)

      Tweens the rotation of a named morph target from fromDegrees to toDegrees about its center. Requires #snapshotMode(boolean) to have a visible effect and an affine-capable Graphics (every modern port); where affine isn't supported the rotation is silently skipped.

      Parameters
      • sourceName: the source-side name passed to #morph(String)
      • fromDegrees: rotation in degrees at t = 0
      • toDegrees: rotation in degrees at t = 1
      Returns

      this transition for chaining

    • scale

      public MorphTransition scale(String sourceName, float fromScale, float toScale)

      Tweens an extra scale multiplier (about the target center, on top of the interpolated bounds) of a named morph target from fromScale to toScale. A value of 1 leaves the interpolated size unchanged; use this for a "pop" that overshoots the target box. Requires #snapshotMode(boolean) to have a visible effect.

      Parameters
      • sourceName: the source-side name passed to #morph(String)
      • fromScale: scale multiplier at t = 0
      • toScale: scale multiplier at t = 1
      Returns

      this transition for chaining

    • morph

      public MorphTransition morph(MorphTransition.MorphElement element)

      Morphs an arbitrary rendered element (an Image, a rendered SVG, a snapshot of any Component) between two states. Unlike the named-component morph this does not require the element to be a child of the source / destination form -- the element is drawn as an overlay at the interpolated position, size, opacity, rotation and scale. Multiple elements can be registered and they compose with the named-component morphs.

      Parameters
      • element: the element description built via MorphElement#create
      Returns

      this transition for chaining

    • setProgress

      public MorphTransition setProgress(double t)

      Steps the transition to a normalized progress t in [0, 1] without reading the animation clock. 0 is the source state, 1 the destination state; intermediate values are eased with the same ease-in-out curve the clock-driven path uses. The call is deterministic, repeatable and may move backwards, so it composes with a frame-export loop that renders the animation at a set of progress fractions:

      MorphTransition t = MorphTransition.create(600).morph(element);
t.init(source, dest);
t.initTransition();
for (double f = 0; f <= 1.0; f += 1.0 / frames) {
    t.setProgress(f);
    t.paint(frameGraphics);
}
t.cleanup();

      #initTransition() must have been invoked first (the AbstractTransitionScreenshotTest harness does this for you). Scrubbing and the clock-driven animate() lifecycle are not meant to be mixed on the same instance.

      Parameters
      • t: the normalized progress, clamped to [0, 1]
      Returns

      this transition for chaining

    • getProgress

      public double getProgress()
      Returns the last normalized progress requested through #setProgress(double) (0 until the first call).

    • isScrubbing

      public boolean isScrubbing()
      Returns true once #setProgress(double) has been used to drive this transition manually.

    • getCurrentOpacity

      public float getCurrentOpacity(String sourceName)
      The interpolated opacity (0..1) of a named morph target at the current progress, or 1 when no opacity tween is registered for that name. Primarily useful for tests / custom rendering.

    • getCurrentRotation

      public float getCurrentRotation(String sourceName)
      The interpolated rotation (degrees) of a named morph target at the current progress, or 0 when no rotation tween is registered for that name.

    • getCurrentScale

      public float getCurrentScale(String sourceName)
      The interpolated scale multiplier of a named morph target at the current progress, or 1 when no scale tween is registered for that name.

    • initTransition

      public void initTransition()
      Callback thats invoked before a transition begins, the source form may be null for the first form in the application.
      Overrides:
      initTransition in class Transition

    • animate

      public boolean animate()

      Allows the animation to reduce "repaint" calls when it returns false. It is called once for every frame. Frames are defined by the com.codename1.ui.Display class.

      Returns

      true if a repaint is desired or false if no repaint is necessary

      Specified by:
      animate in interface Animation
      Specified by:
      animate in class Transition

    • cleanup

      public void cleanup()
      Optional operation to cleanup the garbage left over by a running transition
      Overrides:
      cleanup in class Transition

    • paint

      public void paint(Graphics g)

      Draws the animation, within a component the standard paint method would be invoked since it bares the exact same signature.

      Parameters
      • g: graphics context
      Specified by:
      paint in interface Animation
      Specified by:
      paint in class Transition