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