com.nokia.mid.ui.frameanimator
Class FrameAnimator

java.lang.Object
  com.nokia.mid.ui.frameanimator.FrameAnimator

public class FrameAnimator
extends java.lang.Object

A FrameAnimator is a class that can be used to create linear or decelerated animations. A common use for it is to realize scrolling in UI-components. An application can create an instance of FrameAnimator, activate it by specifying a FrameAnimatorListener, and then trigger an animation by feeding movement-data (coordinates or a direction and speed) into it. Subsequently, the platform will ensure that FrameAnimatorListener.animate(FrameAnimator animator, int x, int y, short delta, short delta, short deltaY, boolean lastFrame) is called (possibly repeatedly) to describe the resulting animation.

An animation is described by the FrameAnimator via a single coordinate A (x,y). An application that uses the FrameAnimator has to specify an initial value for A in register(int x, int y, short maxFps, short maxPps, FrameAnimatorListener listener). Then, after the application has triggered an animation via drag(int x, int y) or kineticScroll(int startSpeed, int direction, int friction, float angle), A is updated by the platform and fed back to the application in FrameAnimatorListener.animate(FrameAnimator animator, int x, int y, short delta, short delta, short deltaY, boolean lastFrame) An ongoing animation can be interrupted at any time by the application by calling stop().

The properties of animations can be controlled in the following ways:

It is possible to influence how often FrameAnimatorListener.animate(FrameAnimator animator, int x, int y, short delta, short delta, short deltaY, boolean lastFrame) is being called during an animation, by specifying the number of frames per second via maxFps in register(int x, int y, short maxFps, short maxPps, FrameAnimatorListener listener)

The actual speed of the animation, i.e. by how much the values of A are changing per frame and time-unit (delta) can be controlled via the speed and friction parameters in kineticScroll(int startSpeed, int direction, int friction, float angle). Additionally, it is possible to specify an upper limit for this delta with the maxPps parameter in register(int x, int y, short maxFps, short maxPps, FrameAnimatorListener listener).

The platforms default-values for frames-per-second and maximum-pixels-per-second can be queried via the system properties System.property("com.nokia.mid.ui.frameanimator.fps") and System.property("com.nokia.mid.ui.frameanimator.pps").

The number of FrameAnimators that can be active at a time is limited to FRAME_ANIMATOR_MAX_CONCURRENT. If an application tries to register a FrameAnimator while the maximum number of concurrent FrameAnimators has been reached, register(int x, int y, short maxFps, short maxPps, FrameAnimatorListener listener) will return false. The application must then first call unregister() on one of its other active FrameAnimators. An application can query the number of its currently registered FrameAnimators with getNumRegisteredFrameAnimators()

Field Summary

static int	FRAME_ANIMATOR_FREE_ANGLE Constant to describe movement in any given direction
static int	FRAME_ANIMATOR_FRICTION_HIGH Constant to describe high friction
static int	FRAME_ANIMATOR_FRICTION_LOW Constant to describe low friction
static int	FRAME_ANIMATOR_FRICTION_MEDIUM Constant to describe medium friction
static int	FRAME_ANIMATOR_HORIZONTAL Constant to describe horizontal movement
static int	FRAME_ANIMATOR_MAX_CONCURRENT Constant that specifies that maximum number of FrameAnimators that can be registered concurrently
static int	FRAME_ANIMATOR_VERTICAL Constant to describe vertical movement

Constructor Summary

FrameAnimator()
Creates a new FrameAnimator-instance

Method Summary

void	drag(int x, int y) Method to issue a linear drag-movement.
static int	getNumRegisteredFrameAnimators() Gets the number of currently registered FrameAnimators
boolean	isRegistered() Returns whether this FrameAniamtor is currently registered
void	kineticScroll(int speed, int direction, int friction, float angle) Initiates a step-by-step kinetic animation, moving A from the current (x,y) coordinate to a new position, which is described by a direction, speed and friction, according to the frame rate and max-pixels-per-second specified by the MIDlet in the register(int x, int y, short maxFps, short maxPps, FrameAnimatorListener listener) method.
void	limitedKineticScroll(int speed, int direction, int friction, float angle, int limitUp, int limitDown)
boolean	register(int x, int y, short maxFps, short maxPps, FrameAnimatorListener listener) Registers this FrameAnimator as active.
void	stop() Aborts an ongoing movement.
void	unregister() Deactivates this FrameAnimator immediately.

Methods inherited from class java.lang.Object

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

Field Detail

FRAME_ANIMATOR_MAX_CONCURRENT

public static final int FRAME_ANIMATOR_MAX_CONCURRENT

Constant that specifies that maximum number of FrameAnimators that can be registered concurrently

See Also:

Constant Field Values

FRAME_ANIMATOR_VERTICAL

public static final int FRAME_ANIMATOR_VERTICAL

Constant to describe vertical movement

See Also:

Constant Field Values

FRAME_ANIMATOR_HORIZONTAL

public static final int FRAME_ANIMATOR_HORIZONTAL

Constant to describe horizontal movement

See Also:

Constant Field Values

FRAME_ANIMATOR_FREE_ANGLE

public static final int FRAME_ANIMATOR_FREE_ANGLE

Constant to describe movement in any given direction

See Also:

Constant Field Values

FRAME_ANIMATOR_FRICTION_LOW

public static final int FRAME_ANIMATOR_FRICTION_LOW

Constant to describe low friction

See Also:

Constant Field Values

FRAME_ANIMATOR_FRICTION_MEDIUM

public static final int FRAME_ANIMATOR_FRICTION_MEDIUM

Constant to describe medium friction

See Also:

Constant Field Values

FRAME_ANIMATOR_FRICTION_HIGH

public static final int FRAME_ANIMATOR_FRICTION_HIGH

Constant to describe high friction

See Also:

Constant Field Values

Constructor Detail

FrameAnimator

public FrameAnimator()

Creates a new FrameAnimator-instance

Method Detail

register

public boolean register(int x,
                        int y,
                        short maxFps,
                        short maxPps,
                        FrameAnimatorListener listener)

Registers this FrameAnimator as active. If this method returns true, the FrameAnimator can be considered active, and can receive calls to its drag(int x, int y), kineticScroll(int startSpeed, int direction, int friction, float angle) and stop() methods.

Parameters:

x - The initial x-value

y - The initial y-value

maxFps - Percentage value, which is used to calculate the final max-frames-per- second value. This final value determines an upper limit for how often FrameAnimatorListener.animate(FrameAnimator animator, int x, int y, short delta, short delta, short deltaY, boolean lastFrame) will be called per second. However the actual frame rate can be lower, depending on the performance of platform. If set to 0, then the default-value will be used. Possible values: 1-200.

maxPps - Percentage value, which is used to calculate the final maximum pixels per second value. If set to 0, then the default-value will be used. Possible values: 1-200

listener - The FrameAnimatorListener to be notified as the animation progresses. It is possible to register the same listener with more than one FrameAnimator.

Returns:

true if the FrameAnimator was successfully registered. false otherwise.

Throws:

java.lang.IllegalStateException - if this FrameAnimator has already been registered.

java.lang.NullPointerException - if listener is null

java.lang.IllegalArgumentException - if coordinate is out of bounds (Less than 0 or greater than 65535)

unregister

public void unregister()

Deactivates this FrameAnimator immediately. Any ongoing movement will be aborted. After this method returns, no more calls must be made to its drag(int x, int y) or kineticScroll(int startSpeed, int direction, int friction, float angle) methods until the FrameAnimator is registered again.

Throws:

java.lang.IllegalStateException - if this FrameAnimator has not been registered

drag

public void drag(int x,
                 int y)

Method to issue a linear drag-movement. Calling this method will trigger this FrameAnimators listeners FrameAnimatorListener.animate(FrameAnimator animator, int x, int y, short delta, short delta, short deltaY, boolean lastFrame) method to be called one or more times to describe the movement as it happens. The platform guarantees that those calls occur within the specified frame rate. If this method is called repeatedly, some intermediate drags might be skipped, so the last call may be fed back to FrameAnimatorListener.animate(FrameAnimator animator, int x, int y, short delta, short delta, short deltaY, boolean lastFrame).

Parameters:

x - The new x-coordinate

y - The new y-coordinate

Throws:

java.lang.IllegalStateException - if this FrameAnimator has not been registered

java.lang.IllegalArgumentException - if coordinate is out of bounds (Less than 0 or greater than 65535)

kineticScroll

public void kineticScroll(int speed,
                          int direction,
                          int friction,
                          float angle)

Initiates a step-by-step kinetic animation, moving A from the current (x,y) coordinate to a new position, which is described by a direction, speed and friction, according to the frame rate and max-pixels-per-second specified by the MIDlet in the register(int x, int y, short maxFps, short maxPps, FrameAnimatorListener listener) method.
The new position will share the same x or y-coordinate with the current coordinate of A if either FRAME_ANIMATOR_HORIZONTAL or FRAME_ANIMATOR_VERTICAL are passed as direction. In this case, the value of angle will be ignored. If direction is set to FRAME_ANIMATOR_FREE_ANGLE, angle has to describe the direction of the interpolated animation in radians:

x = 0, y = 0 ->+------------------------ positive x
               |
               |        direction_angle_radians
               |        =======================
               |
               |                -pi/2
               |                  |
               |                  |
               |   pi or -pi -----+----- 0
               |                  |
               |                  |
               |                 pi/2
               |
           positive y

           

Calling this method will cause FrameAnimatorListener.animate(FrameAnimator animator, int x, int y, short delta, short delta, short deltaY, boolean lastFrame) to be called repeatedly until the interpolation completes, with each successive call updating the (x,y) position in a kinetic fashion according to the speed and deceleration specified by the MIDlet.
This method may be called repeatedly, before an ongoing animation has finished. The result will be equivalent to calling stop() before kineticScroll(int startSpeed, int direction, int friction, float angle).

Parameters:

startSpeed - Initial speed of movement in pixels/second, before any deceleration is applied.

direction - Direction of movement. Must be either FRAME_ANIMATOR_HORIZONTAL, FRAME_ANIMATOR_VERTICAL or FRAME_ANIMATOR_FREE_ANGLE

friction - Friction-value which affects the deceleration. Must be one of FRAME_ANIMATOR_FRICTION_LOW, FRAME_ANIMATOR_FRICTION_MEDIUM or FRAME_ANIMATOR_FRICTION_HIGH

angle - Angle of direction in radians

Throws:

java.lang.IllegalStateException - if this FrameAnimator has not been registered

limitedKineticScroll

public void limitedKineticScroll(int speed,
                                 int direction,
                                 int friction,
                                 float angle,
                                 int limitUp,
                                 int limitDown)

stop

public void stop()

Aborts an ongoing movement. No more calls to this FrameAnimators listeners FrameAnimatorListener.animate(FrameAnimator animator, int x, int y, short delta, short delta, short deltaY, boolean lastFrame) method will occur after this method returns, until a new movement is triggered via drag(int x, int y) or kineticScroll(int startSpeed, int direction, int friction, float angle)

Throws:

java.lang.IllegalStateException - if this FrameAnimator has not been registered

isRegistered

public boolean isRegistered()

Returns whether this FrameAniamtor is currently registered

Returns:

true if active, false otherwise

getNumRegisteredFrameAnimators

public static int getNumRegisteredFrameAnimators()

Gets the number of currently registered FrameAnimators

Returns:

number of registered FrameAnimators