View Javadoc
1   /*
2    * Copyright (c) 1997, 2013, Oracle and/or its affiliates. All rights reserved.
3    * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4    *
5    * This code is free software; you can redistribute it and/or modify it
6    * under the terms of the GNU General Public License version 2 only, as
7    * published by the Free Software Foundation.  Oracle designates this
8    * particular file as subject to the "Classpath" exception as provided
9    * by Oracle in the LICENSE file that accompanied this code.
10   *
11   * This code is distributed in the hope that it will be useful, but WITHOUT
12   * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13   * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
14   * version 2 for more details (a copy is included in the LICENSE file that
15   * accompanied this code).
16   *
17   * You should have received a copy of the GNU General Public License version
18   * 2 along with this work; if not, write to the Free Software Foundation,
19   * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20   *
21   * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22   * or visit www.oracle.com if you need additional information or have any
23   * questions.
24   */
25  package javax.swing;
26  
27  import java.awt.*;
28  import java.awt.event.*;
29  import javax.accessibility.*;
30  
31  /**
32   * The main class for creating a dialog window. You can use this class
33   * to create a custom dialog, or invoke the many class methods
34   * in {@link JOptionPane} to create a variety of standard dialogs.
35   * For information about creating dialogs, see
36   * <em>The Java Tutorial</em> section
37   * <a
38   href="http://docs.oracle.com/javase/tutorial/uiswing/components/dialog.html">How
39   * to Make Dialogs</a>.
40   *
41   * <p>
42   *
43   * The {@code JDialog} component contains a {@code JRootPane}
44   * as its only child.
45   * The {@code contentPane} should be the parent of any children of the
46   * {@code JDialog}.
47   * As a convenience, the {@code add}, {@code remove}, and {@code setLayout}
48   * methods of this class are overridden, so that they delegate calls
49   * to the corresponding methods of the {@code ContentPane}.
50   * For example, you can add a child component to a dialog as follows:
51   * <pre>
52   *       dialog.add(child);
53   * </pre>
54   * And the child will be added to the contentPane.
55   * The {@code contentPane} is always non-{@code null}.
56   * Attempting to set it to {@code null} generates an exception.
57   * The default {@code contentPane} has a {@code BorderLayout}
58   * manager set on it.
59   * Refer to {@link javax.swing.RootPaneContainer}
60   * for details on adding, removing and setting the {@code LayoutManager}
61   * of a {@code JDialog}.
62   * <p>
63   * Please see the {@code JRootPane} documentation for a complete
64   * description of the {@code contentPane}, {@code glassPane},
65   * and {@code layeredPane} components.
66   * <p>
67   * In a multi-screen environment, you can create a {@code JDialog}
68   * on a different screen device than its owner.  See {@link java.awt.Frame} for
69   * more information.
70   * <p>
71   * <strong>Warning:</strong> Swing is not thread safe. For more
72   * information see <a
73   * href="package-summary.html#threading">Swing's Threading
74   * Policy</a>.
75   * <p>
76   * <strong>Warning:</strong>
77   * Serialized objects of this class will not be compatible with
78   * future Swing releases. The current serialization support is
79   * appropriate for short term storage or RMI between applications running
80   * the same version of Swing.  As of 1.4, support for long term storage
81   * of all JavaBeans&trade;
82   * has been added to the {@code java.beans} package.
83   * Please see {@link java.beans.XMLEncoder}.
84   *
85   * @see JOptionPane
86   * @see JRootPane
87   * @see javax.swing.RootPaneContainer
88   *
89   * @beaninfo
90   *      attribute: isContainer true
91   *      attribute: containerDelegate getContentPane
92   *    description: A toplevel window for creating dialog boxes.
93   *
94   * @author David Kloba
95   * @author James Gosling
96   * @author Scott Violet
97   */
98  public class JDialog extends Dialog implements WindowConstants,
99                                                 Accessible,
100                                                RootPaneContainer,
101                                TransferHandler.HasGetTransferHandler
102 {
103     /**
104      * Key into the AppContext, used to check if should provide decorations
105      * by default.
106      */
107     private static final Object defaultLookAndFeelDecoratedKey =
108             new StringBuffer("JDialog.defaultLookAndFeelDecorated");
109 
110     private int defaultCloseOperation = HIDE_ON_CLOSE;
111 
112     /**
113      * @see #getRootPane
114      * @see #setRootPane
115      */
116     protected JRootPane rootPane;
117 
118     /**
119      * If true then calls to {@code add} and {@code setLayout}
120      * will be forwarded to the {@code contentPane}. This is initially
121      * false, but is set to true when the {@code JDialog} is constructed.
122      *
123      * @see #isRootPaneCheckingEnabled
124      * @see #setRootPaneCheckingEnabled
125      * @see javax.swing.RootPaneContainer
126      */
127     protected boolean rootPaneCheckingEnabled = false;
128 
129     /**
130      * The {@code TransferHandler} for this dialog.
131      */
132     private TransferHandler transferHandler;
133 
134     /**
135      * Creates a modeless dialog without a title and without a specified
136      * {@code Frame} owner.  A shared, hidden frame will be
137      * set as the owner of the dialog.
138      * <p>
139      * This constructor sets the component's locale property to the value
140      * returned by {@code JComponent.getDefaultLocale}.
141      * <p>
142      * NOTE: This constructor does not allow you to create an unowned
143      * {@code JDialog}. To create an unowned {@code JDialog}
144      * you must use either the {@code JDialog(Window)} or
145      * {@code JDialog(Dialog)} constructor with an argument of
146      * {@code null}.
147      *
148      * @throws HeadlessException if {@code GraphicsEnvironment.isHeadless()}
149      *     returns {@code true}.
150      * @see java.awt.GraphicsEnvironment#isHeadless
151      * @see JComponent#getDefaultLocale
152      */
153     public JDialog() {
154         this((Frame)null, false);
155     }
156 
157     /**
158      * Creates a modeless dialog with the specified {@code Frame}
159      * as its owner and an empty title. If {@code owner}
160      * is {@code null}, a shared, hidden frame will be set as the
161      * owner of the dialog.
162      * <p>
163      * This constructor sets the component's locale property to the value
164      * returned by {@code JComponent.getDefaultLocale}.
165      * <p>
166      * NOTE: This constructor does not allow you to create an unowned
167      * {@code JDialog}. To create an unowned {@code JDialog}
168      * you must use either the {@code JDialog(Window)} or
169      * {@code JDialog(Dialog)} constructor with an argument of
170      * {@code null}.
171      *
172      * @param owner the {@code Frame} from which the dialog is displayed
173      * @throws HeadlessException if {@code GraphicsEnvironment.isHeadless()}
174      *     returns {@code true}.
175      * @see java.awt.GraphicsEnvironment#isHeadless
176      * @see JComponent#getDefaultLocale
177      */
178     public JDialog(Frame owner) {
179         this(owner, false);
180     }
181 
182     /**
183      * Creates a dialog with an empty title and the specified modality and
184      * {@code Frame} as its owner. If {@code owner} is {@code null},
185      * a shared, hidden frame will be set as the owner of the dialog.
186      * <p>
187      * This constructor sets the component's locale property to the value
188      * returned by {@code JComponent.getDefaultLocale}.
189      * <p>
190      * NOTE: This constructor does not allow you to create an unowned
191      * {@code JDialog}. To create an unowned {@code JDialog}
192      * you must use either the {@code JDialog(Window)} or
193      * {@code JDialog(Dialog)} constructor with an argument of
194      * {@code null}.
195      *
196      * @param owner the {@code Frame} from which the dialog is displayed
197      * @param modal specifies whether dialog blocks user input to other top-level
198      *     windows when shown. If {@code true}, the modality type property is set to
199      *     {@code DEFAULT_MODALITY_TYPE}, otherwise the dialog is modeless.
200      * @throws HeadlessException if {@code GraphicsEnvironment.isHeadless()}
201      *     returns {@code true}.
202      * @see java.awt.GraphicsEnvironment#isHeadless
203      * @see JComponent#getDefaultLocale
204      */
205     public JDialog(Frame owner, boolean modal) {
206         this(owner, "", modal);
207     }
208 
209     /**
210      * Creates a modeless dialog with the specified title and
211      * with the specified owner frame.  If {@code owner}
212      * is {@code null}, a shared, hidden frame will be set as the
213      * owner of the dialog.
214      * <p>
215      * This constructor sets the component's locale property to the value
216      * returned by {@code JComponent.getDefaultLocale}.
217      * <p>
218      * NOTE: This constructor does not allow you to create an unowned
219      * {@code JDialog}. To create an unowned {@code JDialog}
220      * you must use either the {@code JDialog(Window)} or
221      * {@code JDialog(Dialog)} constructor with an argument of
222      * {@code null}.
223      *
224      * @param owner the {@code Frame} from which the dialog is displayed
225      * @param title  the {@code String} to display in the dialog's
226      *                  title bar
227      * @throws HeadlessException if {@code GraphicsEnvironment.isHeadless()}
228      *     returns {@code true}.
229      * @see java.awt.GraphicsEnvironment#isHeadless
230      * @see JComponent#getDefaultLocale
231      */
232     public JDialog(Frame owner, String title) {
233         this(owner, title, false);
234     }
235 
236     /**
237      * Creates a dialog with the specified title, owner {@code Frame}
238      * and modality. If {@code owner} is {@code null},
239      * a shared, hidden frame will be set as the owner of this dialog.
240      * <p>
241      * This constructor sets the component's locale property to the value
242      * returned by {@code JComponent.getDefaultLocale}.
243      * <p>
244      * NOTE: Any popup components ({@code JComboBox},
245      * {@code JPopupMenu}, {@code JMenuBar})
246      * created within a modal dialog will be forced to be lightweight.
247      * <p>
248      * NOTE: This constructor does not allow you to create an unowned
249      * {@code JDialog}. To create an unowned {@code JDialog}
250      * you must use either the {@code JDialog(Window)} or
251      * {@code JDialog(Dialog)} constructor with an argument of
252      * {@code null}.
253      *
254      * @param owner the {@code Frame} from which the dialog is displayed
255      * @param title  the {@code String} to display in the dialog's
256      *     title bar
257      * @param modal specifies whether dialog blocks user input to other top-level
258      *     windows when shown. If {@code true}, the modality type property is set to
259      *     {@code DEFAULT_MODALITY_TYPE} otherwise the dialog is modeless
260      * @throws HeadlessException if {@code GraphicsEnvironment.isHeadless()}
261      *     returns {@code true}.
262      *
263      * @see java.awt.Dialog.ModalityType
264      * @see java.awt.Dialog.ModalityType#MODELESS
265      * @see java.awt.Dialog#DEFAULT_MODALITY_TYPE
266      * @see java.awt.Dialog#setModal
267      * @see java.awt.Dialog#setModalityType
268      * @see java.awt.GraphicsEnvironment#isHeadless
269      * @see JComponent#getDefaultLocale
270      */
271     public JDialog(Frame owner, String title, boolean modal) {
272         super(owner == null? SwingUtilities.getSharedOwnerFrame() : owner,
273               title, modal);
274         if (owner == null) {
275             WindowListener ownerShutdownListener =
276                     SwingUtilities.getSharedOwnerFrameShutdownListener();
277             addWindowListener(ownerShutdownListener);
278         }
279         dialogInit();
280     }
281 
282     /**
283      * Creates a dialog with the specified title,
284      * owner {@code Frame}, modality and {@code GraphicsConfiguration}.
285      * If {@code owner} is {@code null},
286      * a shared, hidden frame will be set as the owner of this dialog.
287      * <p>
288      * This constructor sets the component's locale property to the value
289      * returned by {@code JComponent.getDefaultLocale}.
290      * <p>
291      * NOTE: Any popup components ({@code JComboBox},
292      * {@code JPopupMenu}, {@code JMenuBar})
293      * created within a modal dialog will be forced to be lightweight.
294      * <p>
295      * NOTE: This constructor does not allow you to create an unowned
296      * {@code JDialog}. To create an unowned {@code JDialog}
297      * you must use either the {@code JDialog(Window)} or
298      * {@code JDialog(Dialog)} constructor with an argument of
299      * {@code null}.
300      *
301      * @param owner the {@code Frame} from which the dialog is displayed
302      * @param title  the {@code String} to display in the dialog's
303      *     title bar
304      * @param modal specifies whether dialog blocks user input to other top-level
305      *     windows when shown. If {@code true}, the modality type property is set to
306      *     {@code DEFAULT_MODALITY_TYPE}, otherwise the dialog is modeless.
307      * @param gc the {@code GraphicsConfiguration} of the target screen device;
308      *     if {@code null}, the default system {@code GraphicsConfiguration}
309      *     is assumed
310      * @throws HeadlessException if {@code GraphicsEnvironment.isHeadless()}
311      *     returns {@code true}.
312      * @see java.awt.Dialog.ModalityType
313      * @see java.awt.Dialog.ModalityType#MODELESS
314      * @see java.awt.Dialog#DEFAULT_MODALITY_TYPE
315      * @see java.awt.Dialog#setModal
316      * @see java.awt.Dialog#setModalityType
317      * @see java.awt.GraphicsEnvironment#isHeadless
318      * @see JComponent#getDefaultLocale
319      * @since 1.4
320      */
321     public JDialog(Frame owner, String title, boolean modal,
322                    GraphicsConfiguration gc) {
323         super(owner == null? SwingUtilities.getSharedOwnerFrame() : owner,
324               title, modal, gc);
325         if (owner == null) {
326             WindowListener ownerShutdownListener =
327                     SwingUtilities.getSharedOwnerFrameShutdownListener();
328             addWindowListener(ownerShutdownListener);
329         }
330         dialogInit();
331     }
332 
333     /**
334      * Creates a modeless dialog with the specified {@code Dialog}
335      * as its owner and an empty title.
336      * <p>
337      * This constructor sets the component's locale property to the value
338      * returned by {@code JComponent.getDefaultLocale}.
339      *
340      * @param owner the owner {@code Dialog} from which the dialog is displayed
341      *     or {@code null} if this dialog has no owner
342      * @throws HeadlessException {@code if GraphicsEnvironment.isHeadless()}
343      *     returns {@code true}.
344      * @see java.awt.GraphicsEnvironment#isHeadless
345      * @see JComponent#getDefaultLocale
346      */
347     public JDialog(Dialog owner) {
348         this(owner, false);
349     }
350 
351     /**
352      * Creates a dialog with an empty title and the specified modality and
353      * {@code Dialog} as its owner.
354      * <p>
355      * This constructor sets the component's locale property to the value
356      * returned by {@code JComponent.getDefaultLocale}.
357      *
358      * @param owner the owner {@code Dialog} from which the dialog is displayed
359      *     or {@code null} if this dialog has no owner
360      * @param modal specifies whether dialog blocks user input to other top-level
361      *     windows when shown. If {@code true}, the modality type property is set to
362      *     {@code DEFAULT_MODALITY_TYPE}, otherwise the dialog is modeless.
363      * @throws HeadlessException if {@code GraphicsEnvironment.isHeadless()}
364      *     returns {@code true}.
365      * @see java.awt.Dialog.ModalityType
366      * @see java.awt.Dialog.ModalityType#MODELESS
367      * @see java.awt.Dialog#DEFAULT_MODALITY_TYPE
368      * @see java.awt.Dialog#setModal
369      * @see java.awt.Dialog#setModalityType
370      * @see java.awt.GraphicsEnvironment#isHeadless
371      * @see JComponent#getDefaultLocale
372      */
373     public JDialog(Dialog owner, boolean modal) {
374         this(owner, "", modal);
375     }
376 
377     /**
378      * Creates a modeless dialog with the specified title and
379      * with the specified owner dialog.
380      * <p>
381      * This constructor sets the component's locale property to the value
382      * returned by {@code JComponent.getDefaultLocale}.
383      *
384      * @param owner the owner {@code Dialog} from which the dialog is displayed
385      *     or {@code null} if this dialog has no owner
386      * @param title  the {@code String} to display in the dialog's
387      *                  title bar
388      * @throws HeadlessException if {@code GraphicsEnvironment.isHeadless()}
389      *     returns {@code true}.
390      * @see java.awt.GraphicsEnvironment#isHeadless
391      * @see JComponent#getDefaultLocale
392      */
393     public JDialog(Dialog owner, String title) {
394         this(owner, title, false);
395     }
396 
397     /**
398      * Creates a dialog with the specified title, modality
399      * and the specified owner {@code Dialog}.
400      * <p>
401      * This constructor sets the component's locale property to the value
402      * returned by {@code JComponent.getDefaultLocale}.
403      *
404      * @param owner the owner {@code Dialog} from which the dialog is displayed
405      *     or {@code null} if this dialog has no owner
406      * @param title  the {@code String} to display in the dialog's
407      *     title bar
408      * @param modal specifies whether dialog blocks user input to other top-level
409      *     windows when shown. If {@code true}, the modality type property is set to
410      *     {@code DEFAULT_MODALITY_TYPE}, otherwise the dialog is modeless
411      * @throws HeadlessException if {@code GraphicsEnvironment.isHeadless()}
412      *     returns {@code true}.
413      * @see java.awt.Dialog.ModalityType
414      * @see java.awt.Dialog.ModalityType#MODELESS
415      * @see java.awt.Dialog#DEFAULT_MODALITY_TYPE
416      * @see java.awt.Dialog#setModal
417      * @see java.awt.Dialog#setModalityType
418      * @see java.awt.GraphicsEnvironment#isHeadless
419      * @see JComponent#getDefaultLocale
420      */
421     public JDialog(Dialog owner, String title, boolean modal) {
422         super(owner, title, modal);
423         dialogInit();
424     }
425 
426     /**
427      * Creates a dialog with the specified title, owner {@code Dialog},
428      * modality and {@code GraphicsConfiguration}.
429      *
430      * <p>
431      * NOTE: Any popup components ({@code JComboBox},
432      * {@code JPopupMenu}, {@code JMenuBar})
433      * created within a modal dialog will be forced to be lightweight.
434      * <p>
435      * This constructor sets the component's locale property to the value
436      * returned by {@code JComponent.getDefaultLocale}.
437      *
438      * @param owner the owner {@code Dialog} from which the dialog is displayed
439      *     or {@code null} if this dialog has no owner
440      * @param title  the {@code String} to display in the dialog's
441      *     title bar
442      * @param modal specifies whether dialog blocks user input to other top-level
443      *     windows when shown. If {@code true}, the modality type property is set to
444      *     {@code DEFAULT_MODALITY_TYPE}, otherwise the dialog is modeless
445      * @param gc the {@code GraphicsConfiguration} of the target screen device;
446      *     if {@code null}, the default system {@code GraphicsConfiguration}
447      *     is assumed
448      * @throws HeadlessException if {@code GraphicsEnvironment.isHeadless()}
449      *     returns {@code true}.
450      * @see java.awt.Dialog.ModalityType
451      * @see java.awt.Dialog.ModalityType#MODELESS
452      * @see java.awt.Dialog#DEFAULT_MODALITY_TYPE
453      * @see java.awt.Dialog#setModal
454      * @see java.awt.Dialog#setModalityType
455      * @see java.awt.GraphicsEnvironment#isHeadless
456      * @see JComponent#getDefaultLocale
457      * @since 1.4
458      */
459     public JDialog(Dialog owner, String title, boolean modal,
460                    GraphicsConfiguration gc) {
461         super(owner, title, modal, gc);
462         dialogInit();
463     }
464 
465     /**
466      * Creates a modeless dialog with the specified {@code Window}
467      * as its owner and an empty title.
468      * <p>
469      * This constructor sets the component's locale property to the value
470      * returned by {@code JComponent.getDefaultLocale}.
471      *
472      * @param owner the {@code Window} from which the dialog is displayed or
473      *     {@code null} if this dialog has no owner
474      *
475      * @throws IllegalArgumentException
476      *     if the {@code owner} is not an instance of {@link java.awt.Dialog Dialog}
477      *     or {@link java.awt.Frame Frame}
478      * @throws IllegalArgumentException
479      *     if the {@code owner}'s {@code GraphicsConfiguration} is not from a screen device
480      * @throws HeadlessException
481      *     when {@code GraphicsEnvironment.isHeadless()} returns {@code true}
482      *
483      * @see java.awt.GraphicsEnvironment#isHeadless
484      * @see JComponent#getDefaultLocale
485      *
486      * @since 1.6
487      */
488     public JDialog(Window owner) {
489         this(owner, Dialog.ModalityType.MODELESS);
490     }
491 
492     /**
493      * Creates a dialog with an empty title and the specified modality and
494      * {@code Window} as its owner.
495      * <p>
496      * This constructor sets the component's locale property to the value
497      * returned by {@code JComponent.getDefaultLocale}.
498      *
499      * @param owner the {@code Window} from which the dialog is displayed or
500      *     {@code null} if this dialog has no owner
501      * @param modalityType specifies whether dialog blocks input to other
502      *     windows when shown. {@code null} value and unsupported modality
503      *     types are equivalent to {@code MODELESS}
504      *
505      * @throws IllegalArgumentException
506      *     if the {@code owner} is not an instance of {@link java.awt.Dialog Dialog}
507      *     or {@link java.awt.Frame Frame}
508      * @throws IllegalArgumentException
509      *     if the {@code owner}'s {@code GraphicsConfiguration} is not from a screen device
510      * @throws HeadlessException
511      *     when {@code GraphicsEnvironment.isHeadless()} returns {@code true}
512      * @throws SecurityException
513      *     if the calling thread does not have permission to create modal dialogs
514      *     with the given {@code modalityType}
515      *
516      * @see java.awt.Dialog.ModalityType
517      * @see java.awt.Dialog#setModal
518      * @see java.awt.Dialog#setModalityType
519      * @see java.awt.GraphicsEnvironment#isHeadless
520      * @see JComponent#getDefaultLocale
521      *
522      * @since 1.6
523      */
524     public JDialog(Window owner, ModalityType modalityType) {
525         this(owner, "", modalityType);
526     }
527 
528     /**
529      * Creates a modeless dialog with the specified title and owner
530      * {@code Window}.
531      * <p>
532      * This constructor sets the component's locale property to the value
533      * returned by {@code JComponent.getDefaultLocale}.
534      *
535      * @param owner the {@code Window} from which the dialog is displayed or
536      *     {@code null} if this dialog has no owner
537      * @param title the {@code String} to display in the dialog's
538      *     title bar or {@code null} if the dialog has no title
539      *
540      * @throws IllegalArgumentException
541      *     if the {@code owner} is not an instance of {@link java.awt.Dialog Dialog}
542      *     or {@link java.awt.Frame Frame}
543      * @throws IllegalArgumentException
544      *     if the {@code owner}'s {@code GraphicsConfiguration} is not from a screen device
545      * @throws HeadlessException
546      *     when {@code GraphicsEnvironment.isHeadless()} returns {@code true}
547      *
548      * @see java.awt.GraphicsEnvironment#isHeadless
549      * @see JComponent#getDefaultLocale
550      *
551      * @since 1.6
552      */
553     public JDialog(Window owner, String title) {
554         this(owner, title, Dialog.ModalityType.MODELESS);
555     }
556 
557     /**
558      * Creates a dialog with the specified title, owner {@code Window} and
559      * modality.
560      * <p>
561      * This constructor sets the component's locale property to the value
562      * returned by {@code JComponent.getDefaultLocale}.
563      *
564      * @param owner the {@code Window} from which the dialog is displayed or
565      *     {@code null} if this dialog has no owner
566      * @param title the {@code String} to display in the dialog's
567      *     title bar or {@code null} if the dialog has no title
568      * @param modalityType specifies whether dialog blocks input to other
569      *     windows when shown. {@code null} value and unsupported modality
570      *     types are equivalent to {@code MODELESS}
571      *
572      * @throws IllegalArgumentException
573      *     if the {@code owner} is not an instance of {@link java.awt.Dialog Dialog}
574      *     or {@link java.awt.Frame Frame}
575      * @throws IllegalArgumentException
576      *     if the {@code owner}'s {@code GraphicsConfiguration} is not from a screen device
577      * @throws HeadlessException
578      *     when {@code GraphicsEnvironment.isHeadless()} returns {@code true}
579      * @throws SecurityException
580      *     if the calling thread does not have permission to create modal dialogs
581      *     with the given {@code modalityType}
582      *
583      * @see java.awt.Dialog.ModalityType
584      * @see java.awt.Dialog#setModal
585      * @see java.awt.Dialog#setModalityType
586      * @see java.awt.GraphicsEnvironment#isHeadless
587      * @see JComponent#getDefaultLocale
588      *
589      * @since 1.6
590      */
591     public JDialog(Window owner, String title, Dialog.ModalityType modalityType) {
592         super(owner, title, modalityType);
593         dialogInit();
594     }
595 
596     /**
597      * Creates a dialog with the specified title, owner {@code Window},
598      * modality and {@code GraphicsConfiguration}.
599      * <p>
600      * NOTE: Any popup components ({@code JComboBox},
601      * {@code JPopupMenu}, {@code JMenuBar})
602      * created within a modal dialog will be forced to be lightweight.
603      * <p>
604      * This constructor sets the component's locale property to the value
605      * returned by {@code JComponent.getDefaultLocale}.
606      *
607      * @param owner the {@code Window} from which the dialog is displayed or
608      *     {@code null} if this dialog has no owner
609      * @param title the {@code String} to display in the dialog's
610      *     title bar or {@code null} if the dialog has no title
611      * @param modalityType specifies whether dialog blocks input to other
612      *     windows when shown. {@code null} value and unsupported modality
613      *     types are equivalent to {@code MODELESS}
614      * @param gc the {@code GraphicsConfiguration} of the target screen device;
615      *     if {@code null}, the default system {@code GraphicsConfiguration}
616      *     is assumed
617      * @throws IllegalArgumentException
618      *     if the {@code owner} is not an instance of {@link java.awt.Dialog Dialog}
619      *     or {@link java.awt.Frame Frame}
620      * @throws IllegalArgumentException
621      *     if the {@code owner}'s {@code GraphicsConfiguration} is not from a screen device
622      * @throws HeadlessException
623      *     when {@code GraphicsEnvironment.isHeadless()} returns {@code true}
624      * @throws SecurityException
625      *     if the calling thread does not have permission to create modal dialogs
626      *     with the given {@code modalityType}
627      *
628      * @see java.awt.Dialog.ModalityType
629      * @see java.awt.Dialog#setModal
630      * @see java.awt.Dialog#setModalityType
631      * @see java.awt.GraphicsEnvironment#isHeadless
632      * @see JComponent#getDefaultLocale
633      *
634      * @since 1.6
635      */
636     public JDialog(Window owner, String title, Dialog.ModalityType modalityType,
637                    GraphicsConfiguration gc) {
638         super(owner, title, modalityType, gc);
639         dialogInit();
640     }
641 
642     /**
643      * Called by the constructors to init the {@code JDialog} properly.
644      */
645     protected void dialogInit() {
646         enableEvents(AWTEvent.KEY_EVENT_MASK | AWTEvent.WINDOW_EVENT_MASK);
647         setLocale( JComponent.getDefaultLocale() );
648         setRootPane(createRootPane());
649         setRootPaneCheckingEnabled(true);
650         if (JDialog.isDefaultLookAndFeelDecorated()) {
651             boolean supportsWindowDecorations =
652             UIManager.getLookAndFeel().getSupportsWindowDecorations();
653             if (supportsWindowDecorations) {
654                 setUndecorated(true);
655                 getRootPane().setWindowDecorationStyle(JRootPane.PLAIN_DIALOG);
656             }
657         }
658         sun.awt.SunToolkit.checkAndSetPolicy(this);
659     }
660 
661     /**
662      * Called by the constructor methods to create the default
663      * {@code rootPane}.
664      */
665     protected JRootPane createRootPane() {
666         JRootPane rp = new JRootPane();
667         // NOTE: this uses setOpaque vs LookAndFeel.installProperty as there
668         // is NO reason for the RootPane not to be opaque. For painting to
669         // work the contentPane must be opaque, therefor the RootPane can
670         // also be opaque.
671         rp.setOpaque(true);
672         return rp;
673     }
674 
675     /**
676      * Handles window events depending on the state of the
677      * {@code defaultCloseOperation} property.
678      *
679      * @see #setDefaultCloseOperation
680      */
681     protected void processWindowEvent(WindowEvent e) {
682         super.processWindowEvent(e);
683 
684         if (e.getID() == WindowEvent.WINDOW_CLOSING) {
685             switch(defaultCloseOperation) {
686               case HIDE_ON_CLOSE:
687                  setVisible(false);
688                  break;
689               case DISPOSE_ON_CLOSE:
690                  dispose();
691                  break;
692               case DO_NOTHING_ON_CLOSE:
693                  default:
694                  break;
695             }
696         }
697     }
698 
699 
700     /**
701      * Sets the operation that will happen by default when
702      * the user initiates a "close" on this dialog.
703      * You must specify one of the following choices:
704      * <br><br>
705      * <ul>
706      * <li>{@code DO_NOTHING_ON_CLOSE}
707      * (defined in {@code WindowConstants}):
708      * Don't do anything; require the
709      * program to handle the operation in the {@code windowClosing}
710      * method of a registered {@code WindowListener} object.
711      *
712      * <li>{@code HIDE_ON_CLOSE}
713      * (defined in {@code WindowConstants}):
714      * Automatically hide the dialog after
715      * invoking any registered {@code WindowListener}
716      * objects.
717      *
718      * <li>{@code DISPOSE_ON_CLOSE}
719      * (defined in {@code WindowConstants}):
720      * Automatically hide and dispose the
721      * dialog after invoking any registered {@code WindowListener}
722      * objects.
723      * </ul>
724      * <p>
725      * The value is set to {@code HIDE_ON_CLOSE} by default. Changes
726      * to the value of this property cause the firing of a property
727      * change event, with property name "defaultCloseOperation".
728      * <p>
729      * <b>Note</b>: When the last displayable window within the
730      * Java virtual machine (VM) is disposed of, the VM may
731      * terminate.  See <a href="../../java/awt/doc-files/AWTThreadIssues.html">
732      * AWT Threading Issues</a> for more information.
733      *
734      * @param operation the operation which should be performed when the
735      *        user closes the dialog
736      * @throws IllegalArgumentException if defaultCloseOperation value
737      *         isn't one of the above valid values
738      * @see #addWindowListener
739      * @see #getDefaultCloseOperation
740      * @see WindowConstants
741      *
742      * @beaninfo
743      *   preferred: true
744      *       bound: true
745      *        enum: DO_NOTHING_ON_CLOSE WindowConstants.DO_NOTHING_ON_CLOSE
746      *              HIDE_ON_CLOSE       WindowConstants.HIDE_ON_CLOSE
747      *              DISPOSE_ON_CLOSE    WindowConstants.DISPOSE_ON_CLOSE
748      * description: The dialog's default close operation.
749      */
750     public void setDefaultCloseOperation(int operation) {
751         if (operation != DO_NOTHING_ON_CLOSE &&
752             operation != HIDE_ON_CLOSE &&
753             operation != DISPOSE_ON_CLOSE) {
754             throw new IllegalArgumentException("defaultCloseOperation must be one of: DO_NOTHING_ON_CLOSE, HIDE_ON_CLOSE, or DISPOSE_ON_CLOSE");
755         }
756 
757         int oldValue = this.defaultCloseOperation;
758         this.defaultCloseOperation = operation;
759         firePropertyChange("defaultCloseOperation", oldValue, operation);
760     }
761 
762    /**
763     * Returns the operation which occurs when the user
764     * initiates a "close" on this dialog.
765     *
766     * @return an integer indicating the window-close operation
767     * @see #setDefaultCloseOperation
768     */
769     public int getDefaultCloseOperation() {
770         return defaultCloseOperation;
771     }
772 
773     /**
774      * Sets the {@code transferHandler} property, which is a mechanism to
775      * support transfer of data into this component. Use {@code null}
776      * if the component does not support data transfer operations.
777      * <p>
778      * If the system property {@code suppressSwingDropSupport} is {@code false}
779      * (the default) and the current drop target on this component is either
780      * {@code null} or not a user-set drop target, this method will change the
781      * drop target as follows: If {@code newHandler} is {@code null} it will
782      * clear the drop target. If not {@code null} it will install a new
783      * {@code DropTarget}.
784      * <p>
785      * Note: When used with {@code JDialog}, {@code TransferHandler} only
786      * provides data import capability, as the data export related methods
787      * are currently typed to {@code JComponent}.
788      * <p>
789      * Please see
790      * <a href="http://docs.oracle.com/javase/tutorial/uiswing/dnd/index.html">
791      * How to Use Drag and Drop and Data Transfer</a>, a section in
792      * <em>The Java Tutorial</em>, for more information.
793      *
794      * @param newHandler the new {@code TransferHandler}
795      *
796      * @see TransferHandler
797      * @see #getTransferHandler
798      * @see java.awt.Component#setDropTarget
799      * @since 1.6
800      *
801      * @beaninfo
802      *        bound: true
803      *       hidden: true
804      *  description: Mechanism for transfer of data into the component
805      */
806     public void setTransferHandler(TransferHandler newHandler) {
807         TransferHandler oldHandler = transferHandler;
808         transferHandler = newHandler;
809         SwingUtilities.installSwingDropTargetAsNecessary(this, transferHandler);
810         firePropertyChange("transferHandler", oldHandler, newHandler);
811     }
812 
813     /**
814      * Gets the {@code transferHandler} property.
815      *
816      * @return the value of the {@code transferHandler} property
817      *
818      * @see TransferHandler
819      * @see #setTransferHandler
820      * @since 1.6
821      */
822     public TransferHandler getTransferHandler() {
823         return transferHandler;
824     }
825 
826     /**
827      * Calls {@code paint(g)}.  This method was overridden to
828      * prevent an unnecessary call to clear the background.
829      *
830      * @param g  the {@code Graphics} context in which to paint
831      */
832     public void update(Graphics g) {
833         paint(g);
834     }
835 
836    /**
837     * Sets the menubar for this dialog.
838     *
839     * @param menu the menubar being placed in the dialog
840     *
841     * @see #getJMenuBar
842     *
843     * @beaninfo
844     *      hidden: true
845     * description: The menubar for accessing pulldown menus from this dialog.
846     */
847     public void setJMenuBar(JMenuBar menu) {
848         getRootPane().setMenuBar(menu);
849     }
850 
851    /**
852     * Returns the menubar set on this dialog.
853     *
854     * @see #setJMenuBar
855     */
856     public JMenuBar getJMenuBar() {
857         return getRootPane().getMenuBar();
858     }
859 
860 
861     /**
862      * Returns whether calls to {@code add} and
863      * {@code setLayout} are forwarded to the {@code contentPane}.
864      *
865      * @return true if {@code add} and {@code setLayout}
866      *         are forwarded; false otherwise
867      *
868      * @see #addImpl
869      * @see #setLayout
870      * @see #setRootPaneCheckingEnabled
871      * @see javax.swing.RootPaneContainer
872      */
873     protected boolean isRootPaneCheckingEnabled() {
874         return rootPaneCheckingEnabled;
875     }
876 
877 
878     /**
879      * Sets whether calls to {@code add} and
880      * {@code setLayout} are forwarded to the {@code contentPane}.
881      *
882      * @param enabled  true if {@code add} and {@code setLayout}
883      *        are forwarded, false if they should operate directly on the
884      *        {@code JDialog}.
885      *
886      * @see #addImpl
887      * @see #setLayout
888      * @see #isRootPaneCheckingEnabled
889      * @see javax.swing.RootPaneContainer
890      * @beaninfo
891      *      hidden: true
892      * description: Whether the add and setLayout methods are forwarded
893      */
894     protected void setRootPaneCheckingEnabled(boolean enabled) {
895         rootPaneCheckingEnabled = enabled;
896     }
897 
898     /**
899      * Adds the specified child {@code Component}.
900      * This method is overridden to conditionally forward calls to the
901      * {@code contentPane}.
902      * By default, children are added to the {@code contentPane} instead
903      * of the frame, refer to {@link javax.swing.RootPaneContainer} for
904      * details.
905      *
906      * @param comp the component to be enhanced
907      * @param constraints the constraints to be respected
908      * @param index the index
909      * @throws IllegalArgumentException if {@code index} is invalid
910      * @throws IllegalArgumentException if adding the container's parent
911      *                  to itself
912      * @throws IllegalArgumentException if adding a window to a container
913      *
914      * @see #setRootPaneCheckingEnabled
915      * @see javax.swing.RootPaneContainer
916      */
917     protected void addImpl(Component comp, Object constraints, int index)
918     {
919         if(isRootPaneCheckingEnabled()) {
920             getContentPane().add(comp, constraints, index);
921         }
922         else {
923             super.addImpl(comp, constraints, index);
924         }
925     }
926 
927     /**
928      * Removes the specified component from the container. If
929      * {@code comp} is not the {@code rootPane}, this will forward
930      * the call to the {@code contentPane}. This will do nothing if
931      * {@code comp} is not a child of the {@code JDialog} or
932      * {@code contentPane}.
933      *
934      * @param comp the component to be removed
935      * @throws NullPointerException if {@code comp} is null
936      * @see #add
937      * @see javax.swing.RootPaneContainer
938      */
939     public void remove(Component comp) {
940         if (comp == rootPane) {
941             super.remove(comp);
942         } else {
943             getContentPane().remove(comp);
944         }
945     }
946 
947 
948     /**
949      * Sets the {@code LayoutManager}.
950      * Overridden to conditionally forward the call to the
951      * {@code contentPane}.
952      * Refer to {@link javax.swing.RootPaneContainer} for
953      * more information.
954      *
955      * @param manager the {@code LayoutManager}
956      * @see #setRootPaneCheckingEnabled
957      * @see javax.swing.RootPaneContainer
958      */
959     public void setLayout(LayoutManager manager) {
960         if(isRootPaneCheckingEnabled()) {
961             getContentPane().setLayout(manager);
962         }
963         else {
964             super.setLayout(manager);
965         }
966     }
967 
968 
969     /**
970      * Returns the {@code rootPane} object for this dialog.
971      *
972      * @see #setRootPane
973      * @see RootPaneContainer#getRootPane
974      */
975     public JRootPane getRootPane() {
976         return rootPane;
977     }
978 
979 
980     /**
981      * Sets the {@code rootPane} property.
982      * This method is called by the constructor.
983      *
984      * @param root the {@code rootPane} object for this dialog
985      *
986      * @see #getRootPane
987      *
988      * @beaninfo
989      *   hidden: true
990      * description: the RootPane object for this dialog.
991      */
992     protected void setRootPane(JRootPane root) {
993         if(rootPane != null) {
994             remove(rootPane);
995         }
996         rootPane = root;
997         if(rootPane != null) {
998             boolean checkingEnabled = isRootPaneCheckingEnabled();
999             try {
1000                 setRootPaneCheckingEnabled(false);
1001                 add(rootPane, BorderLayout.CENTER);
1002             }
1003             finally {
1004                 setRootPaneCheckingEnabled(checkingEnabled);
1005             }
1006         }
1007     }
1008 
1009 
1010     /**
1011      * Returns the {@code contentPane} object for this dialog.
1012      *
1013      * @return the {@code contentPane} property
1014      *
1015      * @see #setContentPane
1016      * @see RootPaneContainer#getContentPane
1017      */
1018     public Container getContentPane() {
1019         return getRootPane().getContentPane();
1020     }
1021 
1022 
1023    /**
1024      * Sets the {@code contentPane} property.
1025      * This method is called by the constructor.
1026      * <p>
1027      * Swing's painting architecture requires an opaque {@code JComponent}
1028      * in the containment hierarchy. This is typically provided by the
1029      * content pane. If you replace the content pane it is recommended you
1030      * replace it with an opaque {@code JComponent}.
1031      * @see JRootPane
1032      *
1033      * @param contentPane the {@code contentPane} object for this dialog
1034      *
1035      * @throws java.awt.IllegalComponentStateException (a runtime
1036      *            exception) if the content pane parameter is {@code null}
1037      * @see #getContentPane
1038      * @see RootPaneContainer#setContentPane
1039      *
1040      * @beaninfo
1041      *     hidden: true
1042      *     description: The client area of the dialog where child
1043      *                  components are normally inserted.
1044      */
1045     public void setContentPane(Container contentPane) {
1046         getRootPane().setContentPane(contentPane);
1047     }
1048 
1049     /**
1050      * Returns the {@code layeredPane} object for this dialog.
1051      *
1052      * @return the {@code layeredPane} property
1053      *
1054      * @see #setLayeredPane
1055      * @see RootPaneContainer#getLayeredPane
1056      */
1057     public JLayeredPane getLayeredPane() {
1058         return getRootPane().getLayeredPane();
1059     }
1060 
1061     /**
1062      * Sets the {@code layeredPane} property.
1063      * This method is called by the constructor.
1064      *
1065      * @param layeredPane the new {@code layeredPane} property
1066      *
1067      * @throws java.awt.IllegalComponentStateException (a runtime
1068      *            exception) if the layered pane parameter is null
1069      * @see #getLayeredPane
1070      * @see RootPaneContainer#setLayeredPane
1071      *
1072      * @beaninfo
1073      *     hidden: true
1074      *     description: The pane which holds the various dialog layers.
1075      */
1076     public void setLayeredPane(JLayeredPane layeredPane) {
1077         getRootPane().setLayeredPane(layeredPane);
1078     }
1079 
1080     /**
1081      * Returns the {@code glassPane} object for this dialog.
1082      *
1083      * @return the {@code glassPane} property
1084      *
1085      * @see #setGlassPane
1086      * @see RootPaneContainer#getGlassPane
1087      */
1088     public Component getGlassPane() {
1089         return getRootPane().getGlassPane();
1090     }
1091 
1092     /**
1093      * Sets the {@code glassPane} property.
1094      * This method is called by the constructor.
1095      *
1096      * @param glassPane the {@code glassPane} object for this dialog
1097      * @see #getGlassPane
1098      * @see RootPaneContainer#setGlassPane
1099      *
1100      * @beaninfo
1101      *     hidden: true
1102      *     description: A transparent pane used for menu rendering.
1103      */
1104     public void setGlassPane(Component glassPane) {
1105         getRootPane().setGlassPane(glassPane);
1106     }
1107 
1108     /**
1109      * {@inheritDoc}
1110      *
1111      * @since 1.6
1112      */
1113     public Graphics getGraphics() {
1114         JComponent.getGraphicsInvoked(this);
1115         return super.getGraphics();
1116     }
1117 
1118     /**
1119      * Repaints the specified rectangle of this component within
1120      * {@code time} milliseconds.  Refer to {@code RepaintManager}
1121      * for details on how the repaint is handled.
1122      *
1123      * @param     time   maximum time in milliseconds before update
1124      * @param     x    the <i>x</i> coordinate
1125      * @param     y    the <i>y</i> coordinate
1126      * @param     width    the width
1127      * @param     height   the height
1128      * @see       RepaintManager
1129      * @since     1.6
1130      */
1131     public void repaint(long time, int x, int y, int width, int height) {
1132         if (RepaintManager.HANDLE_TOP_LEVEL_PAINT) {
1133             RepaintManager.currentManager(this).addDirtyRegion(
1134                               this, x, y, width, height);
1135         }
1136         else {
1137             super.repaint(time, x, y, width, height);
1138         }
1139     }
1140 
1141     /**
1142      * Provides a hint as to whether or not newly created {@code JDialog}s
1143      * should have their Window decorations (such as borders, widgets to
1144      * close the window, title...) provided by the current look
1145      * and feel. If {@code defaultLookAndFeelDecorated} is true,
1146      * the current {@code LookAndFeel} supports providing window
1147      * decorations, and the current window manager supports undecorated
1148      * windows, then newly created {@code JDialog}s will have their
1149      * Window decorations provided by the current {@code LookAndFeel}.
1150      * Otherwise, newly created {@code JDialog}s will have their
1151      * Window decorations provided by the current window manager.
1152      * <p>
1153      * You can get the same effect on a single JDialog by doing the following:
1154      * <pre>
1155      *    JDialog dialog = new JDialog();
1156      *    dialog.setUndecorated(true);
1157      *    dialog.getRootPane().setWindowDecorationStyle(JRootPane.PLAIN_DIALOG);
1158      * </pre>
1159      *
1160      * @param defaultLookAndFeelDecorated A hint as to whether or not current
1161      *        look and feel should provide window decorations
1162      * @see javax.swing.LookAndFeel#getSupportsWindowDecorations
1163      * @since 1.4
1164      */
1165     public static void setDefaultLookAndFeelDecorated(boolean defaultLookAndFeelDecorated) {
1166         if (defaultLookAndFeelDecorated) {
1167             SwingUtilities.appContextPut(defaultLookAndFeelDecoratedKey, Boolean.TRUE);
1168         } else {
1169             SwingUtilities.appContextPut(defaultLookAndFeelDecoratedKey, Boolean.FALSE);
1170         }
1171     }
1172 
1173     /**
1174      * Returns true if newly created {@code JDialog}s should have their
1175      * Window decorations provided by the current look and feel. This is only
1176      * a hint, as certain look and feels may not support this feature.
1177      *
1178      * @return true if look and feel should provide Window decorations.
1179      * @since 1.4
1180      */
1181     public static boolean isDefaultLookAndFeelDecorated() {
1182         Boolean defaultLookAndFeelDecorated =
1183             (Boolean) SwingUtilities.appContextGet(defaultLookAndFeelDecoratedKey);
1184         if (defaultLookAndFeelDecorated == null) {
1185             defaultLookAndFeelDecorated = Boolean.FALSE;
1186         }
1187         return defaultLookAndFeelDecorated.booleanValue();
1188     }
1189 
1190     /**
1191      * Returns a string representation of this {@code JDialog}.
1192      * This method
1193      * is intended to be used only for debugging purposes, and the
1194      * content and format of the returned string may vary between
1195      * implementations. The returned string may be empty but may not
1196      * be {@code null}.
1197      *
1198      * @return  a string representation of this {@code JDialog}.
1199      */
1200     protected String paramString() {
1201         String defaultCloseOperationString;
1202         if (defaultCloseOperation == HIDE_ON_CLOSE) {
1203             defaultCloseOperationString = "HIDE_ON_CLOSE";
1204         } else if (defaultCloseOperation == DISPOSE_ON_CLOSE) {
1205             defaultCloseOperationString = "DISPOSE_ON_CLOSE";
1206         } else if (defaultCloseOperation == DO_NOTHING_ON_CLOSE) {
1207             defaultCloseOperationString = "DO_NOTHING_ON_CLOSE";
1208         } else defaultCloseOperationString = "";
1209         String rootPaneString = (rootPane != null ?
1210                                  rootPane.toString() : "");
1211         String rootPaneCheckingEnabledString = (rootPaneCheckingEnabled ?
1212                                                 "true" : "false");
1213 
1214         return super.paramString() +
1215         ",defaultCloseOperation=" + defaultCloseOperationString +
1216         ",rootPane=" + rootPaneString +
1217         ",rootPaneCheckingEnabled=" + rootPaneCheckingEnabledString;
1218     }
1219 
1220 
1221 /////////////////
1222 // Accessibility support
1223 ////////////////
1224 
1225     protected AccessibleContext accessibleContext = null;
1226 
1227     /**
1228      * Gets the AccessibleContext associated with this JDialog.
1229      * For JDialogs, the AccessibleContext takes the form of an
1230      * AccessibleJDialog.
1231      * A new AccessibleJDialog instance is created if necessary.
1232      *
1233      * @return an AccessibleJDialog that serves as the
1234      *         AccessibleContext of this JDialog
1235      */
1236     public AccessibleContext getAccessibleContext() {
1237         if (accessibleContext == null) {
1238             accessibleContext = new AccessibleJDialog();
1239         }
1240         return accessibleContext;
1241     }
1242 
1243     /**
1244      * This class implements accessibility support for the
1245      * {@code JDialog} class.  It provides an implementation of the
1246      * Java Accessibility API appropriate to dialog user-interface
1247      * elements.
1248      */
1249     protected class AccessibleJDialog extends AccessibleAWTDialog {
1250 
1251         // AccessibleContext methods
1252         //
1253         /**
1254          * Get the accessible name of this object.
1255          *
1256          * @return the localized name of the object -- can be null if this
1257          * object does not have a name
1258          */
1259         public String getAccessibleName() {
1260             if (accessibleName != null) {
1261                 return accessibleName;
1262             } else {
1263                 if (getTitle() == null) {
1264                     return super.getAccessibleName();
1265                 } else {
1266                     return getTitle();
1267                 }
1268             }
1269         }
1270 
1271         /**
1272          * Get the state of this object.
1273          *
1274          * @return an instance of AccessibleStateSet containing the current
1275          * state set of the object
1276          * @see AccessibleState
1277          */
1278         public AccessibleStateSet getAccessibleStateSet() {
1279             AccessibleStateSet states = super.getAccessibleStateSet();
1280 
1281             if (isResizable()) {
1282                 states.add(AccessibleState.RESIZABLE);
1283             }
1284             if (getFocusOwner() != null) {
1285                 states.add(AccessibleState.ACTIVE);
1286             }
1287             if (isModal()) {
1288                 states.add(AccessibleState.MODAL);
1289             }
1290             return states;
1291         }
1292 
1293     } // inner class AccessibleJDialog
1294 }