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