001: /*
002: * @(#)Applet.java 1.54 06/10/16
003: *
004: * Copyright 1990-2006 Sun Microsystems, Inc. All Rights Reserved.
005: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
006: *
007: * This program is free software; you can redistribute it and/or
008: * modify it under the terms of the GNU General Public License version
009: * 2 only, as published by the Free Software Foundation.
010: *
011: * This program is distributed in the hope that it will be useful, but
012: * WITHOUT ANY WARRANTY; without even the implied warranty of
013: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
014: * General Public License version 2 for more details (a copy is
015: * included at /legal/license.txt).
016: *
017: * You should have received a copy of the GNU General Public License
018: * version 2 along with this work; if not, write to the Free Software
019: * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
020: * 02110-1301 USA
021: *
022: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
023: * Clara, CA 95054 or visit www.sun.com if you need additional
024: * information or have any questions.
025: */
026:
027: package java.applet;
028:
029: import java.awt.*;
030: import java.awt.image.ColorModel;
031: import java.net.URL;
032: import java.net.MalformedURLException;
033: import java.util.Hashtable;
034: import java.util.Locale;
035:
036: //import javax.accessibility.*;
037:
038: /**
039: * An applet is a small program that is intended not to be run on
040: * its own, but rather to be embedded inside another application.
041: * <p>
042: * The <code>Applet</code> class must be the superclass of any
043: * applet that is to be embedded in a Web page or viewed by the Java
044: * Applet Viewer. The <code>Applet</code> class provides a standard
045: * interface between applets and their environment.
046: *
047: * @author Arthur van Hoff
048: * @author Chris Warth
049: * @version 1.49, 08/21/02
050: * @since JDK1.0
051: */
052: public class Applet extends Panel {
053: /**
054: * Applets can be serialized but the following conventions MUST be followed:
055: *
056: * Before Serialization:
057: * An applet must be in STOPPED state.
058: *
059: * After Deserialization:
060: * The applet will be restored in STOPPED state (and most clients will
061: * likely move it into RUNNING state).
062: * The stub field will be restored by the reader.
063: */
064: transient private AppletStub stub;
065: /* version ID for serialized form. */
066: private static final long serialVersionUID = -5836846270535785031L;
067:
068: /**
069: * Sets this applet's stub. This is done automatically by the system.
070: *
071: * @param stub the new stub.
072: */
073: public final void setStub(AppletStub stub) {
074: this .stub = (AppletStub) stub;
075: }
076:
077: /**
078: * Determines if this applet is active. An applet is marked active
079: * just before its <code>start</code> method is called. It becomes
080: * inactive just before its <code>stop</code> method is called.
081: *
082: * @return <code>true</code> if the applet is active;
083: * <code>false</code> otherwise.
084: * @see java.applet.Applet#start()
085: * @see java.applet.Applet#stop()
086: */
087: public boolean isActive() {
088: if (stub != null) {
089: return stub.isActive();
090: } else { // If stub field not filled in, applet never active
091: return false;
092: }
093: }
094:
095: /**
096: * Returns an absolute URL naming the directory of the document in which
097: * the applet is embedded. For example, suppose an applet is contained
098: * within the document:
099: * <blockquote><pre>
100: * http://java.sun.com/products/jdk/1.2/index.html
101: * </pre></blockquote>
102: * The document base is:
103: * <blockquote><pre>
104: * http://java.sun.com/products/jdk/1.2/
105: * </pre></blockquote>
106: *
107: * @return the {@link java.net.URL} of the document that contains this
108: * applet.
109: * @see java.applet.Applet#getCodeBase()
110: */
111: public URL getDocumentBase() {
112: return stub.getDocumentBase();
113: }
114:
115: /**
116: * Gets the base URL. This is the URL of the applet itself.
117: *
118: * @return the {@link java.net.URL} of
119: * this applet.
120: * @see java.applet.Applet#getDocumentBase()
121: */
122: public URL getCodeBase() {
123: return stub.getCodeBase();
124: }
125:
126: /**
127: * Returns the value of the named parameter in the HTML tag. For
128: * example, if this applet is specified as
129: * <blockquote><pre>
130: * <applet code="Clock" width=50 height=50>
131: * <param name=Color value="blue">
132: * </applet>
133: * </pre></blockquote>
134: * <p>
135: * then a call to <code>getParameter("Color")</code> returns the
136: * value <code>"blue"</code>.
137: * <p>
138: * The <code>name</code> argument is case insensitive.
139: *
140: * @param name a parameter name.
141: * @return the value of the named parameter,
142: * or <code>null</code> if not set.
143: */
144: public String getParameter(String name) {
145: return stub.getParameter(name);
146: }
147:
148: /**
149: * Determines this applet's context, which allows the applet to
150: * query and affect the environment in which it runs.
151: * <p>
152: * This environment of an applet represents the document that
153: * contains the applet.
154: *
155: * @return the applet's context.
156: */
157: public AppletContext getAppletContext() {
158: return stub.getAppletContext();
159: }
160:
161: /**
162: * Requests that this applet be resized.
163: *
164: * @param width the new requested width for the applet.
165: * @param height the new requested height for the applet.
166: */
167: public void resize(int width, int height) {
168: Dimension d = size();
169: if ((d.width != width) || (d.height != height)) {
170: super .resize(width, height);
171: if (stub != null) {
172: stub.appletResize(width, height);
173: }
174: }
175: }
176:
177: /**
178: * Requests that this applet be resized.
179: *
180: * @param d an object giving the new width and height.
181: */
182: public void resize(Dimension d) {
183: resize(d.width, d.height);
184: }
185:
186: /**
187: * Requests that the argument string be displayed in the
188: * "status window". Many browsers and applet viewers
189: * provide such a window, where the application can inform users of
190: * its current state.
191: *
192: * @param msg a string to display in the status window.
193: */
194: public void showStatus(String msg) {
195: getAppletContext().showStatus(msg);
196: }
197:
198: /**
199: * Returns an <code>Image</code> object that can then be painted on
200: * the screen. The <code>url</code> that is passed as an argument
201: * must specify an absolute URL.
202: * <p>
203: * This method always returns immediately, whether or not the image
204: * exists. When this applet attempts to draw the image on the screen,
205: * the data will be loaded. The graphics primitives that draw the
206: * image will incrementally paint on the screen.
207: *
208: * @param url an absolute URL giving the location of the image.
209: * @return the image at the specified URL.
210: * @see java.awt.Image
211: */
212: public Image getImage(URL url) {
213: return getAppletContext().getImage(url);
214: }
215:
216: /**
217: * Returns an <code>Image</code> object that can then be painted on
218: * the screen. The <code>url</code> argument must specify an absolute
219: * URL. The <code>name</code> argument is a specifier that is
220: * relative to the <code>url</code> argument.
221: * <p>
222: * This method always returns immediately, whether or not the image
223: * exists. When this applet attempts to draw the image on the screen,
224: * the data will be loaded. The graphics primitives that draw the
225: * image will incrementally paint on the screen.
226: *
227: * @param url an absolute URL giving the base location of the image.
228: * @param name the location of the image, relative to the
229: * <code>url</code> argument.
230: * @return the image at the specified URL.
231: * @see java.awt.Image
232: */
233: public Image getImage(URL url, String name) {
234: /* Adding a getResource() call below in order to enable
235: * loading of images located inside a jar file. This change
236: * causes this method not to conform to JDK spec. Related bug
237: * IDs are 4157932, 4159155 & 4214785 that allude to the correct
238: * behaviour in JDK.
239: */
240: URL u = this .getClass().getResource(name);
241:
242: if (u != null) {
243: return getImage(u);
244: } else {
245: try {
246: return getImage(new URL(url, name));
247: } catch (MalformedURLException e) {
248: return null;
249: }
250: }
251: }
252:
253: /**
254: * Get an audio clip from the given URL.
255: *
256: * @param url points to the audio clip
257: * @return the audio clip at the specified URL.
258: *
259: * @since 1.2
260: */
261: public final static AudioClip newAudioClip(URL url) {
262: return new sun.applet.AppletAudioClip(url);
263: }
264:
265: /**
266: * Returns the <code>AudioClip</code> object specified by the
267: * <code>URL</code> argument.
268: * <p>
269: * This method always returns immediately, whether or not the audio
270: * clip exists. When this applet attempts to play the audio clip, the
271: * data will be loaded.
272: *
273: * @param url an absolute URL giving the location of the audio clip.
274: * @return the audio clip at the specified URL.
275: * @see java.applet.AudioClip
276: */
277: public AudioClip getAudioClip(URL url) {
278: return getAppletContext().getAudioClip(url);
279: }
280:
281: /**
282: * Returns the <code>AudioClip</code> object specified by the
283: * <code>URL</code> and <code>name</code> arguments.
284: * <p>
285: * This method always returns immediately, whether or not the audio
286: * clip exists. When this applet attempts to play the audio clip, the
287: * data will be loaded.
288: *
289: * @param url an absolute URL giving the base location of the
290: * audio clip.
291: * @param name the location of the audio clip, relative to the
292: * <code>url</code> argument.
293: * @return the audio clip at the specified URL.
294: * @see java.applet.AudioClip
295: */
296: public AudioClip getAudioClip(URL url, String name) {
297: try {
298: return getAudioClip(new URL(url, name));
299: } catch (MalformedURLException e) {
300: return null;
301: }
302: }
303:
304: /**
305: * Returns information about this applet. An applet should override
306: * this method to return a <code>String</code> containing information
307: * about the author, version, and copyright of the applet.
308: * <p>
309: * The implementation of this method provided by the
310: * <code>Applet</code> class returns <code>null</code>.
311: *
312: * @return a string containing information about the author, version, and
313: * copyright of the applet.
314: */
315: public String getAppletInfo() {
316: return null;
317: }
318:
319: /**
320: * Gets the Locale for the applet, if it has been set.
321: * If no Locale has been set, then the default Locale
322: * is returned.
323: *
324: * @return the Locale for the applet
325: * @since JDK1.1
326: */
327:
328: public Locale getLocale() {
329: Locale locale = super .getLocale();
330: if (locale == null) {
331: return Locale.getDefault();
332: }
333: return locale;
334: }
335:
336: /**
337: * Returns information about the parameters than are understood by
338: * this applet. An applet should override this method to return an
339: * array of <code>Strings</code> describing these parameters.
340: * <p>
341: * Each element of the array should be a set of three
342: * <code>Strings</code> containing the name, the type, and a
343: * description. For example:
344: * <p><blockquote><pre>
345: * String pinfo[][] = {
346: * {"fps", "1-10", "frames per second"},
347: * {"repeat", "boolean", "repeat image loop"},
348: * {"imgs", "url", "images directory"}
349: * };
350: * </pre></blockquote>
351: * <p>
352: * The implementation of this method provided by the
353: * <code>Applet</code> class returns <code>null</code>.
354: *
355: * @return an array describing the parameters this applet looks for.
356: */
357: public String[][] getParameterInfo() {
358: return null;
359: }
360:
361: /**
362: * Plays the audio clip at the specified absolute URL. Nothing
363: * happens if the audio clip cannot be found.
364: *
365: * @param url an absolute URL giving the location of the audio clip.
366: */
367: public void play(URL url) {
368: AudioClip clip = getAudioClip(url);
369: if (clip != null) {
370: clip.play();
371: }
372: }
373:
374: /**
375: * Plays the audio clip given the URL and a specifier that is
376: * relative to it. Nothing happens if the audio clip cannot be found.
377: *
378: * @param url an absolute URL giving the base location of the
379: * audio clip.
380: * @param name the location of the audio clip, relative to the
381: * <code>url</code> argument.
382: */
383: public void play(URL url, String name) {
384: AudioClip clip = getAudioClip(url, name);
385: if (clip != null) {
386: clip.play();
387: }
388: }
389:
390: /**
391: * Called by the browser or applet viewer to inform
392: * this applet that it has been loaded into the system. It is always
393: * called before the first time that the <code>start</code> method is
394: * called.
395: * <p>
396: * A subclass of <code>Applet</code> should override this method if
397: * it has initialization to perform. For example, an applet with
398: * threads would use the <code>init</code> method to create the
399: * threads and the <code>destroy</code> method to kill them.
400: * <p>
401: * The implementation of this method provided by the
402: * <code>Applet</code> class does nothing.
403: *
404: * @see java.applet.Applet#destroy()
405: * @see java.applet.Applet#start()
406: * @see java.applet.Applet#stop()
407: */
408: public void init() {
409: }
410:
411: /**
412: * Called by the browser or applet viewer to inform
413: * this applet that it should start its execution. It is called after
414: * the <code>init</code> method and each time the applet is revisited
415: * in a Web page.
416: * <p>
417: * A subclass of <code>Applet</code> should override this method if
418: * it has any operation that it wants to perform each time the Web
419: * page containing it is visited. For example, an applet with
420: * animation might want to use the <code>start</code> method to
421: * resume animation, and the <code>stop</code> method to suspend the
422: * animation.
423: * <p>
424: * The implementation of this method provided by the
425: * <code>Applet</code> class does nothing.
426: *
427: * @see java.applet.Applet#destroy()
428: * @see java.applet.Applet#init()
429: * @see java.applet.Applet#stop()
430: */
431: public void start() {
432: }
433:
434: /**
435: * Called by the browser or applet viewer to inform
436: * this applet that it should stop its execution. It is called when
437: * the Web page that contains this applet has been replaced by
438: * another page, and also just before the applet is to be destroyed.
439: * <p>
440: * A subclass of <code>Applet</code> should override this method if
441: * it has any operation that it wants to perform each time the Web
442: * page containing it is no longer visible. For example, an applet
443: * with animation might want to use the <code>start</code> method to
444: * resume animation, and the <code>stop</code> method to suspend the
445: * animation.
446: * <p>
447: * The implementation of this method provided by the
448: * <code>Applet</code> class does nothing.
449: *
450: * @see java.applet.Applet#destroy()
451: * @see java.applet.Applet#init()
452: */
453: public void stop() {
454: }
455:
456: /**
457: * Called by the browser or applet viewer to inform
458: * this applet that it is being reclaimed and that it should destroy
459: * any resources that it has allocated. The <code>stop</code> method
460: * will always be called before <code>destroy</code>.
461: * <p>
462: * A subclass of <code>Applet</code> should override this method if
463: * it has any operation that it wants to perform before it is
464: * destroyed. For example, an applet with threads would use the
465: * <code>init</code> method to create the threads and the
466: * <code>destroy</code> method to kill them.
467: * <p>
468: * The implementation of this method provided by the
469: * <code>Applet</code> class does nothing.
470: *
471: * @see java.applet.Applet#init()
472: * @see java.applet.Applet#start()
473: * @see java.applet.Applet#stop()
474: */
475: public void destroy() {
476: }
477: }
|