# 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`