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