JWindow


1   /*
2    * @(#)JWindow.java 1.60 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.beans.PropertyChangeListener  ;
12  import java.util.Locale  ;
13  import java.util.Vector  ;
14  import java.io.Serializable  ;
15  
16  import javax.accessibility.*;
17  
18  /** 
19   * A <code>JWindow</code> is a container that can be displayed anywhere on the
20   * user's desktop. It does not have the title bar, window-management buttons,
21   * or other trimmings associated with a <code>JFrame</code>, but it is still a 
22   * "first-class citizen" of the user's desktop, and can exist anywhere
23   * on it.
24   * <p>
25   * The <code>JWindow</code> component contains a <code>JRootPane</code>
26   * as its only child.  The <code>contentPane</code> should be the parent
27   * of any children of the <code>JWindow</code>.
28   * As a conveniance <code>add</code> and its variants, <code>remove</code> and
29   * <code>setLayout</code> have been overridden to forward to the
30   * <code>contentPane</code> as necessary. This means you can write:
31   * <pre>
32   *       window.add(child);
33   * </pre>
34   * And the child will be added to the contentPane.
35   * The <code>contentPane</code> will always be non-<code>null</code>.
36   * Attempting to set it to <code>null</code> will cause the <code>JWindow</code>
37   * to throw an exception. The default <code>contentPane</code> will have a
38   * <code>BorderLayout</code> manager set on it. 
39   * Refer to {@link javax.swing.RootPaneContainer}
40   * for details on adding, removing and setting the <code>LayoutManager</code>
41   * of a <code>JWindow</code>.
42   * <p>
43   * Please see the {@link JRootPane} documentation for a complete description of
44   * the <code>contentPane</code>, <code>glassPane</code>, and
45   * <code>layeredPane</code> components.
46   * <p>
47   * In a multi-screen environment, you can create a <code>JWindow</code>
48   * on a different screen device.  See {@link java.awt.Window} for more
49   * information.
50   * <p>
51   * <strong>Warning:</strong>
52   * Serialized objects of this class will not be compatible with
53   * future Swing releases. The current serialization support is
54   * appropriate for short term storage or RMI between applications running
55   * the same version of Swing.  As of 1.4, support for long term storage
56   * of all JavaBeans<sup><font size="-2">TM</font></sup>
57   * has been added to the <code>java.beans</code> package.
58   * Please see {@link java.beans.XMLEncoder}.
59   *
60   * @see JRootPane
61   *
62   * @beaninfo
63   *      attribute: isContainer true
64   *      attribute: containerDelegate getContentPane
65   *    description: A toplevel window which has no system border or controls.
66   *
67   * @version 1.60 12/19/03
68   * @author David Kloba
69   */
70  public class JWindow extends Window implements Accessible, RootPaneContainer   
71  {
72      /**
73       * The <code>JRootPane</code> instance that manages the
74       * <code>contentPane</code> 
75       * and optional <code>menuBar</code> for this frame, as well as the 
76       * <code>glassPane</code>.
77       *
78       * @see #getRootPane
79       * @see #setRootPane
80       */
81      protected JRootPane   rootPane;
82  
83      /**
84       * If true then calls to <code>add</code> and <code>setLayout</code>
85       * will be forwarded to the <code>contentPane</code>. This is initially
86       * false, but is set to true when the <code>JWindow</code> is constructed.
87       *
88       * @see #isRootPaneCheckingEnabled
89       * @see #setRootPaneCheckingEnabled
90       * @see javax.swing.RootPaneContainer
91       */
92      protected boolean rootPaneCheckingEnabled = false;
93  
94      /**
95       * Creates a window with no specified owner. This window will not be
96       * focusable.
97       * <p>
98       * This constructor sets the component's locale property to the value
99       * returned by <code>JComponent.getDefaultLocale</code>.     
100      *
101      * @throws HeadlessException if
102      *         <code>GraphicsEnvironment.isHeadless()</code> returns true.
103      * @see java.awt.GraphicsEnvironment#isHeadless
104      * @see #isFocusableWindow
105      * @see JComponent#getDefaultLocale
106      */
107     public JWindow() {
108         this((Frame)null);
109     }
110 
111     /**
112      * Creates a window with the specified <code>GraphicsConfiguration</code>
113      * of a screen device. This window will not be focusable.
114      * <p>
115      * This constructor sets the component's locale property to the value
116      * returned by <code>JComponent.getDefaultLocale</code>.     
117      * 
118      * @param gc the <code>GraphicsConfiguration</code> that is used
119      *      to construct the new window with; if gc is <code>null</code>,
120      *      the system default <code>GraphicsConfiguration</code>
121      *      is assumed
122      * @throws HeadlessException If
123      *         <code>GraphicsEnvironment.isHeadless()</code> returns true.
124      * @throws IllegalArgumentException if <code>gc</code> is not from
125      *         a screen device.
126      *
127      * @see java.awt.GraphicsEnvironment#isHeadless
128      * @see #isFocusableWindow
129      * @see JComponent#getDefaultLocale
130      *
131      * @since  1.3
132      */
133     public JWindow(GraphicsConfiguration gc) {
134         this(null, gc);
135         super.setFocusableWindowState(false);
136     }
137     
138     /**
139      * Creates a window with the specified owner frame.
140      * If <code>owner</code> is <code>null</code>, the shared owner
141      * will be used and this window will not be focusable. Also, 
142      * this window will not be focusable unless its owner is showing
143      * on the screen.
144      * <p>
145      * This constructor sets the component's locale property to the value
146      * returned by <code>JComponent.getDefaultLocale</code>.     
147      *
148      * @param owner the frame from which the window is displayed
149      * @throws HeadlessException if GraphicsEnvironment.isHeadless()
150      *            returns true.
151      * @see java.awt.GraphicsEnvironment#isHeadless
152      * @see #isFocusableWindow
153      * @see JComponent#getDefaultLocale
154      */
155     public JWindow(Frame owner) {
156         super(owner == null? SwingUtilities.getSharedOwnerFrame() : owner);
157     if (owner == null) {
158         WindowListener ownerShutdownListener =
159         (WindowListener)SwingUtilities.getSharedOwnerFrameShutdownListener();
160         addWindowListener(ownerShutdownListener);
161     }
162         windowInit();
163     }
164 
165     /**
166      * Creates a window with the specified owner window. This window
167      * will not be focusable unless its owner is showing on the screen.
168      * If <code>owner</code> is <code>null</code>, the shared owner
169      * will be used and this window will not be focusable.
170      * <p>
171      * This constructor sets the component's locale property to the value
172      * returned by <code>JComponent.getDefaultLocale</code>.     
173      *
174      * @param owner the window from which the window is displayed
175      * @throws HeadlessException if
176      *         <code>GraphicsEnvironment.isHeadless()</code> returns true.
177      * @see java.awt.GraphicsEnvironment#isHeadless
178      * @see #isFocusableWindow
179      * @see JComponent#getDefaultLocale
180      */
181     public JWindow(Window owner) {
182         super(owner == null ? (Window)SwingUtilities.getSharedOwnerFrame() :
183               owner);
184     if (owner == null) {
185         WindowListener ownerShutdownListener =
186         (WindowListener)SwingUtilities.getSharedOwnerFrameShutdownListener();
187         addWindowListener(ownerShutdownListener);
188     }
189         windowInit();
190     }
191 
192     /**
193      * Creates a window with the specified owner window and
194      * <code>GraphicsConfiguration</code> of a screen device. If
195      * <code>owner</code> is <code>null</code>, the shared owner will be used
196      * and this window will not be focusable.
197      * <p>
198      * This constructor sets the component's locale property to the value
199      * returned by <code>JComponent.getDefaultLocale</code>.     
200      * 
201      * @param owner the window from which the window is displayed
202      * @param gc the <code>GraphicsConfiguration</code> that is used
203      *      to construct the new window with; if gc is <code>null</code>,
204      *      the system default <code>GraphicsConfiguration</code>
205      *      is assumed, unless <code>owner</code> is also null, in which
206      *          case the <code>GraphicsConfiguration</code> from the
207      *          shared owner frame will be used.
208      * @throws HeadlessException if
209      *         <code>GraphicsEnvironment.isHeadless()</code> returns true.
210      * @throws IllegalArgumentException if <code>gc</code> is not from
211      *         a screen device.
212      *
213      * @see java.awt.GraphicsEnvironment#isHeadless
214      * @see #isFocusableWindow
215      * @see JComponent#getDefaultLocale
216      *
217      * @since  1.3
218      */
219     public JWindow(Window owner, GraphicsConfiguration gc) {
220         super(owner == null ? (Window)SwingUtilities.getSharedOwnerFrame() :
221               owner, gc);
222     if (owner == null) {
223         WindowListener ownerShutdownListener =
224         (WindowListener)SwingUtilities.getSharedOwnerFrameShutdownListener();
225         addWindowListener(ownerShutdownListener);
226     }
227         windowInit();
228     }
229 
230     /**
231      * Called by the constructors to init the <code>JWindow</code> properly.
232      */
233     protected void windowInit() {
234         setLocale( JComponent.getDefaultLocale() );
235         setRootPane(createRootPane());
236         setRootPaneCheckingEnabled(true);
237         sun.awt.SunToolkit.checkAndSetPolicy(this, true);
238     }
239 
240     /**
241      * Called by the constructor methods to create the default
242      * <code>rootPane</code>.
243      */
244     protected JRootPane   createRootPane() {
245         JRootPane   rp = new JRootPane  ();
246         // NOTE: this uses setOpaque vs LookAndFeel.installProperty as there
247         // is NO reason for the RootPane not to be opaque. For painting to
248         // work the contentPane must be opaque, therefor the RootPane can
249         // also be opaque.
250         rp.setOpaque(true);
251         return rp;
252     }
253  
254     /**
255      * Returns whether calls to <code>add</code> and 
256      * <code>setLayout</code> are forwarded to the <code>contentPane</code>.
257      *
258      * @return true if <code>add</code> and <code>setLayout</code> 
259      *         are fowarded; false otherwise
260      *
261      * @see #addImpl
262      * @see #setLayout
263      * @see #setRootPaneCheckingEnabled
264      * @see javax.swing.RootPaneContainer
265      */
266     protected boolean isRootPaneCheckingEnabled() {
267         return rootPaneCheckingEnabled;
268     }
269 
270 
271     /** 
272      * Calls <code>paint(g)</code>.  This method was overridden to 
273      * prevent an unnecessary call to clear the background.
274      *
275      * @param g  the <code>Graphics</code> context in which to paint
276      */
277     public void update(Graphics g) {
278         paint(g);
279     }
280 
281     /**
282      * Sets whether calls to <code>add</code> and 
283      * <code>setLayout</code> are forwarded to the <code>contentPane</code>.
284      * 
285      * @param enabled  true if <code>add</code> and <code>setLayout</code>
286      *        are forwarded, false if they should operate directly on the
287      *        <code>JWindow</code>.
288      *
289      * @see #addImpl
290      * @see #setLayout
291      * @see #isRootPaneCheckingEnabled
292      * @see javax.swing.RootPaneContainer
293      * @beaninfo
294      *      hidden: true
295      * description: Whether the add and setLayout methods are forwarded
296      */
297     protected void setRootPaneCheckingEnabled(boolean enabled) {
298         rootPaneCheckingEnabled = enabled;
299     }
300 
301 
302     /**
303      * Adds the specified child <code>Component</code>.
304      * This method is overridden to conditionally forwad calls to the
305      * <code>contentPane</code>.
306      * By default, children are added to the <code>contentPane</code> instead
307      * of the frame, refer to {@link javax.swing.RootPaneContainer} for
308      * details.
309      * 
310      * @param comp the component to be enhanced
311      * @param constraints the constraints to be respected
312      * @param index the index
313      * @exception IllegalArgumentException if <code>index</code> is invalid
314      * @exception IllegalArgumentException if adding the container's parent
315      *          to itself
316      * @exception IllegalArgumentException if adding a window to a container
317      * 
318      * @see #setRootPaneCheckingEnabled
319      * @see javax.swing.RootPaneContainer
320      */
321     protected void addImpl(Component comp, Object   constraints, int index) 
322     {
323         if(isRootPaneCheckingEnabled()) {
324             getContentPane().add(comp, constraints, index);
325         }
326         else {
327             super.addImpl(comp, constraints, index);
328         }
329     }
330 
331     /** 
332      * Removes the specified component from the container. If
333      * <code>comp</code> is not the <code>rootPane</code>, this will forward
334      * the call to the <code>contentPane</code>. This will do nothing if
335      * <code>comp</code> is not a child of the <code>JWindow</code> or
336      * <code>contentPane</code>.
337      *
338      * @param comp the component to be removed
339      * @throws NullPointerException if <code>comp</code> is null
340      * @see #add
341      * @see javax.swing.RootPaneContainer
342      */
343     public void remove(Component comp) {
344     if (comp == rootPane) {
345         super.remove(comp);
346     } else {
347         getContentPane().remove(comp);
348     }
349     }
350 
351 
352     /**
353      * Sets the <code>LayoutManager</code>.
354      * Overridden to conditionally forward the call to the
355      * <code>contentPane</code>.
356      * Refer to {@link javax.swing.RootPaneContainer} for
357      * more information.
358      *
359      * @param manager the <code>LayoutManager</code>
360      * @see #setRootPaneCheckingEnabled
361      * @see javax.swing.RootPaneContainer
362      */
363     public void setLayout(LayoutManager manager) {
364         if(isRootPaneCheckingEnabled()) {
365             getContentPane().setLayout(manager);
366         }
367         else {
368             super.setLayout(manager);
369         }
370     }
371 
372 
373     /**
374      * Returns the <code>rootPane</code> object for this window.
375      * @return the <code>rootPane</code> property for this window
376      *
377      * @see #setRootPane
378      * @see RootPaneContainer#getRootPane
379      */
380     public JRootPane   getRootPane() { 
381         return rootPane; 
382     }
383 
384 
385     /**
386      * Sets the new <code>rootPane</code> object for this window.
387      * This method is called by the constructor.
388      *
389      * @param root the new <code>rootPane</code> property
390      * @see #getRootPane
391      *
392      * @beaninfo
393      *        hidden: true
394      *   description: the RootPane object for this window.
395      */
396     protected void setRootPane(JRootPane   root) {
397         if(rootPane != null) {
398             remove(rootPane);
399         }
400         rootPane = root;
401         if(rootPane != null) {
402             boolean checkingEnabled = isRootPaneCheckingEnabled();
403             try {
404                 setRootPaneCheckingEnabled(false);
405                 add(rootPane, BorderLayout.CENTER);
406             }
407             finally {
408                 setRootPaneCheckingEnabled(checkingEnabled);
409             }
410         }
411     }
412 
413 
414     /**
415      * Returns the <code>Container</code> which is the <code>contentPane</code>
416      * for this window.
417      *
418      * @return the <code>contentPane</code> property
419      * @see #setContentPane
420      * @see RootPaneContainer#getContentPane
421      */
422     public Container getContentPane() { 
423         return getRootPane().getContentPane(); 
424     }
425 
426     /**
427      * Sets the <code>contentPane</code> property for this window.
428      * This method is called by the constructor.
429      *
430      * @param contentPane the new <code>contentPane</code>
431      *
432      * @exception IllegalComponentStateException (a runtime
433      *            exception) if the content pane parameter is <code>null</code>
434      * @see #getContentPane
435      * @see RootPaneContainer#setContentPane
436      *
437      * @beaninfo
438      *     hidden: true
439      *     description: The client area of the window where child 
440      *                  components are normally inserted.
441      */
442     public void setContentPane(Container contentPane) {
443         getRootPane().setContentPane(contentPane);
444     }
445 
446     /**
447      * Returns the <code>layeredPane</code> object for this window.
448      *
449      * @return the <code>layeredPane</code> property
450      * @see #setLayeredPane
451      * @see RootPaneContainer#getLayeredPane
452      */
453     public JLayeredPane   getLayeredPane() { 
454         return getRootPane().getLayeredPane(); 
455     }
456 
457     /**
458      * Sets the <code>layeredPane</code> property. 
459      * This method is called by the constructor.
460      *
461      * @param layeredPane the new <code>layeredPane</code> object
462      *
463      * @exception IllegalComponentStateException (a runtime
464      *            exception) if the content pane parameter is <code>null</code>
465      * @see #getLayeredPane
466      * @see RootPaneContainer#setLayeredPane
467      *
468      * @beaninfo
469      *     hidden: true
470      *     description: The pane which holds the various window layers.
471      */
472     public void setLayeredPane(JLayeredPane   layeredPane) {
473         getRootPane().setLayeredPane(layeredPane);
474     }
475 
476     /**
477      * Returns the <code>glassPane Component</code> for this window.
478      *
479      * @return the <code>glassPane</code> property
480      * @see #setGlassPane
481      * @see RootPaneContainer#getGlassPane
482      */
483     public Component getGlassPane() { 
484         return getRootPane().getGlassPane(); 
485     }
486 
487     /**
488      * Sets the <code>glassPane</code> property. 
489      * This method is called by the constructor.
490      * @param glassPane the <code>glassPane</code> object for this window
491      *
492      * @see #getGlassPane
493      * @see RootPaneContainer#setGlassPane
494      *
495      * @beaninfo
496      *     hidden: true
497      *     description: A transparent pane used for menu rendering.
498      */
499     public void setGlassPane(Component glassPane) {
500         getRootPane().setGlassPane(glassPane);
501     }
502 
503     /**
504      * Returns a string representation of this <code>JWindow</code>.
505      * This method 
506      * is intended to be used only for debugging purposes, and the 
507      * content and format of the returned string may vary between      
508      * implementations. The returned string may be empty but may not 
509      * be <code>null</code>.
510      * 
511      * @return  a string representation of this <code>JWindow</code>
512      */
513     protected String   paramString() {
514         String   rootPaneCheckingEnabledString = (rootPaneCheckingEnabled ?
515                         "true" : "false");
516 
517         return super.paramString() +
518     ",rootPaneCheckingEnabled=" + rootPaneCheckingEnabledString;
519     }
520 
521 
522 /////////////////
523 // Accessibility support
524 ////////////////
525 
526     /** The accessible context property. */
527     protected AccessibleContext accessibleContext = null;
528 
529     /**
530      * Gets the AccessibleContext associated with this JWindow. 
531      * For JWindows, the AccessibleContext takes the form of an 
532      * AccessibleJWindow. 
533      * A new AccessibleJWindow instance is created if necessary.
534      *
535      * @return an AccessibleJWindow that serves as the 
536      *         AccessibleContext of this JWindow
537      */
538     public AccessibleContext getAccessibleContext() {
539         if (accessibleContext == null) {
540             accessibleContext = new AccessibleJWindow();
541         }
542         return accessibleContext;
543     }
544 
545 
546     /**
547      * This class implements accessibility support for the 
548      * <code>JWindow</code> class.  It provides an implementation of the 
549      * Java Accessibility API appropriate to window user-interface 
550      * elements.
551      */
552     protected class AccessibleJWindow extends AccessibleAWTWindow {
553         // everything is in the new parent, AccessibleAWTWindow
554     }
555 
556 }
557
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags