javax.microedition.m2g
Class SVGAnimator

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

public abstract class SVGAnimator
extends 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.

The SVGAnimator runs animations and updates in the so-called "update thread". When the "update thread" is running (in the Playing and Paused states), all access to the SVG image (i.e. calls to the SVGImage or to the DOM methods) must be done in a Runnable passed to the SVGAnimator's invokeLater or invokeAndWait methods. An SVGAnimator instance can be in one of the following states:

• Stopped. This is the initial state. The SVGAnimator performs no rendering updates. In that state, the update thread is not running and the invokeLater and invokeAndWait methods should not be called. In the stopped state, updates to the SVG image can be done by directly accessing the DOM API or the SVGImage interface. However, the caller is responsible for synchronizing access if multiple threads need to access these APIs on the same SVGImage instance.
  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);
     }
  }
 

Since:

BlackBerry API 4.6.0

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, String componentBaseClass) This method creates a new SVGAnimator for the specified SVGImage.
abstract 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 javax.microedition.lcdui.CustomItem 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(Runnable runnable) Invoke the input Runnable in the Document update thread and return after the Runnable has completed.
abstract void	invokeLater(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 listener) 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

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

Constructor Detail

SVGAnimator

public SVGAnimator()

Since:

BlackBerry API 4.6.0

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:

NullPointerException - if svgImage is null.

IllegalStateException - if svgImage was previously used to create an SVGAnimator instance.

Since:

BlackBerry API 4.6.0

createAnimator

public static SVGAnimator createAnimator(SVGImage svgImage,
                                         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
• "javax.microedition.lcdui.CustomItem" 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:

NullPointerException - if svgImage is null.

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

IllegalStateException - if svgImage was previously used to create an SVGAnimator instance.

Since:

BlackBerry API 4.6.0

setSVGEventListener

public abstract void setSVGEventListener(SVGEventListener listener)

Sets the SVGEventListener associated with this SVGAnimator.

Parameters:

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

Since:

BlackBerry API 4.6.0

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:

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

See Also:

SVGAnimator.getTimeIncrement()

Since:

BlackBerry API 4.6.0

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:

SVGAnimator.setTimeIncrement(float)

Since:

BlackBerry API 4.6.0

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.
In the PLAY state, the animation time line is advanced and animation events (beginEvent, endEvent, repeatEvent) are dispatched by the implementation.(see org.w3c.dom.events.TimeEvent).

Throws:

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

Since:

BlackBerry API 4.6.0

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:

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

Since:

BlackBerry API 4.6.0

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:

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

Since:

BlackBerry API 4.6.0

getTargetComponent

public abstract 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
• javax.microedition.lcdui.CustomItem on profiles supporting LCDUI
• java.awt.Component on profiles supporting AWT

Returns:

target the target component associated with the animator.

See Also:

SVGAnimator.createAnimator(javax.microedition.m2g.SVGImage)

Since:

BlackBerry API 4.6.0

invokeAndWait

public abstract void invokeAndWait(Runnable runnable)
                            throws 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:

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

NullPointerException - if runnable is null.

IllegalStateException - if the animator is in the stopped state.

Since:

BlackBerry API 4.6.0

invokeLater

public abstract void invokeLater(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:

NullPointerException - if runnable is null.

IllegalStateException - if the animator is in the stopped state.

Since:

BlackBerry API 4.6.0