/*

 * Copyright (c) 1997, 2010, Oracle and/or its affiliates. All rights reserved.

 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

 *

 * This code is free software; you can redistribute it and/or modify it

 * under the terms of the GNU General Public License version 2 only, as

 * published by the Free Software Foundation.  Oracle designates this

 * particular file as subject to the "Classpath" exception as provided

 * by Oracle in the LICENSE file that accompanied this code.

 *

 * This code is distributed in the hope that it will be useful, but WITHOUT

 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

 * version 2 for more details (a copy is included in the LICENSE file that

 * accompanied this code).

 *

 * You should have received a copy of the GNU General Public License version

 * 2 along with this work; if not, write to the Free Software Foundation,

 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

 *

 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

 * or visit www.oracle.com if you need additional information or have any

 * questions.

 */

package javax.swing;

import java.awt.*;

import java.awt.event.*;

import javax.accessibility.*;

/**

 * The main class for creating a dialog window. You can use this class

 * to create a custom dialog, or invoke the many class methods

 * in {@link JOptionPane} to create a variety of standard dialogs.

 * For information about creating dialogs, see

 * <em>The Java Tutorial</em> section

 * <a

 href="http://docs.oracle.com/javase/tutorial/uiswing/components/dialog.html">How

 * to Make Dialogs</a>.

 *

 * <p>

 *

 * The {@code JDialog} component contains a {@code JRootPane}

 * as its only child.

 * The {@code contentPane} should be the parent of any children of the

 * {@code JDialog}.

 * <pre>

 *       dialog.add(child);

 * </pre>

 * And the child will be added to the contentPane.

 * The {@code contentPane} is always non-{@code null}.

 * Attempting to set it to {@code null} generates an exception.

 * The default {@code contentPane} has a {@code BorderLayout}

 * manager set on it.

 * Refer to {@link javax.swing.RootPaneContainer}

 * for details on adding, removing and setting the {@code LayoutManager}

 * of a {@code JDialog}.

 * <p>

 * Please see the {@code JRootPane} documentation for a complete

 * description of the {@code contentPane}, {@code glassPane},

 * and {@code layeredPane} components.

 * <p>

 * In a multi-screen environment, you can create a {@code JDialog}

 * on a different screen device than its owner.  See {@link java.awt.Frame} for

 * more information.

 * <p>

 * <strong>Warning:</strong> Swing is not thread safe. For more

 * information see <a

 * href="package-summary.html#threading">Swing's Threading

 * Policy</a>.

 * <p>

 * <strong>Warning:</strong>

 * Serialized objects of this class will not be compatible with

 * future Swing releases. The current serialization support is

 * appropriate for short term storage or RMI between applications running

 * the same version of Swing.  As of 1.4, support for long term storage

 * of all JavaBeans™

 * has been added to the {@code java.beans} package.

 * Please see {@link java.beans.XMLEncoder}.

 *

 * @see JOptionPane

 * @see JRootPane

 * @see javax.swing.RootPaneContainer

 *

 * @beaninfo

 *      attribute: isContainer true

 *      attribute: containerDelegate getContentPane

 *    description: A toplevel window for creating dialog boxes.

 *

 * @author David Kloba

 * @author James Gosling

 * @author Scott Violet

 */

public class JDialog extends Dialog implements WindowConstants,

                                               Accessible,

                                               RootPaneContainer,

                               TransferHandler.HasGetTransferHandler

{

    /**

     * Key into the AppContext, used to check if should provide decorations

     * by default.

     */

    private static final Object defaultLookAndFeelDecoratedKey =

            new StringBuffer("JDialog.defaultLookAndFeelDecorated");

    private int defaultCloseOperation = HIDE_ON_CLOSE;

    /**

     * @see #getRootPane

     * @see #setRootPane

     */

    protected JRootPane rootPane;

    /**

     * If true then calls to {@code add} and {@code setLayout}

     * will be forwarded to the {@code contentPane}. This is initially

     * false, but is set to true when the {@code JDialog} is constructed.

     *

     * @see #isRootPaneCheckingEnabled

     * @see #setRootPaneCheckingEnabled

     * @see javax.swing.RootPaneContainer

     */

    protected boolean rootPaneCheckingEnabled = false;

    /**

     * The {@code TransferHandler} for this dialog.

     */

    private TransferHandler transferHandler;

    /**

     * Creates a modeless dialog without a title and without a specified

     * {@code Frame} owner.  A shared, hidden frame will be

     * set as the owner of the dialog.

     * <p>

     * This constructor sets the component's locale property to the value

     * returned by {@code JComponent.getDefaultLocale}.

     * <p>

     * NOTE: This constructor does not allow you to create an unowned

     * {@code JDialog}. To create an unowned {@code JDialog}

     * you must use either the {@code JDialog(Window)} or

     * {@code JDialog(Dialog)} constructor with an argument of

     * {@code null}.

     *

     * @throws HeadlessException if {@code GraphicsEnvironment.isHeadless()}

     *     returns {@code true}.

     * @see java.awt.GraphicsEnvironment#isHeadless

     * @see JComponent#getDefaultLocale

     */

    public JDialog() {

        this((Frame)null, false);

    }

    /**

     * Creates a modeless dialog with the specified {@code Frame}

     * as its owner and an empty title. If {@code owner}

     * is {@code null}, a shared, hidden frame will be set as the

     * owner of the dialog.

     * <p>

     * This constructor sets the component's locale property to the value

     * returned by {@code JComponent.getDefaultLocale}.

     * <p>

     * NOTE: This constructor does not allow you to create an unowned

     * {@code JDialog}. To create an unowned {@code JDialog}

     * you must use either the {@code JDialog(Window)} or

     * {@code JDialog(Dialog)} constructor with an argument of

     * {@code null}.

     *

     * @param owner the {@code Frame} from which the dialog is displayed

     * @throws HeadlessException if {@code GraphicsEnvironment.isHeadless()}

     *     returns {@code true}.

     * @see java.awt.GraphicsEnvironment#isHeadless

     * @see JComponent#getDefaultLocale

     */

    public JDialog(Frame owner) {

        this(owner, false);

    }

    /**

     * Creates a dialog with an empty title and the specified modality and

     * {@code Frame} as its owner. If {@code owner} is {@code null},

     * a shared, hidden frame will be set as the owner of the dialog.

     * <p>

     * This constructor sets the component's locale property to the value

     * returned by {@code JComponent.getDefaultLocale}.

     * <p>

     * NOTE: This constructor does not allow you to create an unowned

     * {@code JDialog}. To create an unowned {@code JDialog}

     * you must use either the {@code JDialog(Window)} or

     * {@code JDialog(Dialog)} constructor with an argument of

     * {@code null}.

     *

     * @param owner the {@code Frame} from which the dialog is displayed

     * @param modal specifies whether dialog blocks user input to other top-level

     *     windows when shown. If {@code true}, the modality type property is set to

     *     {@code DEFAULT_MODALITY_TYPE}, otherwise the dialog is modeless.

     * @throws HeadlessException if {@code GraphicsEnvironment.isHeadless()}

     *     returns {@code true}.

     * @see java.awt.GraphicsEnvironment#isHeadless

     * @see JComponent#getDefaultLocale

     */

    public JDialog(Frame owner, boolean modal) {

        this(owner, "", modal);

    }

    /**

     * Creates a modeless dialog with the specified title and

     * with the specified owner frame.  If {@code owner}

     * is {@code null}, a shared, hidden frame will be set as the

     * owner of the dialog.

     * <p>

     * This constructor sets the component's locale property to the value

     * returned by {@code JComponent.getDefaultLocale}.

     * <p>

     * NOTE: This constructor does not allow you to create an unowned

     * {@code JDialog}. To create an unowned {@code JDialog}

     * you must use either the {@code JDialog(Window)} or

     * {@code JDialog(Dialog)} constructor with an argument of

     * {@code null}.

     *

     * @param owner the {@code Frame} from which the dialog is displayed

     * @param title  the {@code String} to display in the dialog's

     *                  title bar

     * @throws HeadlessException if {@code GraphicsEnvironment.isHeadless()}

     *     returns {@code true}.

     * @see java.awt.GraphicsEnvironment#isHeadless

     * @see JComponent#getDefaultLocale

     */

    public JDialog(Frame owner, String title) {

        this(owner, title, false);

    }

    /**

     * Creates a dialog with the specified title, owner {@code Frame}

     * and modality. If {@code owner} is {@code null},

     * a shared, hidden frame will be set as the owner of this dialog.

     * <p>

     * This constructor sets the component's locale property to the value

     * returned by {@code JComponent.getDefaultLocale}.

     * <p>

     * NOTE: Any popup components ({@code JComboBox},

     * {@code JPopupMenu}, {@code JMenuBar})

     * created within a modal dialog will be forced to be lightweight.

     * <p>

     * NOTE: This constructor does not allow you to create an unowned

     * {@code JDialog}. To create an unowned {@code JDialog}

     * you must use either the {@code JDialog(Window)} or

     * {@code JDialog(Dialog)} constructor with an argument of

     * {@code null}.

     *

     * @param owner the {@code Frame} from which the dialog is displayed

     * @param title  the {@code String} to display in the dialog's

     *     title bar

     * @param modal specifies whether dialog blocks user input to other top-level

     *     windows when shown. If {@code true}, the modality type property is set to

     *     {@code DEFAULT_MODALITY_TYPE} otherwise the dialog is modeless

     * @throws HeadlessException if {@code GraphicsEnvironment.isHeadless()}

     *     returns {@code true}.

     *

     * @see java.awt.Dialog.ModalityType

     * @see java.awt.Dialog.ModalityType#MODELESS

     * @see java.awt.Dialog#DEFAULT_MODALITY_TYPE

     * @see java.awt.Dialog#setModal

     * @see java.awt.Dialog#setModalityType

     * @see java.awt.GraphicsEnvironment#isHeadless

     * @see JComponent#getDefaultLocale

     */

    public JDialog(Frame owner, String title, boolean modal) {

        super(owner == null? SwingUtilities.getSharedOwnerFrame() : owner,

              title, modal);

        if (owner == null) {

            WindowListener ownerShutdownListener =

                    SwingUtilities.getSharedOwnerFrameShutdownListener();

            addWindowListener(ownerShutdownListener);

        }

        dialogInit();

    }

    /**

     * Creates a dialog with the specified title,

     * owner {@code Frame}, modality and {@code GraphicsConfiguration}.

     * If {@code owner} is {@code null},

     * a shared, hidden frame will be set as the owner of this dialog.

     * <p>

     * This constructor sets the component's locale property to the value

     * returned by {@code JComponent.getDefaultLocale}.

     * <p>

     * NOTE: Any popup components ({@code JComboBox},

     * {@code JPopupMenu}, {@code JMenuBar})

     * created within a modal dialog will be forced to be lightweight.

     * <p>

     * NOTE: This constructor does not allow you to create an unowned

     * {@code JDialog}. To create an unowned {@code JDialog}

     * you must use either the {@code JDialog(Window)} or

     * {@code JDialog(Dialog)} constructor with an argument of

     * {@code null}.

     *

     * @param owner the {@code Frame} from which the dialog is displayed

     * @param title  the {@code String} to display in the dialog's

     *     title bar

     * @param modal specifies whether dialog blocks user input to other top-level

     *     windows when shown. If {@code true}, the modality type property is set to

     *     {@code DEFAULT_MODALITY_TYPE}, otherwise the dialog is modeless.

     * @param gc the {@code GraphicsConfiguration} of the target screen device;

     *     if {@code null}, the default system {@code GraphicsConfiguration}

     *     is assumed

     * @throws HeadlessException if {@code GraphicsEnvironment.isHeadless()}

     *     returns {@code true}.

     * @see java.awt.Dialog.ModalityType

     * @see java.awt.Dialog.ModalityType#MODELESS

     * @see java.awt.Dialog#DEFAULT_MODALITY_TYPE

     * @see java.awt.Dialog#setModal

     * @see java.awt.Dialog#setModalityType

     * @see java.awt.GraphicsEnvironment#isHeadless

     * @see JComponent#getDefaultLocale

     * @since 1.4

     */

    public JDialog(Frame owner, String title, boolean modal,

                   GraphicsConfiguration gc) {

        super(owner == null? SwingUtilities.getSharedOwnerFrame() : owner,

              title, modal, gc);

        if (owner == null) {

            WindowListener ownerShutdownListener =

                    SwingUtilities.getSharedOwnerFrameShutdownListener();

            addWindowListener(ownerShutdownListener);

        }

        dialogInit();

    }

    /**

     * Creates a modeless dialog with the specified {@code Dialog}

     * as its owner and an empty title.

     * <p>

     * This constructor sets the component's locale property to the value

     * returned by {@code JComponent.getDefaultLocale}.

     *

     * @param owner the owner {@code Dialog} from which the dialog is displayed

     *     or {@code null} if this dialog has no owner

     * @throws HeadlessException {@code if GraphicsEnvironment.isHeadless()}

     *     returns {@code true}.

     * @see java.awt.GraphicsEnvironment#isHeadless

     * @see JComponent#getDefaultLocale

     */

    public JDialog(Dialog owner) {

        this(owner, false);

    }

    /**

     * Creates a dialog with an empty title and the specified modality and

     * {@code Dialog} as its owner.

     * <p>

     * This constructor sets the component's locale property to the value

     * returned by {@code JComponent.getDefaultLocale}.

     *

     * @param owner the owner {@code Dialog} from which the dialog is displayed

     *     or {@code null} if this dialog has no owner

     * @param modal specifies whether dialog blocks user input to other top-level

     *     windows when shown. If {@code true}, the modality type property is set to

     *     {@code DEFAULT_MODALITY_TYPE}, otherwise the dialog is modeless.

     * @throws HeadlessException if {@code GraphicsEnvironment.isHeadless()}

     *     returns {@code true}.

     * @see java.awt.Dialog.ModalityType

     * @see java.awt.Dialog.ModalityType#MODELESS

     * @see java.awt.Dialog#DEFAULT_MODALITY_TYPE

     * @see java.awt.Dialog#setModal

     * @see java.awt.Dialog#setModalityType

     * @see java.awt.GraphicsEnvironment#isHeadless

     * @see JComponent#getDefaultLocale

     */

    public JDialog(Dialog owner, boolean modal) {

        this(owner, "", modal);

    }

    /**

     * Creates a modeless dialog with the specified title and

     * with the specified owner dialog.

     * <p>

     * This constructor sets the component's locale property to the value

     * returned by {@code JComponent.getDefaultLocale}.

     *

     * @param owner the owner {@code Dialog} from which the dialog is displayed

     *     or {@code null} if this dialog has no owner

     * @param title  the {@code String} to display in the dialog's

     *                  title bar

     * @throws HeadlessException if {@code GraphicsEnvironment.isHeadless()}

     *     returns {@code true}.

     * @see java.awt.GraphicsEnvironment#isHeadless

     * @see JComponent#getDefaultLocale

     */

    public JDialog(Dialog owner, String title) {

        this(owner, title, false);

    }

    /**

     * Creates a dialog with the specified title, modality

     * and the specified owner {@code Dialog}.

     * <p>

     * This constructor sets the component's locale property to the value

     * returned by {@code JComponent.getDefaultLocale}.

     *

     * @param owner the owner {@code Dialog} from which the dialog is displayed

     *     or {@code null} if this dialog has no owner

     * @param title  the {@code String} to display in the dialog's

     *     title bar

     * @param modal specifies whether dialog blocks user input to other top-level

     *     windows when shown. If {@code true}, the modality type property is set to

     *     {@code DEFAULT_MODALITY_TYPE}, otherwise the dialog is modeless

     * @throws HeadlessException if {@code GraphicsEnvironment.isHeadless()}

     *     returns {@code true}.

     * @see java.awt.Dialog.ModalityType

     * @see java.awt.Dialog.ModalityType#MODELESS

     * @see java.awt.Dialog#DEFAULT_MODALITY_TYPE

     * @see java.awt.Dialog#setModal

     * @see java.awt.Dialog#setModalityType

     * @see java.awt.GraphicsEnvironment#isHeadless

     * @see JComponent#getDefaultLocale

     */

    public JDialog(Dialog owner, String title, boolean modal) {

        super(owner, title, modal);

        dialogInit();

    }

    /**

     * Creates a dialog with the specified title, owner {@code Dialog},

     * modality and {@code GraphicsConfiguration}.

     *

     * <p>

     * NOTE: Any popup components ({@code JComboBox},

     * {@code JPopupMenu}, {@code JMenuBar})

     * created within a modal dialog will be forced to be lightweight.

     * <p>

     * This constructor sets the component's locale property to the value

     * returned by {@code JComponent.getDefaultLocale}.

     *

     * @param owner the owner {@code Dialog} from which the dialog is displayed

     *     or {@code null} if this dialog has no owner

     * @param title  the {@code String} to display in the dialog's

     *     title bar

     * @param modal specifies whether dialog blocks user input to other top-level

     *     windows when shown. If {@code true}, the modality type property is set to

     *     {@code DEFAULT_MODALITY_TYPE}, otherwise the dialog is modeless

     * @param gc the {@code GraphicsConfiguration} of the target screen device;

     *     if {@code null}, the default system {@code GraphicsConfiguration}

     *     is assumed

     * @throws HeadlessException if {@code GraphicsEnvironment.isHeadless()}

     *     returns {@code true}.

     * @see java.awt.Dialog.ModalityType

     * @see java.awt.Dialog.ModalityType#MODELESS

     * @see java.awt.Dialog#DEFAULT_MODALITY_TYPE

     * @see java.awt.Dialog#setModal

     * @see java.awt.Dialog#setModalityType

     * @see java.awt.GraphicsEnvironment#isHeadless

     * @see JComponent#getDefaultLocale

     * @since 1.4

     */

    public JDialog(Dialog owner, String title, boolean modal,

                   GraphicsConfiguration gc) {

        super(owner, title, modal, gc);

        dialogInit();

    }

    /**

     * Creates a modeless dialog with the specified {@code Window}

     * as its owner and an empty title.

     * <p>

     * This constructor sets the component's locale property to the value

     * returned by {@code JComponent.getDefaultLocale}.

     *

     * @param owner the {@code Window} from which the dialog is displayed or

     *     {@code null} if this dialog has no owner

     *

     * @throws IllegalArgumentException

     *     if the {@code owner} is not an instance of {@link java.awt.Dialog Dialog}

     *     or {@link java.awt.Frame Frame}

     * @throws IllegalArgumentException

     *     if the {@code owner}'s {@code GraphicsConfiguration} is not from a screen device

     * @throws HeadlessException

     *     when {@code GraphicsEnvironment.isHeadless()} returns {@code true}

     *

     * @see java.awt.GraphicsEnvironment#isHeadless

     * @see JComponent#getDefaultLocale

     *

     * @since 1.6

     */

    public JDialog(Window owner) {

        this(owner, Dialog.ModalityType.MODELESS);

    }

    /**

     * Creates a dialog with an empty title and the specified modality and

     * {@code Window} as its owner.

     * <p>

     * This constructor sets the component's locale property to the value

     * returned by {@code JComponent.getDefaultLocale}.

     *

     * @param owner the {@code Window} from which the dialog is displayed or

     *     {@code null} if this dialog has no owner

     * @param modalityType specifies whether dialog blocks input to other

     *     windows when shown. {@code null} value and unsupported modality

     *     types are equivalent to {@code MODELESS}

     *

     * @throws IllegalArgumentException

     *     if the {@code owner} is not an instance of {@link java.awt.Dialog Dialog}