]>
Commit | Line | Data |
---|---|---|
e98da3dc | 1 | /* Applet.java -- Java base applet class |
f7aa343f TT |
2 | Copyright (C) 1999, 2002 Free Software Foundation, Inc. |
3 | ||
e98da3dc | 4 | This file is part of GNU Classpath. |
f7aa343f | 5 | |
e98da3dc BM |
6 | GNU Classpath is free software; you can redistribute it and/or modify |
7 | it under the terms of the GNU General Public License as published by | |
8 | the Free Software Foundation; either version 2, or (at your option) | |
9 | any later version. | |
f7aa343f | 10 | |
e98da3dc BM |
11 | GNU Classpath is distributed in the hope that it will be useful, but |
12 | WITHOUT ANY WARRANTY; without even the implied warranty of | |
13 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | |
14 | General Public License for more details. | |
f7aa343f | 15 | |
e98da3dc BM |
16 | You should have received a copy of the GNU General Public License |
17 | along with GNU Classpath; see the file COPYING. If not, write to the | |
18 | Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA | |
19 | 02111-1307 USA. | |
f7aa343f | 20 | |
92aaa246 MW |
21 | Linking this library statically or dynamically with other modules is |
22 | making a combined work based on this library. Thus, the terms and | |
23 | conditions of the GNU General Public License cover the whole | |
24 | combination. | |
25 | ||
26 | As a special exception, the copyright holders of this library give you | |
27 | permission to link this library with independent modules to produce an | |
28 | executable, regardless of the license terms of these independent | |
29 | modules, and to copy and distribute the resulting executable under | |
30 | terms of your choice, provided that you also meet, for each linked | |
31 | independent module, the terms and conditions of the license of that | |
32 | module. An independent module is a module which is not derived from | |
33 | or based on this library. If you modify this library, you may extend | |
34 | this exception to your version of the library, but you are not | |
35 | obligated to do so. If you do not wish to do so, delete this | |
36 | exception statement from your version. */ | |
e98da3dc BM |
37 | |
38 | ||
39 | package java.applet; | |
40 | ||
41 | import java.awt.Dimension; | |
f7aa343f TT |
42 | import java.awt.GraphicsEnvironment; |
43 | import java.awt.HeadlessException; | |
e98da3dc | 44 | import java.awt.Image; |
f7aa343f TT |
45 | import java.awt.Panel; |
46 | import java.io.IOException; | |
47 | import java.io.ObjectInputStream; | |
48 | import java.net.MalformedURLException; | |
e98da3dc BM |
49 | import java.net.URL; |
50 | import java.util.Locale; | |
f7aa343f TT |
51 | import javax.accessibility.AccessibleContext; |
52 | import javax.accessibility.AccessibleRole; | |
53 | import javax.accessibility.AccessibleState; | |
54 | import javax.accessibility.AccessibleStateSet; | |
e98da3dc BM |
55 | |
56 | /** | |
f7aa343f TT |
57 | * This is the base applet class. An applet is a Java program that |
58 | * runs inside a web browser or other applet viewer in a restricted | |
59 | * environment. | |
60 | * | |
61 | * <p>To be useful, a subclass should override at least start(). Also useful | |
62 | * are init, stop, and destroy for control purposes, and getAppletInfo and | |
63 | * getParameterInfo for descriptive purposes. | |
64 | * | |
65 | * @author Aaron M. Renn <arenn@urbanophile.com> | |
66 | * @author Eric Blake <ebb9@email.byu.edu> | |
67 | * @since 1.0 | |
68 | * @status updated to 1.4 | |
69 | */ | |
70 | public class Applet extends Panel | |
e98da3dc | 71 | { |
f7aa343f TT |
72 | /** |
73 | * Compatible with JDK 1.0+. | |
74 | */ | |
75 | private static final long serialVersionUID = -5836846270535785031L; | |
76 | ||
77 | /** The applet stub for this applet. */ | |
78 | private transient AppletStub stub; | |
79 | ||
31e632d3 GH |
80 | /** |
81 | * The dimensions passed to this applet through its HTML tag. | |
82 | */ | |
83 | private transient Dimension dimensions; | |
84 | ||
f7aa343f TT |
85 | /** |
86 | * The accessibility context for this applet. | |
87 | * | |
88 | * @serial the accessibleContext for this | |
89 | * @since 1.2 | |
90 | */ | |
91 | private AccessibleContext accessibleContext; | |
92 | ||
93 | /** | |
94 | * Default constructor for subclasses. | |
95 | * | |
96 | * @throws HeadlessException if in a headless environment | |
97 | */ | |
98 | public Applet() | |
99 | { | |
100 | if (GraphicsEnvironment.isHeadless()) | |
101 | throw new HeadlessException(); | |
102 | } | |
103 | ||
104 | /** | |
105 | * The browser calls this method to set the applet's stub, which is the | |
106 | * low level interface to the browser. Manually setting this to null is | |
107 | * asking for problems down the road. | |
108 | * | |
109 | * @param stub the applet stub for this applet | |
110 | */ | |
111 | public final void setStub(AppletStub stub) | |
112 | { | |
113 | this.stub = stub; | |
114 | } | |
e98da3dc BM |
115 | |
116 | /** | |
f7aa343f TT |
117 | * Tests whether or not this applet is currently active. An applet is active |
118 | * just before the browser invokes start(), and becomes inactive just | |
119 | * before the browser invokes stop(). | |
120 | * | |
121 | * @return <code>true</code> if this applet is active | |
122 | */ | |
123 | public boolean isActive() | |
124 | { | |
125 | return stub.isActive(); | |
126 | } | |
e98da3dc BM |
127 | |
128 | /** | |
f7aa343f TT |
129 | * Returns the basename URL of the document this applet is embedded in. This |
130 | * is everything up to the final '/'. | |
131 | * | |
132 | * @return the URL of the document this applet is embedded in | |
133 | * @see #getCodeBase() | |
134 | */ | |
e98da3dc BM |
135 | public URL getDocumentBase() |
136 | { | |
f7aa343f | 137 | return stub.getDocumentBase(); |
e98da3dc BM |
138 | } |
139 | ||
140 | /** | |
f7aa343f TT |
141 | * Returns the URL of the code base for this applet. |
142 | * | |
143 | * @return the URL of the code base for this applet | |
144 | */ | |
e98da3dc BM |
145 | public URL getCodeBase() |
146 | { | |
f7aa343f | 147 | return stub.getCodeBase(); |
e98da3dc BM |
148 | } |
149 | ||
150 | /** | |
f7aa343f TT |
151 | * Returns the value of the specified parameter that was specified in |
152 | * the <code><APPLET></code> tag for this applet. | |
153 | * | |
154 | * @param name the parameter name | |
155 | * @return the parameter value, or null if the parameter does not exist | |
156 | * @throws NullPointerException if name is null | |
157 | */ | |
e98da3dc BM |
158 | public String getParameter(String name) |
159 | { | |
f7aa343f | 160 | return stub.getParameter(name); |
e98da3dc BM |
161 | } |
162 | ||
163 | /** | |
f7aa343f TT |
164 | * Returns the applet context for this applet. |
165 | * | |
166 | * @return the applet context for this applet | |
167 | */ | |
e98da3dc BM |
168 | public AppletContext getAppletContext() |
169 | { | |
f7aa343f | 170 | return stub.getAppletContext(); |
e98da3dc BM |
171 | } |
172 | ||
173 | /** | |
f7aa343f TT |
174 | * Requests that the applet window for this applet be resized. |
175 | * | |
176 | * @param width the new width in pixels | |
177 | * @param height the new height in pixels | |
178 | */ | |
179 | public void resize(int width, int height) | |
e98da3dc | 180 | { |
f7aa343f | 181 | stub.appletResize(width, height); |
e98da3dc BM |
182 | } |
183 | ||
184 | /** | |
f7aa343f TT |
185 | * Requests that the applet window for this applet be resized. |
186 | * | |
187 | * @param dim the requested dimensions | |
188 | * @throws NullPointerException if dim is null | |
189 | */ | |
190 | public void resize(Dimension dim) | |
e98da3dc | 191 | { |
f7aa343f | 192 | resize(dim.width, dim.height); |
e98da3dc BM |
193 | } |
194 | ||
195 | /** | |
f7aa343f TT |
196 | * Displays the specified message in the status window if that window |
197 | * exists. | |
198 | * | |
199 | * @param message the status message, may be null | |
200 | */ | |
201 | public void showStatus(String message) | |
202 | { | |
203 | getAppletContext().showStatus(message); | |
204 | } | |
205 | ||
206 | /** | |
207 | * Returns an image from the specified URL. Note that the image is not | |
208 | * actually retrieved until the applet attempts to display it, so this | |
209 | * method returns immediately. | |
210 | * | |
211 | * @param url the URL of the image | |
212 | * @return the retrieved image | |
213 | * @throws NullPointerException if url is null | |
214 | */ | |
215 | public Image getImage(URL url) | |
e98da3dc | 216 | { |
f7aa343f | 217 | return getAppletContext().getImage(url); |
e98da3dc BM |
218 | } |
219 | ||
220 | /** | |
f7aa343f TT |
221 | * Returns an image from the specified absolute URL, and relative path |
222 | * from that URL. Note that the image is not actually retrieved until the | |
223 | * applet attempts to display it, so this method returns immediately. | |
224 | * This calls <code>getImage(new URL(url, name))</code>, but if building | |
225 | * the new URL fails, this returns null. | |
226 | * | |
227 | * @param url the base URL of the image | |
228 | * @param name the name of the image relative to the URL | |
229 | * @return the retrieved image, or null on failure | |
230 | * @see #getImage(URL) | |
231 | */ | |
232 | public Image getImage(URL url, String name) | |
233 | { | |
234 | try | |
235 | { | |
236 | return getImage(new URL(url, name)); | |
237 | } | |
238 | catch (MalformedURLException e) | |
239 | { | |
240 | return null; | |
241 | } | |
242 | } | |
243 | ||
244 | /** | |
245 | * Returns an audio clip from the specified URL. This clip is not tied to | |
246 | * any particular applet. | |
247 | * | |
248 | * XXX Classpath does not yet implement this. | |
249 | * | |
250 | * @param url the URL of the audio clip | |
251 | * @return the retrieved audio clip | |
252 | * @throws NullPointerException if url is null | |
253 | * @see #getAudioClip(URL) | |
254 | * @since 1.2 | |
255 | */ | |
256 | public static final AudioClip newAudioClip(URL url) | |
257 | { | |
258 | // This requires an implementation of AudioClip in gnu.java.applet. | |
259 | throw new Error("Not implemented"); | |
260 | } | |
261 | ||
262 | /** | |
263 | * Returns an audio clip from the specified URL. Note that the clip is not | |
264 | * actually retrieved until the applet attempts to play it, so this method | |
265 | * returns immediately. | |
266 | * | |
267 | * @param url the URL of the audio clip | |
268 | * @return the retrieved audio clip | |
269 | * @throws NullPointerException if url is null | |
270 | */ | |
e98da3dc BM |
271 | public AudioClip getAudioClip(URL url) |
272 | { | |
f7aa343f | 273 | return getAppletContext().getAudioClip(url); |
e98da3dc BM |
274 | } |
275 | ||
276 | /** | |
f7aa343f TT |
277 | * Returns an audio clip from the specified absolute URL, and relative path |
278 | * from that URL. Note that the clip is not actually retrieved until the | |
279 | * applet attempts to play it, so this method returns immediately. This | |
280 | * calls <code>getAudioClip(new URL(url, name))</code>, but if building | |
281 | * the new URL fails, this returns null. | |
282 | * | |
283 | * @param url the base URL of the audio clip | |
284 | * @param name the name of the clip relative to the URL | |
285 | * @return the retrieved audio clip, or null on failure | |
286 | * @see #getAudioClip(URL) | |
287 | */ | |
e98da3dc BM |
288 | public AudioClip getAudioClip(URL url, String name) |
289 | { | |
290 | try | |
291 | { | |
f7aa343f | 292 | return getAudioClip(new URL(url, name)); |
e98da3dc | 293 | } |
f7aa343f | 294 | catch (MalformedURLException e) |
e98da3dc | 295 | { |
f7aa343f | 296 | return null; |
e98da3dc BM |
297 | } |
298 | } | |
299 | ||
300 | /** | |
f7aa343f TT |
301 | * Returns a descriptive string with applet defined information. The |
302 | * implementation in this class returns <code>null</code>, so subclasses | |
303 | * must override to return information. | |
304 | * | |
305 | * @return a string describing the author, version, and applet copyright | |
306 | */ | |
307 | public String getAppletInfo() | |
e98da3dc | 308 | { |
f7aa343f | 309 | return null; |
e98da3dc BM |
310 | } |
311 | ||
312 | /** | |
f7aa343f TT |
313 | * Returns the locale for this applet, if it has been set. If no applet |
314 | * specific locale has been set, the default locale is returned. | |
315 | * | |
316 | * @return the locale for this applet | |
317 | * @see Component#setLocale(Locale) | |
318 | * @since 1.1 | |
319 | */ | |
320 | public Locale getLocale() | |
e98da3dc | 321 | { |
f7aa343f | 322 | return super.getLocale(); |
e98da3dc BM |
323 | } |
324 | ||
325 | /** | |
f7aa343f TT |
326 | * Returns a list of parameters this applet supports. Each element of |
327 | * the outer array is an array of three strings with the name of the | |
328 | * parameter, the data type or valid values, and a description. This | |
329 | * method is optional and the default implementation returns null. | |
330 | * | |
331 | * @return the list of parameters supported by this applet | |
332 | */ | |
333 | public String[][] getParameterInfo() | |
e98da3dc | 334 | { |
f7aa343f | 335 | return null; |
e98da3dc BM |
336 | } |
337 | ||
338 | /** | |
f7aa343f TT |
339 | * Loads and plays the audio clip pointed to by the specified URL. This does |
340 | * nothing if the URL does not point to a valid audio clip. | |
341 | * | |
342 | * @param url the URL of the audio clip | |
343 | * @throws NullPointerException if url is null | |
344 | * @see #getAudioClip(URL) | |
345 | */ | |
346 | public void play(URL url) | |
e98da3dc | 347 | { |
f7aa343f | 348 | AudioClip ac = getAudioClip(url); |
e98da3dc BM |
349 | try |
350 | { | |
f7aa343f | 351 | ac.play(); |
e98da3dc | 352 | } |
f7aa343f | 353 | catch (Exception ignored) |
e98da3dc | 354 | { |
e98da3dc BM |
355 | } |
356 | } | |
357 | ||
358 | /** | |
f7aa343f TT |
359 | * Loads and plays the audio clip pointed to by the specified absolute URL, |
360 | * and relative path from that URL. This does nothing if the URL cannot be | |
361 | * constructed, or if it does not point to a valid audio clip. | |
362 | * | |
363 | * @param url the base URL of the audio clip | |
364 | * @param name the name of the audio clip relative to the URL | |
365 | * @see #getAudioClip(URL, String) | |
366 | * @see #play(URL) | |
367 | */ | |
368 | public void play(URL url, String name) | |
e98da3dc | 369 | { |
f7aa343f TT |
370 | try |
371 | { | |
372 | getAudioClip(url, name).play(); | |
373 | } | |
374 | catch (Exception ignored) | |
375 | { | |
376 | } | |
e98da3dc BM |
377 | } |
378 | ||
379 | /** | |
f7aa343f TT |
380 | * This method is called when the applet is first loaded, before start(). |
381 | * The default implementation does nothing; override to do any one-time | |
382 | * initialization. | |
383 | * | |
384 | * @see #start() | |
385 | * @see #stop() | |
386 | * @see #destroy() | |
387 | */ | |
388 | public void init() | |
e98da3dc | 389 | { |
e98da3dc BM |
390 | } |
391 | ||
392 | /** | |
f7aa343f TT |
393 | * This method is called when the applet should start running. This is |
394 | * normally each time a web page containing it is loaded. The default | |
395 | * implemention does nothing; override for your applet to be useful. | |
396 | * | |
397 | * @see #init() | |
398 | * @see #stop() | |
399 | * @see #destroy() | |
400 | */ | |
401 | public void start() | |
e98da3dc | 402 | { |
e98da3dc BM |
403 | } |
404 | ||
405 | /** | |
f7aa343f TT |
406 | * This method is called when the applet should stop running. This is |
407 | * normally when the next web page is loaded. The default implementation | |
408 | * does nothing; override for your applet to stop using resources when | |
409 | * it is no longer visible, but may be restarted soon. | |
410 | * | |
411 | * @see #init() | |
412 | * @see #start() | |
413 | * @see #destroy() | |
414 | */ | |
415 | public void stop() | |
416 | { | |
417 | } | |
e98da3dc BM |
418 | |
419 | /** | |
f7aa343f TT |
420 | * This method is called when the applet is being unloaded. The default |
421 | * implementation does nothing; override for your applet to clean up | |
422 | * resources on exit. | |
423 | * | |
424 | * @see #init() | |
425 | * @see #start() | |
426 | * @see #stop() | |
427 | */ | |
428 | public void destroy() | |
429 | { | |
430 | } | |
e98da3dc BM |
431 | |
432 | /** | |
f7aa343f TT |
433 | * Gets the AccessibleContext associated with this applet, creating one if |
434 | * necessary. This always returns an instance of {@link AccessibleApplet}. | |
435 | * | |
436 | * @return the accessibility context of this applet | |
437 | * @since 1.3 | |
438 | */ | |
439 | public AccessibleContext getAccessibleContext() | |
440 | { | |
441 | if (accessibleContext == null) | |
442 | accessibleContext = new AccessibleApplet(); | |
443 | return accessibleContext; | |
444 | } | |
e98da3dc BM |
445 | |
446 | /** | |
f7aa343f TT |
447 | * Read an applet from an object stream. This checks for a headless |
448 | * environment, then does the normal read. | |
449 | * | |
450 | * @param s the stream to read from | |
451 | * @throws ClassNotFoundException if a class is not found | |
452 | * @throws IOException if deserialization fails | |
453 | * @throws HeadlessException if this is a headless environment | |
454 | * @see GraphicsEnvironment#isHeadless() | |
455 | * @since 1.4 | |
456 | */ | |
457 | private void readObject(ObjectInputStream s) | |
458 | throws ClassNotFoundException, IOException | |
459 | { | |
460 | if (GraphicsEnvironment.isHeadless()) | |
461 | throw new HeadlessException(); | |
462 | s.defaultReadObject(); | |
463 | } | |
e98da3dc | 464 | |
31e632d3 GH |
465 | private Dimension getDimensions () |
466 | { | |
467 | if (dimensions == null) | |
468 | { | |
469 | int width = Integer.parseInt(stub.getParameter("width")); | |
470 | int height = Integer.parseInt(stub.getParameter("height")); | |
471 | ||
472 | dimensions = new Dimension(width, height); | |
473 | } | |
474 | ||
475 | return dimensions; | |
476 | } | |
477 | ||
478 | /** | |
479 | * Returns an instance of {@link Dimension} representing the | |
480 | * applet's width and height parameters. | |
481 | * | |
482 | * @return the applet's preferred size | |
483 | */ | |
484 | public Dimension preferredSize() | |
485 | { | |
c5d2de6b | 486 | return stub == null ? super.preferredSize () : getDimensions (); |
31e632d3 GH |
487 | } |
488 | ||
489 | /** | |
490 | * Returns an instance of {@link Dimension} representing the | |
491 | * applet's width and height parameters. | |
492 | * | |
493 | * @return the applet's minimum size | |
494 | */ | |
495 | public Dimension minimumSize() | |
496 | { | |
c5d2de6b | 497 | return stub == null ? super.minimumSize () : getDimensions (); |
31e632d3 GH |
498 | } |
499 | ||
e98da3dc | 500 | /** |
f7aa343f TT |
501 | * This class provides accessibility support for Applets, and is the |
502 | * runtime type returned by {@link #getAccessibleContext()}. | |
503 | * | |
504 | * @author Eric Blake <ebb9@email.byu.edu> | |
505 | * @since 1.3 | |
506 | */ | |
507 | protected class AccessibleApplet extends AccessibleAWTPanel | |
e98da3dc | 508 | { |
f7aa343f TT |
509 | /** |
510 | * Compatible with JDK 1.4+. | |
511 | */ | |
512 | private static final long serialVersionUID = 8127374778187708896L; | |
e98da3dc | 513 | |
f7aa343f TT |
514 | /** |
515 | * The default constructor. | |
516 | */ | |
517 | protected AccessibleApplet() | |
518 | { | |
519 | } | |
e98da3dc | 520 | |
f7aa343f TT |
521 | /** |
522 | * Get the role of this accessible object, a frame. | |
523 | * | |
524 | * @return the role of the object | |
525 | * @see AccessibleRole#FRAME | |
526 | */ | |
527 | public AccessibleRole getAccessibleRole() | |
528 | { | |
529 | return AccessibleRole.FRAME; | |
530 | } | |
531 | ||
532 | /** | |
533 | * Get the state set of this accessible object. In addition to the default | |
534 | * states of a Component, the applet can also be active. | |
535 | * | |
536 | * @return the role of the object | |
537 | * @see AccessibleState | |
538 | */ | |
539 | public AccessibleStateSet getAccessibleStateSet() | |
540 | { | |
541 | AccessibleStateSet s = super.getAccessibleStateSet(); | |
542 | if (isActive()) | |
543 | s.add(AccessibleState.ACTIVE); | |
544 | return s; | |
545 | } | |
546 | } // class AccessibleApplet | |
547 | } // class Applet |