/[classpath]/classpath/java/applet/Applet.java
ViewVC logotype

Diff of /classpath/java/applet/Applet.java

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

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

Legend:
Removed from v.1.4  
changed lines
  Added in v.1.5

savannah-hackers-public@gnu.org
ViewVC Help
Powered by ViewVC 1.1.26