KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > javax > swing > 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 JavaDoc;
12 import java.util.Locale JavaDoc;
13 import java.util.Vector JavaDoc;
14 import java.io.Serializable JavaDoc;
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 JavaDoc
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 JavaDoc 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 JavaDoc createRootPane() {
245         JRootPane JavaDoc rp = new JRootPane JavaDoc();
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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc paramString() {
514         String JavaDoc 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
Popular Tags