javax.microedition.m2g
Class SVGAnimator

java.lang.Object
  extended by 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:

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:

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:

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:

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





Copyright 1999-2010 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Copyright 1993-2003 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A. All Rights Reserved.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark of Sun Microsystems, Inc.