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