1 /*
2 * Copyright 1995-2006 Sun Microsystems, Inc. All Rights Reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Sun designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Sun in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
22 * CA 95054 USA or visit www.sun.com if you need additional information or
23 * have any questions.
24 */
25 package java.applet;
26
27 import java.awt;
28 import java.awt.image.ColorModel;
29 import java.io.IOException;
30 import java.io.ObjectInputStream;
31 import java.net.URL;
32 import java.net.MalformedURLException;
33 import java.util.Hashtable;
34 import java.util.Locale;
35 import javax.accessibility;
36
37 /**
38 * An applet is a small program that is intended not to be run on
39 * its own, but rather to be embedded inside another application.
40 * <p>
41 * The <code>Applet</code> class must be the superclass of any
42 * applet that is to be embedded in a Web page or viewed by the Java
43 * Applet Viewer. The <code>Applet</code> class provides a standard
44 * interface between applets and their environment.
45 *
46 * @author Arthur van Hoff
47 * @author Chris Warth
48 * @since JDK1.0
49 */
50 public class Applet extends Panel {
51
52 /**
53 * Constructs a new Applet.
54 * <p>
55 * Note: Many methods in <code>java.applet.Applet</code>
56 * may be invoked by the applet only after the applet is
57 * fully constructed; applet should avoid calling methods
58 * in <code>java.applet.Applet</code> in the constructor.
59 *
60 * @exception HeadlessException if GraphicsEnvironment.isHeadless()
61 * returns true.
62 * @see java.awt.GraphicsEnvironment#isHeadless
63 * @since 1.4
64 */
65 public Applet() throws HeadlessException {
66 if (GraphicsEnvironment.isHeadless()) {
67 throw new HeadlessException();
68 }
69 }
70
71 /**
72 * Applets can be serialized but the following conventions MUST be followed:
73 *
74 * Before Serialization:
75 * An applet must be in STOPPED state.
76 *
77 * After Deserialization:
78 * The applet will be restored in STOPPED state (and most clients will
79 * likely move it into RUNNING state).
80 * The stub field will be restored by the reader.
81 */
82 transient private AppletStub stub;
83
84 /* version ID for serialized form. */
85 private static final long serialVersionUID = -5836846270535785031L;
86
87 /**
88 * Read an applet from an object input stream.
89 * @exception HeadlessException if
90 * <code>GraphicsEnvironment.isHeadless()</code> returns
91 * <code>true</code>
92 * @serial
93 * @see java.awt.GraphicsEnvironment#isHeadless
94 * @since 1.4
95 */
96 private void readObject(ObjectInputStream s)
97 throws ClassNotFoundException, IOException, HeadlessException {
98 if (GraphicsEnvironment.isHeadless()) {
99 throw new HeadlessException();
100 }
101 s.defaultReadObject();
102 }
103
104 /**
105 * Sets this applet's stub. This is done automatically by the system.
106 * <p>If there is a security manager, its <code> checkPermission </code>
107 * method is called with the
108 * <code>AWTPermission("setAppletStub")</code>
109 * permission if a stub has already been set.
110 * @param stub the new stub.
111 * @exception SecurityException if the caller cannot set the stub
112 */
113 public final void setStub(AppletStub stub) {
114 if (this.stub != null) {
115 SecurityManager s = System.getSecurityManager();
116 if (s != null) {
117 s.checkPermission(new AWTPermission("setAppletStub"));
118 }
119 }
120 this.stub = (AppletStub)stub;
121 }
122
123 /**
124 * Determines if this applet is active. An applet is marked active
125 * just before its <code>start</code> method is called. It becomes
126 * inactive just before its <code>stop</code> method is called.
127 *
128 * @return <code>true</code> if the applet is active;
129 * <code>false</code> otherwise.
130 * @see java.applet.Applet#start()
131 * @see java.applet.Applet#stop()
132 */
133 public boolean isActive() {
134 if (stub != null) {
135 return stub.isActive();
136 } else { // If stub field not filled in, applet never active
137 return false;
138 }
139 }
140
141 /**
142 * Gets the URL of the document in which this applet is embedded.
143 * For example, suppose an applet is contained
144 * within the document:
145 * <blockquote><pre>
146 * http://java.sun.com/products/jdk/1.2/index.html
147 * </pre></blockquote>
148 * The document base is:
149 * <blockquote><pre>
150 * http://java.sun.com/products/jdk/1.2/index.html
151 * </pre></blockquote>
152 *
153 * @return the {@link java.net.URL} of the document that contains this
154 * applet.
155 * @see java.applet.Applet#getCodeBase()
156 */
157 public URL getDocumentBase() {
158 return stub.getDocumentBase();
159 }
160
161 /**
162 * Gets the base URL. This is the URL of the directory which contains this applet.
163 *
164 * @return the base {@link java.net.URL} of
165 * the directory which contains this applet.
166 * @see java.applet.Applet#getDocumentBase()
167 */
168 public URL getCodeBase() {
169 return stub.getCodeBase();
170 }
171
172 /**
173 * Returns the value of the named parameter in the HTML tag. For
174 * example, if this applet is specified as
175 * <blockquote><pre>
176 * <applet code="Clock" width=50 height=50>
177 * <param name=Color value="blue">
178 * </applet>
179 * </pre></blockquote>
180 * <p>
181 * then a call to <code>getParameter("Color")</code> returns the
182 * value <code>"blue"</code>.
183 * <p>
184 * The <code>name</code> argument is case insensitive.
185 *
186 * @param name a parameter name.
187 * @return the value of the named parameter,
188 * or <code>null</code> if not set.
189 */
190 public String getParameter(String name) {
191 return stub.getParameter(name);
192 }
193
194 /**
195 * Determines this applet's context, which allows the applet to
196 * query and affect the environment in which it runs.
197 * <p>
198 * This environment of an applet represents the document that
199 * contains the applet.
200 *
201 * @return the applet's context.
202 */
203 public AppletContext getAppletContext() {
204 return stub.getAppletContext();
205 }
206
207 /**
208 * Requests that this applet be resized.
209 *
210 * @param width the new requested width for the applet.
211 * @param height the new requested height for the applet.
212 */
213 public void resize(int width, int height) {
214 Dimension d = size();
215 if ((d.width != width) || (d.height != height)) {
216 super.resize(width, height);
217 if (stub != null) {
218 stub.appletResize(width, height);
219 }
220 }
221 }
222
223 /**
224 * Requests that this applet be resized.
225 *
226 * @param d an object giving the new width and height.
227 */
228 public void resize(Dimension d) {
229 resize(d.width, d.height);
230 }
231
232 /**
233 * Requests that the argument string be displayed in the
234 * "status window". Many browsers and applet viewers
235 * provide such a window, where the application can inform users of
236 * its current state.
237 *
238 * @param msg a string to display in the status window.
239 */
240 public void showStatus(String msg) {
241 getAppletContext().showStatus(msg);
242 }
243
244 /**
245 * Returns an <code>Image</code> object that can then be painted on
246 * the screen. The <code>url</code> that is passed as an argument
247 * must specify an absolute URL.
248 * <p>
249 * This method always returns immediately, whether or not the image
250 * exists. When this applet attempts to draw the image on the screen,
251 * the data will be loaded. The graphics primitives that draw the
252 * image will incrementally paint on the screen.
253 *
254 * @param url an absolute URL giving the location of the image.
255 * @return the image at the specified URL.
256 * @see java.awt.Image
257 */
258 public Image getImage(URL url) {
259 return getAppletContext().getImage(url);
260 }
261
262 /**
263 * Returns an <code>Image</code> object that can then be painted on
264 * the screen. The <code>url</code> argument must specify an absolute
265 * URL. The <code>name</code> argument is a specifier that is
266 * relative to the <code>url</code> argument.
267 * <p>
268 * This method always returns immediately, whether or not the image
269 * exists. When this applet attempts to draw the image on the screen,
270 * the data will be loaded. The graphics primitives that draw the
271 * image will incrementally paint on the screen.
272 *
273 * @param url an absolute URL giving the base location of the image.
274 * @param name the location of the image, relative to the
275 * <code>url</code> argument.
276 * @return the image at the specified URL.
277 * @see java.awt.Image
278 */
279 public Image getImage(URL url, String name) {
280 try {
281 return getImage(new URL(url, name));
282 } catch (MalformedURLException e) {
283 return null;
284 }
285 }
286
287 /**
288 * Get an audio clip from the given URL.
289 *
290 * @param url points to the audio clip
291 * @return the audio clip at the specified URL.
292 *
293 * @since 1.2
294 */
295 public final static AudioClip newAudioClip(URL url) {
296 return new sun.applet.AppletAudioClip(url);
297 }
298
299 /**
300 * Returns the <code>AudioClip</code> object specified by the
301 * <code>URL</code> argument.
302 * <p>
303 * This method always returns immediately, whether or not the audio
304 * clip exists. When this applet attempts to play the audio clip, the
305 * data will be loaded.
306 *
307 * @param url an absolute URL giving the location of the audio clip.
308 * @return the audio clip at the specified URL.
309 * @see java.applet.AudioClip
310 */
311 public AudioClip getAudioClip(URL url) {
312 return getAppletContext().getAudioClip(url);
313 }
314
315 /**
316 * Returns the <code>AudioClip</code> object specified by the
317 * <code>URL</code> and <code>name</code> arguments.
318 * <p>
319 * This method always returns immediately, whether or not the audio
320 * clip exists. When this applet attempts to play the audio clip, the
321 * data will be loaded.
322 *
323 * @param url an absolute URL giving the base location of the
324 * audio clip.
325 * @param name the location of the audio clip, relative to the
326 * <code>url</code> argument.
327 * @return the audio clip at the specified URL.
328 * @see java.applet.AudioClip
329 */
330 public AudioClip getAudioClip(URL url, String name) {
331 try {
332 return getAudioClip(new URL(url, name));
333 } catch (MalformedURLException e) {
334 return null;
335 }
336 }
337
338 /**
339 * Returns information about this applet. An applet should override
340 * this method to return a <code>String</code> containing information
341 * about the author, version, and copyright of the applet.
342 * <p>
343 * The implementation of this method provided by the
344 * <code>Applet</code> class returns <code>null</code>.
345 *
346 * @return a string containing information about the author, version, and
347 * copyright of the applet.
348 */
349 public String getAppletInfo() {
350 return null;
351 }
352
353 /**
354 * Gets the locale of the applet. It allows the applet
355 * to maintain its own locale separated from the locale
356 * of the browser or appletviewer.
357 *
358 * @return the locale of the applet; if no locale has
359 * been set, the default locale is returned.
360 * @since JDK1.1
361 */
362 public Locale getLocale() {
363 Locale locale = super.getLocale();
364 if (locale == null) {
365 return Locale.getDefault();
366 }
367 return locale;
368 }
369
370 /**
371 * Returns information about the parameters that are understood by
372 * this applet. An applet should override this method to return an
373 * array of <code>Strings</code> describing these parameters.
374 * <p>
375 * Each element of the array should be a set of three
376 * <code>Strings</code> containing the name, the type, and a
377 * description. For example:
378 * <p><blockquote><pre>
379 * String pinfo[][] = {
380 * {"fps", "1-10", "frames per second"},
381 * {"repeat", "boolean", "repeat image loop"},
382 * {"imgs", "url", "images directory"}
383 * };
384 * </pre></blockquote>
385 * <p>
386 * The implementation of this method provided by the
387 * <code>Applet</code> class returns <code>null</code>.
388 *
389 * @return an array describing the parameters this applet looks for.
390 */
391 public String[][] getParameterInfo() {
392 return null;
393 }
394
395 /**
396 * Plays the audio clip at the specified absolute URL. Nothing
397 * happens if the audio clip cannot be found.
398 *
399 * @param url an absolute URL giving the location of the audio clip.
400 */
401 public void play(URL url) {
402 AudioClip clip = getAudioClip(url);
403 if (clip != null) {
404 clip.play();
405 }
406 }
407
408 /**
409 * Plays the audio clip given the URL and a specifier that is
410 * relative to it. Nothing happens if the audio clip cannot be found.
411 *
412 * @param url an absolute URL giving the base location of the
413 * audio clip.
414 * @param name the location of the audio clip, relative to the
415 * <code>url</code> argument.
416 */
417 public void play(URL url, String name) {
418 AudioClip clip = getAudioClip(url, name);
419 if (clip != null) {
420 clip.play();
421 }
422 }
423
424 /**
425 * Called by the browser or applet viewer to inform
426 * this applet that it has been loaded into the system. It is always
427 * called before the first time that the <code>start</code> method is
428 * called.
429 * <p>
430 * A subclass of <code>Applet</code> should override this method if
431 * it has initialization to perform. For example, an applet with
432 * threads would use the <code>init</code> method to create the
433 * threads and the <code>destroy</code> method to kill them.
434 * <p>
435 * The implementation of this method provided by the
436 * <code>Applet</code> class does nothing.
437 *
438 * @see java.applet.Applet#destroy()
439 * @see java.applet.Applet#start()
440 * @see java.applet.Applet#stop()
441 */
442 public void init() {
443 }
444
445 /**
446 * Called by the browser or applet viewer to inform
447 * this applet that it should start its execution. It is called after
448 * the <code>init</code> method and each time the applet is revisited
449 * in a Web page.
450 * <p>
451 * A subclass of <code>Applet</code> should override this method if
452 * it has any operation that it wants to perform each time the Web
453 * page containing it is visited. For example, an applet with
454 * animation might want to use the <code>start</code> method to
455 * resume animation, and the <code>stop</code> method to suspend the
456 * animation.
457 * <p>
458 * Note: some methods, such as <code>getLocationOnScreen</code>, can only
459 * provide meaningful results if the applet is showing. Because
460 * <code>isShowing</code> returns <code>false</code> when the applet's
461 * <code>start</code> is first called, methods requiring
462 * <code>isShowing</code> to return <code>true</code> should be called from
463 * a <code>ComponentListener</code>.
464 * <p>
465 * The implementation of this method provided by the
466 * <code>Applet</code> class does nothing.
467 *
468 * @see java.applet.Applet#destroy()
469 * @see java.applet.Applet#init()
470 * @see java.applet.Applet#stop()
471 * @see java.awt.Component#isShowing()
472 * @see java.awt.event.ComponentListener#componentShown(java.awt.event.ComponentEvent)
473 */
474 public void start() {
475 }
476
477 /**
478 * Called by the browser or applet viewer to inform
479 * this applet that it should stop its execution. It is called when
480 * the Web page that contains this applet has been replaced by
481 * another page, and also just before the applet is to be destroyed.
482 * <p>
483 * A subclass of <code>Applet</code> should override this method if
484 * it has any operation that it wants to perform each time the Web
485 * page containing it is no longer visible. For example, an applet
486 * with animation might want to use the <code>start</code> method to
487 * resume animation, and the <code>stop</code> method to suspend the
488 * animation.
489 * <p>
490 * The implementation of this method provided by the
491 * <code>Applet</code> class does nothing.
492 *
493 * @see java.applet.Applet#destroy()
494 * @see java.applet.Applet#init()
495 */
496 public void stop() {
497 }
498
499 /**
500 * Called by the browser or applet viewer to inform
501 * this applet that it is being reclaimed and that it should destroy
502 * any resources that it has allocated. The <code>stop</code> method
503 * will always be called before <code>destroy</code>.
504 * <p>
505 * A subclass of <code>Applet</code> should override this method if
506 * it has any operation that it wants to perform before it is
507 * destroyed. For example, an applet with threads would use the
508 * <code>init</code> method to create the threads and the
509 * <code>destroy</code> method to kill them.
510 * <p>
511 * The implementation of this method provided by the
512 * <code>Applet</code> class does nothing.
513 *
514 * @see java.applet.Applet#init()
515 * @see java.applet.Applet#start()
516 * @see java.applet.Applet#stop()
517 */
518 public void destroy() {
519 }
520
521 //
522 // Accessibility support
523 //
524
525 AccessibleContext accessibleContext = null;
526
527 /**
528 * Gets the AccessibleContext associated with this Applet.
529 * For applets, the AccessibleContext takes the form of an
530 * AccessibleApplet.
531 * A new AccessibleApplet instance is created if necessary.
532 *
533 * @return an AccessibleApplet that serves as the
534 * AccessibleContext of this Applet
535 * @since 1.3
536 */
537 public AccessibleContext getAccessibleContext() {
538 if (accessibleContext == null) {
539 accessibleContext = new AccessibleApplet();
540 }
541 return accessibleContext;
542 }
543
544 /**
545 * This class implements accessibility support for the
546 * <code>Applet</code> class. It provides an implementation of the
547 * Java Accessibility API appropriate to applet user-interface elements.
548 * @since 1.3
549 */
550 protected class AccessibleApplet extends AccessibleAWTPanel {
551
552 private static final long serialVersionUID = 8127374778187708896L;
553
554 /**
555 * Get the role of this object.
556 *
557 * @return an instance of AccessibleRole describing the role of the
558 * object
559 */
560 public AccessibleRole getAccessibleRole() {
561 return AccessibleRole.FRAME;
562 }
563
564 /**
565 * Get the state of this object.
566 *
567 * @return an instance of AccessibleStateSet containing the current
568 * state set of the object
569 * @see AccessibleState
570 */
571 public AccessibleStateSet getAccessibleStateSet() {
572 AccessibleStateSet states = super.getAccessibleStateSet();
573 states.add(AccessibleState.ACTIVE);
574 return states;
575 }
576
577 }
578 }
Save This Page