javax.microedition.m2g
Class SVGAnimator

java.lang.Object
  javax.microedition.m2g.SVGAnimator

public abstract class SVGAnimator
extends java.lang.Object

The SVGAnimator class handles automatic rendering of updates and animations in an SVGImage to a target user interface (UI) component. The target component type depends on the Java profile this specification is implemented on, as described in the createAnimator and getTargetComponent methods documentation. There are two types of rendering updates the SVGAnimator handles:

• Animation Updates. The SVGAnimator can run animations and automatically and periodically refreshes its rendering to reflect the effect of animations.
• SVGImage Updates. The SVGAnimator updates its rendering following alterations of the associated SVGImage, for example if the position of one of the graphical elements is modified by an API call.

An SVGAnimator instance can be in one of the following states:

• Stopped. This is the initial state. The SVGAnimator performs no rendering updates.
  Possible transitions:
  • To the playing state, with the play method.
• Playing. This is the typical state for an SVGAnimator. In that state, the SVGAnimator performs both Animation and SVGImage updates. While there are active animations, the animator updates the rendering at a rate not faster than the one defined by the setTimeIncrement method. If SVGImage updates are made (e.g., with calls to the SVGElement setTrait method, see examples), the rendering is updated at the time of the next animation rendering.
  When there are no active animations, the animator will update the rendering after each Runnable passed to the invokeLater or invokeAndWait methods has finished executing.
  Possible transitions:
  • To the stopped state, with the stop method.
  • To the paused state, with the pause method.
• Paused. When in that state, the SVGAnimator only performs SVGImage updates rendering. The animator no longer automatically advances the SVG document's current time, so rendering reflects the animation at the document's current time. Note that a change to the document's current time while in the paused state will trigger a new rendering for the new current time.
  Possible transitions:
  • To the stopped state, with the stop method.
  • To the playing state, with the play method.

The SVGAnimator dispatches events to the SVGEventListener and automatically dispatches events it detects to the SVGImage. Events dispatched by the SVGAnimator are limited to the at-target and bubble phase of the DOM Level 2 event flow.

Code example:

 // Create an SVGAnimator
 SVGImage map = ...; // See the SVGImage documentation.

 SVGAnimator svgAnimator = SVGAnimator.createAnimator(map);

 // Display the associated SVGAnimator component.
 // Depends on the platform.

 // =============== AWT Example ===============
 Panel panel = ....;
 panel.add((Component) svgAnimator.getTargetComponent());
 ...

 // =============== MIDP Example ===============
 Canvas svgCanvas = (Canvas) svgAnimator.getTargetComponent());
 ...

 // Start rendering animations.
 svgAnimator.play();
 ....
 class MapRunnable implements Runnable {
    public void run() {
        // Perform map updates based on current
        // traffic information.
        SVGElement statusRect
             = map.getDocument().getElementById("statusRect");

        // Reflect that traffic status.
        statusRect.setRGBTrait(...); // See setRGBTrait documentation.
    }
 }

 Runnable mapUpdates = new MapRunnable();
 ....

 while (someLoopCondition) {
     if(hasMapUpdate) {
         svgAnimator.invokeAndWait(mapUpdates);
     }
 }
 

Constructor Summary

SVGAnimator()

Method Summary

static SVGAnimator	createAnimator(SVGImage svgImage) This method creates a new SVGAnimator for the specified SVGImage.
static SVGAnimator	createAnimator(SVGImage svgImage, java.lang.String componentBaseClass) This method creates a new SVGAnimator for the specified SVGImage.
abstract java.lang.Object	getTargetComponent() The type of target component associated with the animator depends on the Java profile this specification is implemented on: javax.microedition.lcdui.Canvas on profiles supporting LCDUI java.awt.Component on profiles supporting AWT
abstract float	getTimeIncrement() Returns the current time increment used for animation rendering.
abstract void	invokeAndWait(java.lang.Runnable runnable) Invoke the input Runnable in the Document update thread and return after the Runnable has completed.
abstract void	invokeLater(java.lang.Runnable runnable) Schedule the input Runnable for execution in the update thread at a later time.
abstract void	pause() Transitions this SVGAnimator to the paused state.
abstract void	play() Transitions this SVGAnimator to the playing state.
abstract void	setSVGEventListener(SVGEventListener svgEventListener) Sets the SVGEventListener associated with this SVGAnimator.
abstract void	setTimeIncrement(float timeIncrement) Sets the time increment to use for animation rendering.
abstract void	stop() Transitions this SVGAnimator to the stopped state.

Methods inherited from class java.lang.Object

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

Constructor Detail

SVGAnimator

public SVGAnimator()

Method Detail

createAnimator

public static SVGAnimator createAnimator(SVGImage svgImage)

This method creates a new SVGAnimator for the specified SVGImage.

Parameters:

svgImage - the SVGImage this animator should render.

Returns:

a new SVGAnimator instance.

Throws:

java.lang.NullPointerException - if svgImage is null.

createAnimator

public static SVGAnimator createAnimator(SVGImage svgImage,
                                         java.lang.String componentBaseClass)

This method creates a new SVGAnimator for the specified SVGImage. The following components types must be supported:

• "javax.microedition.lcdui.Canvas" on profiles supporting LCDUI
• "java.awt.Component" on profiles supporting AWT

On platforms that support the Swing UI component framework, the "javax.swing.JComponent" string may be used to request a Swing component.

Parameters:

svgImage - the SVGImage this animator should render.

componentBaseClass - the desired base class for the component associated with the animator. This is used when the platform this specification is implemented on supports multiple UI component frameworks. If componentBaseClass is null, this is equivalent to invoking the createAnimator method with the svgImage parameter only.

Returns:

a new SVGAnimator instance.

Throws:

java.lang.NullPointerException - if svgImage is null.

java.lang.IllegalArgumentException - if the requested componentBaseClass is not supported by the implementation.

setSVGEventListener

public abstract void setSVGEventListener(SVGEventListener svgEventListener)

Sets the SVGEventListener associated with this SVGAnimator.

Parameters:

svgEventListener - the new SVGEventListener which will receive events forwarded by this SVGAnimator. May be null, in which case events are not forwarded by the SVGAnimator.

setTimeIncrement

public abstract void setTimeIncrement(float timeIncrement)

Sets the time increment to use for animation rendering.

Parameters:

timeIncrement - the minimal time that should ellapse between frame rendering. In seconds. Should be greater than zero.

Throws:

java.lang.IllegalArgumentException - if timeIncrement is less than or equal to zero.

See Also:

getTimeIncrement()

getTimeIncrement

public abstract float getTimeIncrement()

Returns the current time increment used for animation rendering. The SVGAnimator increments the SVG document's current time by this amount between each rendering.

Returns:

the current time increment used for animation rendering. The default value is 0.1 (100 milliseconds)

See Also:

setTimeIncrement(float)

play

public abstract void play()

Transitions this SVGAnimator to the playing state. While in the playing state, both Animation and SVGImage updates trigger rendering updates. Note that a change to the document's current time while in the playing state will cause the animator to seek to the new time, and continue to play animations forward.

Throws:

java.lang.IllegalStateException - if the animator is not currently in the stopped or paused state.

pause

public abstract void pause()

Transitions this SVGAnimator to the paused state. The SVGAnimator stops advancing the document's current time automatically (see the SVGDocument's setCurrentTime method). As a result, animations are paused until another call to the play method is made, at which points animations resume from the document's current time. SVGImage updates (through API calls) trigger a rendering update while the SVGAnimator is in the paused state.

Throws:

java.lang.IllegalStateException - if the animator is not in the playing state.

stop

public abstract void stop()

Transitions this SVGAnimator to the stopped state. This causes the SVGAnimator to stop advancing the document's current time automatically, and no rendering updates are performed while in stopped state. A call to the play method will cause the animations to resume from the document's current time.

Throws:

java.lang.IllegalStateException - if the animator is not in the playing or paused state.

getTargetComponent

public abstract java.lang.Object getTargetComponent()

The type of target component associated with the animator depends on the Java profile this specification is implemented on:

• javax.microedition.lcdui.Canvas on profiles supporting LCDUI
• java.awt.Component on profiles supporting AWT

Returns:

target the target component associated with the animator.

See Also:

createAnimator(javax.microedition.m2g.SVGImage)

invokeAndWait

public abstract void invokeAndWait(java.lang.Runnable runnable)
                            throws java.lang.InterruptedException

Invoke the input Runnable in the Document update thread and return after the Runnable has completed.

Parameters:

runnable - the new Runnable to invoke.

Throws:

java.lang.InterruptedException - if the current thread is waiting, sleeping, or otherwise paused for a long time and another thread interrupts it.

java.lang.NullPointerException - if runnable is null.

java.lang.IllegalStateException - if the animator is in the stopped state.

invokeLater

public abstract void invokeLater(java.lang.Runnable runnable)

Schedule the input Runnable for execution in the update thread at a later time.

Parameters:

runnable - the new Runnable to execute in the Document's update thread when time permits.

Throws:

java.lang.NullPointerException - if runnable is null.

java.lang.IllegalStateException - if the animator is in the stopped state.