dialog.html

jsf、swing的官方指南

    null,
    options,
    options[2]);
</pre>
</td>
</tr>
</table>

<dt> <strong><code>JOptionPane</code> (constructor)</strong>
<dd> Creates a <code>JOptionPane</code> with the specified buttons, 
     icons, message, title, and so on.
     You must then add the option pane to a <code>JDialog</code>,
     register a property-change listener on the option pane,
     and show the dialog.
     See <a href="#stayup">Stopping Automatic Dialog Closing</a>
     for details.
<p>
<table summary="layout">
<tr>
<td valign=top>
<IMG SRC="../../figures/uiswing/components/JOptionPaneMetal.png" WIDTH="280" HEIGHT="145" ALT="Explicitly used the JOptionPane constructor"></td>
</tr>
<tr>
<td valign=top>
<pre>
final JOptionPane optionPane = new JOptionPane(
    "The only way to close this dialog is by\n"
    + "pressing one of the following buttons.\n"
    + "Do you understand?",
    JOptionPane.QUESTION_MESSAGE,
    JOptionPane.YES_NO_OPTION);</pre></td></td>
</td>
</tr></table>
</dl>

The arguments to all of the <code>show<em>Xxx</em>Dialog</code>
methods and <code>JOptionPane</code> constructors are standardized,
though the number of arguments for each method and constructor varies.
The following list describes each argument.
To see the exact list of arguments for a particular method, see
<a href="#api">The Dialog API</a>.

<dl>
<dt> <code>Component <em>parentComponent</em></code>
<dd> The first argument to each <code>show<em>Xxx</em>Dialog</code> method
     is always the parent component,
     which must be a frame, a component inside a frame, or null.
     If you specify a frame, 
     then the dialog will appear over the center of the frame,
     and depend on that frame.
     If you specify a component inside a frame,
     then the dialog will appear over the center of that component,
     and depend on that component's frame.
     If you specify null, 
     then the look and feel picks an appropriate position for the dialog
     &#151; generally the center of the screen &#151;
     and the dialog doesn't depend on any visible frame.
<p>
     The <code>JOptionPane</code> constructors do not 
     include this argument.
     Instead, you specify the parent frame
     when you create the <code>JDialog</code>
     that contains the <code>JOptionPane</code>,
     and you use the <code>JDialog</code> <code>setLocationRelativeTo</code>
     method to set the dialog's position.
<dt> <code>Object <em>message</em></code>
<dd> This required argument specifies 
     what the dialog should display in its main area.
     Generally, you specify a string, 
     which results the dialog displaying a label with the specified text.
     You can split the message over several lines
     by putting newline (<code>\n</code>) characters 
     inside the message string.
     For example:

<blockquote><pre>
"Complete the sentence:\n \"Green eggs and...\""
</pre></blockquote>

<dt> <code>String <em>title</em></code>
<dd> The title of the dialog.

<dt> <code>int <em>optionType</em></code>
<dd> Specifies the set of buttons that appear at the bottom of the dialog.
     Choose from one of the following standard sets:
     <code>DEFAULT_OPTION</code>,
     <code>YES_NO_OPTION</code>,
     <code>YES_NO_CANCEL_OPTION</code>,
     <code>OK_CANCEL_OPTION</code>.

<dt> <code>int <em>messageType</em></code>
<dd> This argument determines the icon
     displayed in the dialog.
     Choose from one of the following values:
     <code>PLAIN_MESSAGE</code> (no icon),
     <code>ERROR_MESSAGE</code>,
     <code>INFORMATION_MESSAGE</code>,
     <code>WARNING_MESSAGE</code>,
     <code>QUESTION_MESSAGE</code>. 

<dt> <code>Icon <em>icon</em></code>
<dd> The icon to display in the dialog.

<dt> <code>Object[] <em>options</em></code>
<dd> Generally used to specify the string displayed
     by each button at the bottom of the dialog.
     See <a href="#button">Customizing Button Text in a Standard Dialog</a>
     for more information.
     Can also be used to specify icons to be displayed by the buttons
     or non-button components to be added to the button row.

<dt> <code>Object <em>initialValue</em></code>
<dd> Specifies the default value to be selected.
</dl>

<p>


You can either let the option pane display its default icon 
or specify the icon using the message type
or icon argument.
By default, an option pane created with <code>showMessageDialog</code>
displays the information icon,
one created with <code>showConfirmDialog</code>
or <code>showInputDialog</code>
displays the question icon,
and one created with a <code>JOptionPane</code> constructor
displays no icon.
To specify that the dialog display a standard icon or no icon,
specify the message type corresponding to the icon you desire.
To specify a custom icon, use the icon argument.
The icon argument takes precedence over the message type;
as long as the icon argument has a non-null value,
the dialog displays the specified icon.


</blockquote>
<h3>
<a name="button">Customizing Button Text</a>
</h3>
<blockquote>

When you use <code>JOptionPane</code> to create a dialog,
you can either use the standard button text
(which might vary by look and feel and locale)
or specify different text.
Either way,
the option pane type
determines how many buttons appear.
For example, <code>YES_NO_OPTION</code> dialogs
always have exactly two buttons,
and <code>YES_NO_CANCEL_OPTION</code> dialogs
have three buttons.

<p>

The following code, taken from 

<a class="SourceLink" target="_blank" href="examples/DialogDemo.java"><code>DialogDemo.java</code></a>,
creates two Yes/No dialogs.
The first dialog is implemented with <code>showConfirmDialog</code>,
which uses the look-and-feel wording
for the two buttons.
The second dialog 
uses <code>showOptionDialog</code>
so it can customize the wording.
With the exception of wording changes,
the dialogs are identical.

<p>
<table summary="layout">
<tr>
<td valign=top>
<IMG SRC="../../figures/uiswing/components/CustomizingButtonTextMetal.png" WIDTH="277" HEIGHT="122" ALT="A yes/no dialog, in those words [but perhaps translated]"></td>
<td valign=top>
<pre>
//default icon, custom title
int n = JOptionPane.showConfirmDialog(
    frame,
    "Would you like green eggs and ham?",
    "An Inane Question",
    JOptionPane.YES_NO_OPTION);
</pre>

</td>
</tr>
<tr>
<td valign=top>
<IMG SRC="../../figures/uiswing/components/CustomizingButtonText2Metal.png" WIDTH="277" HEIGHT="122" ALT="A yes/no dialog -- in other words"></td>
<td valign=top>
<pre>
Object[] options = {"Yes, please",
                    "No way!"};
int n = JOptionPane.showOptionDialog(frame,
    "Would you like green eggs and ham?",
    "A Silly Question",
    JOptionPane.YES_NO_OPTION,
    JOptionPane.QUESTION_MESSAGE,
    null,     //don't use a custom Icon
    options,  //the titles of buttons
    options[0]); //default button title
</pre>
</td>
</tr>
</table>

<p>

As the previous code snippets showed, the
<code>showMessageDialog</code>,
<code>showConfirmDialog</code>, and
<code>showOptionDialog</code> methods
return an integer
indicating the user's choice.
The values for this integer are
<code>YES_OPTION</code>,
<code>NO_OPTION</code>,
<code>CANCEL_OPTION</code>,
<code>OK_OPTION</code>, and
<code>CLOSED_OPTION</code>.
Except for <code>CLOSED_OPTION</code>,
each option corresponds to the button the user pressed.
When <code>CLOSED_OPTION</code> is returned,
it indicates that the user closed the dialog window explicitly,
rather than by choosing a button inside the option pane.

<p>

Even if you 
change the strings that the standard dialog buttons display,
the return value is still one of the pre-defined integers.
For example,
a <code>YES_NO_OPTION</code> dialog
always returns one of the following values:
<code>YES_OPTION</code>,
<code>NO_OPTION</code>, or
<code>CLOSED_OPTION</code>.

</blockquote>
<h3>
<a name="input">Getting the User's Input from a Dialog</a>
</h3>
<blockquote>


The only form of <code>show<em>Xxx</em>Dialog</code>
that doesn't return an integer 
is <code>showInputDialog</code>,
which returns an <code>Object</code> instead.
This <code>Object</code> is generally a <code>String</code>
reflecting the user's choice.
Here is an example of using <code>showInputDialog</code>
to create a dialog that lets the user choose one of three strings:

<p><center><IMG SRC="../../figures/uiswing/components/CustomizedDialogMetal.png" WIDTH="268" HEIGHT="152" ALIGN="BOTTOM" ALT="An input dialog with a combo box"></center></p>
<blockquote><pre>
Object[] possibilities = {"ham", "spam", "yam"};
String s = (String)JOptionPane.showInputDialog(
                    frame,
                    "Complete the sentence:\n"
                    + "\"Green eggs and...\"",
                    "Customized Dialog",
                    JOptionPane.PLAIN_MESSAGE,
                    icon,
                    possibilities,
                    "ham");

//If a string was returned, say so.
if ((s != null) && (s.length() > 0)) {
    setLabel("Green eggs and... " + s + "!");
    return;
}

//If you're here, the return value was null/empty.
setLabel("Come on, finish the sentence!");
</pre></blockquote>

If you don't care to limit the user's choices,
you can either use a form of the <code>showInputDialog</code> method
that takes fewer arguments
or specify <code>null</code> for the array of objects.
In the Java look and feel,
substituting <code>null</code>
for <code>possibilities</code>
results in a dialog that has a text field and looks like this:

<p><center><IMG SRC="../../figures/uiswing/components/CustomizedDialog2Metal.png" WIDTH="285" HEIGHT="147" ALIGN="BOTTOM" ALT="An input dialog with a text field"></center></p>
<p>
Because the user can type anything into the text field,
you might want to check the returned value
and ask the user to try again if it's invalid.
Another approach is to create a custom dialog
that validates the user-entered data
before it returns.
See
<a class="SourceLink" target="_blank" href="examples/CustomDialog.java"><code>CustomDialog.java</code></a> for an example of validating data.

<p>

If you're designing a custom dialog,
you need to design your dialog's API 
so that you can query the dialog about what the user chose.
For example, <code>CustomDialog</code>
has a <code>getValidatedText</code> method
that returns the text the user entered.


</blockquote>
<h3>
<a name="stayup">Stopping Automatic Dialog Closing</a>
</h3>
<blockquote>

By default, when the user clicks a <code>JOptionPane</code>-created button,
the dialog closes.
But what if you want to check the user's answer
before closing the dialog?
In this case, 
you must implement your own property change listener
so that when the user clicks a button,
the dialog doesn't automatically close.

<p>

<code>DialogDemo</code> contains two dialogs
that implement a property change listener.
One of these dialogs is a custom modal dialog,
implemented in 

<a class="SourceLink" target="_blank" href="examples/CustomDialog.java"><code>CustomDialog</code></a>,
that uses <code>JOptionPane</code>
both to get the standard icon
and to get layout assistance.
The other dialog, whose code is below,
uses a standard Yes/No <code>JOptionPane</code>.
Though this dialog is rather useless as written,
its code is simple enough
that you can use it as a template
for more complex dialogs.

<p>

Besides setting the property change listener,
the following code also calls
the <code>JDialog</code>'s <code>setDefaultCloseOperation</code> method
and implements a window listener
that handles the window close attempt properly.
If you don't care to be notified
when the user closes the window explicitly,
then ignore the bold code.

<blockquote><pre>
final JOptionPane optionPane = new JOptionPane(
                "The only way to close this dialog is by\n"
                + "pressing one of the following buttons.\n"
                + "Do you understand?",
                JOptionPane.QUESTION_MESSAGE,
                JOptionPane.YES_NO_OPTION);

final JDialog dialog = new JDialog(frame, 
                             "Click a button",
                             true);
dialog.setContentPane(optionPane);
<b>dialog.setDefaultCloseOperation(
    JDialog.DO_NOTHING_ON_CLOSE);
dialog.addWindowListener(new WindowAdapter() {
    public void windowClosing(WindowEvent we) {
        setLabel("Thwarted user attempt to close window.");
    }
});</b>
optionPane.addPropertyChangeListener(
    new PropertyChangeListener() {
        public void propertyChange(PropertyChangeEvent e) {
            String prop = e.getPropertyName();

            if (dialog.isVisible() 
             && (e.getSource() == optionPane)
             && (prop.equals(JOptionPane.VALUE_PROPERTY))) {
                //If you were going to check something