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