Animations

There are many ways to animate and liven the data within a Codename One application, layout animations are probably chief among them. But first you need to understand some basics such as layout reflows.

Layout in tools such as HTML is implicit, when you add something into the UI it’s automatically placed. Other tools such as Codename One use explicit layout, that means you’ve to explicitly request the UI to layout itself after making changes!

When adding a component to a UI that’s already visible, the component won’t show by default.

The chief advantage of explicit layout is performance.

For example, imagine adding 100 components to a form. If the form was laid out automatically, layout would have happened 100 times instead of once when adding was finished. In fact layout reflows are often considered the #1 performance issue for HTML/JavaScript applications.

That’s why, when you add components to a form that’s already showing, you should invoke revalidate() or animate the layout appropriately. This also enables the layout animation behavior explained below.

To understand animations you need to understand a couple of things about Codename One components. When you add a component to a container, it’s added but not positioned anywhere. A novice might notice the setX/setY/setWidth/setHeight methods on a component and try to position it.

This won’t work since these methods are meant for the layout manager, which is implicitly invoked when a form is shown (internally in Codename One). The layout manager uses these methods to position/size the components based on the hints given to it.

If you add components to a form that’s showing, it’s your responsibility to invoke revalidate/layoutContainer to arrange the newly added components (see Layout Reflows).

animateLayout() method is a fancy form of revalidate that animates the components into their laid out position. After changing the layout & invoking this method the components move to their new sizes/positions seamlessly. Form exposes convenience wrappers such as animateLayout*() that forward to the underlying content pane, so you can call the methods directly on the form unless you specifically need to animate a nested container.

This sort of behavior creates a special case where setting the size/position makes sense. When you set the size/position in the demo code here you’re positioning the components at the animation start position above the frame:

Notice these things about this example:

This results in:

While layout animations are powerful effects for adding elements into the UI and drawing attention to them. The inverse of removing an element from the UI is often more important. For example, when you delete or remove an element you want to animate it out.

Layout animations don’t do that since they will try to bring the animated item into place. The exact opposite of a layout animation is the "unlayout animation." Container.animateUnlayout(int, int, Runnable) and the Form.animateUnlayout*() helpers trigger this transition either asynchronously (with a completion callback) or synchronously via the AndWait variants.

The "unlayout animation" takes a valid laid out state and shifts the components to an invalid state that you defined in advance. For example, you can fix the example above to flip the "fall" button into a "rise" button when the buttons come into place and this will allow the buttons to float back up to where they came from in the exact reverse order.

You will notice some similarities with the unlayout animation but the differences represent the exact opposite of the layout animation:

A common trick for animating Components in Codename One is to set their preferred size to 0 and then invoke animateLayout() thus triggering an animation to hide said Component. several issues with this trick but one of the biggest ones is the fact that setPreferredSize has been deprecated for quite a while.

Instead of using that trick you can use setHidden/isHidden who effectively encapsulate this functionality and a bit more.

One of the issues setHidden tries to solve is the fact that preferred size doesn’t include the margin in the total and thus a component might still occupy space despite being hidden. When you request the margin change the current margins are cached, the component is given zero margins while hidden, and those cached values are restored when it’s shown again—without resetting the UIID or other style state.

This functionality might be undesirable which is why there is a version of the setHidden method that accepts a boolean flag indicating whether the margin cache should be manipulated. You can effectively hide/show a component without deprecated code using something like this:

Most animations have two or three variants:

The standard animation is invoked when you don’t care about the completion of the animation. You can do this for a standard animation.

The AndWait variant blocks the calling thread until the animation completes. This is useful for sequencing animations one after the other e.g this code from the kitchen sink demo:

First the UI goes through an "unlayout" animation, once that completes the layout itself is performed.

The callback variant is like the invokeAndBlock variant but uses a more conventional callback semantic which is more familiar to some developers. It accepts a Runnable callback that will be invoked after the fact. For example, you can change the unlayout call from before to use the callback semantics as such:

There are several more variations on the standard animate methods. Several methods accept a numeric fade argument. This is useful to fade out an element in an "unlayout" operation or fade in a regular animation.

The value for the fade argument is a number between 0 and 255 where 0 represents full transparency and 255 represents full opacity.

Some animate layout methods are hierarchy based. They work like the regular animateLayout methods but recurse into the entire Container hierarchy. These methods work well when you have components in a nested hierarchy that need to animate into place. This is demonstrated in the opening sequence of the kitchen sink demo:

The demoComponents Vector contains components from separate containers and this code would not work with a simple animate layout.

All the animations go through a per-form queue: the AnimationManager. This effectively prevents two animations from mutating the UI in parallel so you won’t have collisions between two conflicting sides. Things get more interesting when you try to do something like this:

The reason this happens is that the second remove gets postponed to the end of the animation so it won’t break the animation. This works for remove and add operations on a Container as well as other animations.

The simple yet problematic fix would be:

Why might that still fail?

Events come in constantly during the run of the EDT ^[6], so an event might come in that might trigger an animation in your code. Even if you’re on the EDT keep in mind that you don’t actually block it and an event might come in.

In those cases an animation might start and you might be unaware of that animation and it might still be in action when you expect remove to work.

AnimationManager has built-in support to fix this exact issue.

You can flush the animation queue and run synchronously after all the animations finished and before new ones come in by using something like this:

The Codename One event dispatch thread has a special animation "pulse" allowing an animation to update its state and draw itself. Code can make use of this pulse to implement repetitive polling tasks that have little to do with drawing.

This is helpful since the callback will always occur on the event dispatch thread.

Every component in Codename One contains an animate() method that returns a boolean value, you can also implement the Animation interface in an arbitrary component to implement your own animation. To receive animation events you need to register yourself within the parent form, it’s the responsibility of the parent for to call animate().

If the animate method returns true then the animation will be painted (the paint method of the Animation interface would be invoked).

If you derive from a component, which has its own animation logic you might damage its animation behavior by deregistering it, so use care with the low-level API’s.

For example, you can add more animation logic using code like this:

Animations comprise two parts, the logic (deciding the position, etc.) and the painting. The paint method should be dedicated to painting, not to the actual moving of the components.

The separation of concerns allows you to avoid redundant painting for example, if animate didn’t trigger a change return false to avoid the overhead related to animations.

You discuss low-level animations in more details within the animation section of the clock demo.

Transitions allow you to replace one component with another, most typically forms or dialogs are replaced with a transition but a transition can be applied to replace any arbitrary component.

Developers can implement their own custom transition and install it to components by deriving the Transition class, although most commonly the built in CommonTransitions class is used for almost everything.

You can define transitions for forms/dialogs/menus globally either via the theme constants or via the LookAndFeel class. Or you can install a transition on top-level components via setter methods.

Themes define the default transitions used when showing a form, these differ based on the OS. In most platforms the default is Slide whereas in iOS the default is SlideFade which slides the content pane and title while fading in/out the content of the title area.

Check out the full set of theme constants in the Theme Constants Section.

To apply a transition to a component you can use the Container.replace() method as such:

Container.replace() can also be used with a null transition at which point it replaces instantly with no transition.

The slide transitions are used to move the Form/Component in a sliding motion to the side or up/down. Four basic types of slide transitions exist:

The code below demonstrates the usage of all the main transitions:

The fade transition is pretty trivial and accepts a time value since it has no directional context.

The FlipTransition is also pretty simple but unlike the others it isn’t a part of the CommonTransitions. It has its own FlipTransition class.

BubbleTransition morphs a component into another component using a circular growth motion.

The BubbleTransition accepts the component that will grow into the bubble effect as one of its arguments. It’s primarily designed for Dialog transitions although it could work for more creative use cases:

Android’s material design has a morphing effect where an element from the previous form (activity) animates into a different component on a new activity. Codename One has a morph effect in the Container class but it doesn’t work as a transition between forms and doesn’t allow for multiple separate components to transition at once.

To support this behavior you have the MorphTransition class that provides this same effect coupled with a fade to the rest of the UI (see Figure 181, “Morph Transition”).

Since the transition is created before the form exists you can’t reference explicit components within the form when creating the morph transition (to show which component becomes which) so you need to refer to them by name. This means you need to use setName(String) on the components in the source/destination forms so the transition will be able to find them:

By default MorphTransition paints both endpoints by re-rendering the live source / destination components every frame at the interpolated bounds. That works well when the source is fully visible — a card in the body of one form morphing to a card in the next.

It runs into edge cases when the source lives inside a scrolling container that has children extending past the source’s bounds, or when the source has dynamic content (a video frame, a BrowserComponent, a custom-painted background) that should be visually frozen for the duration of the animation. The legacy live-paint path can leak off-viewport pixels into the morph because the layered pane that holds the source during the animation doesn’t carry the original parent’s clip.

To opt into the image-snapshot path call snapshotMode(true) on the builder:

snapshotMode(true) captures each (source, dest) pair as a clipped Image at initTransition(), then the tween draws those images at the interpolated bounds rather than re-painting the live components. Off-viewport children of the source are clipped at capture time (the image’s own bounds are the clip), so they can’t leak into the morph.

The default MorphTransition behavior (live paint, no snapshots) is unchanged for back-compat. Use snapshot mode opportunistically when the live-paint output exhibits the off-viewport leak, or when the source’s children produce frame-by-frame visual change you want to freeze.

iOS7+ allows swiping back one form to the previous form, Codename One has an API to enable back swipe transition:

That one command will enable swiping back from currentForm. LazyValue allows you to pass a value lazily:

This effectively allows you to pass a form and create it as necessary (for example, for a GUI builder app you don’t have the actual previous form instance), notice that the arguments aren’t used for this case but will be used in other cases.

The code below should work for the transition sample above. Notice that this API was designed to work with "Slide Fade" transition and might have issues with other transition types: