home *** CD-ROM | disk | FTP | other *** search
/ Java 1.2 How-To / JavaHowTo.iso / 3rdParty / jbuilder / unsupported / JDK1.2beta3 / SOURCE / SRC.ZIP / java / applet / Applet.java next >
Encoding:
Java Source  |  1998-03-20  |  14.7 KB  |  441 lines
  1. /*
  2.  * @(#)Applet.java    1.52 98/03/18
  3.  *
  4.  * Copyright 1995-1998 by Sun Microsystems, Inc.,
  5.  * 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
  6.  * All rights reserved.
  7.  *
  8.  * This software is the confidential and proprietary information
  9.  * of Sun Microsystems, Inc. ("Confidential Information").  You
  10.  * shall not disclose such Confidential Information and shall use
  11.  * it only in accordance with the terms of the license agreement
  12.  * you entered into with Sun.
  13.  */
  14. package java.applet;
  15.  
  16. import java.awt.*;
  17. import java.awt.image.ColorModel;
  18. import java.net.URL;
  19. import java.net.MalformedURLException;
  20. import java.util.Hashtable;
  21. import java.util.Locale;
  22.  
  23. /**
  24.  * An applet is a small program that is intended not to be run on 
  25.  * its own, but rather to be embedded inside another application. 
  26.  * <p>
  27.  * The <code>Applet</code> class must be the superclass of any 
  28.  * applet that is to be embedded in a Web page or viewed by the Java 
  29.  * Applet Viewer. The <code>Applet</code> class provides a standard 
  30.  * interface between applets and their environment. 
  31.  *
  32.  * @author      Arthur van Hoff
  33.  * @author      Chris Warth
  34.  * @version     1.52, 03/18/98
  35.  * @since       JDK1.0
  36.  */
  37. public class Applet extends Panel {
  38.     /**
  39.      * Applets can be serialized but the following conventions MUST be followed:
  40.      *
  41.      * Before Serialization:
  42.      * An applet must be in STOPPED state.
  43.      *
  44.      * After Deserialization:
  45.      * The applet will be restored in STOPPED state (and most clients will likely
  46.      *    move it into RUNNING state).
  47.      * The stub field will be restored by the reader.
  48.      */
  49.     transient private AppletStub stub;
  50.  
  51.     /* version ID for serialized form. */
  52.     private static final long serialVersionUID = -5836846270535785031L;
  53.  
  54.     /**
  55.      * Sets this applet's stub. This is done automatically by the system. 
  56.      * 
  57.      * @param   stub   the new stub.
  58.      */
  59.     public final void setStub(AppletStub stub) {
  60.     this.stub = (AppletStub)stub;
  61.     }
  62.  
  63.     /**
  64.      * Determines if this applet is active. An applet is marked active 
  65.      * just before its <code>start</code> method is called. It becomes 
  66.      * inactive just before its <code>stop</code> method is called. 
  67.      *
  68.      * @return  <code>true</code> if the applet is active;
  69.      *          <code>false</code> otherwise.
  70.      * @see     java.applet.Applet#start()
  71.      * @see     java.applet.Applet#stop()
  72.      */
  73.     public boolean isActive() {
  74.     if (stub != null) {
  75.         return stub.isActive();
  76.     } else {    // If stub field not filled in, applet never active
  77.         return false;
  78.     }
  79.     }
  80.     
  81.     /**
  82.      * Gets the document URL. This is the URL of the document in which
  83.      * the applet is embedded.
  84.      *
  85.      * @return  the <a href="java.net.URL.html#_top_"><code>URL</code></a> of
  86.      *          the document that contains this applet.
  87.      * @see     java.applet.Applet#getCodeBase()
  88.      */
  89.     public URL getDocumentBase() {
  90.     return stub.getDocumentBase();
  91.     }
  92.  
  93.     /**
  94.      * Gets the base URL. This is the URL of the applet itself. 
  95.      *
  96.      * @return  the <a href="java.net.URL.html#_top_"><code>URL</code></a> of
  97.      *          this applet.
  98.      * @see     java.applet.Applet#getDocumentBase()
  99.      */
  100.     public URL getCodeBase() {
  101.     return stub.getCodeBase();
  102.     }
  103.  
  104.     /**
  105.      * Returns the value of the named parameter in the HTML tag. For 
  106.      * example, if this applet is specified as
  107.      * <blockquote><pre>
  108.      * <applet code="Clock" width=50 height=50>
  109.      * <param name=Color value="blue">
  110.      * </applet>
  111.      * </pre></blockquote>
  112.      * <p>
  113.      * then a call to <code>getParameter("Color")</code> returns the 
  114.      * value <code>"blue"</code>. 
  115.      * <p>
  116.      * The <code>name</code> argument is case insensitive. 
  117.      *
  118.      * @param   name   a parameter name.
  119.      * @return  the value of the named parameter.
  120.      */
  121.      public String getParameter(String name) {
  122.      return stub.getParameter(name);
  123.      }
  124.  
  125.     /**
  126.      * Determines this applet's context, which allows the applet to 
  127.      * query and affect the environment in which it runs. 
  128.      * <p>
  129.      * This environment of an applet represents the document that 
  130.      * contains the applet. 
  131.      *
  132.      * @return  the applet's context.
  133.      */
  134.     public AppletContext getAppletContext() {
  135.     return stub.getAppletContext();
  136.     }
  137.    
  138.     /**
  139.      * Requests that this applet be resized. 
  140.      *
  141.      * @param   width    the new requested width for the applet.
  142.      * @param   height   the new requested height for the applet.
  143.      */
  144.     public void resize(int width, int height) {
  145.     Dimension d = size();
  146.     if ((d.width != width) || (d.height != height)) {
  147.         super.resize(width, height);
  148.         if (stub != null) {
  149.         stub.appletResize(width, height);
  150.         }
  151.     }
  152.     }
  153.  
  154.     /**
  155.      * Requests that this applet be resized. 
  156.      *
  157.      * @param   d   an object giving the new width and height.
  158.      */    
  159.     public void resize(Dimension d) {
  160.     resize(d.width, d.height);
  161.     }
  162.  
  163.     /**
  164.      * Requests that the argument string be displayed in the 
  165.      * "status window". Many browsers and applet viewers 
  166.      * provide such a window, where the application can inform users of 
  167.      * its current state. 
  168.      *
  169.      * @param   msg   a string to display in the status window.
  170.      */
  171.     public void showStatus(String msg) {
  172.     getAppletContext().showStatus(msg);
  173.     }
  174.  
  175.     /**
  176.      * Returns an <code>Image</code> object that can then be painted on 
  177.      * the screen. The <code>url</code> that is passed as an argument 
  178.      * must specify an absolute URL. 
  179.      * <p>
  180.      * This method always returns immediately, whether or not the image 
  181.      * exists. When this applet attempts to draw the image on the screen, 
  182.      * the data will be loaded. The graphics primitives that draw the 
  183.      * image will incrementally paint on the screen. 
  184.      *
  185.      * @param   url   an absolute URL giving the location of the image.
  186.      * @return  the image at the specified URL.
  187.      * @see     java.awt.Image
  188.      */
  189.     public Image getImage(URL url) {
  190.     return getAppletContext().getImage(url);
  191.     }
  192.  
  193.     /**
  194.      * Returns an <code>Image</code> object that can then be painted on 
  195.      * the screen. The <code>url</code> argument must specify an absolute 
  196.      * URL. The <code>name</code> argument is a specifier that is 
  197.      * relative to the <code>url</code> argument. 
  198.      * <p>
  199.      * This method always returns immediately, whether or not the image 
  200.      * exists. When this applet attempts to draw the image on the screen, 
  201.      * the data will be loaded. The graphics primitives that draw the 
  202.      * image will incrementally paint on the screen. 
  203.      *
  204.      * @param   url    an absolute URL giving the base location of the image.
  205.      * @param   name   the location of the image, relative to the
  206.      *                 <code>url</code> argument.
  207.      * @return  the image at the specified URL.
  208.      * @see     java.awt.Image
  209.      */
  210.     public Image getImage(URL url, String name) {
  211.     try {
  212.         return getImage(new URL(url, name));
  213.     } catch (MalformedURLException e) {
  214.         return null;
  215.     }
  216.     }
  217.  
  218.     /**
  219.      * Get an audio clip from the given URL
  220.      * @param url Points to the audio clip
  221.      *
  222.      * @since       JDK1.2
  223.      */
  224.     public final static AudioClip newAudioClip(URL url) {
  225.         return new sun.applet.AppletAudioClip(url);
  226.     }
  227.  
  228.     /**
  229.      * Returns the <code>AudioClip</code> object specified by the 
  230.      * <code>URL</code> argument. 
  231.      * <p>
  232.      * This method always returns immediately, whether or not the audio 
  233.      * clip exists. When this applet attempts to play the audio clip, the 
  234.      * data will be loaded. 
  235.      *
  236.      * @param   url  an absolute URL giving the location of the audio clip.
  237.      * @return  the audio clip at the specified URL.
  238.      * @see     java.applet.AudioClip
  239.      */
  240.     public AudioClip getAudioClip(URL url) {
  241.     return getAppletContext().getAudioClip(url);
  242.     }
  243.  
  244.     /**
  245.      * Returns the <code>AudioClip</code> object specified by the 
  246.      * <code>URL</code> and <code>name</code> arguments. 
  247.      * <p>
  248.      * This method always returns immediately, whether or not the audio 
  249.      * clip exists. When this applet attempts to play the audio clip, the 
  250.      * data will be loaded. 
  251.      * 
  252.      * @param   url    an absolute URL giving the base location of the
  253.      *                 audio clip.
  254.      * @param   name   the location of the audio clip, relative to the
  255.      *                 <code>url</code> argument.
  256.      * @return  the audio clip at the specified URL.
  257.      * @see     java.applet.AudioClip
  258.      */
  259.     public AudioClip getAudioClip(URL url, String name) {
  260.     try {
  261.         return getAudioClip(new URL(url, name));
  262.     } catch (MalformedURLException e) {
  263.         return null;
  264.     }
  265.     }
  266.  
  267.     /**
  268.      * Returns information about this applet. An applet should override 
  269.      * this method to return a <code>String</code> containing information 
  270.      * about the author, version, and copyright of the applet. 
  271.      * <p>
  272.      * The implementation of this method provided by the 
  273.      * <code>Applet</code> class returns <code>null</code>. 
  274.      *
  275.      * @return  a string containing information about the author, version, and
  276.      *          copyright of the applet.
  277.      */
  278.     public String getAppletInfo() {
  279.     return null;
  280.     }
  281.  
  282.     /** 
  283.      * Gets the Locale for the applet, if it has been set.
  284.      * If no Locale has been set, then the default Locale 
  285.      * is returned.
  286.      *
  287.      * @return  the Locale for the applet
  288.      * @since   JDK1.1
  289.      */
  290.  
  291.     public Locale getLocale() {
  292.       Locale locale = super.getLocale();
  293.       if (locale == null) {
  294.     return Locale.getDefault();
  295.       }
  296.       return locale;
  297.     }
  298.  
  299.     /**
  300.      * Returns information about the parameters than are understood by 
  301.      * this applet. An applet should override this method to return an 
  302.      * array of <code>Strings</code> describing these parameters. 
  303.      * <p>
  304.      * Each element of the array should be a set of three 
  305.      * <code>Strings</code> containing the name, the type, and a 
  306.      * description. For example:
  307.      * <p><blockquote><pre>
  308.      * String pinfo[][] = {
  309.      *     {"fps",    "1-10",    "frames per second"},
  310.      *     {"repeat", "boolean", "repeat image loop"},
  311.      *     {"imgs",   "url",     "images directory"}
  312.      * };
  313.      * </pre></blockquote>
  314.      * <p>
  315.      * The implementation of this method provided by the 
  316.      * <code>Applet</code> class returns <code>null</code>. 
  317.      *
  318.      * @return  an array describing the parameters this applet looks for.
  319.      */
  320.     public String[][] getParameterInfo() {
  321.     return null;
  322.     }
  323.  
  324.     /**
  325.      * Plays the audio clip at the specified absolute URL. Nothing 
  326.      * happens if the audio clip cannot be found. 
  327.      *
  328.      * @param   url   an absolute URL giving the location of the audio clip.
  329.      */
  330.     public void play(URL url) {
  331.     AudioClip clip = getAudioClip(url);
  332.     if (clip != null) {
  333.         clip.play();
  334.     }
  335.     }
  336.  
  337.     /**
  338.      * Plays the audio clip given the URL and a specifier that is 
  339.      * relative to it. Nothing happens if the audio clip cannot be found. 
  340.      *
  341.      * @param   url    an absolute URL giving the base location of the
  342.      *                 audio clip.
  343.      * @param   name   the location of the audio clip, relative to the
  344.      *                 <code>url</code> argument.
  345.      */
  346.     public void play(URL url, String name) {
  347.     AudioClip clip = getAudioClip(url, name);
  348.     if (clip != null) {
  349.         clip.play();
  350.     }
  351.     }
  352.  
  353.     /**
  354.      * Called by the browser or applet viewer to inform 
  355.      * this applet that it has been loaded into the system. It is always 
  356.      * called before the first time that the <code>start</code> method is 
  357.      * called. 
  358.      * <p>
  359.      * A subclass of <code>Applet</code> should override this method if 
  360.      * it has initialization to perform. For example, an applet with 
  361.      * threads would use the <code>init</code> method to create the 
  362.      * threads and the <code>destroy</code> method to kill them. 
  363.      * <p>
  364.      * The implementation of this method provided by the 
  365.      * <code>Applet</code> class does nothing. 
  366.      *
  367.      * @see     java.applet.Applet#destroy()
  368.      * @see     java.applet.Applet#start()
  369.      * @see     java.applet.Applet#stop()
  370.      */
  371.     public void init() {
  372.     }
  373.  
  374.     /**
  375.      * Called by the browser or applet viewer to inform 
  376.      * this applet that it should start its execution. It is called after 
  377.      * the <code>init</code> method and each time the applet is revisited 
  378.      * in a Web page. 
  379.      * <p>
  380.      * A subclass of <code>Applet</code> should override this method if 
  381.      * it has any operation that it wants to perform each time the Web 
  382.      * page containing it is visited. For example, an applet with 
  383.      * animation might want to use the <code>start</code> method to 
  384.      * resume animation, and the <code>stop</code> method to suspend the 
  385.      * animation. 
  386.      * <p>
  387.      * The implementation of this method provided by the 
  388.      * <code>Applet</code> class does nothing. 
  389.      *
  390.      * @see     java.applet.Applet#destroy()
  391.      * @see     java.applet.Applet#init()
  392.      * @see     java.applet.Applet#stop()
  393.      */
  394.     public void start() {
  395.     }
  396.  
  397.     /**
  398.      * Called by the browser or applet viewer to inform 
  399.      * this applet that it should stop its execution. It is called when 
  400.      * the Web page that contains this applet has been replaced by 
  401.      * another page, and also just before the applet is to be destroyed. 
  402.      * <p>
  403.      * A subclass of <code>Applet</code> should override this method if 
  404.      * it has any operation that it wants to perform each time the Web 
  405.      * page containing it is no longer visible. For example, an applet 
  406.      * with animation might want to use the <code>start</code> method to 
  407.      * resume animation, and the <code>stop</code> method to suspend the 
  408.      * animation. 
  409.      * <p>
  410.      * The implementation of this method provided by the 
  411.      * <code>Applet</code> class does nothing. 
  412.      *
  413.      * @see     java.applet.Applet#destroy()
  414.      * @see     java.applet.Applet#init()
  415.      */
  416.     public void stop() {
  417.     }
  418.  
  419.     /**
  420.      * Called by the browser or applet viewer to inform 
  421.      * this applet that it is being reclaimed and that it should destroy 
  422.      * any resources that it has allocated. The <code>stop</code> method 
  423.      * will always be called before <code>destroy</code>. 
  424.      * <p>
  425.      * A subclass of <code>Applet</code> should override this method if 
  426.      * it has any operation that it wants to perform before it is 
  427.      * destroyed. For example, an applet with threads would use the 
  428.      * <code>init</code> method to create the threads and the 
  429.      * <code>destroy</code> method to kill them. 
  430.      * <p>
  431.      * The implementation of this method provided by the 
  432.      * <code>Applet</code> class does nothing. 
  433.      *
  434.      * @see     java.applet.Applet#init()
  435.      * @see     java.applet.Applet#start()
  436.      * @see     java.applet.Applet#stop()
  437.      */
  438.     public void destroy() {
  439.     }
  440. }
  441.