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