Package com.nokia.mid.ui.frameanimator

The FrameAnimator API calculates motion interpolation for kinetic scrolling and linear animations.

See:
Description

Interface Summary

FrameAnimatorListener

Interface to receive animation-updates.

Class Summary

FrameAnimator

A FrameAnimator is a class that can be used to create linear or decelerated animations.

Package com.nokia.mid.ui.frameanimator Description

The FrameAnimator API calculates motion interpolation for kinetic scrolling and linear animations. This could be used, for example, to implement list scrolling in response to a flick or drag gesture. See related document on Series 40 Touch and Type UI Gesture API.

This allows quick traversal of long lists. An upwards flick gesture would cause upward movement, which in the case of a scrolling list would result in list elements scrolling onto the screen from the bottom.

The Nokia FrameAnimator API allows a MIDlet to use the platform logic to control the scrolling of its own UI components. This ensures a MIDlet has the same user experience as the core platform. It also simplifies and reduces development time of the MIDlet because the MIDlet doesn't have to implement its own frame animating logic.

The FrameAnimator API itself is very simple. Consisting of a single class FrameAnimator and interface FrameAnimatorListener.

The MIDlet provides its own class that implements FrameAnimatorListener. This interface provides a single method animate which will be called repeatedly for each frame update in the triggered animation. It is up to the MIDlet to redraw the UI on each call to animate. The FrameAnimator API will simply pass to animate the new x and y coordinates, the deltas from the last frame update and whether this is the last frame, or not, in the current animation.

This FrameAnimator API is independent of the Gesture API and so to trigger the animations from the Touch Gestures the MIDlet needs to also register for Gesture Events using the Gesture API.

The FrameAnimator API supports two types of animations; drag and kinetic scroll. These map to the drag and flick Gesture Events respectively.

To use this API a MIDlet must first create an instance of the FrameAnimator class and register the listener.

frameAnimator = new FrameAnimator();
frameAnimator.register(x, y, maxFps, maxPps, listener);

As well as taking the FrameAnimatorListener instance, the register function also takes a reference x and y locations of the UI component being scrolled and the maximum frames per second (maxFps) and maximum pixels per seconds (maxPps) to use. The maxFps and maxPps will control how often the animate method may be called and the distance in pixels between consecutive frame updates.

For Gesture Drag events, call the FrameAnimator drag method with the new x and y location.

case GestureInterativeZone.GESTURE_DRAG:
        frameAnimator.drag( event.getStartX() + event.getDragDistanceX() ,
                        event.getStartY() + event.getDragDistanceY() );

For Gesture Flick events, call the FrameAnimator kineticScroll method with the flick speed and flick direction obtained from the GestureEvent instance. kineticScroll also takes an angle value and a friction value. The angle can be FRAME_ANIMATOR_FREE_ANGLE, FRAME_ANIMATOR_HORIZONTAL or FRAME_ANIMATOR_VERTICAL. This allows you to restrict the kinetic scroll to a particular axis if desired. The friction parameter can be either FRAME_ANIMATOR_FRICTION_LOW, FRAME_ANIMATOR_FRICTION_MEDIUM or FRAME_ANIMATOR_FRICTION_HIGH and controls the rate of deceleration.

case GestureInteractiveZone.GESTURE_FLICK:
        frameAnimator.kineticScroll( event.getFlickSpeed(),
                FrameAnimator.FRAME_ANIMATOR_FREE_ANGLE,
                FrameAnimator.FRAME_ANIMATOR_FRICTION_MEDIUM,
    event.getFlickDirection() );

Since:

1.0