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