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