Java > Open Source Codes > javax > swing > JOptionPane


1 /*
2  * @(#)JOptionPane.java 1.91 04/03/04
3  *
4  * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6  */
7
8 package javax.swing;
9
10 import java.awt.BorderLayout ;
11 import java.awt.Component ;
12 import java.awt.Container ;
13 import java.awt.Dialog ;
14 import java.awt.Dimension ;
15 import java.awt.KeyboardFocusManager ;
16 import java.awt.Frame ;
17 import java.awt.Point ;
18 import java.awt.HeadlessException ;
19 import java.awt.Toolkit ;
20 import java.awt.Window ;
21 import java.beans.PropertyChangeEvent ;
22 import java.beans.PropertyChangeListener ;
23 import java.awt.event.WindowListener ;
24 import java.awt.event.WindowAdapter ;
25 import java.awt.event.WindowEvent ;
26 import java.awt.event.ComponentAdapter ;
27 import java.awt.event.ComponentEvent ;
28 import java.io.IOException ;
29 import java.io.ObjectInputStream ;
30 import java.io.ObjectOutputStream ;
31 import java.io.Serializable ;
32 import java.lang.reflect.Method ;
33 import java.lang.reflect.InvocationTargetException ;
34 import java.security.AccessController ;
35 import java.security.PrivilegedAction ;
36 import java.util.Vector ;
37 import javax.swing.plaf.OptionPaneUI ;
38 import javax.swing.event.InternalFrameEvent ;
39 import javax.swing.event.InternalFrameAdapter ;
40 import javax.accessibility.*;
41
42 /**
43  * <code>JOptionPane</code> makes it easy to pop up a standard dialog box that
44  * prompts users for a value or informs them of something.
45  * For information about using <code>JOptionPane</code>, see
46  * <a
47  href="http://java.sun.com/docs/books/tutorial/uiswing/components/dialog.html">How to Make Dialogs</a>,
48  * a section in <em>The Java Tutorial</em>.
49  *
50  * <p>
51  *
52  * While the <code>JOptionPane</code>
53  * class may appear complex because of the large number of methods, almost
54  * all uses of this class are one-line calls to one of the static
55  * <code>showXxxDialog</code> methods shown below:
56  * <blockquote>
57  *
58  *
59  * <table border=1 summary="Common JOptionPane method names and their descriptions">
60  * <tr>
61  * <th>Method Name</th>
62  * <th>Description</th>
63  * </tr>
64  * <tr>
65  * <td>showConfirmDialog</td>
66  * <td>Asks a confirming question, like yes/no/cancel.</td>
67  * </tr>
68  * <tr>
69  * <td>showInputDialog</td>
70  * <td>Prompt for some input.</td>
71  * </tr>
72  * <tr>
73  * <td>showMessageDialog</td>
74  * <td>Tell the user about something that has happened.</td>
75  * </tr>
76  * <tr>
77  * <td>showOptionDialog</td>
78  * <td>The Grand Unification of the above three.</td>
79  * </tr>
80  * </table>
81  *
82  * </blockquote>
83  * Each of these methods also comes in a <code>showInternalXXX</code>
84  * flavor, which uses an internal frame to hold the dialog box (see
85  * {@link JInternalFrame}).
86  * Multiple convenience methods have also been defined -- overloaded
87  * versions of the basic methods that use different parameter lists.
88  * <p>
89  * All dialogs are modal. Each <code>showXxxDialog</code> method blocks
90  * the current thread until the user's interaction is complete.
91  * <p>
92  *
93  * <table cellspacing=6 cellpadding=4 border=0 align=right summary="layout">
94  * <tr>
95  * <td bgcolor=#FFe0d0 rowspan=2>icon</td>
96  * <td bgcolor=#FFe0d0>message</td>
97  * </tr>
98  * <tr>
99  * <td bgcolor=#FFe0d0>input value</td>
100  * </tr>
101  * <tr>
102  * <td bgcolor=#FFe0d0 colspan=2>option buttons</td>
103  * </tr>
104  * </table>
105  *
106  * The basic appearance of one of these dialog boxes is generally
107  * similar to the picture at the right, although the various
108  * look-and-feels are
109  * ultimately responsible for the final result. In particular, the
110  * look-and-feels will adjust the layout to accommodate the option pane's
111  * <code>ComponentOrientation</code> property.
112  * <br clear=all>
113  * <p>
114  * <b>Parameters:</b><br>
115  * The parameters to these methods follow consistent patterns:
116  * <blockquote>
117  * <dl compact>
118  * <dt>parentComponent<dd>
119  * Defines the <code>Component</code> that is to be the parent of this
120  * dialog box.
121  * It is used in two ways: the <code>Frame</code> that contains
122  * it is used as the <code>Frame</code>
123  * parent for the dialog box, and its screen coordinates are used in
124  * the placement of the dialog box. In general, the dialog box is placed
125  * just below the component. This parameter may be <code>null</code>,
126  * in which case a default <code>Frame</code> is used as the parent,
127  * and the dialog will be
128  * centered on the screen (depending on the L&F).
129  * <dt><a name=message>message</a><dd>
130  * A descriptive message to be placed in the dialog box.
131  * In the most common usage, message is just a <code>String</code> or
132  * <code>String</code> constant.
133  * However, the type of this parameter is actually <code>Object</code>. Its
134  * interpretation depends on its type:
135  * <dl compact>
136  * <dt>Object[]<dd>An array of objects is interpreted as a series of
137  * messages (one per object) arranged in a vertical stack.
138  * The interpretation is recursive -- each object in the
139  * array is interpreted according to its type.
140  * <dt>Component<dd>The <code>Component</code> is displayed in the dialog.
141  * <dt>Icon<dd>The <code>Icon</code> is wrapped in a <code>JLabel</code>
142  * and displayed in the dialog.
143  * <dt>others<dd>The object is converted to a <code>String</code> by calling
144  * its <code>toString</code> method. The result is wrapped in a
145  * <code>JLabel</code> and displayed.
146  * </dl>
147  * <dt>messageType<dd>Defines the style of the message. The Look and Feel
148  * manager may lay out the dialog differently depending on this value, and
149  * will often provide a default icon. The possible values are:
150  * <ul>
151  * <li><code>ERROR_MESSAGE</code>
152  * <li><code>INFORMATION_MESSAGE</code>
153  * <li><code>WARNING_MESSAGE</code>
154  * <li><code>QUESTION_MESSAGE</code>
155  * <li><code>PLAIN_MESSAGE</code>
156  * </ul>
157  * <dt>optionType<dd>Defines the set of option buttons that appear at
158  * the bottom of the dialog box:
159  * <ul>
160  * <li><code>DEFAULT_OPTION</code>
161  * <li><code>YES_NO_OPTION</code>
162  * <li><code>YES_NO_CANCEL_OPTION</code>
163  * <li><code>OK_CANCEL_OPTION</code>
164  * </ul>
165  * You aren't limited to this set of option buttons. You can provide any
166  * buttons you want using the options parameter.
167  * <dt>options<dd>A more detailed description of the set of option buttons
168  * that will appear at the bottom of the dialog box.
169  * The usual value for the options parameter is an array of
170  * <code>String</code>s. But
171  * the parameter type is an array of <code>Objects</code>.
172  * A button is created for each object depending on its type:
173  * <dl compact>
174  * <dt>Component<dd>The component is added to the button row directly.
175  * <dt>Icon<dd>A <code>JButton</code> is created with this as its label.
176  * <dt>other<dd>The <code>Object</code> is converted to a string using its
177  * <code>toString</code> method and the result is used to
178  * label a <code>JButton</code>.
179  * </dl>
180  * <dt>icon<dd>A decorative icon to be placed in the dialog box. A default
181  * value for this is determined by the <code>messageType</code> parameter.
182  * <dt>title<dd>The title for the dialog box.
183  * <dt>initialValue<dd>The default selection (input value).
184  * </dl>
185  * </blockquote>
186  * <p>
187  * When the selection is changed, <code>setValue</code> is invoked,
188  * which generates a <code>PropertyChangeEvent</code>.
189  * <p>
190  * If a <code>JOptionPane</code> has configured to all input
191  * <code>setWantsInput</code>
192  * the bound property <code>JOptionPane.INPUT_VALUE_PROPERTY</code>
193  * can also be listened
194  * to, to determine when the user has input or selected a value.
195  * <p>
196  * When one of the <code>showXxxDialog</code> methods returns an integer,
197  * the possible values are:
198  * <ul>
199  * <li><code>YES_OPTION</code>
200  * <li><code>NO_OPTION</code>
201  * <li><code>CANCEL_OPTION</code>
202  * <li><code>OK_OPTION</code>
203  * <li><code>CLOSED_OPTION</code>
204  * </ul>
205  * <b>Examples:</b>
206  * <dl>
207  * <dt>Show an error dialog that displays the message, 'alert':
208  * <dd><code>
209  * JOptionPane.showMessageDialog(null, "alert", "alert", JOptionPane.ERROR_MESSAGE);
210  * </code><p>
211  * <dt>Show an internal information dialog with the message, 'information':
212  * <dd><code>
213  * JOptionPane.showInternalMessageDialog(frame, "information",<br>
214  * <ul><ul>"information", JOptionPane.INFORMATION_MESSAGE);</ul></ul>
215  * </code><p>
216  * <dt>Show an information panel with the options yes/no and message 'choose one':
217  * <dd><code>JOptionPane.showConfirmDialog(null,
218  * <ul><ul>"choose one", "choose one", JOptionPane.YES_NO_OPTION);</ul></ul>
219  * </code><p>
220  * <dt>Show an internal information dialog with the options yes/no/cancel and
221  * message 'please choose one' and title information:
222  * <dd><code>JOptionPane.showInternalConfirmDialog(frame,
223  * <ul><ul>"please choose one", "information",</ul></ul>
224  * <ul><ul>JOptionPane.YES_NO_CANCEL_OPTION, JOptionPane.INFORMATION_MESSAGE);</ul></ul>
225  * </code><p>
226  * <dt>Show a warning dialog with the options OK, CANCEL, title 'Warning', and
227  * message 'Click OK to continue':
228  * <dd><code>
229  * Object[] options = { "OK", "CANCEL" };<br>
230  * JOptionPane.showOptionDialog(null, "Click OK to continue", "Warning",
231  * <ul><ul>JOptionPane.DEFAULT_OPTION, JOptionPane.WARNING_MESSAGE,</ul></ul>
232  * <ul><ul>null, options, options[0]);</ul></ul>
233  * </code><p>
234  * <dt>Show a dialog asking the user to type in a String:
235  * <dd><code>
236  * String inputValue = JOptionPane.showInputDialog("Please input a value");
237  * </code><p>
238  * <dt>Show a dialog asking the user to select a String:
239  * <dd><code>
240  * Object[] possibleValues = { "First", "Second", "Third" };<br>
241  * Object selectedValue = JOptionPane.showInputDialog(null,
242  * <ul><ul>"Choose one", "Input",</ul></ul>
243  * <ul><ul>JOptionPane.INFORMATION_MESSAGE, null,</ul></ul>
244  * <ul><ul>possibleValues, possibleValues[0]);</ul></ul>
245  * </code><p>
246  * </dl>
247  * <b>Direct Use:</b><br>
248  * To create and use an <code>JOptionPane</code> directly, the
249  * standard pattern is roughly as follows:
250  * <pre>
251  * JOptionPane pane = new JOptionPane(<i>arguments</i>);
252  * pane.set<i>.Xxxx(...); // Configure</i>
253  * JDialog dialog = pane.createDialog(<i>parentComponent, title</i>);
254  * dialog.show();
255  * Object selectedValue = pane.getValue();
256  * if(selectedValue == null)
257  * return CLOSED_OPTION;
258  * <i>//If there is <b>not</b> an array of option buttons:</i>
259  * if(options == null) {
260  * if(selectedValue instanceof Integer)
261  * return ((Integer)selectedValue).intValue();
262  * return CLOSED_OPTION;
263  * }
264  * <i>//If there is an array of option buttons:</i>
265  * for(int counter = 0, maxCounter = options.length;
266  * counter < maxCounter; counter++) {
267  * if(options[counter].equals(selectedValue))
268  * return counter;
269  * }
270  * return CLOSED_OPTION;
271  * </pre>
272  * <p>
273  * <strong>Warning:</strong>
274  * Serialized objects of this class will not be compatible with
275  * future Swing releases. The current serialization support is
276  * appropriate for short term storage or RMI between applications running
277  * the same version of Swing. As of 1.4, support for long term storage
278  * of all JavaBeans<sup><font size="-2">TM</font></sup>
279  * has been added to the <code>java.beans</code> package.
280  * Please see {@link java.beans.XMLEncoder}.
281  *
282  * @see JInternalFrame
283  *
284  * @beaninfo
285  * attribute: isContainer true
286  * description: A component which implements standard dialog box controls.
287  *
288  * @version 1.91 03/04/04
289  * @author James Gosling
290  * @author Scott Violet
291  */
292 public class JOptionPane extends JComponent implements Accessible
293 {
294     /**
295      * @see #getUIClassID
296      * @see #readObject
297      */
298     private static final String uiClassID = "OptionPaneUI";
299
300     /**
301      * Indicates that the user has not yet selected a value.
302      */
303     public static final Object UNINITIALIZED_VALUE = "uninitializedValue";
304
305     //
306 // Option types
307 //
308 /**
309      * Type meaning Look and Feel should not supply any options -- only
310      * use the options from the <code>JOptionPane</code>.
311      */
312     /** Type used for <code>showConfirmDialog</code>. */
313     public static final int DEFAULT_OPTION = -1;
314     /** Type used for <code>showConfirmDialog</code>. */
315     public static final int YES_NO_OPTION = 0;
316     /** Type used for <code>showConfirmDialog</code>. */
317     public static final int YES_NO_CANCEL_OPTION = 1;
318     /** Type used for <code>showConfirmDialog</code>. */
319     public static final int OK_CANCEL_OPTION = 2;
320
321     //
322 // Return values.
323 //
324 /** Return value from class method if YES is chosen. */
325     public static final int YES_OPTION = 0;
326     /** Return value from class method if NO is chosen. */
327     public static final int NO_OPTION = 1;
328     /** Return value from class method if CANCEL is chosen. */
329     public static final int CANCEL_OPTION = 2;
330     /** Return value form class method if OK is chosen. */
331     public static final int OK_OPTION = 0;
332     /** Return value from class method if user closes window without selecting
333      * anything, more than likely this should be treated as either a
334      * <code>CANCEL_OPTION</code> or <code>NO_OPTION</code>. */
335     public static final int CLOSED_OPTION = -1;
336
337     //
338 // Message types. Used by the UI to determine what icon to display,
339 // and possibly what behavior to give based on the type.
340 //
341 /** Used for error messages. */
342     public static final int ERROR_MESSAGE = 0;
343     /** Used for information messages. */
344     public static final int INFORMATION_MESSAGE = 1;
345     /** Used for warning messages. */
346     public static final int WARNING_MESSAGE = 2;
347     /** Used for questions. */
348     public static final int QUESTION_MESSAGE = 3;
349     /** No icon is used. */
350     public static final int PLAIN_MESSAGE = -1;
351
352     /** Bound property name for <code>icon</code>. */
353     public static final String ICON_PROPERTY = "icon";
354     /** Bound property name for <code>message</code>. */
355     public static final String MESSAGE_PROPERTY = "message";
356     /** Bound property name for <code>value</code>. */
357     public static final String VALUE_PROPERTY = "value";
358     /** Bound property name for <code>option</code>. */
359     public static final String OPTIONS_PROPERTY = "options";
360     /** Bound property name for <code>initialValue</code>. */
361     public static final String INITIAL_VALUE_PROPERTY = "initialValue";
362     /** Bound property name for <code>type</code>. */
363     public static final String MESSAGE_TYPE_PROPERTY = "messageType";
364     /** Bound property name for <code>optionType</code>. */
365     public static final String OPTION_TYPE_PROPERTY = "optionType";
366     /** Bound property name for <code>selectionValues</code>. */
367     public static final String SELECTION_VALUES_PROPERTY = "selectionValues";
368     /** Bound property name for <code>initialSelectionValue</code>. */
369     public static final String INITIAL_SELECTION_VALUE_PROPERTY = "initialSelectionValue";
370     /** Bound property name for <code>inputValue</code>. */
371     public static final String INPUT_VALUE_PROPERTY = "inputValue";
372     /** Bound property name for <code>wantsInput</code>. */
373     public static final String WANTS_INPUT_PROPERTY = "wantsInput";
374
375     /** Icon used in pane. */
376     transient protected Icon icon;
377     /** Message to display. */
378     transient protected Object message;
379     /** Options to display to the user. */
380     transient protected Object [] options;
381     /** Value that should be initially selected in <code>options</code>. */
382     transient protected Object initialValue;
383     /** Message type. */
384     protected int messageType;
385     /**
386      * Option type, one of <code>DEFAULT_OPTION</code>,
387      * <code>YES_NO_OPTION</code>,
388      * <code>YES_NO_CANCEL_OPTION</code> or
389      * <code>OK_CANCEL_OPTION</code>.
390      */
391     protected int optionType;
392     /** Currently selected value, will be a valid option, or
393      * <code>UNINITIALIZED_VALUE</code> or <code>null</code>. */
394     transient protected Object value;
395     /** Array of values the user can choose from. Look and feel will
396      * provide the UI component to choose this from. */
397     protected transient Object [] selectionValues;
398     /** Value the user has input. */
399     protected transient Object inputValue;
400     /** Initial value to select in <code>selectionValues</code>. */
401     protected transient Object initialSelectionValue;
402     /** If true, a UI widget will be provided to the user to get input. */
403     protected boolean wantsInput;
404
405
406     /**
407      * Shows a question-message dialog requesting input from the user. The
408      * dialog uses the default frame, which usually means it is centered on
409      * the screen.
410      *
411      * @param message the <code>Object</code> to display
412      * @exception HeadlessException if
413      * <code>GraphicsEnvironment.isHeadless</code> returns
414      * <code>true</code>
415      * @see java.awt.GraphicsEnvironment#isHeadless
416      */
417     public static String showInputDialog(Object message)
418         throws HeadlessException {
419         return showInputDialog(null, message);
420     }
421
422     /**
423      * Shows a question-message dialog requesting input from the user, with
424      * the input value initialized to <code>initialSelectionValue</code>. The
425      * dialog uses the default frame, which usually means it is centered on
426      * the screen.
427      *
428      * @param message the <code>Object</code> to display
429      * @param initialSelectionValue the value used to initialize the input
430      * field
431      * @since 1.4
432      */
433     public static String showInputDialog(Object message, Object initialSelectionValue) {
434         return showInputDialog(null, message, initialSelectionValue);
435     }
436
437     /**
438      * Shows a question-message dialog requesting input from the user
439      * parented to <code>parentComponent</code>.
440      * The dialog is displayed on top of the <code>Component</code>'s
441      * frame, and is usually positioned below the <code>Component</code>.
442      *
443      * @param parentComponent the parent <code>Component</code> for the
444      * dialog
445      * @param message the <code>Object</code> to display
446      * @exception HeadlessException if
447      * <code>GraphicsEnvironment.isHeadless</code> returns
448      * <code>true</code>
449      * @see java.awt.GraphicsEnvironment#isHeadless
450      */
451     public static String showInputDialog(Component parentComponent,
452         Object message) throws HeadlessException {
453         return showInputDialog(parentComponent, message, UIManager.getString(
454             "OptionPane.inputDialogTitle", parentComponent), QUESTION_MESSAGE);
455     }
456
457     /**
458      * Shows a question-message dialog requesting input from the user and
459      * parented to <code>parentComponent</code>. The input value will be
460      * initialized to <code>initialSelectionValue</code>.
461      * The dialog is displayed on top of the <code>Component</code>'s
462      * frame, and is usually positioned below the <code>Component</code>.
463      *
464      * @param parentComponent the parent <code>Component</code> for the
465      * dialog
466      * @param message the <code>Object</code> to display
467      * @param initialSelectionValue the value used to initialize the input
468      * field
469      * @since 1.4
470      */
471     public static String showInputDialog(Component parentComponent, Object message,
472                      Object initialSelectionValue) {
473         return (String )showInputDialog(parentComponent, message,
474                       UIManager.getString("OptionPane.inputDialogTitle",
475                       parentComponent), QUESTION_MESSAGE, null, null,
476                       initialSelectionValue);
477     }
478
479     /**
480      * Shows a dialog requesting input from the user parented to
481      * <code>parentComponent</code> with the dialog having the title
482      * <code>title</code> and message type <code>messageType</code>.
483      *
484      * @param parentComponent the parent <code>Component</code> for the
485      * dialog
486      * @param message the <code>Object</code> to display
487      * @param title the <code>String</code> to display in the dialog
488      * title bar
489      * @param messageType the type of message that is to be displayed:
490      * <code>ERROR_MESSAGE</code>,
491      * <code>INFORMATION_MESSAGE</code>,
492      * <code>WARNING_MESSAGE</code>,
493      * <code>QUESTION_MESSAGE</code>,
494      * or <code>PLAIN_MESSAGE</code>
495      * @exception HeadlessException if
496      * <code>GraphicsEnvironment.isHeadless</code> returns
497      * <code>true</code>
498      * @see java.awt.GraphicsEnvironment#isHeadless
499      */
500     public static String showInputDialog(Component parentComponent,
501         Object message, String title, int messageType)
502         throws HeadlessException {
503         return (String )showInputDialog(parentComponent, message, title,
504                                        messageType, null, null, null);
505     }
506
507     /**
508      * Prompts the user for input in a blocking dialog where the
509      * initial selection, possible selections, and all other options can
510      * be specified. The user will able to choose from
511      * <code>selectionValues</code>, where <code>null</code> implies the
512      * user can input
513      * whatever they wish, usually by means of a <code>JTextField</code>.
514      * <code>initialSelectionValue</code> is the initial value to prompt
515      * the user with. It is up to the UI to decide how best to represent
516      * the <code>selectionValues</code>, but usually a
517      * <code>JComboBox</code>, <code>JList</code>, or
518      * <code>JTextField</code> will be used.
519      *
520      * @param parentComponent the parent <code>Component</code> for the
521      * dialog
522      * @param message the <code>Object</code> to display
523      * @param title the <code>String</code> to display in the
524      * dialog title bar
525      * @param messageType the type of message to be displayed:
526      * <code>ERROR_MESSAGE</code>,
527      * <code>INFORMATION_MESSAGE</code>,
528      * <code>WARNING_MESSAGE</code>,
529      * <code>QUESTION_MESSAGE</code>,
530      * or <code>PLAIN_MESSAGE</code>
531      * @param icon the <code>Icon</code> image to display
532      * @param selectionValues an array of <code>Object</code>s that
533      * gives the possible selections
534      * @param initialSelectionValue the value used to initialize the input
535      * field
536      * @return user's input, or <code>null</code> meaning the user
537      * canceled the input
538      * @exception HeadlessException if
539      * <code>GraphicsEnvironment.isHeadless</code> returns
540      * <code>true</code>
541      * @see java.awt.GraphicsEnvironment#isHeadless
542      */
543     public static Object showInputDialog(Component parentComponent,
544         Object message, String title, int messageType, Icon icon,
545         Object [] selectionValues, Object initialSelectionValue)
546         throws HeadlessException {
547         JOptionPane pane = new JOptionPane (message, messageType,
548                                               OK_CANCEL_OPTION, icon,
549                                               null, null);
550
551         pane.setWantsInput(true);
552         pane.setSelectionValues(selectionValues);
553         pane.setInitialSelectionValue(initialSelectionValue);
554         pane.setComponentOrientation(((parentComponent == null) ?
555         getRootFrame() : parentComponent).getComponentOrientation());
556
557         int style = styleFromMessageType(messageType);
558         JDialog dialog = pane.createDialog(parentComponent, title, style);
559
560         pane.selectInitialValue();
561         dialog.show();
562         dialog.dispose();
563
564         Object value = pane.getInputValue();
565
566         if (value == UNINITIALIZED_VALUE) {
567             return null;
568         }
569         return value;
570     }
571
572     /**
573      * Brings up an information-message dialog titled "Message".
574      *
575      * @param parentComponent determines the <code>Frame</code> in
576      * which the dialog is displayed; if <code>null</code>,
577      * or if the <code>parentComponent</code> has no
578      * <code>Frame</code>, a default <code>Frame</code> is used
579      * @param message the <code>Object</code> to display
580      * @exception HeadlessException if
581      * <code>GraphicsEnvironment.isHeadless</code> returns
582      * <code>true</code>
583      * @see java.awt.GraphicsEnvironment#isHeadless
584      */
585     public static void showMessageDialog(Component parentComponent,
586         Object message) throws HeadlessException {
587         showMessageDialog(parentComponent, message, UIManager.getString(
588                     "OptionPane.messageDialogTitle", parentComponent),
589                     INFORMATION_MESSAGE);
590     }
591
592     /**
593      * Brings up a dialog that displays a message using a default
594      * icon determined by the <code>messageType</code> parameter.
595      *
596      * @param parentComponent determines the <code>Frame</code>
597      * in which the dialog is displayed; if <code>null</code>,
598      * or if the <code>parentComponent</code> has no
599      * <code>Frame</code>, a default <code>Frame</code> is used
600      * @param message the <code>Object</code> to display
601      * @param title the title string for the dialog
602      * @param messageType the type of message to be displayed:
603      * <code>ERROR_MESSAGE</code>,
604      * <code>INFORMATION_MESSAGE</code>,
605      * <code>WARNING_MESSAGE</code>,
606      * <code>QUESTION_MESSAGE</code>,
607      * or <code>PLAIN_MESSAGE</code>
608      * @exception HeadlessException if
609      * <code>GraphicsEnvironment.isHeadless</code> returns
610      * <code>true</code>
611      * @see java.awt.GraphicsEnvironment#isHeadless
612      */
613     public static void showMessageDialog(Component parentComponent,
614         Object message, String title, int messageType)
615         throws HeadlessException {
616         showMessageDialog(parentComponent, message, title, messageType, null);
617     }
618
619     /**
620      * Brings up a dialog displaying a message, specifying all parameters.
621      *
622      * @param parentComponent determines the <code>Frame</code> in which the
623      * dialog is displayed; if <code>null</code>,
624      * or if the <code>parentComponent</code> has no
625      * <code>Frame</code>, a
626      * default <code>Frame</code> is used
627      * @param message the <code>Object</code> to display
628      * @param title the title string for the dialog
629      * @param messageType the type of message to be displayed:
630      * <code>ERROR_MESSAGE</code>,
631      * <code>INFORMATION_MESSAGE</code>,
632      * <code>WARNING_MESSAGE</code>,
633      * <code>QUESTION_MESSAGE</code>,
634      * or <code>PLAIN_MESSAGE</code>
635      * @param icon an icon to display in the dialog that helps the user
636      * identify the kind of message that is being displayed
637      * @exception HeadlessException if
638      * <code>GraphicsEnvironment.isHeadless</code> returns
639      * <code>true</code>
640      * @see java.awt.GraphicsEnvironment#isHeadless
641      */
642     public static void showMessageDialog(Component parentComponent,
643         Object message, String title, int messageType, Icon icon)
644         throws HeadlessException {
645         showOptionDialog(parentComponent, message, title, DEFAULT_OPTION,
646                          messageType, icon, null, null);
647     }
648
649     /**
650      * Brings up a dialog with the options <i>Yes</i>,
651      * <i>No</i> and <i>Cancel</i>; with the
652      * title, <b>Select an Option</b>.
653      *
654      * @param parentComponent determines the <code>Frame</code> in which the
655      * dialog is displayed; if <code>null</code>,
656      * or if the <code>parentComponent</code> has no
657      * <code>Frame</code>, a
658      * default <code>Frame</code> is used
659      * @param message the <code>Object</code> to display
660      * @return an integer indicating the option selected by the user
661      * @exception HeadlessException if
662      * <code>GraphicsEnvironment.isHeadless</code> returns
663      * <code>true</code>
664      * @see java.awt.GraphicsEnvironment#isHeadless
665      */
666     public static int showConfirmDialog(Component parentComponent,
667         Object message) throws HeadlessException {
668         return showConfirmDialog(parentComponent, message,
669                                  UIManager.getString("OptionPane.titleText"),
670                                  YES_NO_CANCEL_OPTION);
671     }
672
673     /**
674      * Brings up a dialog where the number of choices is determined
675      * by the <code>optionType</code> parameter.
676      *
677      * @param parentComponent determines the <code>Frame</code> in which the
678      * dialog is displayed; if <code>null</code>,
679      * or if the <code>parentComponent</code> has no
680      * <code>Frame</code>, a
681      * default <code>Frame</code> is used
682      * @param message the <code>Object</code> to display
683      * @param title the title string for the dialog
684      * @param optionType an int designating the options available on the dialog:
685      * <code>YES_NO_OPTION</code>, or
686      * <code>YES_NO_CANCEL_OPTION</code>
687      * @return an int indicating the option selected by the user
688      * @exception HeadlessException if
689      * <code>GraphicsEnvironment.isHeadless</code> returns
690      * <code>true</code>
691      * @see java.awt.GraphicsEnvironment#isHeadless
692      */
693     public static int showConfirmDialog(Component parentComponent,
694         Object message, String title, int optionType)
695         throws HeadlessException {
696         return showConfirmDialog(parentComponent, message, title, optionType,
697                                  QUESTION_MESSAGE);
698     }
699
700     /**
701      * Brings up a dialog where the number of choices is determined
702      * by the <code>optionType</code> parameter, where the
703      * <code>messageType</code>
704      * parameter determines the icon to display.
705      * The <code>messageType</code> parameter is primarily used to supply
706      * a default icon from the Look and Feel.
707      *
708      * @param parentComponent determines the <code>Frame</code> in
709      * which the dialog is displayed; if <code>null</code>,
710      * or if the <code>parentComponent</code> has no
711      * <code>Frame</code>, a
712      * default <code>Frame</code> is used.
713      * @param message the <code>Object</code> to display
714      * @param title the title string for the dialog
715      * @param optionType an integer designating the options available
716      * on the dialog: <code>YES_NO_OPTION</code>,
717      * or <code>YES_NO_CANCEL_OPTION</code>
718      * @param messageType an integer designating the kind of message this is;
719      * primarily used to determine the icon from the pluggable
720      * Look and Feel: <code>ERROR_MESSAGE</code>,
721      * <code>INFORMATION_MESSAGE</code>,
722      * <code>WARNING_MESSAGE</code>,
723      * <code>QUESTION_MESSAGE</code>,
724      * or <code>PLAIN_MESSAGE</code>
725      * @return an integer indicating the option selected by the user
726      * @exception HeadlessException if
727      * <code>GraphicsEnvironment.isHeadless</code> returns
728      * <code>true</code>
729      * @see java.awt.GraphicsEnvironment#isHeadless
730      */
731     public static int showConfirmDialog(Component parentComponent,
732         Object message, String title, int optionType, int messageType)
733         throws HeadlessException {
734         return showConfirmDialog(parentComponent, message, title, optionType,
735                                 messageType, null);
736     }
737
738     /**
739      * Brings up a dialog with a specified icon, where the number of
740      * choices is determined by the <code>optionType</code> parameter.
741      * The <code>messageType</code> parameter is primarily used to supply
742      * a default icon from the look and feel.
743      *
744      * @param parentComponent determines the <code>Frame</code> in which the
745      * dialog is displayed; if <code>null</code>,
746      * or if the <code>parentComponent</code> has no
747      * <code>Frame</code>, a
748      * default <code>Frame</code> is used
749      * @param message the Object to display
750      * @param title the title string for the dialog
751      * @param optionType an int designating the options available on the dialog:
752      * <code>YES_NO_OPTION</code>,
753      * or <code>YES_NO_CANCEL_OPTION</code>
754      * @param messageType an int designating the kind of message this is,
755      * primarily used to determine the icon from the pluggable
756      * Look and Feel: <code>ERROR_MESSAGE</code>,
757      * <code>INFORMATION_MESSAGE</code>,
758      * <code>WARNING_MESSAGE</code>,
759      * <code>QUESTION_MESSAGE</code>,
760      * or <code>PLAIN_MESSAGE</code>
761      * @param icon the icon to display in the dialog
762      * @return an int indicating the option selected by the user
763      * @exception HeadlessException if
764      * <code>GraphicsEnvironment.isHeadless</code> returns
765      * <code>true</code>
766      * @see java.awt.GraphicsEnvironment#isHeadless
767      */
768     public static int showConfirmDialog(Component parentComponent,
769         Object message, String title, int optionType,
770         int messageType, Icon icon) throws HeadlessException {
771         return showOptionDialog(parentComponent, message, title, optionType,
772                                 messageType, icon, null, null);
773     }
774
775     /**
776      * Brings up a dialog with a specified icon, where the initial
777      * choice is determined by the <code>initialValue</code> parameter and
778      * the number of choices is determined by the <code>optionType</code>
779      * parameter.
780      * <p>
781      * If <code>optionType</code> is <code>YES_NO_OPTION</code>,
782      * or <code>YES_NO_CANCEL_OPTION</code>
783      * and the <code>options</code> parameter is <code>null</code>,
784      * then the options are
785      * supplied by the look and feel.
786      * <p>
787      * The <code>messageType</code> parameter is primarily used to supply
788      * a default icon from the look and feel.
789      *
790      * @param parentComponent determines the <code>Frame</code>
791      * in which the dialog is displayed; if
792      * <code>null</code>, or if the
793      * <code>parentComponent</code> has no
794      * <code>Frame</code>, a
795      * default <code>Frame</code> is used
796      * @param message the <code>Object</code> to display
797      * @param title the title string for the dialog
798      * @param optionType an integer designating the options available on the
799      * dialog: <code>YES_NO_OPTION</code>,
800      * or <code>YES_NO_CANCEL_OPTION</code>
801      * @param messageType an integer designating the kind of message this is,
802      * primarily used to determine the icon from the
803      * pluggable Look and Feel: <code>ERROR_MESSAGE</code>,
804      * <code>INFORMATION_MESSAGE</code>,
805      * <code>WARNING_MESSAGE</code>,
806      * <code>QUESTION_MESSAGE</code>,
807      * or <code>PLAIN_MESSAGE</code>
808      * @param icon the icon to display in the dialog
809      * @param options an array of objects indicating the possible choices
810      * the user can make; if the objects are components, they
811      * are rendered properly; non-<code>String</code>
812      * objects are
813      * rendered using their <code>toString</code> methods;
814      * if this parameter is <code>null</code>,
815      * the options are determined by the Look and Feel
816      * @param initialValue the object that represents the default selection
817      * for the dialog; only meaningful if <code>options</code>
818      * is used; can be <code>null</code>
819      * @return an integer indicating the option chosen by the user,
820      * or <code>CLOSED_OPTION</code> if the user closed
821      * the dialog
822      * @exception HeadlessException if
823      * <code>GraphicsEnvironment.isHeadless</code> returns
824      * <code>true</code>
825      * @see java.awt.GraphicsEnvironment#isHeadless
826      */
827     public static int showOptionDialog(Component parentComponent,
828         Object message, String title, int optionType, int messageType,
829         Icon icon, Object [] options, Object initialValue)
830         throws HeadlessException {
831         JOptionPane pane = new JOptionPane (message, messageType,
832                                                        optionType, icon,
833                                                        options, initialValue);
834
835         pane.setInitialValue(initialValue);
836         pane.setComponentOrientation(((parentComponent == null) ?
837         getRootFrame() : parentComponent).getComponentOrientation());
838
839         int style = styleFromMessageType(messageType);
840         JDialog dialog = pane.createDialog(parentComponent, title, style);
841
842         pane.selectInitialValue();
843         dialog.show();
844         dialog.dispose();
845
846         Object selectedValue = pane.getValue();
847
848         if(selectedValue == null)
849             return CLOSED_OPTION;
850         if(options == null) {
851             if(selectedValue instanceof Integer )
852                 return ((Integer )selectedValue).intValue();
853             return CLOSED_OPTION;
854         }
855         for(int counter = 0, maxCounter = options.length;
856             counter < maxCounter; counter++) {
857             if(options[counter].equals(selectedValue))
858                 return counter;
859         }
860         return CLOSED_OPTION;
861     }
862
863     /**
864      * Creates and retur