1 /*

     2 * Copyright (c) 2004 Nokia Corporation and/or its subsidiary(-ies).

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:

    15 *

    16 */

    17 

    18 

    19 package javax.microedition.m2g;

    20 

    21 import com.nokia.microedition.m2g.M2GSVGAnimator;

    22 import org.eclipse.swt.widgets.*;

    23 import org.eclipse.swt.widgets.Display;

    24 import com.nokia.microedition.m2g.M2GSVGeSWTAnimator;

    25 /**

    26  * The <code>SVGAnimator</code> class handles automatic rendering of updates and

    27  * animations in an <code>SVGImage</code> to a target user interface (UI) component.

    28  *

    29  * The target component type depends on the Java profile this specification is

    30  * implemented on, as described in the <code>createAnimator</code> and

    31  * <code>getTargetComponent</code> methods documentation.

    32  *

    33  * There are two types of rendering updates the <code>SVGAnimator</code> handles:

    34  *

    35  * <ul>

    36  *   <li><b>Animation Updates.</b> The <code>SVGAnimator</code> can run animations

    37  *       and automatically and periodically refreshes its rendering to

    38  *       reflect the effect of animations.</li>

    39  *   <li><b>SVGImage Updates.</b> The <code>SVGAnimator</code> updates its rendering

    40  *       following alterations of the associated <code>SVGImage</code>,

    41  *       for example if the position of one of the graphical elements is

    42  *       modified by an API call.</li>

    43  * </ul>

    44  *

    45  * An <code>SVGAnimator</code> instance can be in one of the following states:

    46  * <ul>

    47  *   <li><b>Stopped</b>. This is the initial state. The <code>SVGAnimator</code>

    48  *       performs no rendering updates. <br/>

    49  *       Possible transitions:

    50  *       <ul>

    51  *          <li>To the <i>playing</i> state, with the <code>play</code> method.</li>

    52  *       </ul>

    53  *       </li>

    54  *

    55  *   <li><b>Playing</b>. This is the typical state for an

    56  *   <code>SVGAnimator</code>.  In that state, the <code>SVGAnimator</code>

    57  *   performs both Animation and SVGImage updates.

    58  *

    59  *   While there are active animations,

    60  *   the animator updates the rendering at a rate not faster than the one

    61  *   defined by the <code>setTimeIncrement</code> method. If SVGImage updates are made

    62  *   (e.g., with calls to the <code>SVGElement</code>

    63  *   <code>setTrait</code> method, see examples), the rendering is updated at the time of

    64  *   the next animation rendering.<br />

    65  *

    66  *   When there are no active animations, the animator will update the rendering

    67  *   after each <code>Runnable</code> passed to the <code>invokeLater</code> or

    68  *   <code>invokeAndWait</code> methods has finished executing.

    69  *   <br/>

    70  *       Possible transitions:

    71  *       <ul>

    72  *          <li>To the <i>stopped</i> state, with the <code>stop</code> method.</li>

    73  *          <li>To the <i>paused</i> state, with the <code>pause</code> method.</li>

    74  *       </ul>

    75  *   </li>

    76  *

    77  *   <li><b>Paused</b>. When in that state, the <code>SVGAnimator</code> only

    78  *   performs SVGImage updates rendering. The animator no longer automatically

    79  *   advances the SVG document's current time, so rendering reflects the animation

    80  *   at the document's current time. Note that a change to the document's current

    81  *   time while in the <i>paused</i> state will trigger a new rendering for the

    82  *   new current time.

    83  *   <br/>

    84  *       Possible transitions:

    85  *       <ul>

    86  *          <li>To the <i>stopped</i> state, with the <code>stop</code> method.</li>

    87  *          <li>To the <i>playing</i> state, with the <code>play</code> method.</li>

    88  *       </ul>

    89  *   </li>

    90  * </ul>

    91  *

    92  * <b>Code example:</b><br />

    93  * <pre>

    94  * // Create an SVGAnimator

    95  * SVGImage map = ...; // See the SVGImage documentation.

    96  *

    97  * SVGAnimator svgAnimator = SVGAnimator.createAnimator(map);

    98  *

    99  * // Display the associated SVGAnimator component.

   100  * // Depends on the platform.

   101  *

   102  * // =============== AWT Example ===============

   103  * Panel panel = ....;

   104  * panel.add((Component) svgAnimator.getTargetComponent());

   105  * ...

   106  *

   107  * // =============== MIDP Example ===============

   108  * Canvas svgCanvas = (Canvas) svgAnimator.getTargetComponent());

   109  * ...

   110  *

   111  * // Start rendering animations.

   112  * svgAnimator.play();

   113  * ....

   114  * class MapRunnable implements Runnable {

   115  *    public void run() {

   116  *        // Perform map updates based on current

   117  *        // traffic information.

   118  *        SVGElement statusRect

   119  *             = map.getDocument().getElementById("statusRect");

   120  *

   121  *        // Reflect that traffic status.

   122  *        statusRect.setRGBTrait(...); // See setRGBTrait documentation.

   123  *    }

   124  * }

   125  *

   126  * Runnable mapUpdates = new MapRunnable();

   127  * ....

   128  *

   129  * while (someLoopCondition) {

   130  *     if(hasMapUpdate) {

   131  *         svgAnimator.invokeAndWait(mapUpdates);

   132  *     }

   133  * }

   134  * </pre>

   135  */

   136 public abstract class SVGAnimator

   137 {

   138     /**

   139      * This method creates a new <code>SVGAnimator</code> for the specified SVGImage.

   140      *

   141      * @param svgImage the <code>SVGImage</code> this animator should render.

   142      * @return a new <code>SVGAnimator</code> instance.

   143      * @throws NullPointerException if <code>svgImage</code> is null.

   144      */

   145 	

   146 	public static SVGAnimator createAnimator(SVGImage svgImage)

   147 	{

   148 		SVGAnimator tempAnimator = null;

   149 		

   150 		

   151 		

   152 		tempAnimator=M2GSVGAnimator.buildAnimator(svgImage);

   153 		

   154 		

   155 

   156 		return tempAnimator;

   157 	}

   158 	

   159 	

   160 	

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

   162 	{

   163 		SVGAnimator tempAnimator = null;

   164 		

   165 		if (componentBaseClass == "org.eclipse.swt.widgets.Control")

   166 		{

   167 			

   168 			tempAnimator=M2GSVGeSWTAnimator.buildAnimator(svgImage);

   169 			

   170 		}

   171 		else

   172 		{

   173 			

   174 			tempAnimator=M2GSVGAnimator.buildAnimator(svgImage);

   175 			

   176 		}

   177 		return tempAnimator;

   178 	}

   179 	

   180    /* public static SVGAnimator createAnimator(SVGImage svgImage)

   181     {

   182         SVGAnimator tempAnimator = null;

   183         

   184     		

   185     		

   186         tempAnimator=M2GSVGeSWTAnimator.buildAnimator(svgImage);

   187         

   188 				

   189 

   190         //tempAnimator=M2GSVGAnimator.buildAnimator(svgImage);

   191         

   192         return tempAnimator;

   193     }*/

   194 

   195     /**

   196      * This method creates a new <code>SVGAnimator</code> for the specified SVGImage.

   197      *

   198      * The following components types must be supported:

   199      *

   200      * <ul>

   201      * <li> "javax.microedition.lcdui.Canvas" on profiles supporting LCDUI</li>

   202      * <li> "java.awt.Component" on profiles supporting AWT</li>

   203      * </ul>

   204      *

   205      * On platforms that support the Swing UI component framework, the

   206      * "javax.swing.JComponent" string may be used to request a Swing component.

   207      *

   208      * @param svgImage the <code>SVGImage</code> this animator should render.

   209      * @param componentBaseClass the desired base class for the component associated

   210      *        with the animator. This is used when the platform this specification

   211      *        is implemented on supports multiple UI component frameworks. If

   212      *        componentBaseClass is null, this is equivalent to invoking the

   213      *        <code>createAnimator</code> method with the svgImage parameter only.

   214      * @return a new <code>SVGAnimator</code> instance.

   215      * @throws NullPointerException if <code>svgImage</code> is null.

   216      * @throws IllegalArgumentException if the requested

   217      *         <code>componentBaseClass</code> is not supported by the

   218      *         implementation.

   219      */

   220 //	

   221 //	public static SVGAnimator createAnimator(SVGImage svgImage, String componentBaseClass)

   222 //		{

   223 //			SVGAnimator tempAnimator = null;

   224 //			

   225 //			tempAnimator=M2GSVGAnimator.buildAnimator(svgImage, componentBaseClass);

   226 //			

   227 //	        return tempAnimator;

   228 //

   229 //		}

   230 	

   231 	

   232 	

   233 /*    public static SVGAnimator createAnimator(

   234         SVGImage svgImage, String componentBaseClass)

   235     {

   236 				

   237 

   238         SVGAnimator tempAnimator = null;

   239             tempAnimator=M2GSVGeSWTAnimator.buildAnimator(svgImage);

   240 // TODO Check for the toolkit?? tempAnimator=M2GSVGAnimator.buildAnimator(svgImage, componentBaseClass);

   241         return tempAnimator;

   242     }*/

   243 

   244     /**

   245      * The type of target component associated with the animator depends on the

   246      * Java profile this specification is implemented on:

   247      *

   248      * <ul>

   249      * <li> javax.microedition.lcdui.Canvas on profiles supporting LCDUI</li>

   250      * <li> java.awt.Component on profiles supporting AWT</li>

   251      * </ul>

   252      * @return target the target component associated with the animator.

   253      * @see #createAnimator

   254      */

   255     public abstract Object getTargetComponent();

   256 

   257     /**

   258      * Returns the current time increment used for animation rendering. The

   259      * SVGAnimator increments the SVG document's current time by this amount

   260      * between each rendering.

   261      *

   262      * @return the current time increment used for animation rendering. The default

   263      *         value is 0.1 (100 milliseconds)

   264      * @see #setTimeIncrement

   265      */

   266     public abstract float getTimeIncrement();

   267 

   268     /**

   269      * Invoke the input Runnable in the Document update thread and return after

   270      * the Runnable has completed.

   271      *

   272      * @param runnable the new Runnable to invoke.

   273      * @throws java.lang.InterruptedException if the current thread is waiting,

   274      * sleeping, or otherwise paused for a long time and another thread

   275      * interrupts it.

   276      * @throws NullPointerException if <code>runnable</code> is null.

   277      * @throws IllegalStateException if the animator is in the <i>stopped</i> state.

   278      */

   279     public abstract void invokeAndWait(

   280         Runnable runnable) throws InterruptedException;

   281 

   282     /**

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

   284      *

   285      * @param runnable the new Runnable to execute in the Document's update

   286      * thread when time permits.

   287      * @throws NullPointerException if <code>runnable</code> is null.

   288      * @throws IllegalStateException if the animator is in the <i>stopped</i> state.

   289      */

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

   291 

   292     /**

   293      * Transitions this <code>SVGAnimator</code> to the <i>paused</i> state.

   294      * The <code>SVGAnimator</code> stops advancing the document's current time

   295      * automatically (see the SVGDocument's setCurrentTime method). As a result,

   296      * animations are paused until another call to the <code>play</code> method

   297      * is made, at which points animations resume from the document's current

   298      * time. SVGImage updates (through API calls) trigger a rendering update

   299      * while the <code>SVGAnimator</code> is in the <i>paused</i> state.

   300      *

   301      * @throws IllegalStateException if the animator is not in the <i>playing</i>

   302      *         state.

   303      */

   304     public abstract void pause();

   305 

   306     /**

   307      * Transitions this <code>SVGAnimator</code> to the <i>playing</i>

   308      * state. While in the <i>playing</i> state, both Animation and SVGImage

   309      * updates trigger rendering updates. Note that a change to the document's

   310      * current time while in the playing state will cause the animator to seek

   311      * to the new time, and continue to play animations forward.

   312      *

   313      * @throws IllegalStateException if the animator is not currently in

   314      *         the <i>stopped</i> or <i>paused</i> state.

   315      */

   316     public abstract void play();

   317 

   318     /**

   319      * Sets the time increment to use for animation rendering.

   320      *

   321      * @param timeIncrement the minimal time that should ellapse between frame

   322      * rendering. In seconds. Should be greater than zero.

   323      * @throws IllegalArgumentException if timeIncrement is less than or equal to

   324      *         zero.

   325      * @see #getTimeIncrement

   326      */

   327     public abstract void setTimeIncrement(float timeIncrement);

   328 

   329     /**

   330      * Sets the <code>SVGEventListener</code> associated with this

   331      * <code>SVGAnimator</code>.

   332      *

   333      * @param svgEventListener the new SVGEventListener which will receive

   334      *        events forwarded by this <code>SVGAnimator</code>. May be null,

   335      *        in which case events are not forwarded by the <code>SVGAnimator</code>.

   336      */

   337     public abstract void setSVGEventListener(SVGEventListener svgEventListener);

   338 

   339     /**

   340      * Transitions this <code>SVGAnimator</code> to the <i>stopped</i> state.

   341      * This causes the <code>SVGAnimator</code> to stop advancing the document's

   342      * current time automatically, and no rendering updates are performed while

   343      * in <i>stopped</i> state. A call to the <i>play</i> method will cause

   344      * the animations to resume from the document's current time.

   345      *

   346      * @throws IllegalStateException if the animator is not in the <i>playing</i>

   347      *         or <i>paused</i> state.

   348      */

   349     public abstract void stop();

   350 }