JApplet


1   /*
2    * @(#)JApplet.java 1.65 03/12/19
3    *
4    * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5    * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6    */
7   package javax.swing;
8   
9   import java.awt.*;
10  import java.awt.event.*;
11  import java.applet.Applet  ;
12  import java.beans.PropertyChangeListener  ;
13  import java.util.Locale  ;
14  import java.util.Vector  ;
15  import java.io.Serializable  ;
16  import javax.accessibility.*;
17  
18  /**
19   * An extended version of <code>java.applet.Applet</code> that adds support for 
20   * the JFC/Swing component architecture.
21   * You can find task-oriented documentation about using <code>JApplet</code>
22   * in <em>The Java Tutorial</em>,
23   * in the section 
24   * <a
25   href="http://java.sun.com/docs/books/tutorial/uiswing/components/applet.html">How to Make Applets</a>.
26   * <p>
27   * The <code>JApplet</code> class is slightly incompatible with
28   * <code>java.applet.Applet</code>.  <code>JApplet</code> contains a
29   * <code>JRootPane</code> as its only child.  The <code>contentPane</code>
30   * should be the parent of any children of the <code>JApplet</code>.
31   * As a convenience <code>add</code> and its variants, <code>remove</code> and
32   * <code>setLayout</code> have been overridden to forward to the
33   * <code>contentPane</code> as necessary. This means you can write:
34   * <pre>
35   *       applet.add(child);
36   * </pre>
37   *
38   * And the child will be added to the <code>contentPane</code>.
39   * The <code>contentPane</code> will always be non-<code>null</code>.
40   * Attempting to set it to <code>null</code> will cause the
41   * <code>JApplet</code> to throw an exception. The default
42   * <code>contentPane</code> will have a <code>BorderLayout</code>
43   * manager set on it. 
44   * Refer to {@link javax.swing.RootPaneContainer}
45   * for details on adding, removing and setting the <code>LayoutManager</code>
46   * of a <code>JApplet</code>.
47   * <p>
48   * Please see the <code>JRootPane</code> documentation for a
49   * complete description of the <code>contentPane</code>, <code>glassPane</code>,
50   * and <code>layeredPane</code> properties.
51   * <p>
52   * <strong>Warning:</strong>
53   * Serialized objects of this class will not be compatible with
54   * future Swing releases. The current serialization support is
55   * appropriate for short term storage or RMI between applications running
56   * the same version of Swing.  As of 1.4, support for long term storage
57   * of all JavaBeans<sup><font size="-2">TM</font></sup>
58   * has been added to the <code>java.beans</code> package.
59   * Please see {@link java.beans.XMLEncoder}.
60   *
61   * @see javax.swing.RootPaneContainer
62   * @beaninfo
63   *      attribute: isContainer true
64   *      attribute: containerDelegate getContentPane
65   *    description: Swing's Applet subclass.
66   *
67   * @version 1.65 12/19/03
68   * @author Arnaud Weber
69   */
70  public class JApplet extends Applet   implements Accessible, RootPaneContainer   
71  {
72      /**
73       * @see #getRootPane
74       * @see #setRootPane
75       */
76      protected JRootPane   rootPane;
77  
78      /**
79       * If true then calls to <code>add</code> and <code>setLayout</code>
80       * will be forwarded to the <code>contentPane</code>. This is initially
81       * false, but is set to true when the <code>JApplet</code> is constructed.
82       *
83       * @see #isRootPaneCheckingEnabled
84       * @see #setRootPaneCheckingEnabled
85       * @see javax.swing.RootPaneContainer
86       */
87      protected boolean rootPaneCheckingEnabled = false;
88  
89      /**
90       * Creates a swing applet instance.
91       * <p>
92       * This constructor sets the component's locale property to the value
93       * returned by <code>JComponent.getDefaultLocale</code>. 
94       *
95       * @exception HeadlessException if GraphicsEnvironment.isHeadless()
96       * returns true.
97       * @see java.awt.GraphicsEnvironment#isHeadless
98       * @see JComponent#getDefaultLocale
99       */
100     public JApplet() throws HeadlessException {
101         super();
102     // Check the timerQ and restart if necessary.
103     TimerQueue   q = TimerQueue.sharedInstance();
104     if(q != null) {
105         synchronized(q) {
106         if(!q.running)
107             q.start();
108         }
109     }
110 
111     /* Workaround for bug 4155072.  The shared double buffer image
112      * may hang on to a reference to this applet; unfortunately 
113      * Image.getGraphics() will continue to call JApplet.getForeground()
114      * and getBackground() even after this applet has been destroyed.
115      * So we ensure that these properties are non-null here.
116      */
117     setForeground(Color.black);
118     setBackground(Color.white);
119 
120         setLocale( JComponent.getDefaultLocale() );
121         setLayout(new BorderLayout());
122         setRootPane(createRootPane());
123         setRootPaneCheckingEnabled(true);
124     
125     setFocusTraversalPolicyProvider(true);
126         sun.awt.SunToolkit.checkAndSetPolicy(this, true);
127     
128         enableEvents(AWTEvent.KEY_EVENT_MASK);
129     }
130 
131 
132     /** Called by the constructor methods to create the default rootPane. */
133     protected JRootPane   createRootPane() {
134         JRootPane   rp = new JRootPane  ();
135         // NOTE: this uses setOpaque vs LookAndFeel.installProperty as there
136         // is NO reason for the RootPane not to be opaque. For painting to
137         // work the contentPane must be opaque, therefor the RootPane can
138         // also be opaque.
139         rp.setOpaque(true);
140         return rp;
141     }
142     
143     /** 
144      * Just calls <code>paint(g)</code>.  This method was overridden to 
145      * prevent an unnecessary call to clear the background.
146      */
147     public void update(Graphics g) {
148         paint(g);
149     }
150 
151 
152    /**
153     * Sets the menubar for this applet.
154     * @param menuBar the menubar being placed in the applet
155     *
156     * @see #getJMenuBar
157     *
158     * @beaninfo
159     *      hidden: true
160     * description: The menubar for accessing pulldown menus from this applet.
161     */
162     public void setJMenuBar(JMenuBar   menuBar) {
163         getRootPane().setMenuBar(menuBar);
164     }
165 
166    /**
167     * Returns the menubar set on this applet.
168     *
169     * @see #setJMenuBar
170     */
171     public JMenuBar   getJMenuBar() {
172         return getRootPane().getMenuBar();
173     }
174 
175 
176     /**
177      * Returns whether calls to <code>add</code> and 
178      * <code>setLayout</code> are forwarded to the <code>contentPane</code>.
179      *
180      * @return true if <code>add</code> and <code>setLayout</code> 
181      *         are fowarded; false otherwise
182      *
183      * @see #addImpl
184      * @see #setLayout
185      * @see #setRootPaneCheckingEnabled
186      * @see javax.swing.RootPaneContainer
187      */
188     protected boolean isRootPaneCheckingEnabled() {
189         return rootPaneCheckingEnabled;
190     }
191 
192 
193     /**
194      * Sets whether calls to <code>add</code> and 
195      * <code>setLayout</code> are forwarded to the <code>contentPane</code>.
196      * 
197      * @param enabled  true if <code>add</code> and <code>setLayout</code>
198      *        are forwarded, false if they should operate directly on the
199      *        <code>JApplet</code>.
200      *
201      * @see #addImpl
202      * @see #setLayout
203      * @see #isRootPaneCheckingEnabled
204      * @see javax.swing.RootPaneContainer
205      * @beaninfo
206      *      hidden: true
207      * description: Whether the add and setLayout methods are forwarded
208      */
209     protected void setRootPaneCheckingEnabled(boolean enabled) {
210         rootPaneCheckingEnabled = enabled;
211     }
212 
213 
214     /**
215      * Adds the specified child <code>Component</code>.
216      * This method is overridden to conditionally forwad calls to the
217      * <code>contentPane</code>.
218      * By default, children are added to the <code>contentPane</code> instead
219      * of the frame, refer to {@link javax.swing.RootPaneContainer} for
220      * details.
221      * 
222      * @param comp the component to be enhanced
223      * @param constraints the constraints to be respected
224      * @param index the index
225      * @exception IllegalArgumentException if <code>index</code> is invalid
226      * @exception IllegalArgumentException if adding the container's parent
227      *          to itself
228      * @exception IllegalArgumentException if adding a window to a container
229      * 
230      * @see #setRootPaneCheckingEnabled
231      * @see javax.swing.RootPaneContainer
232      */
233     protected void addImpl(Component comp, Object   constraints, int index) 
234     {
235         if(isRootPaneCheckingEnabled()) {
236             getContentPane().add(comp, constraints, index);
237         }
238         else {
239             super.addImpl(comp, constraints, index);
240         }
241     }
242 
243     /** 
244      * Removes the specified component from the container. If
245      * <code>comp</code> is not the <code>rootPane</code>, this will forward
246      * the call to the <code>contentPane</code>. This will do nothing if
247      * <code>comp</code> is not a child of the <code>JFrame</code> or
248      * <code>contentPane</code>.
249      *
250      * @param comp the component to be removed
251      * @throws NullPointerException if <code>comp</code> is null
252      * @see #add
253      * @see javax.swing.RootPaneContainer
254      */
255     public void remove(Component comp) {
256     if (comp == rootPane) {
257         super.remove(comp);
258     } else {
259         getContentPane().remove(comp);
260     }
261     }
262 
263 
264     /**
265      * Sets the <code>LayoutManager</code>.
266      * Overridden to conditionally forward the call to the
267      * <code>contentPane</code>.
268      * Refer to {@link javax.swing.RootPaneContainer} for
269      * more information.
270      *
271      * @param manager the <code>LayoutManager</code>
272      * @see #setRootPaneCheckingEnabled
273      * @see javax.swing.RootPaneContainer
274      */
275     public void setLayout(LayoutManager manager) {
276         if(isRootPaneCheckingEnabled()) {
277             getContentPane().setLayout(manager);
278         }
279         else {
280             super.setLayout(manager);
281         }
282     }
283 
284 
285     /**
286      * Returns the rootPane object for this applet.
287      *
288      * @see #setRootPane
289      * @see RootPaneContainer#getRootPane
290      */
291     public JRootPane   getRootPane() { 
292         return rootPane; 
293     }
294 
295 
296     /**
297      * Sets the rootPane property.  This method is called by the constructor.
298      * @param root the rootPane object for this applet
299      *
300      * @see #getRootPane
301      *
302      * @beaninfo
303      *   hidden: true
304      * description: the RootPane object for this applet.
305      */
306     protected void setRootPane(JRootPane   root) {
307         if(rootPane != null) {
308             remove(rootPane);
309         }
310         rootPane = root;
311         if(rootPane != null) {
312             boolean checkingEnabled = isRootPaneCheckingEnabled();
313             try {
314                 setRootPaneCheckingEnabled(false);
315                 add(rootPane, BorderLayout.CENTER);
316             }
317             finally {
318                 setRootPaneCheckingEnabled(checkingEnabled);
319             }
320         }
321     }
322 
323 
324     /**
325      * Returns the contentPane object for this applet.
326      *
327      * @see #setContentPane
328      * @see RootPaneContainer#getContentPane
329      */
330     public Container getContentPane() { 
331         return getRootPane().getContentPane(); 
332     }
333 
334    /**
335      * Sets the contentPane property.  This method is called by the constructor.
336      * @param contentPane the contentPane object for this applet
337      *
338      * @exception java.awt.IllegalComponentStateException (a runtime
339      *            exception) if the content pane parameter is null
340      * @see #getContentPane
341      * @see RootPaneContainer#setContentPane
342      *
343      * @beaninfo
344      *     hidden: true
345      *     description: The client area of the applet where child 
346      *                  components are normally inserted.
347      */
348     public void setContentPane(Container contentPane) {
349         getRootPane().setContentPane(contentPane);
350     }
351 
352     /**
353      * Returns the layeredPane object for this applet.
354      *
355      * @exception java.awt.IllegalComponentStateException (a runtime
356      *            exception) if the layered pane parameter is null
357      * @see #setLayeredPane
358      * @see RootPaneContainer#getLayeredPane
359      */
360     public JLayeredPane   getLayeredPane() { 
361         return getRootPane().getLayeredPane(); 
362     }
363 
364     /**
365      * Sets the layeredPane property.  This method is called by the constructor.
366      * @param layeredPane the layeredPane object for this applet
367      *
368      * @see #getLayeredPane
369      * @see RootPaneContainer#setLayeredPane
370      *
371      * @beaninfo
372      *     hidden: true
373      *     description: The pane which holds the various applet layers.
374      */
375     public void setLayeredPane(JLayeredPane   layeredPane) {
376         getRootPane().setLayeredPane(layeredPane);
377     }
378 
379     /**
380      * Returns the glassPane object for this applet.
381      *
382      * @see #setGlassPane
383      * @see RootPaneContainer#getGlassPane
384      */
385     public Component getGlassPane() { 
386         return getRootPane().getGlassPane(); 
387     }
388 
389     /**
390      * Sets the glassPane property. 
391      * This method is called by the constructor.
392      * @param glassPane the glassPane object for this applet
393      *
394      * @see #getGlassPane
395      * @see RootPaneContainer#setGlassPane
396      *
397      * @beaninfo
398      *     hidden: true
399      *     description: A transparent pane used for menu rendering.
400      */
401     public void setGlassPane(Component glassPane) {
402         getRootPane().setGlassPane(glassPane);
403     }
404 
405     /**
406      * Returns a string representation of this JApplet. This method 
407      * is intended to be used only for debugging purposes, and the 
408      * content and format of the returned string may vary between      
409      * implementations. The returned string may be empty but may not 
410      * be <code>null</code>.
411      * 
412      * @return  a string representation of this JApplet.
413      */
414     protected String   paramString() {
415     String   rootPaneString = (rootPane != null ?
416                  rootPane.toString() : "");
417     String   rootPaneCheckingEnabledString = (rootPaneCheckingEnabled ?
418                         "true" : "false");
419 
420     return super.paramString() +
421     ",rootPane=" + rootPaneString +
422     ",rootPaneCheckingEnabled=" + rootPaneCheckingEnabledString;
423     }
424 
425 
426 
427 /////////////////
428 // Accessibility support
429 ////////////////
430 
431     protected AccessibleContext accessibleContext = null;
432 
433     /**
434      * Gets the AccessibleContext associated with this JApplet. 
435      * For JApplets, the AccessibleContext takes the form of an 
436      * AccessibleJApplet. 
437      * A new AccessibleJApplet instance is created if necessary.
438      *
439      * @return an AccessibleJApplet that serves as the 
440      *         AccessibleContext of this JApplet
441      */
442     public AccessibleContext getAccessibleContext() {
443         if (accessibleContext == null) {
444             accessibleContext = new AccessibleJApplet();
445         }
446         return accessibleContext;
447     }
448 
449     /**
450      * This class implements accessibility support for the 
451      * <code>JApplet</code> class.
452      */
453     protected class AccessibleJApplet extends AccessibleApplet {
454         // everything moved to new parent, AccessibleApplet
455     }
456 }
457 
458
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags