Simple Dialogs (Java Foundation Classes)

3.15. Simple Dialogs

GUIs often use dialog boxes to handle simple interactions with the user. javax.swing.JOptionPane is a Swing component that is designed to serve as a highly configurable body of a dialog box. Instead of using the JOptionPane directly, however, most Swing programs use one or more of the many static methods defined by JOptionPane. These methods make it quite easy to implement simple dialog-based interactions.

If you take a look at the API for JOptionPane, you'll see that the class defines a group of static methods whose names begin with show and another whose names begin with showInternal. The show methods display simple dialog boxes within JDialog windows, while the showInternal methods display the same dialog boxes inside JInternalFrame windows. These static methods are further broken down by the type of dialog they display. There are several versions of showMessageDialog(), showConfirmDialog(), and showInputDialog(), as well as showInternal versions of the same methods. We'll consider these three types of dialogs--message, confirm, and input--in the sections that follow.

3.15.1. Message Dialogs

Message dialogs are used to display important information to users in a way that is difficult or impossible for them to miss. For example, you might use a message dialog to tell the user that a requested file was not found. To display this message with a JOptionPane, you can use code like this:

JOptionPane.showMessageDialog(mainpanel, "The file you requested, " + 
                              filename + ", was not found. Please try again");

This code produces the dialog shown in Figure 3-4. The dialog remains visible until the user dismisses it by clicking OK.

Figure 3-4. A JOptionPane message dialog

The first argument to showMessageDialog() is the component over which the dialog is to appear. You typically specify the main window or panel of your application. If you specify null, then the dialog will simply be centered on the screen. The second argument is obviously the message to be displayed. If you look at the API again, however, you'll notice that the message argument to this and other JOptionPane methods is defined as an Object, not a String. This means that you are not limited to textual messages. If you pass a Component or an Icon, the JOptionPane displays it as the message. If you pass some other kind of object, JOptionPane attempts to convert it to a string by calling its toString() method. You can even pass an array of objects as the message argument. When you pass more than one object, the objects are displayed top to bottom in the resulting dialog. So, to display a multiline message, for example, you can just pass in an array of String objects, instead of a single long String.

The showMessageDialog() function has variants that take more arguments. The title argument specifies the text to appear in the titlebar of the dialog. The messageType argument specifies the general type of the message. Legal values are the JOptionPane constants that end with _MESSAGE. The values you are most likely to use are INFORMATION_MESSAGE, WARNING_MESSAGE, and ERROR_MESSAGE. Specifying a message type implicitly specifies the icon that appears in the dialog box. If you don't like the default icons, however, there is a version of showMessageDialog() that lets you specify your own icon to display.

3.15.2. Confirm Dialogs

You can use JOptionPane.showConfirmDialog() or JOptionPane.showInternalConfirmDialog() when you want to ask the user a simple question that requires a Yes or No (or perhaps Cancel) answer. For example, you can use one of these methods to present the dialog shown in Figure 3-5.

Figure 3-5. A JOptionPane confirm dialog

The arguments to showConfirmDialog() are much like the arguments to showMessageDialog(), with the addition of the optionType argument. This argument specifies the set of buttons that appears at the bottom of the dialog. Legal values are OK_CANCEL_OPTION, YES_NO_OPTION, and YES_NO_CANCEL_OPTION.

A confirm dialog asks the user a question. The return value of showOptionDialog() or showInternalOptionDialog() is an integer that represents the user's answer in terms of the button the user clicked to dismiss the dialog. The possible values are OK_OPTION, YES_OPTION, NO_OPTION, CANCEL_OPTION, and CLOSED_OPTION. This last value is returned if the user did not click any of the dialog buttons but instead dismissed the dialog by closing the window. Here is some simple code that asks a question with a confirm dialog (note the use of a string array for the message argument):

int response = JOptionPane.showConfirmDialog(mainpanel, new String[] {
       /* first line of the message */       "There are unsaved files.",
       /* second line of message    */       "Save them before quitting?"},
       /* dialog title              */       "Save Before Quitting?",
       /* what buttons to display   */       JOptionPane.YES_NO_CANCEL_OPTION,
       /* icon type to display      */       JOptionPane.WARNING_MESSAGE);
switch(response) {
  case JOptionPane.YES_OPTION:     saveAndQuit();
  case JOptionPane.NO_OPTION:      quitWithoutSaving();
  case JOptionPane.CANCEL_OPTION:
  case JOptionPane.CLOSED_OPTION:  break;  // Don't quit!
}

3.15.3. Input Dialogs

The showInputDialog() and showInternalInputDialog() methods are designed to ask for input that is more complex than a yes-or-no answer. The simple versions of showInputDialog() support asking a question like "What is your name?" and letting the user type a response in a text input area:

String name = JOptionPane.showInputDialog(frame, "What is your name?");

The more complex version of this method allows the user to select an object from a list or pull-down menu of predefined options.

The arguments to showInputDialog() are quite similar to those passed to showMessageDialog() and showConfirmDialog(). To display a list of options to the user, use the seven-argument version of the method and pass in an array of choices and the default choice to display. For example:

String response = (String) JOptionPane.showInputDialog(
		      contentpane,                       // parent
		     "Who is your favorite chipmunk?",   // message
		     "Pick a Chipmunk",                  // dialog title
		      JOptionPane.QUESTION_MESSAGE,      // icon type
		      null,                              // no explicit icon
		      new String[] {                     // choices
			 "Alvin", "Simon", "Theodore" 
		      },  
		      "Alvin");                          // default choice