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