Applet


1   /*
2    * @(#)Applet.java  1.77 04/06/22
3    *
4    * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5    * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6    */
7   package java.applet;
8   
9   import java.awt.*;
10  import java.awt.image.ColorModel  ;
11  import java.io.IOException  ;
12  import java.io.ObjectInputStream  ;
13  import java.net.URL  ;
14  import java.net.MalformedURLException  ;
15  import java.util.Hashtable  ;
16  import java.util.Locale  ;
17  import javax.accessibility.*;
18  
19  /**
20   * An applet is a small program that is intended not to be run on
21   * its own, but rather to be embedded inside another application.
22   * <p>
23   * The <code>Applet</code> class must be the superclass of any
24   * applet that is to be embedded in a Web page or viewed by the Java
25   * Applet Viewer. The <code>Applet</code> class provides a standard
26   * interface between applets and their environment.
27   *
28   * @author      Arthur van Hoff
29   * @author      Chris Warth
30   * @version     1.77, 06/22/04
31   * @since       JDK1.0
32   */
33  public class Applet extends Panel {
34      
35      /**
36       * Creates a new Applet object
37       * @exception HeadlessException if GraphicsEnvironment.isHeadless()
38       * returns true.
39       * @see java.awt.GraphicsEnvironment#isHeadless
40       * @since 1.4
41       */
42      public Applet() throws HeadlessException {
43          if (GraphicsEnvironment.isHeadless()) {
44              throw new HeadlessException();
45          }
46      }
47      
48      /**
49       * Applets can be serialized but the following conventions MUST be followed:
50       *
51       * Before Serialization:
52       * An applet must be in STOPPED state.
53       *
54       * After Deserialization:
55       * The applet will be restored in STOPPED state (and most clients will
56       * likely move it into RUNNING state).
57       * The stub field will be restored by the reader.
58       */
59      transient private AppletStub   stub;
60  
61      /* version ID for serialized form. */
62      private static final long serialVersionUID = -5836846270535785031L;
63  
64      /**
65       * Read an applet from an object input stream.
66       * @exception HeadlessException if
67       * <code>GraphicsEnvironment.isHeadless()</code> returns
68       * <code>true</code>
69       * @serial
70       * @see java.awt.GraphicsEnvironment#isHeadless
71       * @since 1.4
72       */
73      private void readObject(ObjectInputStream   s)
74          throws ClassNotFoundException  , IOException  , HeadlessException {
75          if (GraphicsEnvironment.isHeadless()) {
76              throw new HeadlessException();
77          }
78          s.defaultReadObject();
79      }
80  
81      /**
82       * Sets this applet's stub. This is done automatically by the system.
83       * <p>If there is a security manager, its <code> checkPermission </code>
84       * method is called with the
85       * <code>AWTPermission("setAppletStub")</code>
86       * permission if a stub has already been set.
87       * @param   stub   the new stub.
88       * @exception SecurityException if the caller cannot set the stub
89       */
90      public final void setStub(AppletStub   stub) {
91      if (this.stub != null) {
92          SecurityManager   s = System.getSecurityManager();
93          if (s != null) {
94              s.checkPermission(new AWTPermission("setAppletStub"));
95          }
96      }
97      this.stub = (AppletStub  )stub;
98      }
99  
100     /**
101      * Determines if this applet is active. An applet is marked active
102      * just before its <code>start</code> method is called. It becomes
103      * inactive just before its <code>stop</code> method is called.
104      *
105      * @return  <code>true</code> if the applet is active;
106      *          <code>false</code> otherwise.
107      * @see     java.applet.Applet#start()
108      * @see     java.applet.Applet#stop()
109      */
110     public boolean isActive() {
111     if (stub != null) {
112         return stub.isActive();
113     } else {    // If stub field not filled in, applet never active
114         return false;
115     }
116     }
117 
118     /**
119      * Gets the URL of the document in which this applet is embedded. 
120      * For example, suppose an applet is contained
121      * within the document:
122      * <blockquote><pre>
123      *    http://java.sun.com/products/jdk/1.2/index.html
124      * </pre></blockquote>
125      * The document base is:
126      * <blockquote><pre>
127      *    http://java.sun.com/products/jdk/1.2/index.html
128      * </pre></blockquote>
129      *
130      * @return  the {@link java.net.URL} of the document that contains this
131      *          applet.
132      * @see     java.applet.Applet#getCodeBase()
133      */
134     public URL   getDocumentBase() {
135     return stub.getDocumentBase();
136     }
137 
138     /**
139      * Gets the base URL. This is the URL of the directory which contains this applet.  
140      *
141      * @return  the base {@link java.net.URL} of
142      *          the directory which contains this applet.
143      * @see     java.applet.Applet#getDocumentBase()
144      */
145     public URL   getCodeBase() {
146     return stub.getCodeBase();
147     }
148 
149     /**
150      * Returns the value of the named parameter in the HTML tag. For
151      * example, if this applet is specified as
152      * <blockquote><pre>
153      * &lt;applet code="Clock" width=50 height=50&gt;
154      * &lt;param name=Color value="blue"&gt;
155      * &lt;/applet&gt;
156      * </pre></blockquote>
157      * <p>
158      * then a call to <code>getParameter("Color")</code> returns the
159      * value <code>"blue"</code>.
160      * <p>
161      * The <code>name</code> argument is case insensitive.
162      *
163      * @param   name   a parameter name.
164      * @return  the value of the named parameter,
165      *          or <code>null</code> if not set.
166      */
167      public String   getParameter(String   name) {
168      return stub.getParameter(name);
169      }
170 
171     /**
172      * Determines this applet's context, which allows the applet to
173      * query and affect the environment in which it runs.
174      * <p>
175      * This environment of an applet represents the document that
176      * contains the applet.
177      *
178      * @return  the applet's context.
179      */
180     public AppletContext   getAppletContext() {
181     return stub.getAppletContext();
182     }
183 
184     /**
185      * Requests that this applet be resized.
186      *
187      * @param   width    the new requested width for the applet.
188      * @param   height   the new requested height for the applet.
189      */
190     public void resize(int width, int height) {
191     Dimension d = size();
192     if ((d.width != width) || (d.height != height)) {
193         super.resize(width, height);
194         if (stub != null) {
195         stub.appletResize(width, height);
196         }
197     }
198     }
199 
200     /**
201      * Requests that this applet be resized.
202      *
203      * @param   d   an object giving the new width and height.
204      */
205     public void resize(Dimension d) {
206     resize(d.width, d.height);
207     }
208 
209     /**
210      * Requests that the argument string be displayed in the
211      * "status window". Many browsers and applet viewers
212      * provide such a window, where the application can inform users of
213      * its current state.
214      *
215      * @param   msg   a string to display in the status window.
216      */
217     public void showStatus(String   msg) {
218     getAppletContext().showStatus(msg);
219     }
220 
221     /**
222      * Returns an <code>Image</code> object that can then be painted on
223      * the screen. The <code>url</code> that is passed as an argument
224      * must specify an absolute URL.
225      * <p>
226      * This method always returns immediately, whether or not the image
227      * exists. When this applet attempts to draw the image on the screen,
228      * the data will be loaded. The graphics primitives that draw the
229      * image will incrementally paint on the screen.
230      *
231      * @param   url   an absolute URL giving the location of the image.
232      * @return  the image at the specified URL.
233      * @see     java.awt.Image
234      */
235     public Image getImage(URL   url) {
236     return getAppletContext().getImage(url);
237     }
238 
239     /**
240      * Returns an <code>Image</code> object that can then be painted on
241      * the screen. The <code>url</code> argument must specify an absolute
242      * URL. The <code>name</code> argument is a specifier that is
243      * relative to the <code>url</code> argument.
244      * <p>
245      * This method always returns immediately, whether or not the image
246      * exists. When this applet attempts to draw the image on the screen,
247      * the data will be loaded. The graphics primitives that draw the
248      * image will incrementally paint on the screen.
249      *
250      * @param   url    an absolute URL giving the base location of the image.
251      * @param   name   the location of the image, relative to the
252      *                 <code>url</code> argument.
253      * @return  the image at the specified URL.
254      * @see     java.awt.Image
255      */
256     public Image getImage(URL   url, String   name) {
257     try {
258         return getImage(new URL  (url, name));
259     } catch (MalformedURLException   e) {
260         return null;
261     }
262     }
263 
264     /**
265      * Get an audio clip from the given URL.
266      *
267      * @param url points to the audio clip
268      * @return the audio clip at the specified URL.
269      *
270      * @since       1.2
271      */
272     public final static AudioClip   newAudioClip(URL   url) {
273         return new sun.applet.AppletAudioClip(url);
274     }
275 
276     /**
277      * Returns the <code>AudioClip</code> object specified by the
278      * <code>URL</code> argument.
279      * <p>
280      * This method always returns immediately, whether or not the audio
281      * clip exists. When this applet attempts to play the audio clip, the
282      * data will be loaded.
283      *
284      * @param   url  an absolute URL giving the location of the audio clip.
285      * @return  the audio clip at the specified URL.
286      * @see     java.applet.AudioClip
287      */
288     public AudioClip   getAudioClip(URL   url) {
289     return getAppletContext().getAudioClip(url);
290     }
291 
292     /**
293      * Returns the <code>AudioClip</code> object specified by the
294      * <code>URL</code> and <code>name</code> arguments.
295      * <p>
296      * This method always returns immediately, whether or not the audio
297      * clip exists. When this applet attempts to play the audio clip, the
298      * data will be loaded.
299      *
300      * @param   url    an absolute URL giving the base location of the
301      *                 audio clip.
302      * @param   name   the location of the audio clip, relative to the
303      *                 <code>url</code> argument.
304      * @return  the audio clip at the specified URL.
305      * @see     java.applet.AudioClip
306      */
307     public AudioClip   getAudioClip(URL   url, String   name) {
308     try {
309         return getAudioClip(new URL  (url, name));
310     } catch (MalformedURLException   e) {
311         return null;
312     }
313     }
314 
315     /**
316      * Returns information about this applet. An applet should override
317      * this method to return a <code>String</code> containing information
318      * about the author, version, and copyright of the applet.
319      * <p>
320      * The implementation of this method provided by the
321      * <code>Applet</code> class returns <code>null</code>.
322      *
323      * @return  a string containing information about the author, version, and
324      *          copyright of the applet.
325      */
326     public String   getAppletInfo() {
327     return null;
328     }
329 
330     /**
331      * Gets the Locale for the applet, if it has been set.
332      * If no Locale has been set, then the default Locale
333      * is returned.
334      *
335      * @return  the Locale for the applet
336      * @since   JDK1.1
337      */
338 
339     public Locale   getLocale() {
340       Locale   locale = super.getLocale();
341       if (locale == null) {
342     return Locale.getDefault();
343       }
344       return locale;
345     }
346 
347     /**
348      * Returns information about the parameters that are understood by
349      * this applet. An applet should override this method to return an
350      * array of <code>Strings</code> describing these parameters.
351      * <p>
352      * Each element of the array should be a set of three
353      * <code>Strings</code> containing the name, the type, and a
354      * description. For example:
355      * <p><blockquote><pre>
356      * String pinfo[][] = {
357      *   {"fps",    "1-10",    "frames per second"},
358      *   {"repeat", "boolean", "repeat image loop"},
359      *   {"imgs",   "url",     "images directory"}
360      * };
361      * </pre></blockquote>
362      * <p>
363      * The implementation of this method provided by the
364      * <code>Applet</code> class returns <code>null</code>.
365      *
366      * @return  an array describing the parameters this applet looks for.
367      */
368     public String  [][] getParameterInfo() {
369     return null;
370     }
371 
372     /**
373      * Plays the audio clip at the specified absolute URL. Nothing
374      * happens if the audio clip cannot be found.
375      *
376      * @param   url   an absolute URL giving the location of the audio clip.
377      */
378     public void play(URL   url) {
379     AudioClip   clip = getAudioClip(url);
380     if (clip != null) {
381         clip.play();
382     }
383     }
384 
385     /**
386      * Plays the audio clip given the URL and a specifier that is
387      * relative to it. Nothing happens if the audio clip cannot be found.
388      *
389      * @param   url    an absolute URL giving the base location of the
390      *                 audio clip.
391      * @param   name   the location of the audio clip, relative to the
392      *                 <code>url</code> argument.
393      */
394     public void play(URL   url, String   name) {
395     AudioClip   clip = getAudioClip(url, name);
396     if (clip != null) {
397         clip.play();
398     }
399     }
400 
401     /**
402      * Called by the browser or applet viewer to inform
403      * this applet that it has been loaded into the system. It is always
404      * called before the first time that the <code>start</code> method is
405      * called.
406      * <p>
407      * A subclass of <code>Applet</code> should override this method if
408      * it has initialization to perform. For example, an applet with
409      * threads would use the <code>init</code> method to create the
410      * threads and the <code>destroy</code> method to kill them.
411      * <p>
412      * The implementation of this method provided by the
413      * <code>Applet</code> class does nothing.
414      *
415      * @see     java.applet.Applet#destroy()
416      * @see     java.applet.Applet#start()
417      * @see     java.applet.Applet#stop()
418      */
419     public void init() {
420     }
421 
422     /**
423      * Called by the browser or applet viewer to inform
424      * this applet that it should start its execution. It is called after
425      * the <code>init</code> method and each time the applet is revisited
426      * in a Web page.
427      * <p>
428      * A subclass of <code>Applet</code> should override this method if
429      * it has any operation that it wants to perform each time the Web
430      * page containing it is visited. For example, an applet with
431      * animation might want to use the <code>start</code> method to
432      * resume animation, and the <code>stop</code> method to suspend the
433      * animation.
434      * <p>
435      * Note: some methods, such as <code>getLocationOnScreen</code>, can only
436      * provide meaningful results if the applet is showing.  Because
437      * <code>isShowing</code> returns <code>false</code> when the applet's
438      * <code>start</code> is first called, methods requiring
439      * <code>isShowing</code> to return <code>true</code> should be called from
440      * a <code>ComponentListener</code>.
441      * <p>
442      * The implementation of this method provided by the
443      * <code>Applet</code> class does nothing.
444      *
445      * @see     java.applet.Applet#destroy()
446      * @see     java.applet.Applet#init()
447      * @see     java.applet.Applet#stop()
448      * @see     java.awt.Component#isShowing()
449      * @see     java.awt.event.ComponentListener#componentShown(java.awt.event.ComponentEvent)
450      */
451     public void start() {
452     }
453 
454     /**
455      * Called by the browser or applet viewer to inform
456      * this applet that it should stop its execution. It is called when
457      * the Web page that contains this applet has been replaced by
458      * another page, and also just before the applet is to be destroyed.
459      * <p>
460      * A subclass of <code>Applet</code> should override this method if
461      * it has any operation that it wants to perform each time the Web
462      * page containing it is no longer visible. For example, an applet
463      * with animation might want to use the <code>start</code> method to
464      * resume animation, and the <code>stop</code> method to suspend the
465      * animation.
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      */
473     public void stop() {
474     }
475 
476     /**
477      * Called by the browser or applet viewer to inform
478      * this applet that it is being reclaimed and that it should destroy
479      * any resources that it has allocated. The <code>stop</code> method
480      * will always be called before <code>destroy</code>.
481      * <p>
482      * A subclass of <code>Applet</code> should override this method if
483      * it has any operation that it wants to perform before it is
484      * destroyed. For example, an applet with threads would use the
485      * <code>init</code> method to create the threads and the
486      * <code>destroy</code> method to kill them.
487      * <p>
488      * The implementation of this method provided by the
489      * <code>Applet</code> class does nothing.
490      *
491      * @see     java.applet.Applet#init()
492      * @see     java.applet.Applet#start()
493      * @see     java.applet.Applet#stop()
494      */
495     public void destroy() {
496     }
497 
498     //
499     // Accessibility support
500     //
501 
502     AccessibleContext accessibleContext = null;
503 
504     /**
505      * Gets the AccessibleContext associated with this Applet. 
506      * For applets, the AccessibleContext takes the form of an 
507      * AccessibleApplet. 
508      * A new AccessibleApplet instance is created if necessary.
509      *
510      * @return an AccessibleApplet that serves as the 
511      *         AccessibleContext of this Applet
512      */
513     public AccessibleContext getAccessibleContext() {
514         if (accessibleContext == null) {
515             accessibleContext = new AccessibleApplet();
516         }
517         return accessibleContext;
518     }
519 
520     /**
521      * This class implements accessibility support for the 
522      * <code>Applet</code> class.  It provides an implementation of the 
523      * Java Accessibility API appropriate to applet user-interface elements.
524      */
525     protected class AccessibleApplet extends AccessibleAWTPanel {
526 
527         private static final long serialVersionUID = 8127374778187708896L;
528 
529         /**
530          * Get the role of this object.
531          *
532          * @return an instance of AccessibleRole describing the role of the
533          * object
534          */
535         public AccessibleRole getAccessibleRole() {
536             return AccessibleRole.FRAME;
537         }
538 
539         /**
540          * Get the state of this object.
541          *
542          * @return an instance of AccessibleStateSet containing the current
543          * state set of the object
544          * @see AccessibleState
545          */
546         public AccessibleStateSet getAccessibleStateSet() {
547             AccessibleStateSet states = super.getAccessibleStateSet();
548             states.add(AccessibleState.ACTIVE);
549             return states;
550         }
551 
552     }
553 }
554
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags