1 /*
2 * Copyright (c) 1997, 2015, 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 setBackground(UIManager.getColor("control"));
652 setRootPaneCheckingEnabled(true);
653 if (JDialog.isDefaultLookAndFeelDecorated()) {
654 boolean supportsWindowDecorations =
655 UIManager.getLookAndFeel().getSupportsWindowDecorations();
656 if (supportsWindowDecorations) {
657 setUndecorated(true);
658 getRootPane().setWindowDecorationStyle(JRootPane.PLAIN_DIALOG);
659 }
660 }
661 sun.awt.SunToolkit.checkAndSetPolicy(this);
662 }
663
664 /**
665 * Called by the constructor methods to create the default
666 * {@code rootPane}.
667 *
668 * @return a new {@code JRootPane}
669 */
670 protected JRootPane createRootPane() {
671 JRootPane rp = new JRootPane();
672 // NOTE: this uses setOpaque vs LookAndFeel.installProperty as there
673 // is NO reason for the RootPane not to be opaque. For painting to
674 // work the contentPane must be opaque, therefor the RootPane can
675 // also be opaque.
676 rp.setOpaque(true);
677 return rp;
678 }
679
680 /**
681 * Handles window events depending on the state of the
682 * {@code defaultCloseOperation} property.
683 *
684 * @see #setDefaultCloseOperation
685 */
686 protected void processWindowEvent(WindowEvent e) {
687 super.processWindowEvent(e);
688
689 if (e.getID() == WindowEvent.WINDOW_CLOSING) {
690 switch(defaultCloseOperation) {
691 case HIDE_ON_CLOSE:
692 setVisible(false);
693 break;
694 case DISPOSE_ON_CLOSE:
695 dispose();
696 break;
697 case DO_NOTHING_ON_CLOSE:
698 default:
699 break;
700 }
701 }
702 }
703
704
705 /**
706 * Sets the operation that will happen by default when
707 * the user initiates a "close" on this dialog.
708 * You must specify one of the following choices:
709 * <br><br>
710 * <ul>
711 * <li>{@code DO_NOTHING_ON_CLOSE}
712 * (defined in {@code WindowConstants}):
713 * Don't do anything; require the
714 * program to handle the operation in the {@code windowClosing}
715 * method of a registered {@code WindowListener} object.
716 *
717 * <li>{@code HIDE_ON_CLOSE}
718 * (defined in {@code WindowConstants}):
719 * Automatically hide the dialog after
720 * invoking any registered {@code WindowListener}
721 * objects.
722 *
723 * <li>{@code DISPOSE_ON_CLOSE}
724 * (defined in {@code WindowConstants}):
725 * Automatically hide and dispose the
726 * dialog after invoking any registered {@code WindowListener}
727 * objects.
728 * </ul>
729 * <p>
730 * The value is set to {@code HIDE_ON_CLOSE} by default. Changes
731 * to the value of this property cause the firing of a property
732 * change event, with property name "defaultCloseOperation".
733 * <p>
734 * <b>Note</b>: When the last displayable window within the
735 * Java virtual machine (VM) is disposed of, the VM may
736 * terminate. See <a href="../../java/awt/doc-files/AWTThreadIssues.html">
737 * AWT Threading Issues</a> for more information.
738 *
739 * @param operation the operation which should be performed when the
740 * user closes the dialog
741 * @throws IllegalArgumentException if defaultCloseOperation value
742 * isn't one of the above valid values
743 * @see #addWindowListener
744 * @see #getDefaultCloseOperation
745 * @see WindowConstants
746 *
747 * @beaninfo
748 * preferred: true
749 * bound: true
750 * enum: DO_NOTHING_ON_CLOSE WindowConstants.DO_NOTHING_ON_CLOSE
751 * HIDE_ON_CLOSE WindowConstants.HIDE_ON_CLOSE
752 * DISPOSE_ON_CLOSE WindowConstants.DISPOSE_ON_CLOSE
753 * description: The dialog's default close operation.
754 */
755 public void setDefaultCloseOperation(int operation) {
756 if (operation != DO_NOTHING_ON_CLOSE &&
757 operation != HIDE_ON_CLOSE &&
758 operation != DISPOSE_ON_CLOSE) {
759 throw new IllegalArgumentException("defaultCloseOperation must be one of: DO_NOTHING_ON_CLOSE, HIDE_ON_CLOSE, or DISPOSE_ON_CLOSE");
760 }
761
762 int oldValue = this.defaultCloseOperation;
763 this.defaultCloseOperation = operation;
764 firePropertyChange("defaultCloseOperation", oldValue, operation);
765 }
766
767 /**
768 * Returns the operation which occurs when the user
769 * initiates a "close" on this dialog.
770 *
771 * @return an integer indicating the window-close operation
772 * @see #setDefaultCloseOperation
773 */
774 public int getDefaultCloseOperation() {
775 return defaultCloseOperation;
776 }
777
778 /**
779 * Sets the {@code transferHandler} property, which is a mechanism to
780 * support transfer of data into this component. Use {@code null}
781 * if the component does not support data transfer operations.
782 * <p>
783 * If the system property {@code suppressSwingDropSupport} is {@code false}
784 * (the default) and the current drop target on this component is either
785 * {@code null} or not a user-set drop target, this method will change the
786 * drop target as follows: If {@code newHandler} is {@code null} it will
787 * clear the drop target. If not {@code null} it will install a new
788 * {@code DropTarget}.
789 * <p>
790 * Note: When used with {@code JDialog}, {@code TransferHandler} only
791 * provides data import capability, as the data export related methods
792 * are currently typed to {@code JComponent}.
793 * <p>
794 * Please see
795 * <a href="http://docs.oracle.com/javase/tutorial/uiswing/dnd/index.html">
796 * How to Use Drag and Drop and Data Transfer</a>, a section in
797 * <em>The Java Tutorial</em>, for more information.
798 *
799 * @param newHandler the new {@code TransferHandler}
800 *
801 * @see TransferHandler
802 * @see #getTransferHandler
803 * @see java.awt.Component#setDropTarget
804 * @since 1.6
805 *
806 * @beaninfo
807 * bound: true
808 * hidden: true
809 * description: Mechanism for transfer of data into the component
810 */
811 public void setTransferHandler(TransferHandler newHandler) {
812 TransferHandler oldHandler = transferHandler;
813 transferHandler = newHandler;
814 SwingUtilities.installSwingDropTargetAsNecessary(this, transferHandler);
815 firePropertyChange("transferHandler", oldHandler, newHandler);
816 }
817
818 /**
819 * Gets the {@code transferHandler} property.
820 *
821 * @return the value of the {@code transferHandler} property
822 *
823 * @see TransferHandler
824 * @see #setTransferHandler
825 * @since 1.6
826 */
827 public TransferHandler getTransferHandler() {
828 return transferHandler;
829 }
830
831 /**
832 * Calls {@code paint(g)}. This method was overridden to
833 * prevent an unnecessary call to clear the background.
834 *
835 * @param g the {@code Graphics} context in which to paint
836 */
837 public void update(Graphics g) {
838 paint(g);
839 }
840
841 /**
842 * Sets the menubar for this dialog.
843 *
844 * @param menu the menubar being placed in the dialog
845 *
846 * @see #getJMenuBar
847 *
848 * @beaninfo
849 * hidden: true
850 * description: The menubar for accessing pulldown menus from this dialog.
851 */
852 public void setJMenuBar(final JMenuBar menu) {
853 getRootPane().setJMenuBar(menu);
854 }
855
856 /**
857 * Returns the menubar set on this dialog.
858 *
859 * @return the menubar set on this dialog
860 * @see #setJMenuBar
861 */
862 public JMenuBar getJMenuBar() {
863 return getRootPane().getJMenuBar();
864 }
865
866 /**
867 * Returns whether calls to {@code add} and
868 * {@code setLayout} are forwarded to the {@code contentPane}.
869 *
870 * @return true if {@code add} and {@code setLayout}
871 * are forwarded; false otherwise
872 *
873 * @see #addImpl
874 * @see #setLayout
875 * @see #setRootPaneCheckingEnabled
876 * @see javax.swing.RootPaneContainer
877 */
878 protected boolean isRootPaneCheckingEnabled() {
879 return rootPaneCheckingEnabled;
880 }
881
882
883 /**
884 * Sets whether calls to {@code add} and
885 * {@code setLayout} are forwarded to the {@code contentPane}.
886 *
887 * @param enabled true if {@code add} and {@code setLayout}
888 * are forwarded, false if they should operate directly on the
889 * {@code JDialog}.
890 *
891 * @see #addImpl
892 * @see #setLayout
893 * @see #isRootPaneCheckingEnabled
894 * @see javax.swing.RootPaneContainer
895 * @beaninfo
896 * hidden: true
897 * description: Whether the add and setLayout methods are forwarded
898 */
899 protected void setRootPaneCheckingEnabled(boolean enabled) {
900 rootPaneCheckingEnabled = enabled;
901 }
902
903 /**
904 * Adds the specified child {@code Component}.
905 * This method is overridden to conditionally forward calls to the
906 * {@code contentPane}.
907 * By default, children are added to the {@code contentPane} instead
908 * of the frame, refer to {@link javax.swing.RootPaneContainer} for
909 * details.
910 *
911 * @param comp the component to be enhanced
912 * @param constraints the constraints to be respected
913 * @param index the index
914 * @throws IllegalArgumentException if {@code index} is invalid
915 * @throws IllegalArgumentException if adding the container's parent
916 * to itself
917 * @throws IllegalArgumentException if adding a window to a container
918 *
919 * @see #setRootPaneCheckingEnabled
920 * @see javax.swing.RootPaneContainer
921 */
922 protected void addImpl(Component comp, Object constraints, int index)
923 {
924 if(isRootPaneCheckingEnabled()) {
925 getContentPane().add(comp, constraints, index);
926 }
927 else {
928 super.addImpl(comp, constraints, index);
929 }
930 }
931
932 /**
933 * Removes the specified component from the container. If
934 * {@code comp} is not the {@code rootPane}, this will forward
935 * the call to the {@code contentPane}. This will do nothing if
936 * {@code comp} is not a child of the {@code JDialog} or
937 * {@code contentPane}.
938 *
939 * @param comp the component to be removed
940 * @throws NullPointerException if {@code comp} is null
941 * @see #add
942 * @see javax.swing.RootPaneContainer
943 */
944 public void remove(Component comp) {
945 if (comp == rootPane) {
946 super.remove(comp);
947 } else {
948 getContentPane().remove(comp);
949 }
950 }
951
952
953 /**
954 * Sets the {@code LayoutManager}.
955 * Overridden to conditionally forward the call to the
956 * {@code contentPane}.
957 * Refer to {@link javax.swing.RootPaneContainer} for
958 * more information.
959 *
960 * @param manager the {@code LayoutManager}
961 * @see #setRootPaneCheckingEnabled
962 * @see javax.swing.RootPaneContainer
963 */
964 public void setLayout(LayoutManager manager) {
965 if(isRootPaneCheckingEnabled()) {
966 getContentPane().setLayout(manager);
967 }
968 else {
969 super.setLayout(manager);
970 }
971 }
972
973
974 /**
975 * Returns the {@code rootPane} object for this dialog.
976 *
977 * @see #setRootPane
978 * @see RootPaneContainer#getRootPane
979 */
980 public JRootPane getRootPane() {
981 return rootPane;
982 }
983
984
985 /**
986 * Sets the {@code rootPane} property.
987 * This method is called by the constructor.
988 *
989 * @param root the {@code rootPane} object for this dialog
990 *
991 * @see #getRootPane
992 *
993 * @beaninfo
994 * hidden: true
995 * description: the RootPane object for this dialog.
996 */
997 protected void setRootPane(JRootPane root) {
998 if(rootPane != null) {
999 remove(rootPane);
1000 }
1001 rootPane = root;
1002 if(rootPane != null) {
1003 boolean checkingEnabled = isRootPaneCheckingEnabled();
1004 try {
1005 setRootPaneCheckingEnabled(false);
1006 add(rootPane, BorderLayout.CENTER);
1007 }
1008 finally {
1009 setRootPaneCheckingEnabled(checkingEnabled);
1010 }
1011 }
1012 }
1013
1014
1015 /**
1016 * Returns the {@code contentPane} object for this dialog.
1017 *
1018 * @return the {@code contentPane} property
1019 *
1020 * @see #setContentPane
1021 * @see RootPaneContainer#getContentPane
1022 */
1023 public Container getContentPane() {
1024 return getRootPane().getContentPane();
1025 }
1026
1027
1028 /**
1029 * Sets the {@code contentPane} property.
1030 * This method is called by the constructor.
1031 * <p>
1032 * Swing's painting architecture requires an opaque {@code JComponent}
1033 * in the containment hierarchy. This is typically provided by the
1034 * content pane. If you replace the content pane it is recommended you
1035 * replace it with an opaque {@code JComponent}.
1036 * @see JRootPane
1037 *
1038 * @param contentPane the {@code contentPane} object for this dialog
1039 *
1040 * @throws java.awt.IllegalComponentStateException (a runtime
1041 * exception) if the content pane parameter is {@code null}
1042 * @see #getContentPane
1043 * @see RootPaneContainer#setContentPane
1044 *
1045 * @beaninfo
1046 * hidden: true
1047 * description: The client area of the dialog where child
1048 * components are normally inserted.
1049 */
1050 public void setContentPane(Container contentPane) {
1051 getRootPane().setContentPane(contentPane);
1052 }
1053
1054 /**
1055 * Returns the {@code layeredPane} object for this dialog.
1056 *
1057 * @return the {@code layeredPane} property
1058 *
1059 * @see #setLayeredPane
1060 * @see RootPaneContainer#getLayeredPane
1061 */
1062 public JLayeredPane getLayeredPane() {
1063 return getRootPane().getLayeredPane();
1064 }
1065
1066 /**
1067 * Sets the {@code layeredPane} property.
1068 * This method is called by the constructor.
1069 *
1070 * @param layeredPane the new {@code layeredPane} property
1071 *
1072 * @throws java.awt.IllegalComponentStateException (a runtime
1073 * exception) if the layered pane parameter is null
1074 * @see #getLayeredPane
1075 * @see RootPaneContainer#setLayeredPane
1076 *
1077 * @beaninfo
1078 * hidden: true
1079 * description: The pane which holds the various dialog layers.
1080 */
1081 public void setLayeredPane(JLayeredPane layeredPane) {
1082 getRootPane().setLayeredPane(layeredPane);
1083 }
1084
1085 /**
1086 * Returns the {@code glassPane} object for this dialog.
1087 *
1088 * @return the {@code glassPane} property
1089 *
1090 * @see #setGlassPane
1091 * @see RootPaneContainer#getGlassPane
1092 */
1093 public Component getGlassPane() {
1094 return getRootPane().getGlassPane();
1095 }
1096
1097 /**
1098 * Sets the {@code glassPane} property.
1099 * This method is called by the constructor.
1100 *
1101 * @param glassPane the {@code glassPane} object for this dialog
1102 * @see #getGlassPane
1103 * @see RootPaneContainer#setGlassPane
1104 *
1105 * @beaninfo
1106 * hidden: true
1107 * description: A transparent pane used for menu rendering.
1108 */
1109 public void setGlassPane(Component glassPane) {
1110 getRootPane().setGlassPane(glassPane);
1111 }
1112
1113 /**
1114 * {@inheritDoc}
1115 *
1116 * @since 1.6
1117 */
1118 public Graphics getGraphics() {
1119 JComponent.getGraphicsInvoked(this);
1120 return super.getGraphics();
1121 }
1122
1123 /**
1124 * Repaints the specified rectangle of this component within
1125 * {@code time} milliseconds. Refer to {@code RepaintManager}
1126 * for details on how the repaint is handled.
1127 *
1128 * @param time maximum time in milliseconds before update
1129 * @param x the <i>x</i> coordinate
1130 * @param y the <i>y</i> coordinate
1131 * @param width the width
1132 * @param height the height
1133 * @see RepaintManager
1134 * @since 1.6
1135 */
1136 public void repaint(long time, int x, int y, int width, int height) {
1137 if (RepaintManager.HANDLE_TOP_LEVEL_PAINT) {
1138 RepaintManager.currentManager(this).addDirtyRegion(
1139 this, x, y, width, height);
1140 }
1141 else {
1142 super.repaint(time, x, y, width, height);
1143 }
1144 }
1145
1146 /**
1147 * Provides a hint as to whether or not newly created {@code JDialog}s
1148 * should have their Window decorations (such as borders, widgets to
1149 * close the window, title...) provided by the current look
1150 * and feel. If {@code defaultLookAndFeelDecorated} is true,
1151 * the current {@code LookAndFeel} supports providing window
1152 * decorations, and the current window manager supports undecorated
1153 * windows, then newly created {@code JDialog}s will have their
1154 * Window decorations provided by the current {@code LookAndFeel}.
1155 * Otherwise, newly created {@code JDialog}s will have their
1156 * Window decorations provided by the current window manager.
1157 * <p>
1158 * You can get the same effect on a single JDialog by doing the following:
1159 * <pre>
1160 * JDialog dialog = new JDialog();
1161 * dialog.setUndecorated(true);
1162 * dialog.getRootPane().setWindowDecorationStyle(JRootPane.PLAIN_DIALOG);
1163 * </pre>
1164 *
1165 * @param defaultLookAndFeelDecorated A hint as to whether or not current
1166 * look and feel should provide window decorations
1167 * @see javax.swing.LookAndFeel#getSupportsWindowDecorations
1168 * @since 1.4
1169 */
1170 public static void setDefaultLookAndFeelDecorated(boolean defaultLookAndFeelDecorated) {
1171 if (defaultLookAndFeelDecorated) {
1172 SwingUtilities.appContextPut(defaultLookAndFeelDecoratedKey, Boolean.TRUE);
1173 } else {
1174 SwingUtilities.appContextPut(defaultLookAndFeelDecoratedKey, Boolean.FALSE);
1175 }
1176 }
1177
1178 /**
1179 * Returns true if newly created {@code JDialog}s should have their
1180 * Window decorations provided by the current look and feel. This is only
1181 * a hint, as certain look and feels may not support this feature.
1182 *
1183 * @return true if look and feel should provide Window decorations.
1184 * @since 1.4
1185 */
1186 public static boolean isDefaultLookAndFeelDecorated() {
1187 Boolean defaultLookAndFeelDecorated =
1188 (Boolean) SwingUtilities.appContextGet(defaultLookAndFeelDecoratedKey);
1189 if (defaultLookAndFeelDecorated == null) {
1190 defaultLookAndFeelDecorated = Boolean.FALSE;
1191 }
1192 return defaultLookAndFeelDecorated.booleanValue();
1193 }
1194
1195 /**
1196 * Returns a string representation of this {@code JDialog}.
1197 * This method
1198 * is intended to be used only for debugging purposes, and the
1199 * content and format of the returned string may vary between
1200 * implementations. The returned string may be empty but may not
1201 * be {@code null}.
1202 *
1203 * @return a string representation of this {@code JDialog}.
1204 */
1205 protected String paramString() {
1206 String defaultCloseOperationString;
1207 if (defaultCloseOperation == HIDE_ON_CLOSE) {
1208 defaultCloseOperationString = "HIDE_ON_CLOSE";
1209 } else if (defaultCloseOperation == DISPOSE_ON_CLOSE) {
1210 defaultCloseOperationString = "DISPOSE_ON_CLOSE";
1211 } else if (defaultCloseOperation == DO_NOTHING_ON_CLOSE) {
1212 defaultCloseOperationString = "DO_NOTHING_ON_CLOSE";
1213 } else defaultCloseOperationString = "";
1214 String rootPaneString = (rootPane != null ?
1215 rootPane.toString() : "");
1216 String rootPaneCheckingEnabledString = (rootPaneCheckingEnabled ?
1217 "true" : "false");
1218
1219 return super.paramString() +
1220 ",defaultCloseOperation=" + defaultCloseOperationString +
1221 ",rootPane=" + rootPaneString +
1222 ",rootPaneCheckingEnabled=" + rootPaneCheckingEnabledString;
1223 }
1224
1225
1226 /////////////////
1227 // Accessibility support
1228 ////////////////
1229
1230 /**
1231 * {@code AccessibleContext} associated with this {@code JDialog}
1232 */
1233 protected AccessibleContext accessibleContext = null;
1234
1235 /**
1236 * Gets the AccessibleContext associated with this JDialog.
1237 * For JDialogs, the AccessibleContext takes the form of an
1238 * AccessibleJDialog.
1239 * A new AccessibleJDialog instance is created if necessary.
1240 *
1241 * @return an AccessibleJDialog that serves as the
1242 * AccessibleContext of this JDialog
1243 */
1244 public AccessibleContext getAccessibleContext() {
1245 if (accessibleContext == null) {
1246 accessibleContext = new AccessibleJDialog();
1247 }
1248 return accessibleContext;
1249 }
1250
1251 /**
1252 * This class implements accessibility support for the
1253 * {@code JDialog} class. It provides an implementation of the
1254 * Java Accessibility API appropriate to dialog user-interface
1255 * elements.
1256 */
1257 protected class AccessibleJDialog extends AccessibleAWTDialog {
1258
1259 // AccessibleContext methods
1260 //
1261 /**
1262 * Get the accessible name of this object.
1263 *
1264 * @return the localized name of the object -- can be null if this
1265 * object does not have a name
1266 */
1267 public String getAccessibleName() {
1268 if (accessibleName != null) {
1269 return accessibleName;
1270 } else {
1271 if (getTitle() == null) {
1272 return super.getAccessibleName();
1273 } else {
1274 return getTitle();
1275 }
1276 }
1277 }
1278
1279 /**
1280 * Get the state of this object.
1281 *
1282 * @return an instance of AccessibleStateSet containing the current
1283 * state set of the object
1284 * @see AccessibleState
1285 */
1286 public AccessibleStateSet getAccessibleStateSet() {
1287 AccessibleStateSet states = super.getAccessibleStateSet();
1288
1289 if (isResizable()) {
1290 states.add(AccessibleState.RESIZABLE);
1291 }
1292 if (getFocusOwner() != null) {
1293 states.add(AccessibleState.ACTIVE);
1294 }
1295 if (isModal()) {
1296 states.add(AccessibleState.MODAL);
1297 }
1298 return states;
1299 }
1300
1301 } // inner class AccessibleJDialog
1302 }