80
|
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 |
}
|