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     public static SVGAnimator createAnimator(SVGImage svgImage)

   146     {

   147         SVGAnimator tempAnimator = null;

   148         

   149     		System.out.println("P-Do In CreateAnimator if.");

   150     		

   151         tempAnimator=M2GSVGeSWTAnimator.buildAnimator(svgImage);

   152         

   153 				System.out.println("P-Do In CreateAnimator  tempAnimator Creif.");

   154 

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

   156         

   157         return tempAnimator;

   158     }

   159 

   160     /**

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

   162      *

   163      * The following components types must be supported:

   164      *

   165      * <ul>

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

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

   168      * </ul>

   169      *

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

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

   172      *

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

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

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

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

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

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

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

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

   181      * @throws IllegalArgumentException if the requested

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

   183      *         implementation.

   184      */

   185     public static SVGAnimator createAnimator(

   186         SVGImage svgImage, String componentBaseClass)

   187     {

   188 				System.out.println("P-Do In CreateAnimator of SVGAnimator.");

   189 

   190         SVGAnimator tempAnimator = null;

   191             tempAnimator=M2GSVGeSWTAnimator.buildAnimator(svgImage);

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

   193         return tempAnimator;

   194     }

   195 

   196     /**

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

   198      * Java profile this specification is implemented on:

   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      * @return target the target component associated with the animator.

   205      * @see #createAnimator

   206      */

   207     public abstract Object getTargetComponent();

   208 

   209     /**

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

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

   212      * between each rendering.

   213      *

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

   215      *         value is 0.1 (100 milliseconds)

   216      * @see #setTimeIncrement

   217      */

   218     public abstract float getTimeIncrement();

   219 

   220     /**

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

   222      * the Runnable has completed.

   223      *

   224      * @param runnable the new Runnable to invoke.

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

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

   227      * interrupts it.

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

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

   230      */

   231     public abstract void invokeAndWait(

   232         Runnable runnable) throws InterruptedException;

   233 

   234     /**

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

   236      *

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

   238      * thread when time permits.

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

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

   241      */

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

   243 

   244     /**

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

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

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

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

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

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

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

   252      *

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

   254      *         state.

   255      */

   256     public abstract void pause();

   257 

   258     /**

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

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

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

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

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

   264      *

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

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

   267      */

   268     public abstract void play();

   269 

   270     /**

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

   272      *

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

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

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

   276      *         zero.

   277      * @see #getTimeIncrement

   278      */

   279     public abstract void setTimeIncrement(float timeIncrement);

   280 

   281     /**

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

   283      * <code>SVGAnimator</code>.

   284      *

   285      * @param svgEventListener the new SVGEventListener which will receive

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

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

   288      */

   289     public abstract void setSVGEventListener(SVGEventListener svgEventListener);

   290 

   291     /**

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

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

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

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

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

   297      *

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

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

   300      */

   301     public abstract void stop();

   302 }