/*

 * Copyright 1997-2008 Sun Microsystems, Inc.  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.  Sun designates this

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

 * by Sun 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,

 * CA 95054 USA or visit www.sun.com if you need additional information or

 * have any questions.

 */

package javax.swing;

import java.awt.BorderLayout;

import java.awt.Component;

import java.awt.Container;

import java.awt.Dialog;

import java.awt.Dimension;

import java.awt.KeyboardFocusManager;

import java.awt.Frame;

import java.awt.Point;

import java.awt.HeadlessException;

import java.awt.Toolkit;

import java.awt.Window;

import java.beans.PropertyChangeEvent;

import java.beans.PropertyChangeListener;

import java.awt.event.WindowListener;

import java.awt.event.WindowAdapter;

import java.awt.event.WindowEvent;

import java.awt.event.ComponentAdapter;

import java.awt.event.ComponentEvent;

import java.io.IOException;

import java.io.ObjectInputStream;

import java.io.ObjectOutputStream;

import java.io.Serializable;

import java.lang.reflect.Method;

import java.lang.reflect.InvocationTargetException;

import java.security.AccessController;

import java.security.PrivilegedAction;

import java.util.Vector;

import javax.swing.plaf.OptionPaneUI;

import javax.swing.event.InternalFrameEvent;

import javax.swing.event.InternalFrameAdapter;

import javax.accessibility.*;

import static javax.swing.ClientPropertyKey.PopupFactory_FORCE_HEAVYWEIGHT_POPUP;

/**

 * <code>JOptionPane</code> makes it easy to pop up a standard dialog box that

 * prompts users for a value or informs them of something.

 * For information about using <code>JOptionPane</code>, see

 * <a

 href="http://java.sun.com/docs/books/tutorial/uiswing/components/dialog.html">How to Make Dialogs</a>,

 * a section in <em>The Java Tutorial</em>.

 *

 * <p>

 *

 * While the <code>JOptionPane</code>

 * class may appear complex because of the large number of methods, almost

 * all uses of this class are one-line calls to one of the static

 * <code>showXxxDialog</code> methods shown below:

 * <blockquote>

 *

 *

 * <table border=1 summary="Common JOptionPane method names and their descriptions">

 * <tr>

 *    <th>Method Name</th>

 *    <th>Description</th>

 * </tr>

 * <tr>

 *    <td>showConfirmDialog</td>

 *    <td>Asks a confirming question, like yes/no/cancel.</td>

 * </tr>

 * <tr>

 *    <td>showInputDialog</td>

 *    <td>Prompt for some input.</td>

 * </tr>

 * <tr>

 *   <td>showMessageDialog</td>

 *   <td>Tell the user about something that has happened.</td>

 * </tr>

 * <tr>

 *   <td>showOptionDialog</td>

 *   <td>The Grand Unification of the above three.</td>

 * </tr>

 * </table>

 *

 * </blockquote>

 * Each of these methods also comes in a <code>showInternalXXX</code>

 * flavor, which uses an internal frame to hold the dialog box (see

 * {@link JInternalFrame}).

 * Multiple convenience methods have also been defined -- overloaded

 * versions of the basic methods that use different parameter lists.

 * <p>

 * All dialogs are modal. Each <code>showXxxDialog</code> method blocks

 * the caller until the user's interaction is complete.

 * <p>

 *

 * <table cellspacing=6 cellpadding=4 border=0 align=right summary="layout">

 * <tr>

 *  <td bgcolor=#FFe0d0 rowspan=2>icon</td>

 *  <td bgcolor=#FFe0d0>message</td>

 * </tr>

 * <tr>

 *  <td bgcolor=#FFe0d0>input value</td>

 * </tr>

 * <tr>

 *   <td bgcolor=#FFe0d0 colspan=2>option buttons</td>

 * </tr>

 * </table>

 *

 * The basic appearance of one of these dialog boxes is generally

 * similar to the picture at the right, although the various

 * look-and-feels are

 * ultimately responsible for the final result.  In particular, the

 * look-and-feels will adjust the layout to accommodate the option pane's

 * <code>ComponentOrientation</code> property.

 * <br clear=all>

 * <p>

 * <b>Parameters:</b><br>

 * The parameters to these methods follow consistent patterns:

 * <blockquote>

 * <dl compact>

 * <dt>parentComponent<dd>

 * Defines the <code>Component</code> that is to be the parent of this

 * dialog box.

 * It is used in two ways: the <code>Frame</code> that contains

 * it is used as the <code>Frame</code>

 * parent for the dialog box, and its screen coordinates are used in

 * the placement of the dialog box. In general, the dialog box is placed

 * just below the component. This parameter may be <code>null</code>,

 * in which case a default <code>Frame</code> is used as the parent,

 * and the dialog will be

 * centered on the screen (depending on the L&F).

 * <dt><a name=message>message</a><dd>

 * A descriptive message to be placed in the dialog box.

 * In the most common usage, message is just a <code>String</code> or

 * <code>String</code> constant.

 * However, the type of this parameter is actually <code>Object</code>. Its

 * interpretation depends on its type:

 * <dl compact>

 * <dt>Object[]<dd>An array of objects is interpreted as a series of

 *                 messages (one per object) arranged in a vertical stack.

 *                 The interpretation is recursive -- each object in the

 *                 array is interpreted according to its type.

 * <dt>Component<dd>The <code>Component</code> is displayed in the dialog.

 * <dt>Icon<dd>The <code>Icon</code> is wrapped in a <code>JLabel</code>

 *               and displayed in the dialog.

 * <dt>others<dd>The object is converted to a <code>String</code> by calling

 *               its <code>toString</code> method. The result is wrapped in a

 *               <code>JLabel</code> and displayed.

 * </dl>

 * <dt>messageType<dd>Defines the style of the message. The Look and Feel

 * manager may lay out the dialog differently depending on this value, and

 * will often provide a default icon. The possible values are:

 * <ul>

 * <li><code>ERROR_MESSAGE</code>

 * <li><code>INFORMATION_MESSAGE</code>

 * <li><code>WARNING_MESSAGE</code>

 * <li><code>QUESTION_MESSAGE</code>

 * <li><code>PLAIN_MESSAGE</code>

 * </ul>

 * <dt>optionType<dd>Defines the set of option buttons that appear at

 * the bottom of the dialog box:

 * <ul>

 * <li><code>DEFAULT_OPTION</code>

 * <li><code>YES_NO_OPTION</code>

 * <li><code>YES_NO_CANCEL_OPTION</code>

 * <li><code>OK_CANCEL_OPTION</code>

 * </ul>

 * You aren't limited to this set of option buttons.  You can provide any

 * buttons you want using the options parameter.

 * <dt>options<dd>A more detailed description of the set of option buttons

 * that will appear at the bottom of the dialog box.

 * The usual value for the options parameter is an array of

 * <code>String</code>s. But

 * the parameter type is an array of <code>Objects</code>.

 * A button is created for each object depending on its type:

 * <dl compact>

 * <dt>Component<dd>The component is added to the button row directly.

 * <dt>Icon<dd>A <code>JButton</code> is created with this as its label.

 * <dt>other<dd>The <code>Object</code> is converted to a string using its

 *              <code>toString</code> method and the result is used to

 *              label a <code>JButton</code>.

 * </dl>

 * <dt>icon<dd>A decorative icon to be placed in the dialog box. A default

 * value for this is determined by the <code>messageType</code> parameter.

 * <dt>title<dd>The title for the dialog box.

 * <dt>initialValue<dd>The default selection (input value).

 * </dl>

 * </blockquote>

 * <p>

 * When the selection is changed, <code>setValue</code> is invoked,

 * which generates a <code>PropertyChangeEvent</code>.

 * <p>

 * If a <code>JOptionPane</code> has configured to all input

 * <code>setWantsInput</code>

 * the bound property <code>JOptionPane.INPUT_VALUE_PROPERTY</code>

 *  can also be listened

 * to, to determine when the user has input or selected a value.

 * <p>

 * When one of the <code>showXxxDialog</code> methods returns an integer,

 * the possible values are:

 * <ul>

 * <li><code>YES_OPTION</code>

 * <li><code>NO_OPTION</code>

 * <li><code>CANCEL_OPTION</code>

 * <li><code>OK_OPTION</code>

 * <li><code>CLOSED_OPTION</code>

 * </ul>

 * <b>Examples:</b>

 * <dl>

 * <dt>Show an error dialog that displays the message, 'alert':

 * <dd><code>

 * JOptionPane.showMessageDialog(null, "alert", "alert", JOptionPane.ERROR_MESSAGE);

 * </code><p>

 * <dt>Show an internal information dialog with the message, 'information':

 * <dd><code>

 * JOptionPane.showInternalMessageDialog(frame, "information",<br>

 *             <ul><ul>"information", JOptionPane.INFORMATION_MESSAGE);</ul></ul>

 * </code><p>

 * <dt>Show an information panel with the options yes/no and message 'choose one':

 * <dd><code>JOptionPane.showConfirmDialog(null,

 *             <ul><ul>"choose one", "choose one", JOptionPane.YES_NO_OPTION);</ul></ul>

 * </code><p>

 * <dt>Show an internal information dialog with the options yes/no/cancel and

 * message 'please choose one' and title information:

 * <dd><code>JOptionPane.showInternalConfirmDialog(frame,

 *             <ul><ul>"please choose one", "information",</ul></ul>

 *             <ul><ul>JOptionPane.YES_NO_CANCEL_OPTION, JOptionPane.INFORMATION_MESSAGE);</ul></ul>

 * </code><p>

 * <dt>Show a warning dialog with the options OK, CANCEL, title 'Warning', and

 * message 'Click OK to continue':

 * <dd><code>

 * Object[] options = { "OK", "CANCEL" };<br>

 * JOptionPane.showOptionDialog(null, "Click OK to continue", "Warning",

 *             <ul><ul>JOptionPane.DEFAULT_OPTION, JOptionPane.WARNING_MESSAGE,</ul></ul>

 *             <ul><ul>null, options, options[0]);</ul></ul>

 * </code><p>

 * <dt>Show a dialog asking the user to type in a String:

 * <dd><code>

 * String inputValue = JOptionPane.showInputDialog("Please input a value");

 * </code><p>

 * <dt>Show a dialog asking the user to select a String:

 * <dd><code>

 * Object[] possibleValues = { "First", "Second", "Third" };<br>

 * Object selectedValue = JOptionPane.showInputDialog(null,

 *             <ul><ul>"Choose one", "Input",</ul></ul>

 *             <ul><ul>JOptionPane.INFORMATION_MESSAGE, null,</ul></ul>

 *             <ul><ul>possibleValues, possibleValues[0]);</ul></ul>

 * </code><p>

 * </dl>

 * <b>Direct Use:</b><br>

 * To create and use an <code>JOptionPane</code> directly, the

 * standard pattern is roughly as follows:

 * <pre>

 *     JOptionPane pane = new JOptionPane(<i>arguments</i>);

 *     pane.set<i>.Xxxx(...); // Configure</i>

 *     JDialog dialog = pane.createDialog(<i>parentComponent, title</i>);

 *     dialog.show();

 *     Object selectedValue = pane.getValue();

 *     if(selectedValue == null)

 *       return CLOSED_OPTION;

 *     <i>//If there is <b>not</b> an array of option buttons:</i>

 *     if(options == null) {

 *       if(selectedValue instanceof Integer)

 *          return ((Integer)selectedValue).intValue();

 *       return CLOSED_OPTION;

 *     }

 *     <i>//If there is an array of option buttons:</i>

 *     for(int counter = 0, maxCounter = options.length;

 *        counter < maxCounter; counter++) {

 *        if(options[counter].equals(selectedValue))

 *        return counter;

 *     }

 *     return CLOSED_OPTION;

 * </pre>

 * <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<sup><font size="-2">TM</font></sup>

 * has been added to the <code>java.beans</code> package.

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

 *

 * @see JInternalFrame

 *

 * @beaninfo

 *      attribute: isContainer true

 *    description: A component which implements standard dialog box controls.

 *

 * @author James Gosling

 * @author Scott Violet

 */

public class JOptionPane extends JComponent implements Accessible

{

    /**

     * @see #getUIClassID

     * @see #readObject

     */

    private static final String uiClassID = "OptionPaneUI";

    /**

     * Indicates that the user has not yet selected a value.

     */

    public static final Object      UNINITIALIZED_VALUE = "uninitializedValue";

    //

    // Option types

    //

    /**

     * Type meaning Look and Feel should not supply any options -- only

     * use the options from the <code>JOptionPane</code>.

     */

    public static final int         DEFAULT_OPTION = -1;

    /** Type used for <code>showConfirmDialog</code>. */

    public static final int         YES_NO_OPTION = 0;

    /** Type used for <code>showConfirmDialog</code>. */

    public static final int         YES_NO_CANCEL_OPTION = 1;

    /** Type used for <code>showConfirmDialog</code>. */

    public static final int         OK_CANCEL_OPTION = 2;

    //

    // Return values.

    //

    /** Return value from class method if YES is chosen. */

    public static final int         YES_OPTION = 0;

    /** Return value from class method if NO is chosen. */

    public static final int         NO_OPTION = 1;

    /** Return value from class method if CANCEL is chosen. */

    public static final int         CANCEL_OPTION = 2;

    /** Return value form class method if OK is chosen. */

    public static final int         OK_OPTION = 0;

    /** Return value from class method if user closes window without selecting

     * anything, more than likely this should be treated as either a

     * <code>CANCEL_OPTION</code> or <code>NO_OPTION</code>. */

    public static final int         CLOSED_OPTION = -1;

    //

    // Message types. Used by the UI to determine what icon to display,

    // and possibly what behavior to give based on the type.

    //

    /** Used for error messages. */

    public static final int  ERROR_MESSAGE = 0;

    /** Used for information messages. */

    public static final int  INFORMATION_MESSAGE = 1;

    /** Used for warning messages. */

    public static final int  WARNING_MESSAGE = 2;

    /** Used for questions. */

    public static final int  QUESTION_MESSAGE = 3;

    /** No icon is used. */

    public static final int   PLAIN_MESSAGE = -1;

    /** Bound property name for <code>icon</code>. */

    public static final String      ICON_PROPERTY = "icon";

    /** Bound property name for <code>message</code>. */

    public static final String      MESSAGE_PROPERTY = "message";

    /** Bound property name for <code>value</code>. */

    public static final String      VALUE_PROPERTY = "value";

    /** Bound property name for <code>option</code>. */

    public static final String      OPTIONS_PROPERTY = "options";

    /** Bound property name for <code>initialValue</code>. */

    public static final String      INITIAL_VALUE_PROPERTY = "initialValue";

    /** Bound property name for <code>type</code>. */

    public static final String      MESSAGE_TYPE_PROPERTY = "messageType";

    /** Bound property name for <code>optionType</code>. */

    public static final String      OPTION_TYPE_PROPERTY = "optionType";

    /** Bound property name for <code>selectionValues</code>. */

    public static final String      SELECTION_VALUES_PROPERTY = "selectionValues";

    /** Bound property name for <code>initialSelectionValue</code>. */

    public static final String      INITIAL_SELECTION_VALUE_PROPERTY = "initialSelectionValue";

    /** Bound property name for <code>inputValue</code>. */

    public static final String      INPUT_VALUE_PROPERTY = "inputValue";

    /** Bound property name for <code>wantsInput</code>. */

    public static final String      WANTS_INPUT_PROPERTY = "wantsInput";

    /** Icon used in pane. */

    transient protected Icon                  icon;

    /** Message to display. */

    transient protected Object                message;

    /** Options to display to the user. */

    transient protected Object[]              options;

    /** Value that should be initially selected in <code>options</code>. */

    transient protected Object                initialValue;

    /** Message type. */

    protected int                   messageType;

    /**

     * Option type, one of <code>DEFAULT_OPTION</code>,

     * <code>YES_NO_OPTION</code>,

     * <code>YES_NO_CANCEL_OPTION</code> or

     * <code>OK_CANCEL_OPTION</code>.

     */

    protected int                   optionType;

    /** Currently selected value, will be a valid option, or

     * <code>UNINITIALIZED_VALUE</code> or <code>null</code>. */

    transient protected Object                value;

    /** Array of values the user can choose from. Look and feel will

     * provide the UI component to choose this from. */

    protected transient Object[]              selectionValues;

    /** Value the user has input. */

    protected transient Object                inputValue;

    /** Initial value to select in <code>selectionValues</code>. */

    protected transient Object                initialSelectionValue;

    /** If true, a UI widget will be provided to the user to get input. */

    protected boolean                         wantsInput;

    /**

     * Shows a question-message dialog requesting input from the user. The

     * dialog uses the default frame, which usually means it is centered on

     * the screen.

     *

     * @param message the <code>Object</code> to display

     * @exception HeadlessException if

     *   <code>GraphicsEnvironment.isHeadless</code> returns

     *   <code>true</code>

     * @see java.awt.GraphicsEnvironment#isHeadless

     */

    public static String showInputDialog(Object message)

        throws HeadlessException {

        return showInputDialog(null, message);

    }

    /**

     * Shows a question-message dialog requesting input from the user, with

     * the input value initialized to <code>initialSelectionValue</code>. The

     * dialog uses the default frame, which usually means it is centered on

     * the screen.

     *

     * @param message the <code>Object</code> to display

     * @param initialSelectionValue the value used to initialize the input

     *                 field

     * @since 1.4

     */

    public static String showInputDialog(Object message, Object initialSelectionValue) {

        return showInputDialog(null, message, initialSelectionValue);

    }

    /**

     * Shows a question-message dialog requesting input from the user

     * parented to <code>parentComponent</code>.

     * The dialog is displayed on top of the <code>Component</code>'s

     * frame, and is usually positioned below the <code>Component</code>.

     *

     * @param parentComponent  the parent <code>Component</code> for the

     *          dialog

     * @param message  the <code>Object</code> to display

     * @exception HeadlessException if

     *    <code>GraphicsEnvironment.isHeadless</code> returns

     *    <code>true</code>

     * @see java.awt.GraphicsEnvironment#isHeadless

     */

    public static String showInputDialog(Component parentComponent,

        Object message) throws HeadlessException {

        return showInputDialog(parentComponent, message, UIManager.getString(

            "OptionPane.inputDialogTitle", parentComponent), QUESTION_MESSAGE);

    }

    /**

     * Shows a question-message dialog requesting input from the user and

     * parented to <code>parentComponent</code>. The input value will be

     * initialized to <code>initialSelectionValue</code>.

     * The dialog is displayed on top of the <code>Component</code>'s

     * frame, and is usually positioned below the <code>Component</code>.

     *

     * @param parentComponent  the parent <code>Component</code> for the

     *          dialog

     * @param message the <code>Object</code> to display

     * @param initialSelectionValue the value used to initialize the input

     *                 field

     * @since 1.4

     */

    public static String showInputDialog(Component parentComponent, Object message,

                                         Object initialSelectionValue) {

        return (String)showInputDialog(parentComponent, message,

                      UIManager.getString("OptionPane.inputDialogTitle",

                      parentComponent), QUESTION_MESSAGE, null, null,

                      initialSelectionValue);

    }

    /**

     * Shows a dialog requesting input from the user parented to

     * <code>parentComponent</code> with the dialog having the title

     * <code>title</code> and message type <code>messageType</code>.

     *

     * @param parentComponent  the parent <code>Component</code> for the

     *                  dialog

     * @param message  the <code>Object</code> to display

     * @param title    the <code>String</code> to display in the dialog

     *                  title bar

     * @param messageType the type of message that is to be displayed:

     *                  <code>ERROR_MESSAGE</code>,

     *                  <code>INFORMATION_MESSAGE</code>,

     *                  <code>WARNING_MESSAGE</code>,

     *                  <code>QUESTION_MESSAGE</code>,

     *                  or <code>PLAIN_MESSAGE</code>

     * @exception HeadlessException if

     *   <code>GraphicsEnvironment.isHeadless</code> returns

     *   <code>true</code>

     * @see java.awt.GraphicsEnvironment#isHeadless

     */

    public static String showInputDialog(Component parentComponent,

        Object message, String title, int messageType)

        throws HeadlessException {

        return (String)showInputDialog(parentComponent, message, title,

                                       messageType, null, null, null);

    }