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