![]() ![]() ![]() |
Start of Tutorial > Start of Trail > Start of Lesson | Search |
Several classes support dialogs -- windows that are more limited than frames. To create simple, standard dialogs, you use theJOptionPane
class. The
ProgressMonitor
class can put up a dialog that shows the progress of an operation. Two other classes,JColorChooser
andJFileChooser
, also supply standard dialogs. To bring up a print dialog, you can either use thegetPrintJob
method defined in theToolkit
class or, if you're using Java 2, use the Printing
. To create custom dialogs, use the
JDialog
class directly.
The code for simple dialogs can be minimal. For example, here's an informational dialog:
Here is the code that creates and shows it:
The rest of this section covers the following topics:JOptionPane.showMessageDialog(frame, "Eggs aren't supposed to be green.");
Every dialog is dependent on a frame. When that frame is destroyed, so are its dependent dialogs. When the frame is iconified, its dependent dialogs disappear from the screen. When the frame is deiconified, its dependent dialogs return to the screen. The AWT automatically provides this behavior.A dialog can be modal. When a modal dialog is visible, it blocks user input to all other windows in the program. The dialogs that
JOptionPane
provides are modal. To create a non-modal dialog, you must use theJDialog
class directly.The
JDialog
class is a subclass of the AWTjava.awt.Dialog
class. It adds to
Dialog
a root pane and support for a default close operation. These are the same features thatJFrame
has, and usingJDialog
directly is very similar to usingJFrame
directly. If you're going to useJDialog
directly, then you should understand the material in Using Top-Level Containers and Using Frames, especially Responding to Window-Closing Events.Even when you use
JOptionPane
to implement a dialog, you're still using aJDialog
behind the scenes. The reason is thatJOptionPane
is simply a container that can automatically create aJDialog
and add itself to theJDialog
's content pane.
Here's a picture of an application that displays dialogs.
Try this:
- Compile and run the application. The main source file is
DialogDemo.java
. You will also need one other source file and an image file. See the examples index for links to all the files required by this example.
See Getting Started with Swing if you need help compiling or running this application.- Click the Show it! button.
A modal dialog will appear. Until you close it, the application will be unresponsive, although it will repaint itself if necessary. You can close the dialog either by clicking a button in the dialog or explicitly, such as by using the dialog's window decorations.- Iconify the DialogDemo window while a dialog is showing.
The dialog will disappear from the screen until you deiconify the DialogDemo window.- In the More Dialogs pane, click the bottom radio button and then the Show it! button. A non-modal dialog will appear. Note that the DialogDemo window remains fully functional while the non-modal dialog is up.
UsingJOptionPane
, you can create and customize several different kinds of dialogs.JOptionPane
provides support for laying out standard dialogs, providing icons, specifying the dialog's title and text, and customizing the button text. Other features allow you to customize the components the dialog displays and specify where the dialog should appear onscreen. You can even specify that an option pane put itself into an internal frame (JInternalFrame
) instead of aJDialog
.
Note: The internal frames thatJOptionPane
creates currently behave differently from modal dialogs. They don't behave modally, and in general seem more like frames than like dialogs. For this reason, we don't currently recommend their use.When you create a
JOptionPane
, look-and-feel-specific code adds components to theJOptionPane
and determines the layout of those components.
JOptionPane
's icon support lets you easily specify which icon the dialog displays. You can use a custom icon, no icon at all, or any one of four standardJOptionPane
icons (question, information, warning, and error). Each look and feel has its own versions of the four standard icons. The following figure shows the icons used in the Java Look & Feel.
Icons provided by JOptionPane
(Java Look & Feel shown)question information warning error
For most simple modal dialogs, you create and show the dialog using one ofJOptionPane
'sshowXxxDialog
methods. If your dialog should be an internal frame, then addInternal
aftershow
-- for example,showMessageDialog
changes toshowInternalMessageDialog
. If you need to control the dialog's window-closing behavior or if the dialog isn't modal, then you should directly instantiateJOptionPane
and add it to aJDialog
instance. Then invokesetVisible(true)
on theJDialog
to make it appear.The two most useful
showXxxDialog
methods areshowMessageDialog
andshowOptionDialog
. TheshowMessageDialog
method displays a simple, one-button dialog. TheshowOptionDialog
method displays a customized dialog -- it can display a variety of buttons with customized button text, and can contain a standard text message or a collection of components.The other two
showXxxDialog
methods are used less often. TheshowConfirmDialog
method asks the user to confirm something, but has the disadvantage of having standard button text (Yes/No or the localized equivalent, for example), rather than button text customized to the user's situation (Start/Cancel, for example). A fourth method,showInputDialog
, is designed to display a modal dialog that gets a string from the user, using either a text field or an uneditable combo box. However, input dialogs aren't very useful right now, since the text field doesn't let you perform validation before the dialog goes away, and combo boxes in dialogs don't yet work well.Here are some examples, taken from
DialogDemo.java
, of using
showMessageDialog
,showOptionDialog
, and theJOptionPane
constructor. For more example code, seeDialogDemo.java
and the other programs listed in Examples that Use Dialogs.
The arguments to all of the
showMessageDialog
- Displays a modal dialog with one button, which is labeled "OK" (or the localized equivalent). You can easily specify the message, icon, and title that the dialog displays. Here are some examples of using
showMessageDialog
:
//default title and icon JOptionPane.showMessageDialog(frame, "Eggs aren't supposed to be green."); //custom title, warning icon JOptionPane.showMessageDialog(frame, "Eggs aren't supposed to be green.", "Inane warning", JOptionPane.WARNING_MESSAGE); //custom title, error icon JOptionPane.showMessageDialog(frame, "Eggs aren't supposed to be green.", "Inane error", JOptionPane.ERROR_MESSAGE); //custom title, no icon JOptionPane.showMessageDialog(frame, "Eggs aren't supposed to be green.", "A plain message", JOptionPane.PLAIN_MESSAGE); //custom title, custom icon JOptionPane.showMessageDialog(frame, "Eggs aren't supposed to be green.", "Inane custom dialog", JOptionPane.INFORMATION_MESSAGE, icon);showOptionDialog
- Displays a modal dialog with the specified buttons, icons, message, title, and so on. With this method, you can change the text that appears on the buttons of standard dialogs. You can also perform many other kinds of customization.
//Custom button text Object[] options = {"Yes, please", "No, thanks", "No eggs, no ham!"}; int n = JOptionPane.showOptionDialog(frame, "Would you like some green eggs to go " + "with that ham?", "A Silly Question", JOptionPane.YES_NO_CANCEL_OPTION, JOptionPane.QUESTION_MESSAGE, null, options, options[2]);JOptionPane
(constructor)- Creates a
JOptionPane
with the specified buttons, icons, message, title, and so on. You must then add the option pane to aJDialog
, register a property-change listener on the option pane, and show the dialog. See Stopping Automatic Dialog Closing for details.
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);showXxxDialog
methods andJOptionPane
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 The Dialog API.
Component parentComponent
- The first argument to each
showXxxDialog
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 -- generally the center of the screen, and the dialog doesn't depend on any visible frame.The
JOptionPane
constructors do not include this argument. Instead, you specify the parent frame when you create theJDialog
that contains theJOptionPane
, and you use theJDialog
setLocationRelativeTo
method to set the dialog's position.Object message
- 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 (
\n
) characters inside the message string. For example:"Complete the sentence:\n \"Green eggs and...\""String title
- The title of the dialog.
int optionType
- Specifies the set of buttons that appear at the bottom of the dialog. Choose from one of the following standard sets:
DEFAULT_OPTION
,YES_NO_OPTION
,YES_NO_CANCEL_OPTION
,OK_CANCEL_OPTION
.int messageType
- This argument determines the icon displayed in the dialog. Choose from one of the following values:
PLAIN_MESSAGE
(no icon),ERROR_MESSAGE
,INFORMATION_MESSAGE
,WARNING_MESSAGE
,QUESTION_MESSAGE
.Icon icon
- The icon to display in the dialog.
Object[] options
- Further specifies the option buttons to appear at the buttom of the dialog. Generally, you specify an array of strings for the buttons. See Customizing Button Text in a Standard Dialog for more information.
Object initialValue
- Specifies the default value to be selected.
You can either let the default icon be used or specify the icon using the message type or icon argument. By default, a dialog created with
showMessageDialog
displays the information icon, and a dialog created withshowConfirmDialog
orshowInputDialog
displays the question icon. An option pane created with aJOptionPane
constructor displays no icon, by default. To specify that the dialog display a standard icon or no icon, specify the message type. 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.
When you useJOptionPane
to create a dialog, you can choose either to use the standard button text (which might vary by look and feel) or to specify different text.The following code, taken from
DialogDemo.java
, creates two Yes/No dialogs. The first dialog is implemented with
showConfirmDialog
, which uses the look-and-feel wording for the two buttons. The second dialog usesshowOptionDialog
so it can customize the wording. With the exception of wording changes, the dialogs are identical.
//default icon, custom title int n = JOptionPane.showConfirmDialog( frame, "Would you like green eggs and ham?", "An Inane Question", JOptionPane.YES_NO_OPTION); 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
As the previous code snippets showed, theshowMessageDialog
,showConfirmDialog
, andshowOptionDialog
methods return an integer indicating the user's choice. The values for this integer areYES_OPTION
,NO_OPTION
,CANCEL_OPTION
,OK_OPTION
, andCLOSED_OPTION
. Except forCLOSED_OPTION
, each option corresponds to the button the user pressed. WhenCLOSED_OPTION
is returned, it indicates that the user closed the dialog window explicitly, rather than by choosing a button inside the option pane.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
YES_NO_OPTION
dialog always returns one of the following values:YES_OPTION
,NO_OPTION
, orCLOSED_OPTION
.
If you're designing a custom dialog, on the other hand, then you need to design your dialog's API so that you can query the dialog about what the user chose. For example, the dialog implemented in
CustomDialog.java
has a
getValidatedText
method that returns the text the user entered.
By default, when the user clicks aJOptionPane
-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.
DialogDemo
contains two dialogs that implement a property change listener. One of these dialogs is a custom modal dialog, implemented inCustomDialog
, that uses
JOptionPane
both to get the standard icon and to get layout assistance. The other dialog, whose code is below, uses a standard Yes/NoJOptionPane
, 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.Besides setting the property change listener, the following code also calls the
JDialog
'ssetDefaultCloseOperation
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.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); dialog.setDefaultCloseOperation( JDialog.DO_NOTHING_ON_CLOSE); dialog.addWindowListener(new WindowAdapter() { public void windowClosing(WindowEvent we) { setLabel("Thwarted user attempt to close window."); } }); optionPane.addPropertyChangeListener( new PropertyChangeListener() { public void propertyChange(PropertyChangeEvent e) { String prop = e.getPropertyName(); if (dialog.isVisible() && (e.getSource() == optionPane) && (prop.equals(JOptionPane.VALUE_PROPERTY) || prop.equals(JOptionPane.INPUT_VALUE_PROPERTY))) { //If you were going to check something //before closing the window, you'd do //it here. dialog.setVisible(false); } } }); dialog.pack(); dialog.setVisible(true); int value = ((Integer)optionPane.getValue()).intValue(); if (value == JOptionPane.YES_OPTION) { setLabel("Good."); } else if (value == JOptionPane.NO_OPTION) { setLabel("Try using the window decorations " + "to close the non-auto-closing dialog. " + "You can't!"); }
The following tables list the commonly usedJOptionPane
andJDialog
constructors and methods. Other methods you're likely to call are defined by theDialog
,
Window
and
Component
classes and include
pack
,setSize
, andsetVisible
.The API is listed as follows:
- Showing Standard Modal Dialogs (using
JOptionPane
Class Methods- Methods for Using
JOptionPane
s Directly- Other
JOptionPane
Constructors and Methods- Frequently Used
JDialog
Constructors and Methods
Showing Standard Modal Dialogs (Using JOptionPane
Class Methods)Method Purpose int showMessageDialog(Component, Object)
int showMessageDialog(Component, Object, String, int)
int showMessageDialog(Component, Object, String, int, Icon)Show a one-button, modal dialog that gives the user some information. The arguments specify (in order) the parent component, message, title, message type, and icon for the dialog. See Creating and Showing Simple Dialogs for a discussion of the arguments and their effects. int showOptionDialog(Component, Object, String, int, int, Icon, Object[], Object)
Show a customized modal dialog. The arguments specify (in order) the parent component, message, title, option type, message type, icon, options, and initial value for the dialog. See Creating and Showing Simple Dialogs for a discussion of the arguments and their effects. int showConfirmDialog(Component, Object)
int showConfirmDialog(Component, Object, String, int)
int showConfirmDialog(Component, Object, String, int, int)
int showConfirmDialog(Component, Object, String, int, int, Icon)Show a modal dialog that asks the user a question. The arguments specify (in order) the parent component, message, title, option type, message type, and icon for the dialog. See Creating and Showing Simple Dialogs for a discussion of the arguments and their effects. String showInputDialog(Object)
String showInputDialog(Component, Object)
String showInputDialog(Component, Object, String, int)
String showInputDialog(Component, Object, String, int, Icon, Object[], Object)Show a modal dialog that prompts the user for input. The single-argument version specifies just the message, with the parent component assumed to be null. The arguments for the other versions specify (in order) the parent component, message, title, message type, icon, options, and initial value for the dialog. See Creating and Showing Simple Dialogs for a discussion of the arguments and their effects. int showInternalMessageDialog(...)
int showInternalOptionDialog(...)
int showInternalConfirmDialog(...)
String showInternalInputDialog(...)Implement a standard dialog as an internal frame. See the JOptionPane
API documentationfor the exact list of arguments.
Methods for Using JOptionPane
s DirectlyMethod or Constructor Purpose JOptionPane()
JOptionPane(Object)
JOptionPane(Object, int)
JOptionPane(Object, int, int)
JOptionPane(Object, int, int, Icon)
JOptionPane(Object, int, int, Icon, Object[])
JOptionPane(Object, int, int, Icon, Object[], Object)Creates a JOptionPane
instance. See Creating and Showing Simple Dialogs for a discussion of the arguments and their effects.Frame getFrameForComponent(Component)
JDesktopPane getDesktopPaneForComponent(Component)Handy JOptionPane
class methods that find the frame or desktop pane, respectively, that the specified component is in.
Frequently Used JDialog
Constructors and MethodsMethod/Constructor Purpose JDialog()
JDialog(Frame)
JDialog(Frame, boolean)
JDialog(Frame, String)
JDialog(Frame, String, boolean)Creates a JDialog
instance. TheFrame
argument, if any, is the frame (usually aJFrame
object) that the dialog depends on. Make the boolean argumenttrue
to specify a modal dialog,false
or absent to specify a non-modal dialog. You can also specify the title of the dialog, using a string argument.Container getContentPane()
setContentPane(Container)Get and set the content pane, which is usually the container of all the dialog's components. See Using Top-Level Containers for more information. int getDefaultCloseOperation()
setDefaultCloseOperation(int)Get and set what happens when the user tries to close the dialog. Possible values: DISPOSE_ON_CLOSE
,DO_NOTHING_ON_CLOSE
,HIDE_ON_CLOSE
(the default). See Responding to Window-Closing Events for more information.void setLocationRelativeTo(Component)
Centers the dialog over the specified component.
This table lists examples that useJOptionPane
orJDialog
. To find other examples that use dialogs, see the example lists for progress bars, color choosers, and file choosers.
Example Where Described Notes DialogDemo
,
CustomDialog
This section Creates many kinds of dialogs, using JOptionPane
andJDialog
.Framework
-- Brings up a confirmation dialog when the user selects the Quit menu item. ListDialog
How to Use BoxLayout Implements a modal dialog containing a scrolling list and two buttons. Doesn't use JOptionPane
, except for the utility methodgetFrameForComponent
.TableDemo
How to Use Tables Brings up a warning dialog when the user types a non-number entry into a cell that must contain a number.
![]() ![]() ![]() |
Start of Tutorial > Start of Trail > Start of Lesson | Search |